supipowers 1.5.2 → 2.0.0

package/src/mempalace/schema.ts

@@ -0,0 +1,264 @@
+export const MEMPALACE_ACTIONS = [
+  "status",
+  "list_wings",
+  "list_rooms",
+  "get_taxonomy",
+  "search",
+  "check_duplicate",
+  "get_aaak_spec",
+  "get_drawer",
+  "list_drawers",
+  "add_drawer",
+  "update_drawer",
+  "delete_drawer",
+  "kg_query",
+  "kg_add",
+  "kg_invalidate",
+  "kg_timeline",
+  "kg_stats",
+  "traverse",
+  "find_tunnels",
+  "graph_stats",
+  "create_tunnel",
+  "list_tunnels",
+  "delete_tunnel",
+  "follow_tunnels",
+  "diary_write",
+  "diary_read",
+  "hook_settings",
+  "memories_filed_away",
+  "reconnect",
+  "setup",
+  "version",
+  "init",
+  "mine",
+  "split",
+  "repair",
+  "wake_up",
+] as const;
+
+export type MempalaceAction = typeof MEMPALACE_ACTIONS[number];
+
+export interface MempalaceParams {
+  action: MempalaceAction;
+  palace?: string;
+  wing?: string;
+  room?: string;
+  query?: string;
+  limit?: number;
+  offset?: number;
+  drawer_id?: string;
+  content?: string;
+  source_file?: string;
+  added_by?: string;
+  subject?: string;
+  predicate?: string;
+  object?: string;
+  valid_from?: string;
+  valid_to?: string;
+  ended?: boolean;
+  as_of?: string;
+  direction?: string;
+  start_room?: string;
+  max_hops?: number;
+  source_wing?: string;
+  source_room?: string;
+  target_wing?: string;
+  target_room?: string;
+  label?: string;
+  tunnel_id?: string;
+  agent_name?: string;
+  entry?: string;
+  topic?: string;
+  dir?: string;
+  mode?: string;
+  extract?: boolean;
+  dry_run?: boolean;
+  include_ignored?: boolean;
+  no_gitignore?: boolean;
+  yes?: boolean;
+  timeout?: number;
+}
+
+export interface MempalaceValidationResult {
+  valid: boolean;
+  errors: string[];
+  params?: MempalaceParams;
+}
+
+const STRING_FIELDS = [
+  "palace",
+  "wing",
+  "room",
+  "query",
+  "drawer_id",
+  "content",
+  "source_file",
+  "added_by",
+  "subject",
+  "predicate",
+  "object",
+  "valid_from",
+  "valid_to",
+  "as_of",
+  "direction",
+  "start_room",
+  "source_wing",
+  "source_room",
+  "target_wing",
+  "target_room",
+  "label",
+  "tunnel_id",
+  "agent_name",
+  "entry",
+  "topic",
+  "dir",
+  "mode",
+] as const;
+
+const POSITIVE_INTEGER_FIELDS = ["limit", "max_hops", "timeout"] as const;
+const NON_NEGATIVE_INTEGER_FIELDS = ["offset"] as const;
+const BOOLEAN_FIELDS = ["ended", "extract", "dry_run", "include_ignored", "no_gitignore", "yes"] as const;
+
+const REQUIRED_FIELDS: Partial<Record<MempalaceAction, readonly (keyof MempalaceParams)[]>> = {
+  search: ["query"],
+  check_duplicate: ["content"],
+  get_drawer: ["drawer_id"],
+  list_drawers: ["wing"],
+  add_drawer: ["content"],
+  update_drawer: ["drawer_id", "content"],
+  delete_drawer: ["drawer_id"],
+  kg_query: ["subject"],
+  kg_add: ["subject", "predicate", "object"],
+  kg_invalidate: ["subject", "predicate"],
+  kg_timeline: ["subject"],
+  traverse: ["start_room"],
+  find_tunnels: ["source_wing", "source_room"],
+  create_tunnel: ["source_wing", "source_room", "target_wing", "target_room", "label"],
+  delete_tunnel: ["tunnel_id"],
+  follow_tunnels: ["source_wing", "source_room"],
+  diary_write: ["entry"],
+  init: ["dir"],
+  mine: ["dir"],
+  split: ["source_file"],
+  repair: ["dir"],
+};
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+export function isMempalaceAction(action: unknown): action is MempalaceAction {
+  return typeof action === "string" && (MEMPALACE_ACTIONS as readonly string[]).includes(action);
+}
+
+function isNonEmptyString(value: unknown): value is string {
+  return typeof value === "string" && value.trim().length > 0;
+}
+
+export const mempalaceToolParameters = {
+  type: "object",
+  additionalProperties: false,
+  properties: {
+    action: {
+      type: "string",
+      enum: MEMPALACE_ACTIONS,
+      description: "Action to dispatch.",
+    },
+    palace: { type: "string" },
+    wing: { type: "string" },
+    room: { type: "string" },
+    query: { type: "string" },
+    limit: { type: "integer", minimum: 1 },
+    offset: { type: "integer", minimum: 0 },
+    drawer_id: { type: "string" },
+    content: { type: "string" },
+    source_file: { type: "string" },
+    added_by: { type: "string" },
+    subject: { type: "string" },
+    predicate: { type: "string" },
+    object: { type: "string" },
+    valid_from: { type: "string" },
+    valid_to: { type: "string" },
+    ended: { type: "boolean" },
+    as_of: { type: "string" },
+    direction: { type: "string" },
+    start_room: { type: "string" },
+    max_hops: { type: "integer", minimum: 1 },
+    source_wing: { type: "string" },
+    source_room: { type: "string" },
+    target_wing: { type: "string" },
+    target_room: { type: "string" },
+    label: { type: "string" },
+    tunnel_id: { type: "string" },
+    agent_name: { type: "string" },
+    entry: { type: "string" },
+    topic: { type: "string" },
+    dir: { type: "string" },
+    mode: { type: "string" },
+    extract: { type: "boolean" },
+    dry_run: { type: "boolean" },
+    include_ignored: { type: "boolean" },
+    no_gitignore: { type: "boolean" },
+    yes: { type: "boolean" },
+    timeout: { type: "integer", minimum: 1 },
+  },
+  required: ["action"],
+} as const;
+
+export function validateMempalaceParams(params: unknown): MempalaceValidationResult {
+  if (!isRecord(params)) {
+    return { valid: false, errors: ["params must be an object"] };
+  }
+
+  const errors: string[] = [];
+  const action = params.action;
+  if (!isMempalaceAction(action)) {
+    errors.push(
+      action === undefined
+        ? "action is required"
+        : "action must be one of the supported MemPalace actions",
+    );
+    return { valid: false, errors };
+  }
+
+  for (const field of STRING_FIELDS) {
+    const value = params[field];
+    if (value !== undefined && typeof value !== "string") {
+      errors.push(`${field} must be a string`);
+    }
+  }
+
+  for (const field of BOOLEAN_FIELDS) {
+    const value = params[field];
+    if (value !== undefined && typeof value !== "boolean") {
+      errors.push(`${field} must be a boolean`);
+    }
+  }
+
+  for (const field of POSITIVE_INTEGER_FIELDS) {
+    const value = params[field];
+    if (value !== undefined && (typeof value !== "number" || !Number.isInteger(value) || value < 1)) {
+      errors.push(`${field} must be a positive integer`);
+    }
+  }
+
+  for (const field of NON_NEGATIVE_INTEGER_FIELDS) {
+    const value = params[field];
+    if (value !== undefined && (typeof value !== "number" || !Number.isInteger(value) || value < 0)) {
+      errors.push(`${field} must be a non-negative integer`);
+    }
+  }
+
+  for (const field of REQUIRED_FIELDS[action] ?? []) {
+    if (!isNonEmptyString(params[field])) {
+      errors.push(`${field} is required for action ${action}`);
+    }
+  }
+
+  if (errors.length > 0) {
+    return { valid: false, errors };
+  }
+
+  return { valid: true, errors: [], params: params as unknown as MempalaceParams };
+}

