shabti 2.3.0 → 2.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "shabti",
-  "version": "2.3.0",
+  "version": "2.5.0",
   "description": "Agent Memory OS — semantic memory for AI agents",
   "type": "module",
   "main": "native.cjs",

package/src/a2a/agentCard.js

@@ -0,0 +1,48 @@
+import { readFileSync } from "fs";
+
+const { version } = JSON.parse(
+  readFileSync(new URL("../../package.json", import.meta.url), "utf8"),
+);
+
+export function buildAgentCard(baseUrl) {
+  return {
+    protocolVersion: "0.3.0",
+    name: "Shabti Memory Engine",
+    description: "A2A-compatible memory agent providing storage, search, and status operations",
+    url: baseUrl,
+    version,
+    capabilities: {
+      streaming: false,
+      pushNotifications: false,
+      stateTransitionHistory: false,
+    },
+    defaultInputModes: ["text", "application/json"],
+    defaultOutputModes: ["application/json"],
+    skills: [
+      {
+        id: "memory_store",
+        name: "Store Memory",
+        description: "Persist a memory entry with content and optional metadata tags",
+        tags: ["memory", "store", "save", "remember"],
+        inputModes: ["text", "application/json"],
+        outputModes: ["application/json"],
+      },
+      {
+        id: "memory_search",
+        name: "Search Memories",
+        description: "Search stored memories using semantic similarity queries",
+        tags: ["memory", "search", "recall", "find", "query"],
+        inputModes: ["text", "application/json"],
+        outputModes: ["application/json"],
+      },
+      {
+        id: "memory_status",
+        name: "Memory Status",
+        description: "Get status information about the memory engine",
+        tags: ["memory", "status", "health", "stats"],
+        inputModes: ["text"],
+        outputModes: ["application/json"],
+      },
+    ],
+  };
+}

package/src/a2a/server.js

