loom-claw 0.1.0

package/index.ts

@@ -0,0 +1,1164 @@
+/**
+ * loom-claw — Loom cognitive memory as an OpenClaw Context Engine plugin.
+ *
+ * Connects OpenClaw to a running Loom Python backend for structured
+ * schema-based long-term memory. Registers:
+ *   - A Context Engine (assemble/afterTurn lifecycle)
+ *   - Agent tools (loom_inspect, loom_build, loom_forget, loom_update)
+ *   - Slash commands (/loom status|inspect|forget|reset|templates|config)
+ */
+
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
+import { Type } from "@sinclair/typebox";
+import { LoomContextEngine } from "./src/engine.js";
+import { LoomClient } from "./src/client.js";
+import { resolveConfig } from "./src/config.js";
+import type { LoomPluginConfig } from "./src/types.js";
+
+/** Telegram messages are capped at ~4096 chars; leave buffer for formatting. */
+const INSPECT_MAX_LENGTH = 3500;
+
+/** Helper: wrap a text string into AgentToolResult format. */
+function textToolResult(text: string) {
+  return {
+    content: [{ type: "text" as const, text }],
+    details: { text },
+  };
+}
+
+function extractPluginConfig(api: OpenClawPluginApi): LoomPluginConfig {
+  const fullConfig = api.config as Record<string, unknown>;
+  const plugins = fullConfig?.plugins as Record<string, unknown> | undefined;
+  const entries = plugins?.entries as Record<string, Record<string, unknown>> | undefined;
+  const entry = entries?.["loom-claw"];
+  if (entry) {
+    return resolveConfig(process.env, {
+      ...((entry.config as Record<string, unknown>) || {}),
+      enabled: entry.enabled,
+    });
+  }
+  return resolveConfig(process.env, {});
+}
+
+const loomPlugin = {
+  id: "loom-claw",
+  name: "Loom Cognitive Memory",
+  description:
+    "Connects OpenClaw to a Loom backend for structured schema-based long-term memory. " +
+    "The Loom CM agent automatically extracts key information from conversations " +
+    "into structured schemas, then injects relevant data back into the model context.",
+
+  configSchema: {
+    parse(value: unknown): LoomPluginConfig {
+      const raw =
+        value && typeof value === "object" && !Array.isArray(value)
+          ? (value as Record<string, unknown>)
+          : {};
+      return resolveConfig(process.env, raw);
+    },
+  },
+
+  register(api: OpenClawPluginApi) {
+    const config = extractPluginConfig(api);
+
+    if (!config.enabled) {
+      api.logger.info("[loom-claw] Plugin disabled via config");
+      return;
+    }
+
+    const engine = new LoomContextEngine(config, api.logger);
+
+    api.registerContextEngine("loom-claw", () => engine);
+
+    // -- Agent tools --
+    api.registerTool(() => createLoomInspectTool(engine), { name: "loom_inspect" });
+    api.registerTool(() => createLoomBuildTool(engine), { name: "loom_build" });
+    api.registerTool(() => createLoomForgetTool(engine), { name: "loom_forget" });
+    api.registerTool(() => createLoomUpdateTool(engine), { name: "loom_update" });
+
+    // -- Slash commands --
+    api.registerCommand({
+      name: "loom",
+      description: "Loom memory management — /loom help for all commands",
+      acceptsArgs: true,
+      requireAuth: true,
+      handler: createLoomCommandHandler(engine),
+    });
+
+    api.logger.info(
+      `[loom-claw] Plugin loaded (backend=${config.loomBaseUrl}, ` +
+        `schema=${config.schemaId}, buildEvery=${config.buildEveryNTurns} turns)`,
+    );
+  },
+};
+
+export default loomPlugin;
+
+// ---------------------------------------------------------------------------
+// Slash command handler
+// ---------------------------------------------------------------------------
+
+function createLoomCommandHandler(engine: LoomContextEngine) {
+  return async (ctx: { args?: string }) => {
+    const client = engine.getClient();
+    const cfg = engine.getConfig();
+    const args = (ctx.args || "").trim();
+    const [subcommand, ...rest] = args.split(/\s+/);
+    const subArgs = rest.join(" ").trim();
+
+    if (!engine.isReachable()) {
+      const ok = await client.ping();
+      if (ok) engine.setReachable(true);
+    }
+
+    if (!engine.isReachable()) {
+      return {
+        text: `⚠️ Loom backend unreachable (${cfg.loomBaseUrl})\nMake sure the Loom service is running.`,
+      };
+    }
+
+    switch (subcommand.toLowerCase()) {
+      case "status":
+      case "": {
+        try {
+          const schemas = await client.listSchemas();
+          const sessions = await client.listSessions();
+          const lines = [
+            "🧠 **Loom status**",
+            `- Backend: ${cfg.loomBaseUrl} ✅`,
+            `- Schema ID: \`${cfg.schemaId}\``,
+            `- Session ID: \`${engine.getLoomSessionId()}\``,
+            `- Schema domains: ${schemas.length ? schemas.join(", ") : "(empty)"}`,
+            `- Sessions: ${sessions.length}`,
+            `- Auto-extract: every ${cfg.buildEveryNTurns} turn(s)`,
+          ];
+          return { text: lines.join("\n") };
+        } catch (e) {
+          return { text: `❌ Failed to get status: ${e}` };
+        }
+      }
+
+      case "inspect": {
+        try {
+          const fullResult = await client.inspectAll(cfg.schemaId, true, -1);
+          const fullText = fullResult.text || "";
+
+          if (!fullText) {
+            return { text: "📭 Memory is empty" };
+          }
+
+          if (fullText.length <= INSPECT_MAX_LENGTH) {
+            return { text: fullText };
+          }
+
+          const summaryResult = await client.inspectAll(cfg.schemaId, false, -1);
+          const summaryText = summaryResult.text || "";
+          const lines = [
+            "⚠️ Memory content is long; showing structure summary only:",
+            "",
+            summaryText,
+            "",
+            `💡 Full content is ${fullText.length} characters`,
+          ];
+          let text = lines.join("\n");
+          if (text.length > INSPECT_MAX_LENGTH) {
+            text = text.slice(0, INSPECT_MAX_LENGTH) + "\n\n… (truncated)";
+          }
+          return { text };
+        } catch (e) {
+          return { text: `❌ inspect failed: ${e}` };
+        }
+      }
+
+      case "forget": {
+        if (!subArgs) {
+          return {
+            text: "Usage: `/loom forget <domain>` or `/loom forget --all`\nExample: `/loom forget identity`",
+          };
+        }
+        try {
+          if (subArgs === "--all") {
+            const result = await client.clearAllSchemas(cfg.schemaId);
+            return { text: `🗑️ Cleared all schemas (${result.count} domain(s))` };
+          }
+          await client.deleteSchema(subArgs, cfg.schemaId);
+          return { text: `🗑️ Deleted domain: \`${subArgs}\`` };
+        } catch (e) {
+          return { text: `❌ forget failed: ${e}` };
+        }
+      }
+
+      case "reset": {
+        try {
+          const result = await client.newSchema(engine.getLoomSessionId());
+          const msg = result.backup_id
+            ? `🔄 Schema reset (backup: ${result.backup_id})`
+            : "🔄 Schema reset";
+          return { text: msg };
+        } catch (e) {
+          return { text: `❌ reset failed: ${e}` };
+        }
+      }
+
+      case "new": {
+        const newName = subArgs.trim();
+        try {
+          const loomSessionId = engine.getLoomSessionId();
+          const result = await client.createSchemaFile(loomSessionId, newName);
+          engine.onSchemaChanged(result.schema_id);
+          const lines = [
+            `✅ Created and switched to new schema: \`${result.schema_id}\``,
+            `Use \`/loom schemas\` to list schemas`,
+            "",
+            "💡 To create from a template: `/loom templates use <name>`",
+          ];
+          return { text: lines.join("\n") };
+        } catch (e) {
+          return { text: `❌ create failed: ${e}` };
+        }
+      }
+
+      case "templates": {
+        const templateSub = rest[0]?.toLowerCase() || "";
+
+        if (!templateSub || templateSub === "list") {
+          return handleTemplateList(client);
+        }
+
+        if (templateSub === "show" || templateSub === "preview") {
+          const tmplName = rest[1]?.trim();
+          if (!tmplName) {
+            return {
+              text: "Usage: `/loom templates show <name>`\nUse `/loom templates` to list templates",
+            };
+          }
+          return handleTemplateShow(client, tmplName);
+        }
+
+        if (templateSub === "use" || templateSub === "apply") {
+          const tmplName = rest[1]?.trim();
+          if (!tmplName) {
+            return {
+              text:
+                "Usage: `/loom templates use <name> [schema_name]`\nCreates a new schema from the template and switches to it. Schema name is optional.\nUse `/loom templates` to list templates",
+            };
+          }
+          const schemaName = rest[2]?.trim() || "";
+          return handleTemplateApply(client, engine, tmplName, schemaName);
+        }
+
+        if (templateSub === "create" || templateSub === "new") {
+          const wizardSub = rest[1]?.toLowerCase() || "";
+          const wizardArgs = rest.slice(2).join(" ").trim();
+          const fullArgs = rest.slice(1).join(" ").trim();
+          return handleTemplateCreateWizard(client, wizardSub, wizardArgs, fullArgs);
+        }
+
+        if (templateSub === "delete" || templateSub === "remove") {
+          const tmplName = rest[1]?.trim();
+          if (!tmplName) {
+            return {
+              text: "Usage: `/loom templates delete <name>`\n⚠️ Only custom templates can be deleted",
+            };
+          }
+          return handleTemplateDelete(client, tmplName);
+        }
+
+        if (templateSub === "help") {
+          return { text: formatTemplateHelp() };
+        }
+
+        return { text: `❌ Unknown templates subcommand: \`${templateSub}\`\n\n` + formatTemplateHelp() };
+      }
+
+      case "schemas":
+      case "list": {
+        try {
+          const saved = await client.listSavedSchemas();
+          const backups = await client.listBackups();
+          const lines: string[] = ["📂 **Schema files**"];
+          if (!saved.length) {
+            lines.push("(no saved schemas)");
+          } else {
+            for (const s of saved) {
+              const active = s.schema_id === cfg.schemaId ? " ← current" : "";
+              lines.push(`- \`${s.schema_id}\` (${s.domain_count} domains, ${s.file_size}B)${active}`);
+            }
+          }
+          if (backups.length) {
+            lines.push("", "📦 **Backups**");
+            for (const b of backups) {
+              lines.push(`- \`${b.backup_id}\` (${b.file_size}B, ${b.created_at})`);
+            }
+          }
+          lines.push("", "Switch: `/loom switch <schema_id>`");
+          lines.push("Restore: `/loom restore <backup_id>`");
+          return { text: lines.join("\n") };
+        } catch (e) {
+          return { text: `❌ Failed to list schemas: ${e}` };
+        }
+      }
+
+      case "switch": {
+        if (!subArgs) {
+          return { text: "Usage: `/loom switch <schema_id>`\nUse `/loom schemas` for available schemas" };
+        }
+        try {
+          await engine.handleSchemaSwitch(subArgs);
+          return { text: `✅ Switched to schema: \`${subArgs}\`` };
+        } catch (e) {
+          return { text: `❌ switch failed: ${e}` };
+        }
+      }
+
+      case "restore": {
+        if (!subArgs) {
+          return { text: "Usage: `/loom restore <backup_id>`\nUse `/loom schemas` for backups" };
+        }
+        try {
+          await client.restoreSchema(subArgs, cfg.schemaId);
+          return { text: `✅ Restored from backup: \`${subArgs}\` → \`${cfg.schemaId}\`` };
+        } catch (e) {
+          return { text: `❌ restore failed: ${e}` };
+        }
+      }
+
+      case "config": {
+        if (!subArgs) {
+          const lines = [
+            "⚙️ **Current config**",
+            `- \`buildEveryNTurns\` = ${cfg.buildEveryNTurns} (extract every ${cfg.buildEveryNTurns} turn(s))`,
+            `- \`loomBaseUrl\` = ${cfg.loomBaseUrl}`,
+            `- \`sessionId\` = ${cfg.sessionId} (active: ${engine.getLoomSessionId()})`,
+            `- \`schemaId\` = ${cfg.schemaId}`,
+            "",
+            "Change: `/loom config buildEveryNTurns <number>`",
+          ];
+          return { text: lines.join("\n") };
+        }
+        const configParts = subArgs.split(/\s+/);
+        const key = configParts[0];
+        const value = configParts.slice(1).join(" ");
+
+        if (key === "buildEveryNTurns") {
+          const n = parseInt(value, 10);
+          if (!value || isNaN(n) || n < 1) {
+            return {
+              text: `❌ Provide a positive integer.\nUsage: \`/loom config buildEveryNTurns 3\``,
+            };
+          }
+          engine.updateConfig({ buildEveryNTurns: n });
+          return {
+            text: `✅ Extraction interval updated to every **${n}** turn(s)\n⚠️ Runtime only; restarting the gateway restores values from config`,
+          };
+        }
+
+        return { text: `❌ Cannot change \`${key}\`.\nConfigurable: \`buildEveryNTurns\`` };
+      }
+
+      case "help":
+      default: {
+        return {
+          text: [
+            "🧠 **Loom memory commands**",
+            "",
+            "**View**",
+            "`/loom` — status",
+            "`/loom inspect` — memory content (summary if too long)",
+            "",
+            "**Manage**",
+            "`/loom forget <domain>` — delete a domain",
+            "`/loom forget --all` — clear all memory",
+            "`/loom reset` — backup and reset current schema",
+            "",
+            "**Schema files**",
+            "`/loom schemas` — list schemas and backups",
+            "`/loom new [name]` — create blank schema and switch",
+            "`/loom switch <id>` — switch schema",
+            "`/loom restore <backup_id>` — restore from backup",
+            "",
+            "**Templates**",
+            "`/loom templates` — list templates",
+            "`/loom templates show <name>` — preview template fields",
+            "`/loom templates use <name> [schema]` — create schema from template",
+            "`/loom templates create` — wizard for custom template",
+            "`/loom templates delete <name>` — delete custom template",
+            "",
+            "**Config**",
+            "`/loom config` — current settings",
+            "`/loom config buildEveryNTurns <N>` — extraction interval",
+          ].join("\n"),
+        };
+      }
+    }
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Agent tools
+// ---------------------------------------------------------------------------
+
+function createLoomInspectTool(engine: LoomContextEngine) {
+  return {
+    name: "loom_inspect",
+    label: "Loom Inspect",
+    description:
+      "Inspect the Loom memory schema structure. Returns an overview of all stored " +
+      "memory domains and their fields with values.",
+    parameters: Type.Object({
+      show_values: Type.Optional(Type.Boolean({ description: "Whether to include field values (default: true)" })),
+    }),
+    async execute(_toolCallId: string, params: { show_values?: boolean }) {
+      if (!engine.isReachable()) return textToolResult("Loom backend is not reachable.");
+      try {
+        const result = await engine.getClient().inspectAll(
+          engine.getConfig().schemaId,
+          params.show_values !== false,
+        );
+        return textToolResult(result.text || "Memory schemas are empty.");
+      } catch (e) {
+        return textToolResult(`Failed to inspect schemas: ${e}`);
+      }
+    },
+  };
+}
+
+function createLoomBuildTool(engine: LoomContextEngine) {
+  return {
+    name: "loom_build",
+    label: "Loom Build",
+    description:
+      "Manually trigger Loom to extract and store information from the provided text " +
+      "into structured memory schemas. Use when the user shares important personal " +
+      "information that should be remembered long-term.",
+    parameters: Type.Object({
+      text: Type.String({ description: "Text to process and extract information from" }),
+    }),
+    async execute(_toolCallId: string, params: { text: string }) {
+      if (!engine.isReachable()) return textToolResult("Loom backend is not reachable.");
+      try {
+        await engine.getClient().build(params.text, engine.getLoomSessionId());
+        return textToolResult("Memory updated successfully.");
+      } catch (e) {
+        return textToolResult(`Failed to build memory: ${e}`);
+      }
+    },
+  };
+}
+
+function createLoomForgetTool(engine: LoomContextEngine) {
+  return {
+    name: "loom_forget",
+    label: "Loom Forget",
+    description:
+      "Delete a schema domain from Loom memory. Use when the user asks to forget " +
+      "specific information. Pass the domain name (e.g. 'identity', 'preferences').",
+    parameters: Type.Object({
+      domain: Type.String({ description: "Domain name to delete (e.g. 'identity', 'preferences'). Use '--all' to clear everything." }),
+    }),
+    async execute(_toolCallId: string, params: { domain: string }) {
+      if (!engine.isReachable()) return textToolResult("Loom backend is not reachable.");
+      try {
+        const client = engine.getClient();
+        const schemaId = engine.getConfig().schemaId;
+        if (params.domain === "--all") {
+          const result = await client.clearAllSchemas(schemaId);
+          return textToolResult(`All schemas cleared (${result.count} domains removed).`);
+        }
+        await client.deleteSchema(params.domain, schemaId);
+        return textToolResult(`Domain '${params.domain}' deleted successfully.`);
+      } catch (e) {
+        return textToolResult(`Failed to forget: ${e}`);
+      }
+    },
+  };
+}
+
+function createLoomUpdateTool(engine: LoomContextEngine) {
+  return {
+    name: "loom_update",
+    label: "Loom Update",
+    description:
+      "Trigger schema update from the Loom session's recent chat history. " +
+      "Useful after a long conversation to ensure all important info is captured.",
+    parameters: Type.Object({
+      rounds: Type.Optional(Type.Number({ description: "Number of recent chat rounds to process (default: all available)" })),
+    }),
+    async execute(_toolCallId: string, params: { rounds?: number }) {
+      if (!engine.isReachable()) return textToolResult("Loom backend is not reachable.");
+      try {
+        await engine.getClient().updateSchemaFromChat(
+          engine.getLoomSessionId(),
+          params.rounds,
+        );
+        return textToolResult("Schema updated from chat history.");
+      } catch (e) {
+        return textToolResult(`Failed to update schema: ${e}`);
+      }
+    },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Template management handlers
+// ---------------------------------------------------------------------------
+
+async function handleTemplateList(client: LoomClient) {
+  try {
+    const grouped = await client.listTemplatesGrouped();
+    const lines: string[] = ["📋 **Available templates**", ""];
+
+    const groupLabels: Record<string, string> = {
+      builtin: "🔒 Built-in",
+      user: "📁 Shared",
+      custom: "✏️ Custom",
+    };
+
+    let hasAny = false;
+    for (const [source, label] of Object.entries(groupLabels)) {
+      const items = grouped[source] || [];
+      if (items.length) {
+        hasAny = true;
+        lines.push(`**${label}**`);
+        for (const t of items) {
+          lines.push(`- \`${t.name}\` — ${t.description || "(no description)"} (${t.domain_count} domains)`);
+        }
+        lines.push("");
+      }
+    }
+
+    if (!hasAny) {
+      return { text: "📭 No templates available" };
+    }
+
+    lines.push(
+      "---",
+      "💡 **Next steps**",
+      "`/loom templates show <name>` — preview fields",
+      "`/loom templates use <name> [schema]` — create schema from template",
+      "`/loom templates create` — custom template wizard",
+      "`/loom templates delete <name>` — delete a custom template",
+    );
+
+    return { text: lines.join("\n") };
+  } catch (e) {
+    return { text: `❌ Failed to list templates: ${e}` };
+  }
+}
+
+async function handleTemplateShow(client: LoomClient, name: string) {
+  try {
+    const tmpl = await client.getTemplate(name);
+    const lines: string[] = [`📋 **Template: ${tmpl.name}**`, ""];
+
+    if (tmpl.description) {
+      lines.push(`> ${tmpl.description}`, "");
+    }
+
+    lines.push(`Source: \`${tmpl.source}\` | Domains: ${tmpl.domains.length}`, "");
+
+    const data = tmpl.data as Record<string, Record<string, unknown>>;
+    for (const domainName of tmpl.domains) {
+      const domain = data[domainName];
+      if (!domain || typeof domain !== "object") continue;
+      const domainData = (domain as Record<string, unknown>).data as Record<string, Record<string, unknown>> | undefined;
+      if (!domainData) continue;
+
+      const fields = Object.keys(domainData).filter((k) => k !== "meta");
+      lines.push(`**📂 ${domainName}** (${fields.length} field(s))`);
+      for (const field of fields) {
+        const desc = domainData[field]?.description || "";
+        lines.push(`  - \`${field}\`: ${desc}`);
+      }
+      lines.push("");
+    }
+
+    lines.push("---", `Use \`/loom templates use ${name}\` to create a schema from this template`);
+    return { text: lines.join("\n") };
+  } catch (e) {
+    return { text: `❌ Failed to load template: ${e}` };
+  }
+}
+
+async function handleTemplateApply(
+  client: LoomClient,
+  engine: LoomContextEngine,
+  templateName: string,
+  schemaName = "",
+) {
+  try {
+    const loomSessionId = engine.getLoomSessionId();
+    const result = await client.createSchemaFile(loomSessionId, schemaName, templateName);
+    engine.onSchemaChanged(result.schema_id);
+
+    const lines = [
+      `✅ Created schema \`${result.schema_id}\` from template \`${templateName}\``,
+      "",
+      "Schema structure is ready; Loom will extract into these fields in later turns.",
+      "",
+      "`/loom inspect` — view structure",
+      "`/loom schemas` — list schemas",
+    ];
+    return { text: lines.join("\n") };
+  } catch (e) {
+    return { text: `❌ Failed to create schema from template: ${e}` };
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Template creation wizard — state and handlers
+// ---------------------------------------------------------------------------
+
+interface WizardDomain {
+  fields: Record<string, string>;
+}
+
+interface WizardState {
+  name: string;
+  description: string;
+  domains: Record<string, WizardDomain>;
+  createdAt: number;
+}
+
+const WIZARD_TIMEOUT_MS = 30 * 60 * 1000;
+let _wizardState: WizardState | null = null;
+
+function getWizard(): WizardState | null {
+  if (_wizardState && Date.now() - _wizardState.createdAt > WIZARD_TIMEOUT_MS) {
+    _wizardState = null;
+  }
+  return _wizardState;
+}
+
+function formatWizardStatus(w: WizardState): string {
+  const lines: string[] = [
+    "📋 **Template wizard — progress**",
+    "",
+    `Name: \`${w.name || "(not set)"}\``,
+    `Description: ${w.description || "(not set)"}`,
+    "",
+  ];
+
+  const domainNames = Object.keys(w.domains);
+  if (domainNames.length === 0) {
+    lines.push("Domains: (none yet)");
+  } else {
+    lines.push(`**Domains (${domainNames.length})**`);
+    for (const [dName, dData] of Object.entries(w.domains)) {
+      const fieldNames = Object.keys(dData.fields);
+      lines.push(`- \`${dName}\` — ${fieldNames.length} field(s): ${fieldNames.map((f) => `\`${f}\``).join(", ")}`);
+    }
+  }
+
+  lines.push("");
+  const canSave = w.name && domainNames.length > 0;
+  if (!w.name) {
+    lines.push("**Next:** set template name");
+    lines.push("`/loom templates create name <name> [description]`");
+  } else if (domainNames.length === 0) {
+    lines.push("**Next:** add at least one domain");
+    lines.push("`/loom templates create domain <domain> <field1|desc, field2|desc>`");
+  } else {
+    lines.push("**Optional:**");
+    lines.push("`/loom templates create domain <name> <fields...>` — add another domain");
+    lines.push("`/loom templates create remove <domain>` — remove a domain");
+    if (canSave) {
+      lines.push("`/loom templates create done` — **save template**");
+    }
+  }
+  lines.push("`/loom templates create cancel` — abort");
+
+  return lines.join("\n");
+}
+
+/**
+ * Wizard-based template creation handler. Supports sub-commands:
+ *   (no args)          → show wizard overview / start wizard
+ *   name <n> [desc]    → set template name and optional description
+ *   desc <text>        → set/update description
+ *   domain <n> <fields>→ add a domain with fields
+ *   remove <domain>    → remove a domain
+ *   done / save        → save the template
+ *   cancel             → cancel wizard
+ *   --json <data>      → direct JSON creation (advanced)
+ *
+ * Also supports the legacy compact format for backward compatibility.
+ */
+async function handleTemplateCreateWizard(
+  client: LoomClient,
+  sub: string,
+  subArgs: string,
+  fullArgs: string,
+) {
+  // -- Direct JSON mode (advanced) --
+  if (fullArgs.startsWith("--json ") || fullArgs.startsWith("--json=")) {
+    const jsonStr = fullArgs.startsWith("--json=") ? fullArgs.slice(7) : fullArgs.slice(7);
+    try {
+      const data = JSON.parse(jsonStr);
+      const result = await client.saveCustomTemplate(data);
+      return { text: `✅ Custom template saved: \`${result.name}\`\nFile: \`${result.path}\`` };
+    } catch (e) {
+      if (e instanceof SyntaxError) {
+        return { text: `❌ Invalid JSON: ${e.message}\nCheck the JSON syntax.` };
+      }
+      return { text: `❌ Failed to save template: ${e}` };
+    }
+  }
+
+  // -- Legacy compact format: detect multi-line or "name desc\n domain:..." pattern --
+  if (sub && !["name", "desc", "domain", "add", "remove", "rm", "done", "save", "cancel", "status", "help"].includes(sub)) {
+    if (fullArgs.includes("\n") || fullArgs.includes(":")) {
+      try {
+        const parsed = parseCompactTemplate(fullArgs);
+        const result = await client.saveCustomTemplate(parsed);
+        const domainCount = Object.keys(parsed).filter((k) => k !== "_meta").length;
+        const lines = [
+          `✅ Custom template saved: \`${result.name}\``,
+          `File: \`${result.path}\``,
+          `Domains: ${domainCount}`,
+          "",
+          `Preview: \`/loom templates show ${result.name}\``,
+          `Apply: \`/loom templates use ${result.name}\` on a new schema`,
+        ];
+        return { text: lines.join("\n") };
+      } catch (e) {
+        if (e instanceof TemplateParseError) {
+          return {
+            text: `❌ Parse error: ${e.message}\n\n💡 Try the wizard: \`/loom templates create\``,
+          };
+        }
+        return { text: `❌ Failed to save template: ${e}` };
+      }
+    }
+  }
+
+  // -- Wizard sub-commands --
+  switch (sub) {
+    case "": {
+      // Start new wizard or show status of existing one
+      const existing = getWizard();
+      if (existing) {
+        return { text: formatWizardStatus(existing) };
+      }
+      _wizardState = { name: "", description: "", domains: {}, createdAt: Date.now() };
+      return {
+        text: [
+          "✏️ **Template creation wizard**",
+          "",
+          "Create a custom template step by step.",
+          "",
+          "**Step 1:** set template name",
+          "`/loom templates create name <name> [description]`",
+          "",
+          "Example:",
+          "`/loom templates create name game_character RPG character memory`",
+          "",
+          "`/loom templates create help` for all wizard commands",
+        ].join("\n"),
+      };
+    }
+
+    case "name": {
+      if (!subArgs) {
+        return {
+          text: "Usage: `/loom templates create name <name> [description]`\nName: letters, digits, underscores, hyphens only",
+        };
+      }
+      const parts = subArgs.split(/\s+/);
+      const name = parts[0];
+      const desc = parts.slice(1).join(" ");
+      if (/[^a-zA-Z0-9_-]/.test(name)) {
+        return {
+          text: `❌ Invalid template name \`${name}\` — use letters, digits, underscores, hyphens only`,
+        };
+      }
+      if (!_wizardState) {
+        _wizardState = { name: "", description: "", domains: {}, createdAt: Date.now() };
+      }
+      _wizardState.name = name;
+      if (desc) _wizardState.description = desc;
+      return {
+        text: [
+          `✅ Template name: \`${name}\`${desc ? `\nDescription: ${desc}` : ""}`,
+          "",
+          "**Step 2:** add a domain (memory group)",
+          "`/loom templates create domain <domain> <field1|desc, field2|desc>`",
+          "",
+          "Examples:",
+          "`/loom templates create domain character name|name, class|class, level|level`",
+          "`/loom templates create domain story main_quest|main quest, achievements|achievements`",
+        ].join("\n"),
+      };
+    }
+
+    case "desc": {
+      if (!subArgs) {
+        return { text: "Usage: `/loom templates create desc <description>`" };
+      }
+      if (!_wizardState) {
+        _wizardState = { name: "", description: "", domains: {}, createdAt: Date.now() };
+      }
+      _wizardState.description = subArgs;
+      return { text: `✅ Description updated: ${subArgs}\n\n` + formatWizardStatus(_wizardState) };
+    }
+
+    case "domain":
+    case "add": {
+      if (!subArgs) {
+        return {
+          text: [
+            "Usage: `/loom templates create domain <domain> <field definitions>`",
+            "",
+            "**Field format:** `name|description` or `name` (comma-separated)",
+            "",
+            "Examples:",
+            "`/loom templates create domain identity name|name, age|age, location|location`",
+            "`/loom templates create domain preferences music|music, food|food`",
+          ].join("\n"),
+        };
+      }
+      const firstSpace = subArgs.indexOf(" ");
+      if (firstSpace === -1) {
+        return {
+          text: `❌ Add field definitions for the domain\nUsage: \`/loom templates create domain ${subArgs} field1|desc, field2|desc\``,
+        };
+      }
+      const domainName = subArgs.slice(0, firstSpace).trim();
+      const fieldsStr = subArgs.slice(firstSpace + 1).trim();
+
+      if (/[^a-zA-Z0-9_]/.test(domainName)) {
+        return {
+          text: `❌ Invalid domain name \`${domainName}\` — letters, digits, underscores only`,
+        };
+      }
+
+      const fields: Record<string, string> = {};
+      const fieldParts = fieldsStr.split(",").map((s) => s.trim()).filter(Boolean);
+      for (const part of fieldParts) {
+        const pipeIdx = part.indexOf("|");
+        if (pipeIdx === -1) {
+          const fieldName = part.trim().replace(/\s+/g, "_");
+          if (fieldName) fields[fieldName] = fieldName;
+        } else {
+          const fieldName = part.slice(0, pipeIdx).trim().replace(/\s+/g, "_");
+          const fieldDesc = part.slice(pipeIdx + 1).trim();
+          if (fieldName) fields[fieldName] = fieldDesc || fieldName;
+        }
+      }
+
+      if (Object.keys(fields).length === 0) {
+        return { text: "❌ Define at least one field\nFormat: `name|desc, name|desc`" };
+      }
+
+      if (!_wizardState) {
+        _wizardState = { name: "", description: "", domains: {}, createdAt: Date.now() };
+      }
+      _wizardState.domains[domainName] = { fields };
+
+      const fieldList = Object.entries(fields)
+        .map(([n, d]) => `  \`${n}\` — ${d}`)
+        .join("\n");
+      const domainCount = Object.keys(_wizardState.domains).length;
+      const canSave = _wizardState.name && domainCount > 0;
+
+      return {
+        text: [
+          `✅ Added domain \`${domainName}\` (${Object.keys(fields).length} field(s))`,
+          fieldList,
+          "",
+          `Total domains: ${domainCount}`,
+          "",
+          "Add more: `/loom templates create domain <name> <fields...>`",
+          "Remove: `/loom templates create remove <domain>`",
+          canSave
+            ? "**Save:** `/loom templates create done`"
+            : `⚠️ Set template name first: \`/loom templates create name <name>\``,
+        ].join("\n"),
+      };
+    }
+
+    case "remove":
+    case "rm": {
+      if (!subArgs) {
+        return { text: "Usage: `/loom templates create remove <domain>`" };
+      }
+      const w = getWizard();
+      if (!w) {
+        return { text: "❌ No wizard in progress. Start with `/loom templates create`" };
+      }
+      const target = subArgs.trim();
+      if (!w.domains[target]) {
+        const available = Object.keys(w.domains);
+        return {
+          text: `❌ Domain \`${target}\` not found\nDomains: ${available.length ? available.map((d) => `\`${d}\``).join(", ") : "(none)"}`,
+        };
+      }
+      delete w.domains[target];
+      return { text: `🗑️ Removed domain \`${target}\`\n\n` + formatWizardStatus(w) };
+    }
+
+    case "done":
+    case "save": {
+      const w = getWizard();
+      if (!w) {
+        return { text: "❌ No wizard in progress. Start with `/loom templates create`" };
+      }
+      if (!w.name) {
+        return { text: "❌ Template name not set\nRun: `/loom templates create name <name>`" };
+      }
+      if (Object.keys(w.domains).length === 0) {
+        return {
+          text: "❌ Add at least one domain\nRun: `/loom templates create domain <domain> <fields...>`",
+        };
+      }
+
+      const templateData = buildTemplateFromWizard(w);
+      try {
+        const result = await client.saveCustomTemplate(templateData);
+        _wizardState = null;
+        return {
+          text: [
+            `✅ Custom template saved: \`${result.name}\``,
+            `File: \`${result.path}\``,
+            `Domains: ${Object.keys(w.domains).length}`,
+            "",
+            `Preview: \`/loom templates show ${result.name}\``,
+            `Apply: \`/loom templates use ${result.name}\` on a new schema`,
+          ].join("\n"),
+        };
+      } catch (e) {
+        return { text: `❌ Failed to save template: ${e}` };
+      }
+    }
+
+    case "cancel": {
+      if (!getWizard()) {
+        return { text: "ℹ️ No template wizard in progress" };
+      }
+      _wizardState = null;
+      return { text: "🚫 Template creation cancelled" };
+    }
+
+    case "status": {
+      const w = getWizard();
+      if (!w) {
+        return { text: "ℹ️ No wizard in progress. Start with `/loom templates create`" };
+      }
+      return { text: formatWizardStatus(w) };
+    }
+
+    case "help": {
+      return { text: formatTemplateCreateHelp() };
+    }
+
+    default: {
+      return { text: `❌ Unknown wizard command: \`${sub}\`\n\n` + formatTemplateCreateHelp() };
+    }
+  }
+}
+
+function buildTemplateFromWizard(w: WizardState): Record<string, unknown> {
+  const result: Record<string, unknown> = {
+    _meta: { name: w.name, description: w.description || `Custom template: ${w.name}` },
+  };
+
+  for (const [domainName, domainData] of Object.entries(w.domains)) {
+    const data: Record<string, unknown> = {
+      meta: {
+        domain: { value: domainName, description: `Schema domain: ${domainName}` },
+        created_at: { value: "", description: "Creation timestamp" },
+        last_updated: { value: "", description: "Last update timestamp" },
+        mutable: { value: "true", description: "Whether CM can modify this domain" },
+      },
+    };
+    for (const [fn, fd] of Object.entries(domainData.fields)) {
+      data[fn] = { value: "", description: fd };
+    }
+    result[domainName] = { data, _mutable: true };
+  }
+
+  return result;
+}
+
+async function handleTemplateDelete(client: LoomClient, name: string) {
+  try {
+    await client.deleteCustomTemplate(name);
+    return { text: `🗑️ Custom template deleted: \`${name}\`` };
+  } catch (e) {
+    return {
+      text: `❌ Failed to delete template: ${e}\n⚠️ Only custom templates can be deleted (not built-in or shared)`,
+    };
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Template compact format parser
+// ---------------------------------------------------------------------------
+
+class TemplateParseError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "TemplateParseError";
+  }
+}
+
+/**
+ * Parses the compact template format:
+ *
+ *   name [optional description]
+ *   domain1: field1 | desc, field2 | desc
+ *   domain2: field3 | desc
+ *
+ * Lines starting with whitespace are domain definitions.
+ * The first non-indented token is the template name; remaining text is description.
+ */
+function parseCompactTemplate(input: string): Record<string, unknown> {
+  const lines = input.split("\n").map((l) => l.trimEnd());
+  if (!lines.length || !lines[0].trim()) {
+    throw new TemplateParseError("Template name cannot be empty");
+  }
+
+  const headerLine = lines[0].trim();
+  const headerParts = headerLine.split(/\s+/);
+  const name = headerParts[0];
+  const description = headerParts.slice(1).join(" ");
+
+  if (!name || /[^a-zA-Z0-9_-]/.test(name)) {
+    throw new TemplateParseError(
+      `Invalid template name "${name}" — use letters, digits, underscores, hyphens only`,
+    );
+  }
+
+  const result: Record<string, unknown> = {
+    _meta: { name, description: description || `Custom template: ${name}` },
+  };
+
+  let domainCount = 0;
+  for (let i = 1; i < lines.length; i++) {
+    const line = lines[i];
+    if (!line.trim()) continue;
+
+    const domainMatch = line.trim().match(/^([a-zA-Z_][a-zA-Z0-9_]*)\s*:\s*(.+)$/);
+    if (!domainMatch) {
+      throw new TemplateParseError(
+        `Line ${i + 1} invalid: "${line.trim()}"\n` +
+        `Expected: domain_name: field1 | desc, field2 | desc`,
+      );
+    }
+
+    const domainName = domainMatch[1];
+    const fieldsStr = domainMatch[2];
+
+    const fields: Record<string, string> = {};
+    const fieldParts = fieldsStr.split(",").map((s) => s.trim()).filter(Boolean);
+    for (const part of fieldParts) {
+      const pipeIdx = part.indexOf("|");
+      if (pipeIdx === -1) {
+        const fieldName = part.trim().replace(/\s+/g, "_");
+        fields[fieldName] = fieldName;
+      } else {
+        const fieldName = part.slice(0, pipeIdx).trim().replace(/\s+/g, "_");
+        const fieldDesc = part.slice(pipeIdx + 1).trim();
+        if (!fieldName) {
+          throw new TemplateParseError(`Line ${i + 1} empty field name: "${part}"`);
+        }
+        fields[fieldName] = fieldDesc || fieldName;
+      }
+    }
+
+    const domainData: Record<string, Record<string, string>> = {
+      meta: {
+        domain: domainName,
+        created_at: "",
+        last_updated: "",
+        mutable: "true",
+      },
+    };
+    for (const [fn, fd] of Object.entries(fields)) {
+      domainData[fn] = { value: "", description: fd };
+    }
+
+    const metaFormatted: Record<string, { value: string; description: string }> = {};
+    metaFormatted["domain"] = { value: domainName, description: `Schema domain: ${domainName}` };
+    metaFormatted["created_at"] = { value: "", description: "Creation timestamp" };
+    metaFormatted["last_updated"] = { value: "", description: "Last update timestamp" };
+    metaFormatted["mutable"] = { value: "true", description: "Whether CM can modify this domain" };
+
+    const data: Record<string, unknown> = { meta: metaFormatted };
+    for (const [fn, fd] of Object.entries(fields)) {
+      data[fn] = { value: "", description: fd };
+    }
+
+    result[domainName] = { data, _mutable: true };
+    domainCount++;
+  }
+
+  if (domainCount === 0) {
+    throw new TemplateParseError(
+      "Define at least one domain\nFormat: domain_name: field1 | desc, field2 | desc",
+    );
+  }
+
+  return result;
+}
+
+// ---------------------------------------------------------------------------
+// Help text formatters
+// ---------------------------------------------------------------------------
+
+function formatTemplateHelp(): string {
+  return [
+    "📋 **Template commands**",
+    "",
+    "**List / preview**",
+    "`/loom templates` — list templates (grouped by source)",
+    "`/loom templates show <name>` — preview domains and fields",
+    "",
+    "**Apply**",
+    "`/loom templates use <name> [schema]` — create schema from template and switch",
+    "",
+    "**Custom**",
+    "`/loom templates create` — wizard for custom template",
+    "`/loom templates delete <name>` — delete a custom template",
+    "",
+    "**Help**",
+    "`/loom templates help` — this help",
+  ].join("\n");
+}
+
+function formatTemplateCreateHelp(): string {
+  return [
+    "✏️ **Create a custom template**",
+    "",
+    "**Wizard** (recommended)",
+    "",
+    "Small steps; no need to memorize the full format:",
+    "",
+    "1️⃣ `/loom templates create` — start",
+    "2️⃣ `/loom templates create name <name> [description]`",
+    "3️⃣ `/loom templates create domain <domain> <field1|desc, field2|desc>` — repeat as needed",
+    "4️⃣ `/loom templates create done` — save",
+    "",
+    "**Example:**",
+    "`/loom templates create name game_character RPG character`",
+    "`/loom templates create domain character name|name, class|class, level|level`",
+    "`/loom templates create domain story main_quest|main quest, achievements|achievements`",
+    "`/loom templates create done`",
+    "",
+    "**Other wizard commands:**",
+    "`/loom templates create desc <text>` — set description",
+    "`/loom templates create remove <domain>` — remove a domain",
+    "`/loom templates create status` — progress",
+    "`/loom templates create cancel` — abort",
+    "",
+    "---",
+    "",
+    "**One-shot** (advanced)",
+    "",
+    "```",
+    "/loom templates create my_template My description",
+    "  domain1: field1 | desc, field2 | desc",
+    "  domain2: field3 | desc",
+    "```",
+  ].join("\n");
+}