@alfe.ai/openclaw-memory-cloud 0.0.38 → 0.0.39

package/README.md

@@ -0,0 +1,37 @@
+# `@alfe.ai/openclaw-memory-cloud`
+
+OpenClaw's private, per-agent cloud-memory plugin. It captures bounded
+conversation windows, recalls escaped context, and exposes tools for vector
+memory and the per-agent knowledge graph through the Alfe Agent API.
+
+## Safety model
+
+Live capture state is isolated by the canonical OpenClaw `sessionKey`; there is
+no process-wide current session. Flushes for one session are serialized so the
+memory service's high-water mark cannot observe a later batch first. A
+strictly monotonic, owner-only epoch fences daemon restarts. If that state
+cannot be secured, auto-capture is disabled while recall and explicit tools
+remain available.
+
+`memory_forget` is a two-step operation: the first call previews up to five
+current matches and the second must confirm those exact IDs in the same order.
+`memory_learn` accepts bounded inline text or a regular, non-symlink file under
+the configured runtime workspace. Service responses are normalized before
+they reach the model, and recalled context is escaped and capped at 16 KiB.
+
+## Development
+
+```bash
+pnpm --filter @alfe.ai/openclaw-memory-cloud lint
+pnpm --filter @alfe.ai/openclaw-memory-cloud typecheck
+pnpm --filter @alfe.ai/openclaw-memory-cloud test
+pnpm --filter @alfe.ai/openclaw-memory-cloud build
+```
+
+The package publishes ESM and CJS entrypoints. The OpenClaw loader uses the
+default-only `./plugin` export. Keep the tool
+catalog and configuration bounds aligned with `openclaw.plugin.json` and the
+memory service's agent routes.
+
+Part of [Alfe](https://alfe.ai). See the [documentation](https://docs.alfe.ai)
+for platform setup.

package/dist/index.cjs

@@ -0,0 +1,2 @@
+const require_plugin = require("./plugin2.cjs");
+module.exports = require_plugin.plugin;

package/dist/index.d.cts

@@ -0,0 +1,2 @@
+import { t as plugin } from "./plugin.cjs";
+export { plugin as default };

package/dist/index.d.ts

@@ -1,60 +1,2 @@
-/**
- * memory-cloud — OpenClaw memory extension
- *
- * Replaces the builtin LanceDB memory extension with cloud-backed storage:
- * - Turbopuffer for vector storage (via services/memory Lambda proxy)
- * - DynamoDB for knowledge graph
- * - Haiku for classification + entity extraction
- *
- * Registers:
- * - Memory tools: memory_recall, memory_store, memory_forget, memory_navigate, memory_graph, memory_stats
- * - Lifecycle hooks: before_agent_start (auto-recall), agent_end (auto-capture), message_received (idle debounce)
- * - Memory runtime: replaces builtin SQLite backend with cloud backend
- */
-interface PluginApi {
-    pluginConfig?: Record<string, unknown>;
-    config: Record<string, unknown>;
-    logger: {
-        info: (msg: string, ctx?: Record<string, unknown>) => void;
-        debug: (msg: string, ctx?: Record<string, unknown>) => void;
-        warn: (msg: string, ctx?: Record<string, unknown>) => void;
-        error: (msg: string, ctx?: Record<string, unknown>) => void;
-    };
-    registerTool: (factory: (ctx: ToolContext) => Tool, opts?: {
-        names?: string[];
-    }) => void;
-    registerHook: (events: string | string[], handler: (...args: unknown[]) => unknown, opts?: {
-        name?: string;
-        description?: string;
-    }) => void;
-    on: (hookName: string, handler: (...args: unknown[]) => unknown, opts?: {
-        priority?: number;
-    }) => void;
-    registerMemoryPromptSection: (builder: (params: {
-        availableTools: Set<string>;
-    }) => string[]) => void;
-    registerMemoryRuntime: (runtime: unknown) => void;
-}
-interface ToolContext {
-    agentId?: string;
-    sessionKey?: string;
-    sessionId?: string;
-    messageChannel?: string;
-}
-interface Tool {
-    name: string;
-    label: string;
-    description: string;
-    parameters: Record<string, unknown>;
-    execute: (toolCallId: string, params: Record<string, unknown>) => Promise<unknown>;
-}
-declare const _default: {
-    id: string;
-    name: string;
-    description: string;
-    version: string;
-    kind: "memory";
-    register(api: PluginApi): void;
-};
-export default _default;
-//# sourceMappingURL=index.d.ts.map
+import { t as plugin } from "./plugin.js";
+export { plugin as default };

package/dist/index.js

@@ -1,396 +1,2 @@
-/**
- * memory-cloud — OpenClaw memory extension
- *
- * Replaces the builtin LanceDB memory extension with cloud-backed storage:
- * - Turbopuffer for vector storage (via services/memory Lambda proxy)
- * - DynamoDB for knowledge graph
- * - Haiku for classification + entity extraction
- *
- * Registers:
- * - Memory tools: memory_recall, memory_store, memory_forget, memory_navigate, memory_graph, memory_stats
- * - Lifecycle hooks: before_agent_start (auto-recall), agent_end (auto-capture), message_received (idle debounce)
- * - Memory runtime: replaces builtin SQLite backend with cloud backend
- */
-import * as fs from "node:fs/promises";
-import * as path from "node:path";
-import { resolveConfig } from "@alfe.ai/config";
-import { AgentApiClient, installToolErrorCapture } from "@alfe.ai/agent-api-client";
-import { AutoCapture } from "./auto-capture.js";
-import { AutoRecall } from "./auto-recall.js";
-import { formatSearchResults } from "./formatter.js";
-import { runSessionsBackfill } from "./session-backfill.js";
-import { resolveIngestEpoch } from "./ingest-epoch.js";
-import { createRequire } from 'node:module';
-const require = createRequire(import.meta.url);
-const pkg = require('../package.json');
-const DEFAULT_CONFIG = {
-    autoCapture: true,
-    autoRecall: true,
-    captureMaxChars: 500,
-    idleFlushSeconds: 60,
-    backfillSessions: true,
-    backfillMaxSessions: 50,
-};
-function resolvePluginConfig(pluginConfig) {
-    return {
-        autoCapture: typeof pluginConfig?.autoCapture === "boolean" ? pluginConfig.autoCapture : DEFAULT_CONFIG.autoCapture,
-        autoRecall: typeof pluginConfig?.autoRecall === "boolean" ? pluginConfig.autoRecall : DEFAULT_CONFIG.autoRecall,
-        captureMaxChars: typeof pluginConfig?.captureMaxChars === "number" ? pluginConfig.captureMaxChars : DEFAULT_CONFIG.captureMaxChars,
-        idleFlushSeconds: typeof pluginConfig?.idleFlushSeconds === "number" ? pluginConfig.idleFlushSeconds : DEFAULT_CONFIG.idleFlushSeconds,
-        backfillSessions: typeof pluginConfig?.backfillSessions === "boolean" ? pluginConfig.backfillSessions : DEFAULT_CONFIG.backfillSessions,
-        backfillMaxSessions: typeof pluginConfig?.backfillMaxSessions === "number" && Number.isFinite(pluginConfig.backfillMaxSessions) && pluginConfig.backfillMaxSessions > 0
-            ? Math.floor(pluginConfig.backfillMaxSessions)
-            : DEFAULT_CONFIG.backfillMaxSessions,
-    };
-}
-export default {
-    id: "@alfe.ai/openclaw-memory-cloud",
-    name: "Cloud Memory",
-    description: "Persistent agent memory backed by Turbopuffer + DynamoDB knowledge graph",
-    version: pkg.version,
-    kind: "memory",
-    register(api) {
-        // First thing, before any registerTool call: tool failures emit a
-        // deterministic [ERROR] line the gateway's runtime-output monitor captures
-        // to Sentry. See @alfe.ai/agent-api-client tool-error-capture.
-        installToolErrorCapture(api, { plugin: "openclaw-memory-cloud" });
-        const config = resolvePluginConfig(api.pluginConfig);
-        const logger = api.logger;
-        const alfeConfig = resolveConfig();
-        const client = new AgentApiClient({
-            apiKey: alfeConfig.apiKey,
-            apiUrl: alfeConfig.apiUrl,
-        });
-        // Strictly-monotonic per-boot epoch, resolved once at process start.
-        // Guards against a backward wall-clock step across a restart (which would
-        // otherwise trap every live-capture flush in the server's stale-boot
-        // branch and silently drop it). See ingest-epoch.ts.
-        const ingestEpoch = resolveIngestEpoch({ logger });
-        const autoCapture = new AutoCapture(client, config, logger, ingestEpoch);
-        const autoRecall = new AutoRecall(client, config, logger);
-        // ─── Memory prompt section ──────────────────────────────────
-        api.registerMemoryPromptSection(({ availableTools }) => {
-            const lines = ["## Memory"];
-            if (availableTools.has("memory_recall")) {
-                lines.push("Use memory_recall to search your conversation history and knowledge graph.");
-                lines.push("Results include structured facts (from knowledge graph) and relevant conversation excerpts.");
-            }
-            if (availableTools.has("memory_store")) {
-                lines.push("Use memory_store to explicitly save important information for future reference.");
-            }
-            if (availableTools.has("memory_learn")) {
-                lines.push("Use memory_learn when the user asks you to learn or remember something — or when you read a doc with durable facts. Pass the source text directly; the system auto-classifies and extracts entities.");
-            }
-            if (availableTools.has("memory_graph")) {
-                lines.push("Use memory_graph to look up what you know about a specific entity.");
-            }
-            return lines;
-        });
-        // ─── Tools ──────────────────────────────────────────────────
-        api.registerTool(() => ({
-            name: "memory_recall",
-            label: "Memory Recall",
-            description: "Search conversation memory and knowledge graph. Returns structured facts and relevant conversation excerpts.",
-            parameters: {
-                type: "object",
-                properties: {
-                    query: { type: "string", description: "What to search for" },
-                    limit: { type: "number", description: "Maximum results (default 10)" },
-                    topic: { type: "string", description: "Filter by topic" },
-                    tag: { type: "string", description: "Filter by tag (fact/decision/preference/event/discovery)" },
-                },
-                required: ["query"],
-            },
-            execute: async (_toolCallId, params) => {
-                const results = await client.memorySearch(params.query, {
-                    limit: params.limit,
-                    topic: params.topic,
-                    tag: params.tag,
-                });
-                return formatSearchResults(results);
-            },
-        }), { names: ["memory_recall", "memory_search"] });
-        api.registerTool(() => ({
-            name: "memory_store",
-            label: "Memory Store",
-            description: "Explicitly save a piece of information to long-term memory.",
-            parameters: {
-                type: "object",
-                properties: {
-                    text: { type: "string", description: "The information to remember" },
-                    topic: { type: "string", description: "Topic category (e.g., person name, project)" },
-                    tag: { type: "string", description: "Memory type: fact, decision, preference, event, discovery" },
-                    importance: { type: "number", description: "Importance 0-1 (default 0.7)" },
-                },
-                required: ["text"],
-            },
-            execute: async (_toolCallId, params) => {
-                const result = await client.memoryStore(params.text, {
-                    topic: params.topic,
-                    tag: params.tag,
-                    importance: params.importance,
-                });
-                return `Stored memory: ${result.memoryId}`;
-            },
-        }), { names: ["memory_store"] });
-        api.registerTool(() => ({
-            name: "memory_learn",
-            label: "Memory Learn",
-            description: "Save arbitrary content (a paragraph, a doc, a fact list) into long-term memory. The system auto-classifies and extracts entities. Use this when the user asks you to learn, remember, or study something — or when you read a document worth retaining. Pass the source text directly; do not paraphrase first.",
-            parameters: {
-                type: "object",
-                properties: {
-                    content: { type: "string", description: "Inline text to ingest. Provide either content OR path, not both." },
-                    path: { type: "string", description: "Workspace-relative file path to read and ingest. Provide either content OR path, not both." },
-                    source: { type: "string", description: "Optional label describing where the content came from (e.g. doc title, url)." },
-                },
-            },
-            execute: async (_toolCallId, params) => {
-                const content = typeof params.content === "string" ? params.content : undefined;
-                const filePath = typeof params.path === "string" ? params.path : undefined;
-                const source = typeof params.source === "string" ? params.source : undefined;
-                if (!content && !filePath) {
-                    return "Error: provide either `content` or `path`.";
-                }
-                if (content && filePath) {
-                    return "Error: provide either `content` or `path`, not both.";
-                }
-                let text;
-                let resolvedSource = source;
-                let sourceType = "inline";
-                if (filePath !== undefined) {
-                    const cwd = process.cwd();
-                    const resolved = path.resolve(cwd, filePath);
-                    if (!resolved.startsWith(cwd + path.sep) && resolved !== cwd) {
-                        return `Error: path "${filePath}" escapes the workspace.`;
-                    }
-                    try {
-                        text = await fs.readFile(resolved, "utf8");
-                    }
-                    catch (err) {
-                        return `Error reading "${filePath}": ${err instanceof Error ? err.message : String(err)}`;
-                    }
-                    resolvedSource = source ?? filePath;
-                    sourceType = "file";
-                }
-                else if (content !== undefined) {
-                    text = content;
-                }
-                else {
-                    return "Error: provide either `content` or `path`.";
-                }
-                try {
-                    const result = await client.memoryLearn({ text, source: resolvedSource, sourceType });
-                    const label = result.source ?? "content";
-                    return `Stored ${String(result.memoriesStored)} memories (${String(result.triplesStored)} facts, ${String(result.chunks)} chunks) from ${label}.`;
-                }
-                catch (err) {
-                    logger.warn("memory_learn failed", { err: String(err) });
-                    return `Error: failed to store memory — ${err instanceof Error ? err.message : String(err)}`;
-                }
-            },
-        }), { names: ["memory_learn"] });
-        api.registerTool(() => ({
-            name: "memory_forget",
-            label: "Memory Forget",
-            description: "Search for and delete memories matching a query.",
-            parameters: {
-                type: "object",
-                properties: {
-                    query: { type: "string", description: "Search for memories to delete" },
-                },
-                required: ["query"],
-            },
-            execute: async (_toolCallId, params) => {
-                const results = await client.memorySearch(params.query, { limit: 5 });
-                if (results.memories.length === 0)
-                    return "No matching memories found.";
-                const deleted = [];
-                for (const mem of results.memories) {
-                    try {
-                        await client.memoryDelete(mem.id);
-                        deleted.push(mem.id);
-                    }
-                    catch {
-                        logger.warn("Failed to delete memory", { memoryId: mem.id });
-                    }
-                }
-                return `Deleted ${String(deleted.length)} of ${String(results.memories.length)} matching memories.`;
-            },
-        }), { names: ["memory_forget"] });
-        api.registerTool(() => ({
-            name: "memory_graph",
-            label: "Knowledge Graph",
-            description: "Look up what you know about a specific entity from the knowledge graph.",
-            parameters: {
-                type: "object",
-                properties: {
-                    entity: { type: "string", description: "The entity to look up (person, concept, system)" },
-                },
-                required: ["entity"],
-            },
-            execute: async (_toolCallId, params) => {
-                const result = await client.memoryLookupEntity(params.entity);
-                if (result.triples.length === 0)
-                    return `No knowledge found about "${params.entity}".`;
-                const facts = result.triples.map((t) => `- ${result.subject} ${t.predicate} ${t.object} (since ${t.validFrom.slice(0, 10)})`);
-                return `Known facts about ${result.subject}:\n${facts.join("\n")}`;
-            },
-        }), { names: ["memory_graph"] });
-        api.registerTool(() => ({
-            name: "memory_stats",
-            label: "Memory Stats",
-            description: "Get memory storage statistics.",
-            parameters: { type: "object", properties: {} },
-            execute: async () => {
-                const s = await client.memoryStats();
-                return `Memories: ${String(s.vectorCount)}, Knowledge facts: ${String(s.tripleCount)}, Storage: ${String(Math.round(s.storageEstimateBytes / 1024))} KB`;
-            },
-        }), { names: ["memory_stats"] });
-        api.registerTool(() => ({
-            name: "memory_navigate",
-            label: "Memory Navigate",
-            description: "Browse your memory palace structure — list topics, subtopics, and memory counts.",
-            parameters: { type: "object", properties: {} },
-            execute: async () => {
-                const nav = await client.memoryNavigate();
-                const topics = nav.topics;
-                if (topics.length === 0)
-                    return "No memories stored yet.";
-                const lines = topics.map((t) => `- ${t.name} (${String(t.tripleCount)} facts, subtopics: ${t.subtopics.join(", ") || "none"})`);
-                return `Memory topics:\n${lines.join("\n")}`;
-            },
-        }), { names: ["memory_navigate"] });
-        // ─── Lifecycle hooks ────────────────────────────────────────
-        // Auto-recall: inject relevant memories at session start
-        api.on("before_agent_start", async (event, ctx) => {
-            const startEvent = event;
-            const agentCtx = ctx;
-            const prompt = typeof startEvent.prompt === "string" ? startEvent.prompt : "";
-            const sessionKey = typeof agentCtx.sessionKey === "string" ? agentCtx.sessionKey : undefined;
-            const channelId = typeof agentCtx.channelId === "string" ? agentCtx.channelId : undefined;
-            if (sessionKey) {
-                autoCapture.setSession(sessionKey, { channelId });
-            }
-            const contextXml = await autoRecall.loadForPrompt(prompt);
-            if (contextXml) {
-                return { prependContext: contextXml };
-            }
-            return undefined;
-        }, { priority: 10 });
-        // Track incoming messages for idle debounce
-        api.on("message_received", (event) => {
-            const msgEvent = event;
-            const content = typeof msgEvent.content === "string" ? msgEvent.content : "";
-            autoCapture.trackMessage("user", content);
-        });
-        // Track outgoing messages
-        api.on("message_sending", (event) => {
-            const msgEvent = event;
-            const content = typeof msgEvent.content === "string" ? msgEvent.content : "";
-            autoCapture.trackMessage("assistant", content);
-        });
-        // Final flush on session end
-        api.on("agent_end", async (event) => {
-            const endEvent = event;
-            if (endEvent.success !== false) {
-                await autoCapture.onAgentEnd();
-            }
-        });
-        // Fire-and-forget first-run sync: workspace files (MEMORY.md / memory/*.md)
-        // and pre-existing chat sessions, each idempotent via its own
-        // PalaceMetadata flag (bootstrapSyncedAt / sessionsBackfillSyncedAt).
-        void runStartupSync(client, config, logger).catch((err) => {
-            logger.warn("memory startup sync failed; will retry on next startup", { err: String(err) });
-        });
-        logger.info("memory-cloud extension registered", { autoCapture: config.autoCapture, autoRecall: config.autoRecall });
-    },
-};
-async function runStartupSync(client, config, logger) {
-    // Fetch status ONCE, before the file bootstrap runs: the sessions backfill
-    // computes its dedup cutoff from the pre-bootstrap `syncedAt` (an agent
-    // that already had memory installed captured everything after that moment
-    // live, so backfilling past it would duplicate memories).
-    let status;
-    try {
-        status = await client.memoryBootstrapStatus();
-    }
-    catch (err) {
-        logger.debug("memory bootstrap status check failed; skipping", { err: String(err) });
-        return;
-    }
-    const startupMs = Date.now();
-    if (status.synced) {
-        logger.debug("memory bootstrap: already synced, skipping");
-    }
-    else {
-        try {
-            await runBootstrap(client, logger);
-        }
-        catch (err) {
-            logger.warn("memory bootstrap failed; will retry on next startup", { err: String(err) });
-        }
-    }
-    // Strict `=== false` on purpose: an old server (deployed before the
-    // sessions-backfill release) omits the field entirely, and its mark
-    // endpoint would clobber `bootstrapSyncedAt` — corrupting the cutoff
-    // anchor. Defer until the service is deployed and reports the flag.
-    if (config.backfillSessions && status.sessionsBackfillSynced === false) {
-        const installedAtMs = status.syncedAt ? Date.parse(status.syncedAt) : Number.POSITIVE_INFINITY;
-        const cutoffMs = Math.min(startupMs, Number.isNaN(installedAtMs) ? Number.POSITIVE_INFINITY : installedAtMs);
-        await runSessionsBackfill(client, config, logger, { cutoffMs });
-    }
-}
-async function runBootstrap(client, logger) {
-    const cwd = process.cwd();
-    const filesToSync = [];
-    try {
-        await fs.access(path.join(cwd, "MEMORY.md"));
-        filesToSync.push("MEMORY.md");
-    }
-    catch { /* missing — fine */ }
-    try {
-        const memoryDir = path.join(cwd, "memory");
-        const entries = await fs.readdir(memoryDir, { withFileTypes: true });
-        for (const entry of entries) {
-            if (entry.isFile() && entry.name.endsWith(".md")) {
-                filesToSync.push(path.join("memory", entry.name));
-            }
-        }
-    }
-    catch { /* no memory/ dir — fine */ }
-    if (filesToSync.length === 0) {
-        logger.debug("memory bootstrap: no files to sync, marking complete");
-        try {
-            await client.memoryBootstrapStatusMark();
-        }
-        catch { /* retry next start */ }
-        return;
-    }
-    logger.info("memory bootstrap: ingesting files", { count: filesToSync.length });
-    for (const relPath of filesToSync) {
-        try {
-            const text = await fs.readFile(path.join(cwd, relPath), "utf8");
-            if (text.trim().length === 0)
-                continue;
-            const result = await client.memoryLearn({ text, source: relPath, sourceType: "file" });
-            logger.debug("memory bootstrap: file ingested", {
-                file: relPath,
-                memoriesStored: result.memoriesStored,
-                triplesStored: result.triplesStored,
-            });
-        }
-        catch (err) {
-            logger.warn("memory bootstrap: file failed; will retry on next startup", { file: relPath, err: String(err) });
-            return;
-        }
-    }
-    try {
-        await client.memoryBootstrapStatusMark();
-        logger.info("memory bootstrap: complete");
-    }
-    catch (err) {
-        logger.warn("memory bootstrap: mark failed; will retry on next startup", { err: String(err) });
-    }
-}
-//# sourceMappingURL=index.js.map
+import { t as plugin } from "./plugin2.js";
+export { plugin as default };

package/dist/plugin.cjs

@@ -0,0 +1,2 @@
+const require_plugin = require("./plugin2.cjs");
+module.exports = require_plugin.plugin;

package/dist/plugin.d.cts

@@ -0,0 +1,59 @@
+import { TSchema } from "@sinclair/typebox";
+
+//#region ../openclaw-plugin-kit/dist/index.d.ts
+
+//# sourceMappingURL=types.d.ts.map
+//#endregion
+//#region src/tools.d.ts
+/** Shape returned to OpenClaw from a tool `execute`. */
+interface ToolResult {
+  content: {
+    type: "text";
+    text: string;
+  }[];
+  details: unknown;
+  isError?: boolean;
+}
+interface ToolDef<TParameters = unknown> {
+  name: string;
+  description: string;
+  label: string;
+  parameters: TParameters;
+  execute: (toolCallId: string, params: Record<string, unknown>) => Promise<ToolResult>;
+}
+/** Deliberately model-safe validation/usage failure. Other exceptions stay private. */
+//#endregion
+//#region src/runtime.d.ts
+interface PluginLogger {
+  info(message: string, context?: Record<string, unknown>): void;
+  debug(message: string, context?: Record<string, unknown>): void;
+  warn(message: string, context?: Record<string, unknown>): void;
+  error(message: string, context?: Record<string, unknown>): void;
+}
+interface PluginApi {
+  pluginConfig?: unknown;
+  logger: PluginLogger;
+  registerTool(tool: ToolDef<TSchema>, options?: {
+    names?: string[];
+  }): void;
+  on(hookName: string, handler: (...args: unknown[]) => unknown, options?: {
+    priority?: number;
+  }): void;
+  registerMemoryPromptSection(builder: (params: {
+    availableTools: Set<string>;
+  }) => string[]): void;
+}
+interface MemoryCloudPlugin {
+  id: string;
+  name: string;
+  description: string;
+  version: string;
+  kind: "memory";
+  register(api: PluginApi): void;
+}
+//#endregion
+//#region src/plugin.d.ts
+declare const plugin: MemoryCloudPlugin;
+//#endregion
+export { plugin as t };
+//# sourceMappingURL=plugin.d.cts.map

package/dist/plugin.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin.d.cts","names":["KitLogger","ToolResult","ToolDef","TParameters","Record","Promise","PublicToolError","Error","publicToolError","ok","errResult","defineTool","IpcResponse","IpcClient","IpcModule","ConnectToDaemonOptions","ConnectToDaemonDependencies","connectToDaemon","ResolveOpenClawSdkOptions","ResolveOpenClawSdkDependencies","resolveOpenClawSdk","T","getActivationKey","isActivated","resetActivation","guardedStart"],"sources":["../../openclaw-plugin-kit/dist/index.d.ts","../src/runtime.ts","../src/plugin.ts"],"sourcesContent":["//#region src/types.d.ts\n/**\n * Minimal logger contract shared by every helper in the kit.\n *\n * Deliberately the *narrowest* shape in the fleet: some plugins declare\n * variadic loggers (`info(msg: string, ...args: unknown[])`), others\n * single-arg (`info(msg: string)`). Both are assignable to this. The kit\n * only ever calls with a single string.\n */\ninterface KitLogger {\n  info(msg: string): void;\n  warn(msg: string): void;\n  error(msg: string): void;\n  debug(msg: string): void;\n}\n//# sourceMappingURL=types.d.ts.map\n//#endregion\n//#region src/tools.d.ts\n/** Shape returned to OpenClaw from a tool `execute`. */\ninterface ToolResult {\n  content: {\n    type: \"text\";\n    text: string;\n  }[];\n  details: unknown;\n  isError?: boolean;\n}\ninterface ToolDef<TParameters = unknown> {\n  name: string;\n  description: string;\n  label: string;\n  parameters: TParameters;\n  execute: (toolCallId: string, params: Record<string, unknown>) => Promise<ToolResult>;\n}\n/** Deliberately model-safe validation/usage failure. Other exceptions stay private. */\ndeclare class PublicToolError extends Error {\n  readonly name = \"PublicToolError\";\n}\ndeclare function publicToolError(message: string): PublicToolError;\n/** Wrap bounded JSON in the OpenClaw tool-result envelope. */\ndeclare function ok(data: unknown): ToolResult;\n/** Wrap an explicitly public error in a captured OpenClaw error envelope. */\ndeclare function errResult(message: string): ToolResult;\n/**\n * Define a tool whose unexpected exceptions never expose provider, filesystem,\n * credential, or transport diagnostics to the model. Throw `PublicToolError`\n * only for a message deliberately safe for model display.\n */\ndeclare function defineTool<TParameters>(def: {\n  name: string;\n  description: string;\n  parameters: TParameters;\n  handler: (params: Record<string, unknown>) => Promise<unknown>;\n}): ToolDef<TParameters>;\n//# sourceMappingURL=tools.d.ts.map\n//#endregion\n//#region src/daemon.d.ts\ninterface IpcResponse {\n  ok: boolean;\n  error?: {\n    message?: string;\n  };\n  [key: string]: unknown;\n}\ninterface IpcClient {\n  on(event: string, handler: (...args: unknown[]) => void): void;\n  request(method: string, params: Record<string, unknown>): Promise<IpcResponse>;\n  start(): void;\n  stop(): void;\n}\ninterface IpcModule {\n  IPCClient: new (socketPath: string, log: KitLogger) => IpcClient;\n}\ninterface ConnectToDaemonOptions {\n  pluginId: string;\n  capabilities?: readonly string[];\n  onMessage?: (msg: Record<string, unknown>) => void;\n  standaloneNote?: string;\n}\ninterface ConnectToDaemonDependencies {\n  loadIpcModule?: () => Promise<IpcModule>;\n}\ndeclare function connectToDaemon(socketPath: string, log: KitLogger, options: ConnectToDaemonOptions, dependencies?: ConnectToDaemonDependencies): Promise<IpcClient | null>;\n//#endregion\n//#region src/sdk.d.ts\ninterface ResolveOpenClawSdkOptions {\n  specifier?: string;\n  exportName?: string;\n  unresolvableNote?: string;\n}\ninterface ResolveOpenClawSdkDependencies {\n  anchors?: readonly string[];\n  globalPackageJsonPath?: string;\n  requireFrom?: (anchor: string) => (specifier: string) => unknown;\n}\ndeclare function resolveOpenClawSdk<T = unknown>(log: KitLogger, options?: ResolveOpenClawSdkOptions, dependencies?: ResolveOpenClawSdkDependencies): T | null;\n//# sourceMappingURL=sdk.d.ts.map\n\n//#endregion\n//#region src/activation.d.ts\n/**\n * Canonical activation-flag key for a plugin: `__alfe<Name>PluginActivated`.\n *\n * Accepts a short name (`\"google\"`, `\"google-chat\"`) or a full package name\n * (`\"@alfe.ai/openclaw-teams\"`); scope + `openclaw-` prefix are stripped\n * and the remainder PascalCased:\n *\n *   getActivationKey(\"google\")                  → \"__alfeGooglePluginActivated\"\n *   getActivationKey(\"google-chat\")             → \"__alfeGoogleChatPluginActivated\"\n *   getActivationKey(\"@alfe.ai/openclaw-teams\") → \"__alfeTeamsPluginActivated\"\n */\ndeclare function getActivationKey(name: string): string;\n/** True when the activation flag for `key` is currently set. */\ndeclare function isActivated(key: string): boolean;\n/**\n * Clear the activation flag so a later start can run again.\n *\n * Call this LAST in stop/deactivate paths — after side effects are stopped\n * (see the ordering rule in the module doc). Also exported for soft-failure\n * paths inside a `guardedStart` fn that want to log at a custom level and\n * return normally instead of throwing.\n */\ndeclare function resetActivation(key: string): void;\n/**\n * Run a service start exactly once per activation cycle.\n *\n * - If the flag is already set, logs at debug and returns `false` (skipped).\n * - Otherwise sets the flag and runs `fn`.\n * - If `fn` throws synchronously OR returns a promise that rejects, the\n *   flag is RESET (so a later activate can retry) and the error is logged.\n *   Errors are not rethrown — matching fleet behavior where a failed start\n *   must never crash the host's plugin loader.\n *\n * Returns `true` when the start was initiated (even if an async portion\n * later fails), `false` when skipped or when `fn` threw synchronously.\n *\n * Note: cleaning up partial side effects on failure is `fn`'s job (throw\n * only after tearing down what was started); the kit only guarantees the\n * flag reset happens after `fn` has failed — i.e. after `fn`'s own cleanup.\n */\ndeclare function guardedStart(key: string, log: KitLogger, fn: () => void | Promise<void>): boolean;\n//# sourceMappingURL=activation.d.ts.map\n\n//#endregion\nexport { type ConnectToDaemonDependencies, type ConnectToDaemonOptions, type IpcClient, type IpcResponse, type KitLogger, PublicToolError, type ResolveOpenClawSdkDependencies, type ResolveOpenClawSdkOptions, type ToolDef, type ToolResult, connectToDaemon, defineTool, errResult, getActivationKey, guardedStart, isActivated, ok, publicToolError, resetActivation, resolveOpenClawSdk };\n//# sourceMappingURL=index.d.ts.map"],"mappings":";;;;;;;;UAmBUC,UAAAA,CCiCyB;EAAM,OAAA,EAAA;IAGxB,IAAA,EAAA,MAAS;IAAA,IAAA,EAAA,MAAA;;SAGG,EAAA,OAAA;SAAR,CAAA,EAAA,OAAA;;UD/BXC,OCiC2D,CAAA,cAAA,OAAA,CAAA,CAAA;EAUrE,IAAiB,EAAA,MAAA;;;cDvCHC;EE/BiE,OAEzE,EAAA,CAAA,UAAqD,EAA7C,MAAA,EAAA,MAAA,EF8B0BC,ME9BmB,CAAA,MAAA,EAAA,OAAA,CAAA,EAAA,GF8BSC,OE9BT,CF8BiBJ,UE9BjB,CAAA;;;;;AF6B7CE,UCiBG,YAAA,CDjBHA;MAC0BC,CAAAA,OAAAA,EAAAA,MAAAA,EAAAA,OAAAA,CAAAA,ECiBN,MDjBMA,CAAAA,MAAAA,EAAAA,OAAAA,CAAAA,CAAAA,EAAAA,IAAAA;OAAoCH,CAAAA,OAAAA,EAAAA,MAAAA,EAAAA,OAAAA,CAAAA,ECkBzC,MDlByCA,CAAAA,MAAAA,EAAAA,OAAAA,CAAAA,CAAAA,EAAAA,IAAAA;MAARI,CAAAA,OAAAA,EAAAA,MAAAA,EAAAA,OAAAA,CAAAA,ECmBlC,MDnBkCA,CAAAA,MAAAA,EAAAA,OAAAA,CAAAA,CAAAA,EAAAA,IAAAA;EAAO,KAAA,CAAA,OAAA,EAAA,MAAA,EAAA,OAAA,CAAA,ECoBxC,MDpBwC,CAAA,MAAA,EAAA,OAAA,CAAA,CAAA,EAAA,IAAA;;UCuB1D,SAAA;;EAPA,MAAA,EASP,YATmB;EAAA,YAAA,CAAA,IAAA,EAUR,OAVQ,CAUA,OAVA,CAAA,EAAA,QAAA,EAAA;IACK,KAAA,CAAA,EAAA,MAAA,EAAA;MACC,IAAA;KACD,QAAA,EAAA,MAAA,EAAA,OAAA,EAAA,CAAA,GAAA,IAAA,EAAA,OAAA,EAAA,EAAA,GAAA,OAAA,EAAA,OACO,CADP,EAAA;IACC,QAAA,CAAA,EAAA,MAAA;EAAM,CAAA,CAAA,EAAA,IAAA;EAGxB,2BAAS,CAAA,OAAA,EAAA,CAAA,MAAA,EAAA;IAAA,cAAA,EAKwC,GALxC,CAAA,MAAA,CAAA;KAEhB,GAAA,MAAA,EAAA,CAAA,EAAA,IAAA;;UAaO,iBAAA;;;;;;gBAMD;;;;cC1EV,QAAQ"}

package/dist/plugin.d.ts

@@ -0,0 +1,59 @@
+import { TSchema } from "@sinclair/typebox";
+
+//#region ../openclaw-plugin-kit/dist/index.d.ts
+
+//# sourceMappingURL=types.d.ts.map
+//#endregion
+//#region src/tools.d.ts
+/** Shape returned to OpenClaw from a tool `execute`. */
+interface ToolResult {
+  content: {
+    type: "text";
+    text: string;
+  }[];
+  details: unknown;
+  isError?: boolean;
+}
+interface ToolDef<TParameters = unknown> {
+  name: string;
+  description: string;
+  label: string;
+  parameters: TParameters;
+  execute: (toolCallId: string, params: Record<string, unknown>) => Promise<ToolResult>;
+}
+/** Deliberately model-safe validation/usage failure. Other exceptions stay private. */
+//#endregion
+//#region src/runtime.d.ts
+interface PluginLogger {
+  info(message: string, context?: Record<string, unknown>): void;
+  debug(message: string, context?: Record<string, unknown>): void;
+  warn(message: string, context?: Record<string, unknown>): void;
+  error(message: string, context?: Record<string, unknown>): void;
+}
+interface PluginApi {
+  pluginConfig?: unknown;
+  logger: PluginLogger;
+  registerTool(tool: ToolDef<TSchema>, options?: {
+    names?: string[];
+  }): void;
+  on(hookName: string, handler: (...args: unknown[]) => unknown, options?: {
+    priority?: number;
+  }): void;
+  registerMemoryPromptSection(builder: (params: {
+    availableTools: Set<string>;
+  }) => string[]): void;
+}
+interface MemoryCloudPlugin {
+  id: string;
+  name: string;
+  description: string;
+  version: string;
+  kind: "memory";
+  register(api: PluginApi): void;
+}
+//#endregion
+//#region src/plugin.d.ts
+declare const plugin: MemoryCloudPlugin;
+//#endregion
+export { plugin as t };
+//# sourceMappingURL=plugin.d.ts.map