@@ -0,0 +1,371 @@
+import { createServer } from "http";
+import { randomUUID } from "crypto";
+import { buildAgentCard } from "./agentCard.js";
+import { createEngine } from "../core/engine.js";
+
+// ============================================================
+// Task Store (in-memory)
+// ============================================================
+
+export class TaskStore {
+  constructor() {
+    this.tasks = new Map();
+  }
+
+  create(contextId) {
+    const task = {
+      kind: "task",
+      id: randomUUID(),
+      contextId: contextId || randomUUID(),
+      status: { state: "submitted", timestamp: new Date().toISOString() },
+      artifacts: [],
+      history: [],
+    };
+    this.tasks.set(task.id, task);
+    return task;
+  }
+
+  get(id) {
+    return this.tasks.get(id) || null;
+  }
+
+  set(id, task) {
+    this.tasks.set(id, task);
+  }
+
+  clear() {
+    this.tasks.clear();
+  }
+}
+
+// ============================================================
+// Skill Handlers
+// ============================================================
+
+async function handleMemoryStore(engine, parts) {
+  let content = null;
+  let opts = {};
+
+  for (const part of parts) {
+    if (part.kind === "data" && part.data) {
+      content = part.data.content || content;
+      if (part.data.namespace) opts.namespace = part.data.namespace;
+      if (part.data.tags) opts.tags = part.data.tags;
+      if (part.data.ttl) opts.ttlSeconds = part.data.ttl;
+    } else if (part.kind === "text" && part.text) {
+      content = content || part.text;
+    }
+  }
+
+  if (!content) {
+    throw Object.assign(new Error("Missing content in message parts"), { code: -32602 });
+  }
+
+  const result = await engine.store(content, opts);
+  return {
+    artifactId: randomUUID(),
+    name: "store_result",
+    parts: [{ kind: "data", data: { status: result.status, id: result.id || result.existingId } }],
+  };
+}
+
+async function handleMemorySearch(engine, parts) {
+  let query = null;
+  let limit = 10;
+
+  for (const part of parts) {
+    if (part.kind === "data" && part.data) {
+      query = part.data.query || query;
+      if (part.data.limit) limit = part.data.limit;
+    } else if (part.kind === "text" && part.text) {
+      query = query || part.text;
+    }
+  }
+
+  if (!query) {
+    throw Object.assign(new Error("Missing query in message parts"), { code: -32602 });
+  }
+
+  const results = await engine.executeQuery({ text: query, limit });
+  const formatted = results.map((r) => ({
+    id: r.id,
+    content: r.content,
+    score: r.score,
+    namespace: r.namespace,
+  }));
+
+  return {
+    artifactId: randomUUID(),
+    name: "search_results",
+    parts: [{ kind: "data", data: { query, results: formatted, count: formatted.length } }],
+  };
+}
+
+function handleMemoryStatus(engine) {
+  const status = engine.status();
+  return {
+    artifactId: randomUUID(),
+    name: "status",
+    parts: [
+      {
+        kind: "data",
+        data: {
+          status: "ok",
+          entry_count: status.entryCount,
+          tier: status.tier,
+          model_id: status.modelId,
+        },
+      },
+    ],
+  };
+}
+
+// ============================================================
+// Skill Router
+// ============================================================
+
+export function resolveSkill(parts) {
+  // Check for explicit skill in data parts
+  for (const part of parts) {
+    if (part.kind === "data" && part.data?.skill) {
+      return part.data.skill;
+    }
+  }
+
+  // Text-based routing
+  for (const part of parts) {
+    if (part.kind === "text" && part.text) {
+      const lower = part.text.toLowerCase();
+      if (/\b(store|save|remember)\b/.test(lower)) return "memory_store";
+      if (/\b(search|find|recall|query)\b/.test(lower)) return "memory_search";
+      if (/\b(status|health|stats|info)\b/.test(lower)) return "memory_status";
+    }
+  }
+
+  // Check for structured data that implies a skill
+  for (const part of parts) {
+    if (part.kind === "data" && part.data) {
+      if (part.data.content) return "memory_store";
+      if (part.data.query) return "memory_search";
+    }
+  }
+
+  return null;
+}
+
+// ============================================================
+// JSON-RPC Dispatcher (testable without HTTP)
+// ============================================================
+
+export async function dispatchRpc(engine, taskStore, method, params) {
+  switch (method) {
+    case "message/send":
+      return handleMessageSend(engine, taskStore, params || {});
+    case "tasks/get":
+      return handleTasksGet(taskStore, params || {});
+    case "tasks/cancel":
+      return handleTasksCancel(taskStore, params || {});
+    default:
+      return { error: { code: -32601, message: `Method not found: ${method}` } };
+  }
+}
+
+async function handleMessageSend(engine, taskStore, params) {
+  const message = params?.message;
+  if (!message || !message.parts || message.parts.length === 0) {
+    return { error: { code: -32602, message: "Missing message or parts" } };
+  }
+
+  const skill = resolveSkill(message.parts);
+  if (!skill) {
+    return {
+      error: { code: -32005, message: "Could not determine which skill to invoke from message" },
+    };
+  }
+
+  const task = taskStore.create(message.contextId);
+
+  // Store the incoming message in history
+  task.history.push(message);
+
+  try {
+    task.status = { state: "working", timestamp: new Date().toISOString() };
+
+    let artifact;
+    switch (skill) {
+      case "memory_store":
+        artifact = await handleMemoryStore(engine, message.parts);
+        break;
+      case "memory_search":
+        artifact = await handleMemorySearch(engine, message.parts);
+        break;
+      case "memory_status":
+        artifact = handleMemoryStatus(engine);
+        break;
+      default:
+        task.status = { state: "failed", timestamp: new Date().toISOString() };
+        taskStore.set(task.id, task);
+        return { error: { code: -32004, message: `Unknown skill: ${skill}` } };
+    }
+
+    task.artifacts = [artifact];
+    task.status = { state: "completed", timestamp: new Date().toISOString() };
+  } catch (err) {
+    task.status = {
+      state: "failed",
+      timestamp: new Date().toISOString(),
+      message: {
+        kind: "message",
+        role: "agent",
+        messageId: randomUUID(),
+        parts: [{ kind: "text", text: err.message }],
+      },
+    };
+    taskStore.set(task.id, task);
+    if (err.code) return { error: { code: err.code, message: err.message } };
+    return { error: { code: -32603, message: err.message } };
+  }
+
+  taskStore.set(task.id, task);
+  return { result: task };
+}
+
+function handleTasksGet(taskStore, params) {
+  const id = params?.id;
+  if (!id) return { error: { code: -32602, message: "Missing task id" } };
+
+  const task = taskStore.get(id);
+  if (!task) return { error: { code: -32001, message: `Task not found: ${id}` } };
+
+  // Apply historyLength filter
+  if (params.historyLength !== undefined) {
+    const result = { ...task };
+    const n = params.historyLength;
+    result.history = n === 0 ? [] : task.history.slice(-n);
+    return { result };
+  }
+
+  return { result: task };
+}
+
+function handleTasksCancel(taskStore, params) {
+  const id = params?.id;
+  if (!id) return { error: { code: -32602, message: "Missing task id" } };
+
+  const task = taskStore.get(id);
+  if (!task) return { error: { code: -32001, message: `Task not found: ${id}` } };
+
+  const terminal = ["completed", "failed", "canceled", "rejected"];
+  if (terminal.includes(task.status.state)) {
+    return {
+      error: { code: -32002, message: `Task is already in terminal state: ${task.status.state}` },
+    };
+  }
+
+  task.status = { state: "canceled", timestamp: new Date().toISOString() };
+  taskStore.set(task.id, task);
+  return { result: task };
+}
+
+// ============================================================
+// HTTP Server
+// ============================================================
+
+function readBody(req) {
+  return new Promise((resolve, reject) => {
+    const chunks = [];
+    req.on("data", (c) => chunks.push(c));
+    req.on("end", () => resolve(Buffer.concat(chunks).toString()));
+    req.on("error", reject);
+  });
+}
+
+export function startA2AServer(port = 3000) {
+  let engine = null;
+  let engineError = null;
+
+  function getEngine() {
+    if (engine) return engine;
+    if (engineError) throw engineError;
+    try {
+      engine = createEngine();
+    } catch (err) {
+      engineError = err;
+      throw err;
+    }
+    return engine;
+  }
+
+  const baseUrl = `http://localhost:${port}/`;
+  const agentCard = buildAgentCard(baseUrl);
+  const taskStore = new TaskStore();
+
+  const server = createServer(async (req, res) => {
+    // CORS headers
+    res.setHeader("Access-Control-Allow-Origin", "*");
+    res.setHeader("Access-Control-Allow-Methods", "GET, POST, OPTIONS");
+    res.setHeader("Access-Control-Allow-Headers", "Content-Type");
+
+    if (req.method === "OPTIONS") {
+      res.writeHead(204);
+      return res.end();
+    }
+
+    // Agent Card discovery
+    if (req.method === "GET" && req.url === "/.well-known/agent-card.json") {
+      res.writeHead(200, { "Content-Type": "application/json" });
+      return res.end(JSON.stringify(agentCard, null, 2));
+    }
+
+    // JSON-RPC endpoint
+    if (req.method === "POST" && (req.url === "/" || req.url === "")) {
+      let body;
+      try {
+        body = await readBody(req);
+      } catch {
+        res.writeHead(400);
+        return res.end();
+      }
+
+      let rpc;
+      try {
+        rpc = JSON.parse(body);
+      } catch {
+        res.writeHead(200, { "Content-Type": "application/json" });
+        return res.end(
+          JSON.stringify({
+            jsonrpc: "2.0",
+            id: null,
+            error: { code: -32700, message: "Parse error" },
+          }),
+        );
+      }
+
+      const { id, method, params } = rpc;
+      let response;
+
+      try {
+        response = await dispatchRpc(getEngine(), taskStore, method, params);
+      } catch (err) {
+        response = { error: { code: -32603, message: `Engine error: ${err.message}` } };
+      }
+
+      res.writeHead(200, { "Content-Type": "application/json" });
+      if (response.error) {
+        return res.end(JSON.stringify({ jsonrpc: "2.0", id, error: response.error }));
+      }
+      return res.end(JSON.stringify({ jsonrpc: "2.0", id, result: response.result }));
+    }
+
+    res.writeHead(404);
+    res.end("Not Found");
+  });
+
+  server.listen(port, "127.0.0.1", () => {
+    console.log(`\n  Shabti A2A server listening on ${baseUrl}`);
+    console.log(`  Agent Card: ${baseUrl}.well-known/agent-card.json`);
+    console.log(`  Skills: ${agentCard.skills.map((s) => s.id).join(", ")}\n`);
+  });
+
+  return server;
+}