package/src/mempalace/session-summary.ts

@@ -0,0 +1,198 @@
+import type { EventStore, TrackedEvent } from "../context-mode/event-store.js";
+import { buildResumeSnapshot } from "../context-mode/snapshot-builder.js";
+
+export interface SessionSummaryOptions {
+  cwd: string;
+  sessionId: string;
+  wing: string;
+  defaultAgentName: string;
+  now?: string;
+  eventStore?: Pick<EventStore, "getEventCounts" | "getEvents"> | null;
+  sessionManager?: { getBranch?: () => unknown[] } | null;
+  maxChars?: number;
+}
+
+export interface CompactionCheckpoint {
+  content: string;
+  metadata: {
+    wing: string;
+    room: "compaction-checkpoints";
+    added_by: string;
+    source_file: string;
+  };
+}
+
+export interface ShutdownDiary {
+  entry: string;
+  metadata: {
+    agent_name: string;
+    wing: string;
+    topic: "shutdown";
+    timestamp: string;
+    source_file: string;
+  };
+}
+
+const DEFAULT_MAX_CHARS = 8000;
+const EVENT_CATEGORIES = ["decision", "task", "intent", "rule"] as const;
+
+function truncate(text: string, maxChars: number): string {
+  return text.length <= maxChars ? text : `${text.slice(0, Math.max(0, maxChars - 1)).trimEnd()}…`;
+}
+
+function safeParse(data: string): Record<string, unknown> | null {
+  try {
+    const parsed = JSON.parse(data);
+    return typeof parsed === "object" && parsed !== null && !Array.isArray(parsed) ? parsed as Record<string, unknown> : null;
+  } catch {
+    return null;
+  }
+}
+
+function summarizeTask(data: Record<string, unknown>): string | null {
+  const input = data.input as Record<string, unknown> | undefined;
+  const ops = Array.isArray(input?.ops) ? input.ops as Array<Record<string, unknown>> : [];
+  const parts = ops.map((op) => {
+    const verb = typeof op.op === "string" ? op.op : "";
+    const target = typeof op.task === "string" ? op.task : typeof op.phase === "string" ? op.phase : "";
+    return [verb, target].filter(Boolean).join(": ");
+  }).filter(Boolean);
+  return parts.length > 0 ? parts.join("; ") : JSON.stringify(data).slice(0, 240);
+}
+
+function summarizeEvent(event: TrackedEvent): string | null {
+  const data = safeParse(event.data);
+  if (!data) return null;
+  if (event.category === "decision") {
+    const prompt = typeof data.prompt === "string" ? data.prompt.trim() : "";
+    return prompt ? `decision: ${prompt}` : null;
+  }
+  if (event.category === "task") {
+    const summary = summarizeTask(data);
+    return summary ? `task: ${summary}` : null;
+  }
+  if (event.category === "intent") {
+    const intent = typeof data.intent === "string" ? data.intent : "intent";
+    const prompt = typeof data.prompt === "string" ? data.prompt : "";
+    return `intent ${intent}: ${prompt}`.trim();
+  }
+  if (event.category === "rule") {
+    const path = typeof data.path === "string" ? data.path : typeof data.file === "string" ? data.file : "";
+    return path ? `rule loaded: ${path}` : null;
+  }
+  return null;
+}
+
+function eventStoreSection(options: SessionSummaryOptions): string | null {
+  const eventStore = options.eventStore;
+  if (!eventStore) return null;
+
+  let snapshot = "";
+  try {
+    snapshot = buildResumeSnapshot(eventStore as EventStore, options.sessionId);
+  } catch {
+    snapshot = "";
+  }
+
+  const lines: string[] = [];
+  try {
+    const events = eventStore.getEvents(options.sessionId, { categories: [...EVENT_CATEGORIES], limit: 40 });
+    for (const event of events) {
+      const summary = summarizeEvent(event as TrackedEvent);
+      if (summary) lines.push(`- ${summary}`);
+    }
+  } catch {
+    // fall through to snapshot-only or later fallbacks
+  }
+
+  if (!snapshot && lines.length === 0) return null;
+  return [
+    "Event-store summary",
+    snapshot,
+    ...lines,
+  ].filter(Boolean).join("\n");
+}
+
+function branchText(entry: unknown): string | null {
+  if (typeof entry === "string") return entry;
+  if (typeof entry !== "object" || entry === null) return null;
+  const record = entry as Record<string, unknown>;
+  const role = typeof record.role === "string" ? record.role : "entry";
+  const content = record.content;
+  let text = "";
+  if (typeof content === "string") {
+    text = content;
+  } else if (Array.isArray(content)) {
+    text = content
+      .map((part) => typeof part === "object" && part !== null && typeof (part as { text?: unknown }).text === "string" ? (part as { text: string }).text : "")
+      .filter(Boolean)
+      .join("\n");
+  }
+  return text ? `${role}: ${text}` : null;
+}
+
+function sessionManagerSection(options: SessionSummaryOptions): string | null {
+  try {
+    const branch = options.sessionManager?.getBranch?.();
+    if (!Array.isArray(branch) || branch.length === 0) return null;
+    const lines = branch.map(branchText).filter((line): line is string => Boolean(line)).slice(-10);
+    return lines.length > 0 ? ["Session branch fallback", ...lines.map((line) => `- ${line}`)].join("\n") : null;
+  } catch {
+    return null;
+  }
+}
+
+function fallbackSection(reason: "compaction" | "shutdown", options: SessionSummaryOptions, now: string): string {
+  return [
+    `timestamp: ${now}`,
+    `cwd: ${options.cwd}`,
+    `wing: ${options.wing}`,
+    `session: ${options.sessionId}`,
+    `reason: ${reason}`,
+    "Structured session data unavailable.",
+  ].join("\n");
+}
+
+function buildBody(title: string, reason: "compaction" | "shutdown", options: SessionSummaryOptions): { body: string; now: string } {
+  const now = options.now ?? new Date().toISOString();
+  const source = eventStoreSection(options)
+    ?? sessionManagerSection(options)
+    ?? fallbackSection(reason, options, now);
+  const body = [
+    `# ${title}`,
+    `generated_at: ${now}`,
+    `cwd: ${options.cwd}`,
+    `wing: ${options.wing}`,
+    `session_id: ${options.sessionId}`,
+    "",
+    source,
+  ].join("\n");
+  return { body: truncate(body, options.maxChars ?? DEFAULT_MAX_CHARS), now };
+}
+
+export function buildCompactionCheckpoint(options: SessionSummaryOptions): CompactionCheckpoint {
+  const { body, now } = buildBody("MemPalace compaction checkpoint", "compaction", options);
+  return {
+    content: body,
+    metadata: {
+      wing: options.wing,
+      room: "compaction-checkpoints",
+      added_by: options.defaultAgentName,
+      source_file: `omp-session:${options.sessionId}:compaction:${now}`,
+    },
+  };
+}
+
+export function buildShutdownDiary(options: SessionSummaryOptions): ShutdownDiary {
+  const { body, now } = buildBody("MemPalace shutdown diary", "shutdown", options);
+  return {
+    entry: body,
+    metadata: {
+      agent_name: options.defaultAgentName,
+      wing: options.wing,
+      topic: "shutdown",
+      timestamp: now,
+      source_file: `omp-session:${options.sessionId}:shutdown:${now}`,
+    },
+  };
+}

