squad-openclaw 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * squad-openclaw — OpenClaw gateway plugin for Squad
+ *
+ * Provides:
+ *   - Entity registry with FTS and vector search (entity_*)
+ *   - Filesystem tools for remote clients (fs_read, fs_write, fs_list)
+ *   - Version check and self-update gateway methods (squad.version.*)
+ */
+declare function squadAppPlugin(api: any): void;
+
+export { squadAppPlugin as default };

package/dist/index.js

@@ -0,0 +1,1081 @@
+var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require : typeof Proxy !== "undefined" ? new Proxy(x, {
+  get: (a, b) => (typeof require !== "undefined" ? require : a)[b]
+}) : x)(function(x) {
+  if (typeof require !== "undefined") return require.apply(this, arguments);
+  throw Error('Dynamic require of "' + x + '" is not supported');
+});
+
+// src/entities.ts
+import { Type as T } from "@sinclair/typebox";
+import Database from "better-sqlite3";
+import path from "path";
+import fs from "fs";
+var DB_NAME = "squad.db";
+var EMBEDDING_DIMENSIONS = 1536;
+var EMBEDDING_MODEL = "google/gemini-embedding-001";
+var SYNC_INTERVAL_MS = 6e4;
+var EntityType = T.Union([
+  T.Literal("agent"),
+  T.Literal("skill"),
+  T.Literal("tool"),
+  T.Literal("session"),
+  T.Literal("file"),
+  T.Literal("directory"),
+  T.Literal("url"),
+  T.Literal("memory"),
+  T.Literal("asset")
+]);
+var db;
+var vecEnabled = false;
+function getDb(configDir) {
+  if (db) return db;
+  const pluginDir = path.join(configDir, "extensions", "squad-app");
+  const dataDir = path.join(pluginDir, "data");
+  fs.mkdirSync(dataDir, { recursive: true });
+  const dbPath = path.join(dataDir, DB_NAME);
+  db = new Database(dbPath);
+  db.pragma("journal_mode = WAL");
+  db.pragma("foreign_keys = ON");
+  try {
+    const sqliteVec = __require("sqlite-vec");
+    sqliteVec.load(db);
+    vecEnabled = true;
+  } catch {
+  }
+  runMigrations(db);
+  return db;
+}
+function runMigrations(db2) {
+  db2.exec(`
+    CREATE TABLE IF NOT EXISTS _schema_version (
+      version INTEGER PRIMARY KEY
+    )
+  `);
+  const currentVersion = db2.prepare("SELECT MAX(version) as v FROM _schema_version").get()?.v ?? 0;
+  const migrations = [
+    {
+      version: 1,
+      up: () => {
+        db2.exec(`
+          CREATE TABLE IF NOT EXISTS entities (
+            id          TEXT PRIMARY KEY,
+            type        TEXT NOT NULL,
+            name        TEXT NOT NULL,
+            title       TEXT,
+            description TEXT,
+            metadata    TEXT,
+            source      TEXT NOT NULL DEFAULT 'manual',
+            source_key  TEXT,
+            created_at  INTEGER NOT NULL,
+            updated_at  INTEGER NOT NULL
+          );
+          CREATE INDEX IF NOT EXISTS idx_entities_type ON entities(type);
+          CREATE INDEX IF NOT EXISTS idx_entities_name ON entities(name);
+        `);
+      }
+    },
+    {
+      version: 3,
+      up: () => {
+        db2.exec(`
+          CREATE VIRTUAL TABLE IF NOT EXISTS search_fts USING fts5(
+            entity_id UNINDEXED,
+            entity_type UNINDEXED,
+            name,
+            title,
+            description,
+            content,
+            tokenize='porter unicode61'
+          );
+        `);
+      }
+    },
+    {
+      version: 4,
+      up: () => {
+        if (!vecEnabled) return;
+        db2.exec(`
+          CREATE VIRTUAL TABLE IF NOT EXISTS search_vec USING vec0(
+            entity_id TEXT PRIMARY KEY,
+            embedding float[${EMBEDDING_DIMENSIONS}]
+          );
+        `);
+      }
+    }
+  ];
+  const pending = migrations.filter((m) => m.version > currentVersion);
+  if (pending.length === 0) return;
+  const migrate = db2.transaction(() => {
+    for (const m of pending) {
+      m.up();
+      db2.prepare("INSERT INTO _schema_version (version) VALUES (?)").run(
+        m.version
+      );
+    }
+  });
+  migrate();
+}
+function entityRow(row) {
+  return {
+    ...row,
+    metadata: row.metadata ? JSON.parse(row.metadata) : {}
+  };
+}
+function ftsUpsert(db2, entityId, entityType, name, title, description, content) {
+  ftsDelete(db2, entityId);
+  db2.prepare(
+    `INSERT INTO search_fts (entity_id, entity_type, name, title, description, content)
+     VALUES (?, ?, ?, ?, ?, ?)`
+  ).run(entityId, entityType, name, title ?? "", description ?? "", content);
+}
+function ftsDelete(db2, entityId) {
+  const existing = db2.prepare("SELECT * FROM search_fts WHERE entity_id = ?").get(entityId);
+  if (existing) {
+    db2.prepare(
+      `INSERT INTO search_fts (search_fts, entity_id, entity_type, name, title, description, content)
+       VALUES ('delete', ?, ?, ?, ?, ?, ?)`
+    ).run(
+      existing.entity_id,
+      existing.entity_type,
+      existing.name,
+      existing.title,
+      existing.description,
+      existing.content
+    );
+  }
+}
+function ftsSearch(db2, query, entityType, limit = 20) {
+  const safeQuery = query.replace(/[*"(){}[\]^~\\:]/g, " ").trim().split(/\s+/).filter(Boolean).map((term) => `"${term}"*`).join(" OR ");
+  if (!safeQuery) return [];
+  let sql = `
+    SELECT e.*, search_fts.rank
+    FROM search_fts
+    JOIN entities e ON e.id = search_fts.entity_id
+    WHERE search_fts MATCH ?
+  `;
+  const params = [safeQuery];
+  if (entityType) {
+    sql += ` AND search_fts.entity_type = ?`;
+    params.push(entityType);
+  }
+  sql += ` ORDER BY search_fts.rank LIMIT ?`;
+  params.push(limit);
+  return db2.prepare(sql).all(...params).map(entityRow);
+}
+function vecUpsert(db2, entityId, embedding) {
+  if (!vecEnabled) return;
+  db2.prepare("DELETE FROM search_vec WHERE entity_id = ?").run(entityId);
+  const buffer = embedding instanceof Float32Array ? Buffer.from(embedding.buffer) : Buffer.from(new Float32Array(embedding).buffer);
+  db2.prepare("INSERT INTO search_vec (entity_id, embedding) VALUES (?, ?)").run(
+    entityId,
+    buffer
+  );
+}
+function vecSearch(db2, embedding, limit = 20) {
+  if (!vecEnabled) return [];
+  const buffer = embedding instanceof Float32Array ? Buffer.from(embedding.buffer) : Buffer.from(new Float32Array(embedding).buffer);
+  const rows = db2.prepare(
+    `SELECT entity_id, distance
+       FROM search_vec
+       WHERE embedding MATCH ?
+       ORDER BY distance
+       LIMIT ?`
+  ).all(buffer, limit);
+  if (rows.length === 0) return [];
+  const ids = rows.map((r) => r.entity_id);
+  const placeholders = ids.map(() => "?").join(",");
+  const entities = db2.prepare(`SELECT * FROM entities WHERE id IN (${placeholders})`).all(...ids).map(entityRow);
+  const entityMap = new Map(entities.map((e) => [e.id, e]));
+  return rows.map((r) => {
+    const entity = entityMap.get(r.entity_id);
+    if (!entity) return null;
+    return { ...entity, _distance: r.distance };
+  }).filter(Boolean);
+}
+async function generateEmbedding(text, configDir) {
+  const config = readEmbeddingsConfig(configDir);
+  if (!config) return null;
+  const response = await fetch(`${config.apiUrl}/embeddings`, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+      Authorization: `Bearer ${config.apiKey}`
+    },
+    body: JSON.stringify({
+      model: config.model,
+      input: text,
+      dimensions: config.dimensions
+    })
+  });
+  if (!response.ok) {
+    const err2 = await response.text();
+    throw new Error(`Embedding API error (${response.status}): ${err2}`);
+  }
+  const data = await response.json();
+  return new Float32Array(data.data[0].embedding);
+}
+function readEmbeddingsConfig(configDir) {
+  try {
+    const raw = fs.readFileSync(
+      path.join(configDir, "openclaw.json"),
+      "utf-8"
+    );
+    const config = JSON.parse(raw);
+    const emb = config.embeddings;
+    if (!emb?.apiUrl || !emb?.apiKey) return null;
+    return {
+      apiUrl: emb.apiUrl,
+      apiKey: emb.apiKey,
+      model: emb.model ?? EMBEDDING_MODEL,
+      dimensions: emb.dimensions ?? EMBEDDING_DIMENSIONS
+    };
+  } catch {
+    return null;
+  }
+}
+function buildEmbeddingText(entity) {
+  const parts = [entity.type + ":", entity.name];
+  if (entity.title) parts.push(entity.title);
+  if (entity.description) parts.push(entity.description);
+  return parts.join(" ");
+}
+function syncEntitiesFromFilesystem(db2, configDir) {
+  let synced = 0;
+  let removed = 0;
+  const now = Date.now();
+  const upsert = db2.prepare(`
+    INSERT INTO entities (id, type, name, title, description, metadata, source, source_key, created_at, updated_at)
+    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+    ON CONFLICT(id) DO UPDATE SET
+      name = excluded.name,
+      title = excluded.title,
+      description = excluded.description,
+      metadata = excluded.metadata,
+      updated_at = excluded.updated_at
+  `);
+  const agentsDir = path.join(configDir, "agents");
+  const seenAgentIds = /* @__PURE__ */ new Set();
+  if (fs.existsSync(agentsDir)) {
+    const entries = fs.readdirSync(agentsDir, { withFileTypes: true });
+    for (const entry of entries) {
+      if (!entry.isDirectory()) continue;
+      const agentId = entry.name;
+      seenAgentIds.add(agentId);
+      let name = agentId;
+      let description = "";
+      const metadata = {};
+      const soulPath = path.join(agentsDir, agentId, "SOUL.md");
+      if (fs.existsSync(soulPath)) {
+        try {
+          const content = fs.readFileSync(soulPath, "utf-8");
+          const firstLine = content.split("\n")[0]?.replace(/^#\s*/, "").trim();
+          if (firstLine) name = firstLine;
+          description = content.slice(0, 500);
+          metadata.soul_content = content;
+        } catch {
+        }
+      }
+      upsert.run(
+        agentId,
+        "agent",
+        name,
+        name,
+        description,
+        JSON.stringify(metadata),
+        "filesystem",
+        soulPath,
+        now,
+        now
+      );
+      ftsUpsert(db2, agentId, "agent", name, name, description, "");
+      synced++;
+    }
+  }
+  const staleAgents = db2.prepare(
+    "SELECT id FROM entities WHERE type = 'agent' AND source = 'filesystem' AND id NOT IN (" + Array.from(seenAgentIds).map(() => "?").join(",") + ")"
+  ).all(...Array.from(seenAgentIds));
+  if (seenAgentIds.size > 0) {
+    for (const stale of staleAgents) {
+      db2.prepare("DELETE FROM entities WHERE id = ?").run(stale.id);
+      ftsDelete(db2, stale.id);
+      removed++;
+    }
+  }
+  try {
+    const raw = fs.readFileSync(
+      path.join(configDir, "openclaw.json"),
+      "utf-8"
+    );
+    const config = JSON.parse(raw);
+    const allowedTools = config?.tools?.allow ?? [];
+    for (const toolName of allowedTools) {
+      const toolId = `tool:${toolName}`;
+      upsert.run(
+        toolId,
+        "tool",
+        toolName,
+        toolName,
+        null,
+        JSON.stringify({ tool_name: toolName }),
+        "filesystem",
+        "openclaw.json:tools.allow",
+        now,
+        now
+      );
+      ftsUpsert(db2, toolId, "tool", toolName, toolName, "", "");
+      synced++;
+    }
+  } catch {
+  }
+  const seedPath = path.join(
+    configDir,
+    "extensions",
+    "squad-app",
+    "data",
+    "search-seed.json"
+  );
+  try {
+    if (fs.existsSync(seedPath)) {
+      const seedRaw = fs.readFileSync(seedPath, "utf-8");
+      const seedEntities = JSON.parse(seedRaw);
+      for (const entity of seedEntities) {
+        upsert.run(
+          entity.id,
+          entity.type,
+          entity.name,
+          entity.title,
+          entity.description,
+          JSON.stringify(entity.metadata ?? {}),
+          entity.source ?? "gateway",
+          entity.sourceKey ?? null,
+          now,
+          now
+        );
+        ftsUpsert(
+          db2,
+          entity.id,
+          entity.type,
+          entity.name,
+          entity.title,
+          entity.description,
+          ""
+        );
+        synced++;
+      }
+    }
+  } catch {
+  }
+  return { synced, removed };
+}
+function hybridSearch(db2, ftsResults, vecResults, limit) {
+  const k = 60;
+  const scores = /* @__PURE__ */ new Map();
+  for (let i = 0; i < ftsResults.length; i++) {
+    const entity = ftsResults[i];
+    const rrf = 1 / (k + i + 1);
+    const existing = scores.get(entity.id);
+    if (existing) {
+      existing.score += rrf;
+    } else {
+      scores.set(entity.id, { score: rrf, entity });
+    }
+  }
+  for (let i = 0; i < vecResults.length; i++) {
+    const entity = vecResults[i];
+    const rrf = 1 / (k + i + 1);
+    const existing = scores.get(entity.id);
+    if (existing) {
+      existing.score += rrf;
+    } else {
+      scores.set(entity.id, { score: rrf, entity });
+    }
+  }
+  return Array.from(scores.values()).sort((a, b) => b.score - a.score).slice(0, limit).map((s) => ({ ...s.entity, _rrf_score: s.score }));
+}
+function registerEntityTools(api) {
+  let syncTimer = null;
+  api.registerTool({
+    name: "entity_upsert",
+    description: "Register or update an entity in the unified entity registry. Makes the entity searchable and resolvable via {{type:id}} references.",
+    parameters: T.Object({
+      id: T.String({ description: "Unique entity ID" }),
+      type: EntityType,
+      name: T.String({ description: "Primary display name" }),
+      title: T.Optional(T.String({ description: "Longer title" })),
+      description: T.Optional(T.String({ description: "Description text" })),
+      metadata: T.Optional(
+        T.Any({ description: "JSON object with type-specific data" })
+      ),
+      source: T.Optional(
+        T.String({
+          description: "Origin: gateway, filesystem, plugin, manual"
+        })
+      ),
+      sourceKey: T.Optional(
+        T.String({ description: "Source-specific identifier" })
+      ),
+      content: T.Optional(
+        T.String({
+          description: "Additional searchable text content (e.g., file contents, memory text)"
+        })
+      )
+    }),
+    async execute(_id, params, _ctx) {
+      const configDir2 = _ctx?.configDir ?? process.env.HOME + "/.openclaw";
+      const database = getDb(configDir2);
+      const now = Date.now();
+      const existing = database.prepare("SELECT created_at FROM entities WHERE id = ?").get(params.id);
+      const createdAt = existing?.created_at ?? now;
+      database.prepare(
+        `INSERT INTO entities (id, type, name, title, description, metadata, source, source_key, created_at, updated_at)
+           VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+           ON CONFLICT(id) DO UPDATE SET
+             type = excluded.type,
+             name = excluded.name,
+             title = excluded.title,
+             description = excluded.description,
+             metadata = excluded.metadata,
+             source = excluded.source,
+             source_key = excluded.source_key,
+             updated_at = excluded.updated_at`
+      ).run(
+        params.id,
+        params.type,
+        params.name,
+        params.title ?? null,
+        params.description ?? null,
+        params.metadata ? JSON.stringify(params.metadata) : null,
+        params.source ?? "manual",
+        params.sourceKey ?? null,
+        createdAt,
+        now
+      );
+      ftsUpsert(
+        database,
+        params.id,
+        params.type,
+        params.name,
+        params.title ?? null,
+        params.description ?? null,
+        params.content ?? ""
+      );
+      const entity = database.prepare("SELECT * FROM entities WHERE id = ?").get(params.id);
+      return {
+        content: [{ type: "text", text: JSON.stringify(entityRow(entity)) }]
+      };
+    }
+  });
+  api.registerTool({
+    name: "entity_get",
+    description: "Get a single entity by ID with full details. Used for reference resolution.",
+    parameters: T.Object({
+      entityId: T.String({ description: "The entity ID to retrieve" })
+    }),
+    async execute(_id, params, _ctx) {
+      const configDir2 = _ctx?.configDir ?? process.env.HOME + "/.openclaw";
+      const database = getDb(configDir2);
+      const entity = database.prepare("SELECT * FROM entities WHERE id = ?").get(params.entityId);
+      if (!entity) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify({ error: "Entity not found" })
+            }
+          ],
+          isError: true
+        };
+      }
+      return {
+        content: [{ type: "text", text: JSON.stringify(entityRow(entity)) }]
+      };
+    }
+  });
+  api.registerTool({
+    name: "entity_list",
+    description: "List entities with optional type and source filters.",
+    parameters: T.Object({
+      type: T.Optional(EntityType),
+      source: T.Optional(T.String({ description: "Filter by source" })),
+      limit: T.Optional(
+        T.Number({ description: "Max results (default 100)" })
+      )
+    }),
+    async execute(_id, params, _ctx) {
+      const configDir2 = _ctx?.configDir ?? process.env.HOME + "/.openclaw";
+      const database = getDb(configDir2);
+      const conditions = [];
+      const values = [];
+      if (params.type) {
+        conditions.push("type = ?");
+        values.push(params.type);
+      }
+      if (params.source) {
+        conditions.push("source = ?");
+        values.push(params.source);
+      }
+      const where = conditions.length > 0 ? `WHERE ${conditions.join(" AND ")}` : "";
+      const limit = params.limit ?? 100;
+      const entities = database.prepare(
+        `SELECT * FROM entities ${where} ORDER BY updated_at DESC LIMIT ?`
+      ).all(...values, limit);
+      return {
+        content: [
+          { type: "text", text: JSON.stringify(entities.map(entityRow)) }
+        ]
+      };
+    }
+  });
+  api.registerTool({
+    name: "entity_delete",
+    description: "Delete an entity from the registry by ID. Also removes FTS and vector data.",
+    parameters: T.Object({
+      entityId: T.String({ description: "The entity ID to delete" })
+    }),
+    async execute(_id, params, _ctx) {
+      const configDir2 = _ctx?.configDir ?? process.env.HOME + "/.openclaw";
+      const database = getDb(configDir2);
+      const del = database.transaction(() => {
+        const result2 = database.prepare("DELETE FROM entities WHERE id = ?").run(params.entityId);
+        ftsDelete(database, params.entityId);
+        if (vecEnabled) {
+          database.prepare("DELETE FROM search_vec WHERE entity_id = ?").run(params.entityId);
+        }
+        return result2;
+      });
+      const result = del();
+      if (result.changes === 0) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify({ error: "Entity not found" })
+            }
+          ],
+          isError: true
+        };
+      }
+      return {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify({ deleted: params.entityId })
+          }
+        ]
+      };
+    }
+  });
+  api.registerTool({
+    name: "entity_search",
+    description: "Search entities using full-text search, vector search, or hybrid. Returns ranked results.",
+    parameters: T.Object({
+      query: T.String({ description: "Search query text" }),
+      type: T.Optional(
+        T.String({ description: "Filter results by entity type" })
+      ),
+      mode: T.Optional(
+        T.Union(
+          [T.Literal("fts"), T.Literal("vector"), T.Literal("hybrid")],
+          {
+            description: "Search mode: fts (full-text, default), vector (semantic), hybrid (both merged via RRF)"
+          }
+        )
+      ),
+      limit: T.Optional(
+        T.Number({ description: "Max results (default 20)" })
+      )
+    }),
+    async execute(_id, params, _ctx) {
+      const configDir2 = _ctx?.configDir ?? process.env.HOME + "/.openclaw";
+      const database = getDb(configDir2);
+      const mode = params.mode ?? "fts";
+      const limit = params.limit ?? 20;
+      let results;
+      if (mode === "fts") {
+        results = ftsSearch(database, params.query, params.type, limit);
+      } else if (mode === "vector") {
+        if (!vecEnabled) {
+          return {
+            content: [
+              {
+                type: "text",
+                text: JSON.stringify({
+                  error: "Vector search unavailable \u2014 sqlite-vec extension not loaded"
+                })
+              }
+            ],
+            isError: true
+          };
+        }
+        const embedding = await generateEmbedding(params.query, configDir2);
+        if (!embedding) {
+          return {
+            content: [
+              {
+                type: "text",
+                text: JSON.stringify({
+                  error: "Embedding generation failed \u2014 check embeddings config in openclaw.json"
+                })
+              }
+            ],
+            isError: true
+          };
+        }
+        results = vecSearch(database, embedding, limit);
+        if (params.type) {
+          results = results.filter((r) => r.type === params.type);
+        }
+      } else {
+        const ftsResults = ftsSearch(
+          database,
+          params.query,
+          params.type,
+          limit
+        );
+        let vecResults = [];
+        if (vecEnabled) {
+          const embedding = await generateEmbedding(params.query, configDir2);
+          if (embedding) {
+            vecResults = vecSearch(database, embedding, limit);
+            if (params.type) {
+              vecResults = vecResults.filter(
+                (r) => r.type === params.type
+              );
+            }
+          }
+        }
+        results = hybridSearch(database, ftsResults, vecResults, limit);
+      }
+      return {
+        content: [{ type: "text", text: JSON.stringify(results) }]
+      };
+    }
+  });
+  api.registerTool({
+    name: "entity_batch_resolve",
+    description: "Resolve multiple entity IDs in a single call. Returns a map of ID to entity data. Missing entities are omitted.",
+    parameters: T.Object({
+      entityIds: T.Array(T.String(), {
+        description: "Array of entity IDs to resolve"
+      })
+    }),
+    async execute(_id, params, _ctx) {
+      const configDir2 = _ctx?.configDir ?? process.env.HOME + "/.openclaw";
+      const database = getDb(configDir2);
+      if (!params.entityIds || params.entityIds.length === 0) {
+        return {
+          content: [{ type: "text", text: JSON.stringify({}) }]
+        };
+      }
+      const placeholders = params.entityIds.map(() => "?").join(",");
+      const entities = database.prepare(`SELECT * FROM entities WHERE id IN (${placeholders})`).all(...params.entityIds);
+      const result = {};
+      for (const entity of entities) {
+        const parsed = entityRow(entity);
+        result[parsed.id] = parsed;
+      }
+      return {
+        content: [{ type: "text", text: JSON.stringify(result) }]
+      };
+    }
+  });
+  api.registerTool({
+    name: "entity_embed",
+    description: "Generate and store a vector embedding for an entity using OpenRouter (google/gemini-embedding-001). Requires embeddings config in openclaw.json.",
+    parameters: T.Object({
+      entityId: T.String({
+        description: "The entity ID to generate an embedding for"
+      })
+    }),
+    async execute(_id, params, _ctx) {
+      const configDir2 = _ctx?.configDir ?? process.env.HOME + "/.openclaw";
+      const database = getDb(configDir2);
+      if (!vecEnabled) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify({
+                error: "Vector search unavailable \u2014 sqlite-vec extension not loaded"
+              })
+            }
+          ],
+          isError: true
+        };
+      }
+      const entity = database.prepare("SELECT * FROM entities WHERE id = ?").get(params.entityId);
+      if (!entity) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify({ error: "Entity not found" })
+            }
+          ],
+          isError: true
+        };
+      }
+      const text = buildEmbeddingText(entity);
+      const embedding = await generateEmbedding(text, configDir2);
+      if (!embedding) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify({
+                error: "Embedding generation failed \u2014 check embeddings config in openclaw.json"
+              })
+            }
+          ],
+          isError: true
+        };
+      }
+      vecUpsert(database, params.entityId, embedding);
+      return {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify({
+              entityId: params.entityId,
+              dimensions: embedding.length,
+              embedded: true
+            })
+          }
+        ]
+      };
+    }
+  });
+  api.registerTool({
+    name: "entity_sync",
+    description: "Reconcile the entity registry with data on the filesystem (agents, tools from openclaw.json). Call this after configuration changes to ensure the registry is up to date.",
+    parameters: T.Object({
+      sources: T.Optional(
+        T.Array(T.String(), {
+          description: "Which sources to sync: 'agents', 'tools'. Default: all."
+        })
+      )
+    }),
+    async execute(_id, _params, _ctx) {
+      const configDir2 = _ctx?.configDir ?? process.env.HOME + "/.openclaw";
+      const database = getDb(configDir2);
+      const result = syncEntitiesFromFilesystem(database, configDir2);
+      return {
+        content: [{ type: "text", text: JSON.stringify(result) }]
+      };
+    }
+  });
+  const configDir = process.env.HOME + "/.openclaw";
+  try {
+    const database = getDb(configDir);
+    syncEntitiesFromFilesystem(database, configDir);
+  } catch {
+  }
+  syncTimer = setInterval(() => {
+    try {
+      if (db) {
+        syncEntitiesFromFilesystem(db, configDir);
+      }
+    } catch {
+    }
+  }, SYNC_INTERVAL_MS);
+}
+
+// src/filesystem.ts
+import fs2 from "fs";
+import path2 from "path";
+function expandHome(p) {
+  if (p.startsWith("~/") || p === "~") {
+    return path2.join(process.env.HOME ?? "/root", p.slice(1));
+  }
+  return p;
+}
+function validatePath(p, allowedRoots) {
+  const resolved = path2.resolve(expandHome(p));
+  if (!allowedRoots || allowedRoots.length === 0) return resolved;
+  const allowed = allowedRoots.some((root) => {
+    const resolvedRoot = path2.resolve(expandHome(root));
+    return resolved === resolvedRoot || resolved.startsWith(resolvedRoot + path2.sep);
+  });
+  if (!allowed) {
+    throw new Error(`Path "${p}" is outside allowed roots`);
+  }
+  return resolved;
+}
+function ok(data) {
+  return {
+    content: [{ type: "text", text: JSON.stringify(data) }]
+  };
+}
+function err(message) {
+  return {
+    content: [{ type: "text", text: JSON.stringify({ error: message }) }],
+    isError: true
+  };
+}
+function listDir(dirPath, opts) {
+  const dirents = fs2.readdirSync(dirPath, { withFileTypes: true });
+  const results = [];
+  for (const dirent of dirents) {
+    if (!opts.includeHidden && dirent.name.startsWith(".")) continue;
+    const entryPath = path2.join(dirPath, dirent.name);
+    let type = "other";
+    if (dirent.isFile()) type = "file";
+    else if (dirent.isDirectory()) type = "directory";
+    else if (dirent.isSymbolicLink()) type = "symlink";
+    const entry = { name: dirent.name, path: entryPath, type };
+    try {
+      const stat = fs2.statSync(entryPath);
+      entry.size = stat.size;
+      entry.modified = stat.mtime.toISOString();
+    } catch {
+    }
+    if (type === "directory" && opts.recursive && opts.depth < opts.maxDepth) {
+      try {
+        entry.children = listDir(entryPath, { ...opts, depth: opts.depth + 1 });
+      } catch {
+      }
+    }
+    results.push(entry);
+  }
+  return results;
+}
+function registerFilesystemTools(api) {
+  const allowedRoots = api.pluginConfig?.["fs.allowedRoots"] ?? [];
+  api.registerTool({
+    name: "fs_read",
+    label: "Read File",
+    description: "Read a file from the server filesystem. Returns the file contents as text. Supports ~ for home directory expansion.",
+    parameters: {
+      type: "object",
+      properties: {
+        path: {
+          type: "string",
+          description: "Absolute or ~-prefixed path to the file to read"
+        },
+        encoding: {
+          type: "string",
+          description: "File encoding (default: utf-8)",
+          enum: ["utf-8", "base64", "ascii", "latin1"]
+        }
+      },
+      required: ["path"]
+    },
+    async execute(_id, params) {
+      try {
+        const filePath = validatePath(params.path, allowedRoots);
+        const encoding = params.encoding ?? "utf-8";
+        const content = fs2.readFileSync(filePath, encoding);
+        const stat = fs2.statSync(filePath);
+        return ok({
+          path: filePath,
+          content,
+          size: stat.size,
+          modified: stat.mtime.toISOString()
+        });
+      } catch (e) {
+        const msg = e instanceof Error ? e.message : String(e);
+        return err(`fs_read failed: ${msg}`);
+      }
+    }
+  });
+  api.registerTool({
+    name: "fs_write",
+    label: "Write File",
+    description: "Write content to a file on the server filesystem. Creates parent directories if they don't exist. Supports ~ for home directory expansion.",
+    parameters: {
+      type: "object",
+      properties: {
+        path: {
+          type: "string",
+          description: "Absolute or ~-prefixed path to the file to write"
+        },
+        content: {
+          type: "string",
+          description: "Content to write to the file"
+        },
+        encoding: {
+          type: "string",
+          description: "File encoding (default: utf-8)",
+          enum: ["utf-8", "base64", "ascii", "latin1"]
+        },
+        mkdir: {
+          type: "boolean",
+          description: "Create parent directories if they don't exist (default: true)"
+        }
+      },
+      required: ["path", "content"]
+    },
+    async execute(_id, params) {
+      try {
+        const filePath = validatePath(params.path, allowedRoots);
+        const content = params.content;
+        const encoding = params.encoding ?? "utf-8";
+        const mkdir = params.mkdir !== false;
+        if (mkdir) {
+          fs2.mkdirSync(path2.dirname(filePath), { recursive: true });
+        }
+        fs2.writeFileSync(filePath, content, encoding);
+        const stat = fs2.statSync(filePath);
+        return ok({
+          path: filePath,
+          size: stat.size,
+          written: true
+        });
+      } catch (e) {
+        const msg = e instanceof Error ? e.message : String(e);
+        return err(`fs_write failed: ${msg}`);
+      }
+    }
+  });
+  api.registerTool({
+    name: "fs_list",
+    label: "List Directory",
+    description: "List contents of a directory on the server filesystem. Returns file metadata including name, type, size, and modification time. Supports ~ for home directory expansion.",
+    parameters: {
+      type: "object",
+      properties: {
+        path: {
+          type: "string",
+          description: "Absolute or ~-prefixed path to the directory to list"
+        },
+        recursive: {
+          type: "boolean",
+          description: "List recursively (default: false, max depth 3)"
+        },
+        includeHidden: {
+          type: "boolean",
+          description: "Include hidden files/directories starting with . (default: false)"
+        }
+      },
+      required: ["path"]
+    },
+    async execute(_id, params) {
+      try {
+        const dirPath = validatePath(params.path, allowedRoots);
+        const recursive = params.recursive === true;
+        const includeHidden = params.includeHidden === true;
+        const entries = listDir(dirPath, { recursive, includeHidden, depth: 0, maxDepth: 3 });
+        return ok({
+          path: dirPath,
+          count: entries.length,
+          entries
+        });
+      } catch (e) {
+        const msg = e instanceof Error ? e.message : String(e);
+        return err(`fs_list failed: ${msg}`);
+      }
+    }
+  });
+}
+
+// src/version.ts
+import { execSync } from "child_process";
+import fs3 from "fs";
+import path3 from "path";
+import { fileURLToPath } from "url";
+var PACKAGE_NAME = "squad-openclaw";
+function getCurrentVersion() {
+  const thisFile = fileURLToPath(import.meta.url);
+  const pkgPath = path3.resolve(path3.dirname(thisFile), "..", "package.json");
+  try {
+    const pkg = JSON.parse(fs3.readFileSync(pkgPath, "utf-8"));
+    return pkg.version ?? "0.0.0";
+  } catch {
+    return "0.0.0";
+  }
+}
+async function fetchLatestVersion() {
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), 1e4);
+  try {
+    const res = await fetch(`https://registry.npmjs.org/${PACKAGE_NAME}`, {
+      signal: controller.signal
+    });
+    if (!res.ok) throw new Error(`npm registry returned ${res.status}`);
+    const data = await res.json();
+    return data["dist-tags"]?.latest ?? "0.0.0";
+  } finally {
+    clearTimeout(timeout);
+  }
+}
+function registerVersionMethods(api) {
+  api.registerGatewayMethod(
+    "squad.version.check",
+    async ({ respond }) => {
+      try {
+        const current = getCurrentVersion();
+        let latest;
+        try {
+          latest = await fetchLatestVersion();
+        } catch {
+          respond(true, {
+            current,
+            latest: null,
+            updateAvailable: false,
+            registryError: "Could not reach npm registry"
+          });
+          return;
+        }
+        respond(true, {
+          current,
+          latest,
+          updateAvailable: latest !== current && latest !== "0.0.0"
+        });
+      } catch (e) {
+        const msg = e instanceof Error ? e.message : String(e);
+        respond(false, { error: msg });
+      }
+    }
+  );
+  api.registerGatewayMethod(
+    "squad.version.update",
+    async ({ respond }) => {
+      try {
+        const before = getCurrentVersion();
+        let updateOutput = "";
+        try {
+          updateOutput = execSync(
+            `openclaw plugins update ${PACKAGE_NAME} 2>&1`,
+            { timeout: 12e4, encoding: "utf-8" }
+          );
+        } catch {
+          try {
+            updateOutput = execSync(
+              `npm install -g ${PACKAGE_NAME}@latest 2>&1`,
+              { timeout: 12e4, encoding: "utf-8" }
+            );
+          } catch (npmErr) {
+            const msg = npmErr instanceof Error ? npmErr.message : String(npmErr);
+            respond(false, {
+              error: `Update failed: ${msg}`,
+              output: updateOutput
+            });
+            return;
+          }
+        }
+        const after = getCurrentVersion();
+        const updated = before !== after;
+        respond(true, {
+          previousVersion: before,
+          currentVersion: after,
+          updated,
+          restartRequired: updated,
+          output: updateOutput.slice(0, 500)
+        });
+      } catch (e) {
+        const msg = e instanceof Error ? e.message : String(e);
+        respond(false, { error: msg });
+      }
+    }
+  );
+}
+
+// src/index.ts
+function squadAppPlugin(api) {
+  registerEntityTools(api);
+  registerFilesystemTools(api);
+  registerVersionMethods(api);
+}
+export {
+  squadAppPlugin as default
+};

package/openclaw.plugin.json

@@ -0,0 +1,16 @@
+{
+  "id": "squad-app",
+  "name": "Squad App",
+  "description": "Entity registry with FTS/vector search, filesystem tools, and self-update for Squad",
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {
+      "fs.allowedRoots": {
+        "type": "array",
+        "items": { "type": "string" },
+        "description": "Restrict fs_read/fs_write/fs_list to these directories. Empty or omitted = allow all."
+      }
+    }
+  }
+}

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "squad-openclaw",
+  "version": "1.0.0",
+  "description": "Entity registry, filesystem tools, and version management plugin for OpenClaw gateway",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "openclaw": {
+    "extensions": ["./dist/index.js"]
+  },
+  "files": [
+    "dist/",
+    "openclaw.plugin.json"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": ["openclaw", "openclaw-plugin", "squad"],
+  "dependencies": {
+    "@sinclair/typebox": "^0.31.0",
+    "better-sqlite3": "^11.0.0"
+  },
+  "optionalDependencies": {
+    "sqlite-vec": "^0.1.6"
+  },
+  "devDependencies": {
+    "@types/better-sqlite3": "^7.6.8",
+    "tsup": "^8.0.0",
+    "typescript": "^5.0.0"
+  }
+}