package/src/a2a/standalone.js

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+/**
+ * Standalone A2A server entry point.
+ * Used by tests and `shabti a2a` CLI command.
+ */
+import { startA2AServer } from "./server.js";
+
+const port = parseInt(process.env.SHABTI_A2A_PORT || "3000", 10);
+startA2AServer(port);

package/src/commands/a2a.js

@@ -0,0 +1,12 @@
+import { startA2AServer } from "../a2a/server.js";
+
+export function registerA2A(program) {
+  program
+    .command("a2a")
+    .description("Start the A2A (Agent-to-Agent) protocol server")
+    .option("-p, --port <port>", "Port to listen on", "3000")
+    .action((opts) => {
+      const port = parseInt(opts.port, 10);
+      startA2AServer(port);
+    });
+}

package/src/commands/export.js

@@ -0,0 +1,44 @@
+import { writeFileSync } from "fs";
+import { createEngine } from "../core/engine.js";
+import { success, error } from "../utils/style.js";
+
+export function registerExport(program) {
+  program
+    .command("export")
+    .description("Export memory entries as JSONL")
+    .option("-n, --namespace <ns>", "Filter by namespace")
+    .option("--no-embeddings", "Exclude embedding vectors from output")
+    .option("-o, --output <file>", "Write to file instead of stdout")
+    .option("--limit <n>", "Maximum number of entries to export")
+    .action(async (opts) => {
+      try {
+        const engine = createEngine();
+        const listOpts = {};
+        if (opts.namespace) listOpts.namespace = opts.namespace;
+        if (opts.limit) listOpts.limit = parseInt(opts.limit, 10);
+        listOpts.includeEmbeddings = opts.embeddings !== false ? false : false;
+        // --no-embeddings sets opts.embeddings = false (commander negatable)
+        // default: exclude embeddings for smaller output
+        listOpts.includeEmbeddings = opts.embeddings === true;
+
+        const entries = engine.listEntries(listOpts);
+
+        const lines = entries.map((e) => JSON.stringify(e));
+        const output = lines.join("\n");
+
+        if (opts.output) {
+          writeFileSync(opts.output, output + (lines.length ? "\n" : ""), "utf8");
+          success(`Exported ${entries.length} entries to ${opts.output}`);
+        } else {
+          if (output) console.log(output);
+          // Print summary to stderr so it doesn't pollute piped output
+          process.stderr.write(`\n${entries.length} entries exported\n`);
+        }
+
+        await engine.shutdown();
+      } catch (err) {
+        error(err.message);
+        process.exitCode = 1;
+      }
+    });
+}