package/src/mempalace/tool.ts

@@ -0,0 +1,186 @@
+import type { Platform } from "../platform/types.js";
+import type { SupipowersConfig } from "../types.js";
+import { createMempalaceBridge, type MempalaceBridgeFacade } from "./bridge.js";
+import { resolveMempalaceConfig, type ResolvedMempalaceConfig } from "./config.js";
+import { formatMempalaceError, formatMempalaceResult } from "./format.js";
+import { mempalaceToolParameters, validateMempalaceParams, type MempalaceParams } from "./schema.js";
+import {
+  resolveBridgeScriptPath,
+  setupMempalaceRuntime,
+  type BridgePathResult,
+  type SetupMempalaceRuntimeOptions,
+  type SetupMempalaceRuntimeResult,
+} from "./runtime.js";
+import {
+  snapshotMempalaceInstall,
+  type MempalaceInstallSnapshot,
+} from "./installer-helper.js";
+
+export interface MempalaceToolDeps {
+  createBridge?: (config: ResolvedMempalaceConfig, cwd: string) => MempalaceBridgeFacade;
+  resolveBridgeScriptPath?: () => BridgePathResult;
+  setupRuntime?: (options: SetupMempalaceRuntimeOptions) => Promise<SetupMempalaceRuntimeResult>;
+  /**
+   * Installation readiness probe. Default reads the filesystem; tests can inject
+   * a stub. The tool is registered only when this returns `ready: true`.
+   */
+  snapshotInstall?: (config: SupipowersConfig, cwd: string) => MempalaceInstallSnapshot;
+}
+
+function toolResult(text: string, details: Record<string, unknown>): { content: Array<{ type: "text"; text: string }>; details: Record<string, unknown> } {
+  return { content: [{ type: "text", text }], details };
+}
+
+function readCwd(toolCtx: unknown): string {
+  if (typeof toolCtx === "object" && toolCtx !== null && typeof (toolCtx as { cwd?: unknown }).cwd === "string") {
+    return (toolCtx as { cwd: string }).cwd;
+  }
+  return process.cwd();
+}
+
+function emitProgress(onUpdate: unknown, text: string): void {
+  if (typeof onUpdate !== "function") return;
+  // OMP's tool runtime treats the value passed to onUpdate as a partial tool
+  // result. It iterates `partialResult.content.map(...)`, so we must pass a
+  // shape that mirrors the final `{ content: [...] }` return.
+  try {
+    onUpdate({ content: [{ type: "text", text }] });
+  } catch {
+    // best effort — never let a progress notification kill the tool call
+  }
+}
+
+async function executeSetup(
+  params: MempalaceParams,
+  resolved: ResolvedMempalaceConfig,
+  cwd: string,
+  managedBinDir: string,
+  deps: MempalaceToolDeps,
+  onUpdate: unknown,
+): Promise<{ content: Array<{ type: "text"; text: string }>; details: Record<string, unknown> }> {
+  const bridgePath = (deps.resolveBridgeScriptPath ?? resolveBridgeScriptPath)();
+  if (!bridgePath.ok) {
+    const formatted = formatMempalaceError(bridgePath.error, {
+      ok: false,
+      action: params.action,
+      bridgeScriptPath: bridgePath.path,
+    });
+    return toolResult(formatted.text, formatted.details as Record<string, unknown>);
+  }
+
+  const setup = await (deps.setupRuntime ?? setupMempalaceRuntime)({
+    cwd,
+    config: resolved,
+    bridgeScriptPath: bridgePath.path,
+    managedBinDir,
+    onProgress: (message) => emitProgress(onUpdate, message),
+  });
+
+  if (!setup.ok) {
+    const formatted = formatMempalaceError(setup.error, {
+      ok: false,
+      action: "setup",
+      stderrTail: setup.stderrTail,
+    });
+    return toolResult(formatted.text, formatted.details as Record<string, unknown>);
+  }
+
+  const formatted = formatMempalaceResult(
+    "setup",
+    { message: "setup complete", ...setup.details },
+    resolved.budgets,
+  );
+  return toolResult(formatted.text, {
+    ok: true,
+    action: "setup",
+    setup: setup.details,
+  });
+}
+
+export function registerMempalaceTool(
+  platform: Platform,
+  config: SupipowersConfig,
+  deps: MempalaceToolDeps = {},
+): void {
+  if (!config.mempalace.enabled) return;
+  if (typeof platform.registerTool !== "function") return;
+
+  // Gate exposure on installation readiness. Without uv + the managed venv +
+  // the Python bridge script all present, every action fails — surfacing a
+  // dead tool in the agent's catalog only invites broken tool calls. Setup is
+  // driven explicitly by `/supi:memory setup`, so this gate is recoverable.
+  const snapshotFn = deps.snapshotInstall ?? ((cfg, cwd) => snapshotMempalaceInstall(platform.paths, cwd, cfg));
+  let snapshot: MempalaceInstallSnapshot;
+  try {
+    snapshot = snapshotFn(config, process.cwd());
+  } catch (error) {
+    (platform as { logger?: { warn?: (message: string, error?: unknown) => void } }).logger?.warn?.(
+      "supi-mempalace: install snapshot failed; tool will not be registered",
+      error,
+    );
+    return;
+  }
+  if (!snapshot.ready) return;
+
+  platform.registerTool({
+    name: "mempalace",
+    label: "MemPalace",
+    description:
+      "MemPalace memory dispatcher. **MUST** call `search` before answering past-fact questions; write only on explicit user request.",
+    parameters: mempalaceToolParameters,
+    async execute(_toolCallId: string, rawParams: unknown, _signal: AbortSignal, onUpdate: unknown, toolCtx: unknown) {
+      try {
+        const validation = validateMempalaceParams(rawParams);
+        if (!validation.valid || !validation.params) {
+          return toolResult(`MemPalace validation failed:\n${validation.errors.map((error) => `- ${error}`).join("\n")}`, {
+            ok: false,
+            errors: validation.errors,
+          });
+        }
+
+        const cwd = readCwd(toolCtx);
+        const resolved = resolveMempalaceConfig(config, cwd, platform.paths);
+        const params = validation.params;
+
+        if (params.action === "setup") {
+          return await executeSetup(params, resolved, cwd, platform.paths.global("bin"), deps, onUpdate);
+        }
+
+        const bridge = deps.createBridge
+          ? deps.createBridge(resolved, cwd)
+          : createMempalaceBridge({ cwd, config: resolved });
+        const result = await bridge.execute(params);
+
+        if (!result.ok) {
+          const formatted = formatMempalaceError(result.error, {
+            ok: false,
+            action: result.action,
+            diagnostics: result.diagnostics,
+          });
+          return toolResult(formatted.text, {
+            ok: false,
+            action: result.action,
+            error: result.error,
+            diagnostics: result.diagnostics,
+          });
+        }
+
+        const formatted = formatMempalaceResult(result.action, result.result, resolved.budgets);
+        return toolResult(formatted.text, {
+          ok: true,
+          action: result.action,
+          result: result.result,
+          diagnostics: result.diagnostics,
+          formattedDetails: formatted.details,
+        });
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        const stack = error instanceof Error ? error.stack : undefined;
+        return toolResult(
+          `MemPalace tool crashed: ${message}`,
+          { ok: false, error: { code: "tool_crash", message, stack } },
+        );
+      }
+    },
+  });
+}