package/src/commands/import.js

@@ -0,0 +1,66 @@
+import { readFileSync } from "fs";
+import { createEngine } from "../core/engine.js";
+import { success, error, info, warn } from "../utils/style.js";
+
+export function registerImport(program) {
+  program
+    .command("import")
+    .description("Import memory entries from a JSONL file")
+    .argument("<file>", "Path to JSONL file")
+    .option("-n, --namespace <ns>", "Override namespace for all imported entries")
+    .option("--dry-run", "Parse and validate without storing")
+    .action(async (file, opts) => {
+      try {
+        const raw = readFileSync(file, "utf8");
+        const lines = raw
+          .split("\n")
+          .map((l) => l.trim())
+          .filter((l) => l.length > 0);
+
+        if (lines.length === 0) {
+          info("No entries found in file.");
+          return;
+        }
+
+        // Parse all lines first to validate
+        const entries = [];
+        for (let i = 0; i < lines.length; i++) {
+          try {
+            entries.push(JSON.parse(lines[i]));
+          } catch {
+            warn(`Skipping invalid JSON on line ${i + 1}`);
+          }
+        }
+
+        if (opts.dryRun) {
+          info(`Dry run: ${entries.length} entries parsed, 0 stored.`);
+          return;
+        }
+
+        const engine = createEngine();
+        let stored = 0;
+        let skipped = 0;
+
+        for (const entry of entries) {
+          const storeOpts = {};
+          storeOpts.namespace = opts.namespace || entry.namespace || undefined;
+          if (entry.tags && entry.tags.length) storeOpts.tags = entry.tags;
+          if (entry.sessionId || entry.session_id)
+            storeOpts.sessionId = entry.sessionId || entry.session_id;
+
+          const result = await engine.store(entry.content, storeOpts);
+          if (result.status === "stored") {
+            stored++;
+          } else {
+            skipped++;
+          }
+        }
+
+        success(`Import complete: ${stored} stored, ${skipped} skipped (duplicates)`);
+        await engine.shutdown();
+      } catch (err) {
+        error(err.message);
+        process.exitCode = 1;
+      }
+    });
+}

package/src/index.js

@@ -3,6 +3,7 @@
 import { readFileSync } from "fs";
 import chalk from "chalk";
 import { Command } from "commander";
+import { registerA2A } from "./commands/a2a.js";
 import { registerChat } from "./commands/chat.js";
 import { registerConfig } from "./commands/config.js";
 import { registerHello } from "./commands/hello.js";
@@ -11,6 +12,8 @@ import { registerSearch } from "./commands/search.js";
 import { registerSnapshot } from "./commands/snapshot.js";
 import { registerSpin } from "./commands/spin.js";
 import { registerStatus } from "./commands/status.js";
+import { registerExport } from "./commands/export.js";
+import { registerImport } from "./commands/import.js";
 import { registerStore } from "./commands/store.js";
 
 const { version } = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
@@ -69,6 +72,7 @@ function buildProgram() {
     .name("shabti")
     .description("Agent Memory OS — semantic memory for AI agents")
     .version(version);
+  registerA2A(program);
   registerChat(program);
   registerConfig(program);
   registerHello(program);
@@ -77,6 +81,8 @@ function buildProgram() {
   registerSnapshot(program);
   registerSpin(program);
   registerStatus(program);
+  registerExport(program);
+  registerImport(program);
   registerStore(program);
 
   program

package/src/mcp/server.js

@@ -73,6 +73,17 @@ const TOOLS = [
       },
     },
   },
+  {
+    name: "memory_export",
+    description: "Export all memory entries as a JSONL array",
+    inputSchema: {
+      type: "object",
+      properties: {
+        namespace: { type: "string", description: "Filter by namespace" },
+        limit: { type: "integer", description: "Maximum entries to export" },
+      },
+    },
+  },
   {
     name: "memory_gc",
     description: "Garbage collect expired memory entries (removes entries past their TTL)",
@@ -306,6 +317,29 @@ async function handleToolsCall(id, params) {
     }
   }
 
+  if (name === "memory_export") {
+    if (!eng) {
+      return respondError(id, -32603, "Engine not available");
+    }
+    try {
+      const listOpts = {};
+      if (args?.namespace) listOpts.namespace = args.namespace;
+      if (args?.limit) listOpts.limit = args.limit;
+      const entries = eng.listEntries(listOpts);
+      const lines = entries.map((e) => JSON.stringify(e));
+      return respond(id, {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify({ entries: entries.length, data: lines.join("\n") }, null, 2),
+          },
+        ],
+      });
+    } catch (err) {
+      return respondError(id, -32603, err.message);
+    }
+  }
+
   if (name === "memory_gc") {
     if (!eng) {
       return respondError(id, -32603, "Engine not available");