agentlife 1.0.0

package/index.test.ts

@@ -0,0 +1,1905 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import * as fs from "node:fs/promises";
+import { mkdtempSync } from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+
+// ---------------------------------------------------------------------------
+// Mock API factory
+// ---------------------------------------------------------------------------
+
+function createMockApi(configOverride?: { agents?: { list: any[] } }) {
+  const services: { id: string; start: Function; stop?: Function }[] = [];
+  const hooks: { events: string; handler: Function; opts?: any }[] = [];
+  const gatewayMethods: { method: string; handler: Function }[] = [];
+  const onHooks: { hookName: string; handler: Function }[] = [];
+
+  const configData: any = configOverride ?? { agents: { list: [] } };
+  const writeConfigCalls: any[] = [];
+
+  const api = {
+    id: "agentlife",
+    name: "AgentLife",
+    source: "test",
+    config: {},
+    pluginConfig: {},
+    runtime: {
+      config: {
+        loadConfig: vi.fn(() => configData),
+        writeConfigFile: vi.fn(async (cfg: any) => {
+          writeConfigCalls.push(structuredClone(cfg));
+          Object.assign(configData, cfg);
+        }),
+      },
+    },
+    logger: { info: vi.fn(), warn: vi.fn(), error: vi.fn(), debug: vi.fn() },
+    registerService: vi.fn((s: any) => services.push(s)),
+    registerHook: vi.fn((events: string, handler: Function, opts?: any) =>
+      hooks.push({ events, handler, opts }),
+    ),
+    registerGatewayMethod: vi.fn((method: string, handler: Function) =>
+      gatewayMethods.push({ method, handler }),
+    ),
+    on: vi.fn((hookName: string, handler: Function) =>
+      onHooks.push({ hookName, handler }),
+    ),
+    resolvePath: vi.fn((p: string) => p),
+  };
+
+  return { api, services, hooks, gatewayMethods, onHooks, writeConfigCalls, configData };
+}
+
+// ---------------------------------------------------------------------------
+// 1. Plugin registration
+// ---------------------------------------------------------------------------
+
+describe("plugin registration", () => {
+  it("registers expected services, hooks, and gateway methods", async () => {
+    vi.resetModules();
+    const { default: register } = await import("./index.ts");
+    const { api, services, hooks, gatewayMethods, onHooks } = createMockApi();
+    register(api as any);
+
+    expect(services.map((s) => s.id)).toEqual([
+      "agentlife-surfaces",
+      "agentlife-provisioning",
+    ]);
+
+    expect(hooks).toHaveLength(1);
+    expect(hooks[0].events).toBe("agent:bootstrap");
+
+    expect(onHooks).toHaveLength(1);
+    expect(onHooks[0].hookName).toBe("after_tool_call");
+
+    expect(gatewayMethods.map((m) => m.method).sort()).toEqual([
+      "agentlife.agents",
+      "agentlife.bootstrap",
+      "agentlife.createAgent",
+      "agentlife.db.exec",
+      "agentlife.db.query",
+      "agentlife.dismiss",
+      "agentlife.history",
+      "agentlife.surfaces",
+    ]);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// 2. Orchestrator prompt content
+// ---------------------------------------------------------------------------
+
+describe("orchestrator prompt content", () => {
+  let tmpDir: string;
+
+  beforeEach(() => {
+    tmpDir = mkdtempSync(path.join(os.tmpdir(), "agentlife-test-"));
+    vi.stubEnv("HOME", tmpDir);
+  });
+
+  afterEach(async () => {
+    await fs.rm(tmpDir, { recursive: true, force: true });
+  });
+
+  it("contains correct routing instructions", async () => {
+    vi.resetModules();
+    const { default: register } = await import("./index.ts");
+    const { api, services } = createMockApi();
+    register(api as any);
+
+    await services.find((s) => s.id === "agentlife-provisioning")!.start();
+
+    const agentsMd = await fs.readFile(
+      path.join(tmpDir, ".openclaw", "workspace-agentlife", "AGENTS.md"),
+      "utf-8",
+    );
+
+    expect(agentsMd).toContain("You are a message router");
+    expect(agentsMd).toContain("Never answer directly");
+    expect(agentsMd).toContain("Never use the canvas tool");
+    expect(agentsMd).toContain("AGENT_REGISTRY.md");
+    expect(agentsMd).toContain("agents_list");
+    expect(agentsMd).toContain("sessions_send");
+    expect(agentsMd).toContain("sessions_spawn");
+    expect(agentsMd).toContain("Multi-Agent Fan-Out");
+    expect(agentsMd).toContain("agentlife-builder");
+    expect(agentsMd).toContain("Not a chatbot");
+    expect(agentsMd).toContain("you ARE the assistant");
+    expect(agentsMd).toContain("Cannot reach");
+  });
+});
+
+// ---------------------------------------------------------------------------
+// 3. Builder prompt content
+// ---------------------------------------------------------------------------
+
+describe("builder prompt content", () => {
+  let tmpDir: string;
+
+  beforeEach(() => {
+    tmpDir = mkdtempSync(path.join(os.tmpdir(), "agentlife-test-"));
+    vi.stubEnv("HOME", tmpDir);
+  });
+
+  afterEach(async () => {
+    await fs.rm(tmpDir, { recursive: true, force: true });
+  });
+
+  it("contains correct builder instructions", async () => {
+    vi.resetModules();
+    const { default: register } = await import("./index.ts");
+    const { api, services } = createMockApi();
+    register(api as any);
+
+    await services.find((s) => s.id === "agentlife-provisioning")!.start();
+
+    const agentsMd = await fs.readFile(
+      path.join(
+        tmpDir,
+        ".openclaw",
+        "workspace-agentlife-builder",
+        "AGENTS.md",
+      ),
+      "utf-8",
+    );
+
+    expect(agentsMd).toContain(
+      "expert at creating and improving OpenClaw agents",
+    );
+    expect(agentsMd).toContain("Interactive Overlays");
+    expect(agentsMd).toContain("NEVER ask multiple questions in text");
+    expect(agentsMd).toContain("overlay");
+    expect(agentsMd).toContain("agentlife.createAgent");
+    expect(agentsMd).toContain("description");
+    // Model guide should NOT be present — models are provider-agnostic
+    expect(agentsMd).not.toContain("Default to **sonnet**");
+  });
+});
+
+// ---------------------------------------------------------------------------
+// 4. Agent provisioning
+// ---------------------------------------------------------------------------
+
+describe("agent provisioning", () => {
+  let tmpDir: string;
+
+  beforeEach(() => {
+    tmpDir = mkdtempSync(path.join(os.tmpdir(), "agentlife-test-"));
+    vi.stubEnv("HOME", tmpDir);
+  });
+
+  afterEach(async () => {
+    await fs.rm(tmpDir, { recursive: true, force: true });
+  });
+
+  it("creates workspace directories for both agents", async () => {
+    vi.resetModules();
+    const { default: register } = await import("./index.ts");
+    const { api, services } = createMockApi();
+    register(api as any);
+
+    await services.find((s) => s.id === "agentlife-provisioning")!.start();
+
+    const orchestratorStat = await fs.stat(
+      path.join(tmpDir, ".openclaw", "workspace-agentlife"),
+    );
+    expect(orchestratorStat.isDirectory()).toBe(true);
+
+    const builderStat = await fs.stat(
+      path.join(tmpDir, ".openclaw", "workspace-agentlife-builder"),
+    );
+    expect(builderStat.isDirectory()).toBe(true);
+  });
+
+  it("writes AGENTS.md in each workspace", async () => {
+    vi.resetModules();
+    const { default: register } = await import("./index.ts");
+    const { api, services } = createMockApi();
+    register(api as any);
+
+    await services.find((s) => s.id === "agentlife-provisioning")!.start();
+
+    const orchestratorMd = await fs.readFile(
+      path.join(tmpDir, ".openclaw", "workspace-agentlife", "AGENTS.md"),
+      "utf-8",
+    );
+    expect(orchestratorMd.length).toBeGreaterThan(0);
+
+    const builderMd = await fs.readFile(
+      path.join(
+        tmpDir,
+        ".openclaw",
+        "workspace-agentlife-builder",
+        "AGENTS.md",
+      ),
+      "utf-8",
+    );
+    expect(builderMd.length).toBeGreaterThan(0);
+  });
+
+  it("writes empty stub files to prevent boilerplate", async () => {
+    vi.resetModules();
+    const { default: register } = await import("./index.ts");
+    const { api, services } = createMockApi();
+    register(api as any);
+
+    await services.find((s) => s.id === "agentlife-provisioning")!.start();
+
+    const stubs = [
+      "SOUL.md",
+      "TOOLS.md",
+      "IDENTITY.md",
+      "USER.md",
+      "HEARTBEAT.md",
+      "BOOTSTRAP.md",
+    ];
+    for (const stub of stubs) {
+      const content = await fs.readFile(
+        path.join(tmpDir, ".openclaw", "workspace-agentlife", stub),
+        "utf-8",
+      );
+      expect(content).toBe("");
+    }
+  });
+
+  it("adds both agents to config with orchestrator first and default", async () => {
+    vi.resetModules();
+    const { default: register } = await import("./index.ts");
+    const { api, services, writeConfigCalls } = createMockApi();
+    register(api as any);
+
+    await services.find((s) => s.id === "agentlife-provisioning")!.start();
+
+    expect(api.runtime.config.writeConfigFile).toHaveBeenCalledTimes(1);
+    const list = writeConfigCalls[0].agents.list;
+
+    expect(list[0].id).toBe("agentlife");
+    expect(list[0].default).toBe(true);
+    expect(list[0].subagents).toEqual({ allowAgents: ["*"] });
+
+    expect(list[1].id).toBe("agentlife-builder");
+  });
+
+  it("is idempotent — second run does not call writeConfigFile", async () => {
+    vi.resetModules();
+    const { default: register } = await import("./index.ts");
+    const { api, services } = createMockApi();
+    register(api as any);
+
+    await services.find((s) => s.id === "agentlife-provisioning")!.start();
+    expect(api.runtime.config.writeConfigFile).toHaveBeenCalledTimes(1);
+
+    vi.clearAllMocks();
+    await services.find((s) => s.id === "agentlife-provisioning")!.start();
+    expect(api.runtime.config.writeConfigFile).not.toHaveBeenCalled();
+  });
+
+  it("preserves existing user agents in list", async () => {
+    vi.resetModules();
+    const { default: register } = await import("./index.ts");
+    const userAgent = {
+      id: "my-agent",
+      name: "My Agent",
+      workspace: "/tmp/my-agent",
+    };
+    const { api, services, writeConfigCalls } = createMockApi({
+      agents: { list: [userAgent] },
+    });
+    register(api as any);
+
+    await services.find((s) => s.id === "agentlife-provisioning")!.start();
+
+    const list = writeConfigCalls[0].agents.list;
+    expect(list.some((a: any) => a.id === "my-agent")).toBe(true);
+    expect(list[0].id).toBe("agentlife");
+    expect(list[list.length - 1].id).toBe("agentlife-builder");
+  });
+});
+
+// ---------------------------------------------------------------------------
+// 5. Bootstrap injection
+// ---------------------------------------------------------------------------
+
+describe("bootstrap injection", () => {
+  let tmpDir: string;
+  let register: (api: any) => void;
+  let api: ReturnType<typeof createMockApi>["api"];
+  let hooks: ReturnType<typeof createMockApi>["hooks"];
+  let services: ReturnType<typeof createMockApi>["services"];
+  let gatewayMethods: ReturnType<typeof createMockApi>["gatewayMethods"];
+
+  beforeEach(async () => {
+    tmpDir = mkdtempSync(path.join(os.tmpdir(), "agentlife-test-"));
+    vi.resetModules();
+    const mod = await import("./index.ts");
+    register = mod.default;
+    const mock = createMockApi();
+    api = mock.api;
+    hooks = mock.hooks;
+    services = mock.services;
+    gatewayMethods = mock.gatewayMethods;
+    register(api as any);
+  });
+
+  afterEach(async () => {
+    await fs.rm(tmpDir, { recursive: true, force: true });
+  });
+
+  function bootstrapHandler() {
+    return hooks.find((h) => h.events === "agent:bootstrap")!.handler;
+  }
+
+  it("replaces TOOLS.md with TENAZITAS_GUIDANCE for regular agents", () => {
+    const bootstrapFiles = [
+      {
+        name: "TOOLS.md",
+        path: "/some/path/TOOLS.md",
+        content: "original",
+        missing: false,
+      },
+    ];
+    bootstrapHandler()({ context: { bootstrapFiles, agentId: "some-agent" } });
+
+    const toolsFile = bootstrapFiles.find((f) => f.name === "TOOLS.md")!;
+    expect(toolsFile.content).toContain("a2ui_push");
+    expect(toolsFile.content).toContain("WidgetDSL");
+    expect(toolsFile.content).toContain("overlay");
+    expect(toolsFile.path).toBe("agentlife://a2ui-guidance");
+  });
+
+  it("injects TENAZITAS_GUIDANCE for builder agent (not skipped)", () => {
+    const bootstrapFiles = [
+      {
+        name: "TOOLS.md",
+        path: "/some/path/TOOLS.md",
+        content: "original",
+        missing: false,
+      },
+    ];
+    bootstrapHandler()({
+      context: { bootstrapFiles, agentId: "agentlife-builder" },
+    });
+
+    const toolsFile = bootstrapFiles.find((f) => f.name === "TOOLS.md")!;
+    expect(toolsFile.content).toContain("a2ui_push");
+    expect(toolsFile.content).toContain("WidgetDSL");
+  });
+
+  it("does NOT replace TOOLS.md for orchestrator", () => {
+    const bootstrapFiles = [
+      {
+        name: "TOOLS.md",
+        path: "/path/TOOLS.md",
+        content: "original tools",
+        missing: false,
+      },
+    ];
+    bootstrapHandler()({
+      context: { bootstrapFiles, agentId: "agentlife" },
+    });
+
+    const toolsFile = bootstrapFiles.find((f) => f.name === "TOOLS.md")!;
+    expect(toolsFile.content).toBe("original tools");
+  });
+
+  it("injects AGENT_REGISTRY.md for orchestrator when registry has entries", async () => {
+    await services
+      .find((s) => s.id === "agentlife-surfaces")!
+      .start({ stateDir: tmpDir, config: {} });
+
+    const createAgent = gatewayMethods.find(
+      (m) => m.method === "agentlife.createAgent",
+    )!.handler;
+    await createAgent({
+      params: {
+        id: "test-specialist",
+        name: "Test",
+        workspace: "/tmp/test",
+        description: "Runs automated tests and validates code quality across the codebase",
+      },
+      respond: vi.fn(),
+    });
+
+    const bootstrapFiles: any[] = [];
+    bootstrapHandler()({
+      context: { bootstrapFiles, agentId: "agentlife" },
+    });
+
+    const regFile = bootstrapFiles.find(
+      (f: any) => f.name === "AGENT_REGISTRY.md",
+    );
+    expect(regFile).toBeTruthy();
+    expect(regFile.content).toContain("test-specialist");
+    expect(regFile.content).toContain("Runs automated tests");
+  });
+
+  it("does NOT inject AGENT_REGISTRY.md for orchestrator with empty registry", () => {
+    const bootstrapFiles: any[] = [];
+    bootstrapHandler()({
+      context: { bootstrapFiles, agentId: "agentlife" },
+    });
+
+    const regFile = bootstrapFiles.find(
+      (f: any) => f.name === "AGENT_REGISTRY.md",
+    );
+    expect(regFile).toBeUndefined();
+  });
+
+  it("handles missing bootstrapFiles without crashing", () => {
+    expect(() => bootstrapHandler()({ context: {} })).not.toThrow();
+  });
+
+  it("replaces existing TOOLS.md without creating duplicates", () => {
+    const bootstrapFiles = [
+      {
+        name: "AGENTS.md",
+        path: "/path/AGENTS.md",
+        content: "agent stuff",
+        missing: false,
+      },
+      {
+        name: "TOOLS.md",
+        path: "/path/TOOLS.md",
+        content: "old tools",
+        missing: false,
+      },
+      {
+        name: "SOUL.md",
+        path: "/path/SOUL.md",
+        content: "soul",
+        missing: false,
+      },
+    ];
+    bootstrapHandler()({
+      context: { bootstrapFiles, agentId: "some-agent" },
+    });
+
+    const toolsFiles = bootstrapFiles.filter((f) => f.name === "TOOLS.md");
+    expect(toolsFiles).toHaveLength(1);
+    expect(toolsFiles[0].content).toContain("a2ui_push");
+  });
+});
+
+// ---------------------------------------------------------------------------
+// 6. Gateway: agentlife.createAgent
+// ---------------------------------------------------------------------------
+
+describe("gateway: agentlife.createAgent", () => {
+  let tmpDir: string;
+
+  beforeEach(() => {
+    tmpDir = mkdtempSync(path.join(os.tmpdir(), "agentlife-test-"));
+  });
+
+  afterEach(async () => {
+    await fs.rm(tmpDir, { recursive: true, force: true });
+  });
+
+  it("creates new agent and responds with status created", async () => {
+    vi.resetModules();
+    const { default: register } = await import("./index.ts");
+    const { api, services, gatewayMethods } = createMockApi();
+    register(api as any);
+
+    await services
+      .find((s) => s.id === "agentlife-surfaces")!
+      .start({ stateDir: tmpDir, config: {} });
+
+    const createAgent = gatewayMethods.find(
+      (m) => m.method === "agentlife.createAgent",
+    )!.handler;
+    const respond = vi.fn();
+    await createAgent({
+      params: {
+        id: "new-agent",
+        name: "New Agent",
+        workspace: "/tmp/new-agent",
+        description: "Does new things",
+      },
+      respond,
+    });
+
+    expect(respond).toHaveBeenCalledWith(
+      true,
+      expect.objectContaining({ status: "created", id: "new-agent" }),
+    );
+    expect(api.runtime.config.writeConfigFile).toHaveBeenCalled();
+  });
+
+  it("responds with status exists for duplicate agent", async () => {
+    vi.resetModules();
+    const { default: register } = await import("./index.ts");
+    const { api, services, gatewayMethods } = createMockApi({
+      agents: { list: [{ id: "existing-agent", workspace: "/tmp/existing" }] },
+    });
+    register(api as any);
+
+    await services
+      .find((s) => s.id === "agentlife-surfaces")!
+      .start({ stateDir: tmpDir, config: {} });
+
+    const createAgent = gatewayMethods.find(
+      (m) => m.method === "agentlife.createAgent",
+    )!.handler;
+    const respond = vi.fn();
+    await createAgent({
+      params: {
+        id: "existing-agent",
+        name: "Existing",
+        workspace: "/tmp/existing",
+        description: "Already there",
+      },
+      respond,
+    });
+
+    expect(respond).toHaveBeenCalledWith(
+      true,
+      expect.objectContaining({ status: "exists" }),
+    );
+    expect(api.runtime.config.writeConfigFile).not.toHaveBeenCalled();
+  });
+
+  it("always updates registry when description provided", async () => {
+    vi.resetModules();
+    const { default: register } = await import("./index.ts");
+    const { api, services, gatewayMethods } = createMockApi({
+      agents: { list: [{ id: "existing-agent", workspace: "/tmp/existing" }] },
+    });
+    register(api as any);
+
+    await services
+      .find((s) => s.id === "agentlife-surfaces")!
+      .start({ stateDir: tmpDir, config: {} });
+
+    const createAgent = gatewayMethods.find(
+      (m) => m.method === "agentlife.createAgent",
+    )!.handler;
+    await createAgent({
+      params: {
+        id: "existing-agent",
+        name: "Updated",
+        workspace: "/tmp/existing",
+        description: "Monitors and updates existing agent configurations and workspaces",
+      },
+      respond: vi.fn(),
+    });
+
+    const agentsMethod = gatewayMethods.find(
+      (m) => m.method === "agentlife.agents",
+    )!.handler;
+    const respond = vi.fn();
+    agentsMethod({ respond });
+
+    expect(respond).toHaveBeenCalledWith(
+      true,
+      expect.objectContaining({
+        count: 1,
+        agents: expect.objectContaining({
+          "existing-agent": expect.objectContaining({
+            description: "Monitors and updates existing agent configurations and workspaces",
+          }),
+        }),
+      }),
+    );
+  });
+
+  it("rejects missing id", async () => {
+    vi.resetModules();
+    const { default: register } = await import("./index.ts");
+    const { api, gatewayMethods } = createMockApi();
+    register(api as any);
+
+    const createAgent = gatewayMethods.find(
+      (m) => m.method === "agentlife.createAgent",
+    )!.handler;
+    const respond = vi.fn();
+    await createAgent({ params: { workspace: "/tmp/test" }, respond });
+
+    expect(respond).toHaveBeenCalledWith(false, {
+      error: "missing agent id",
+    });
+  });
+
+  it("rejects missing workspace", async () => {
+    vi.resetModules();
+    const { default: register } = await import("./index.ts");
+    const { api, gatewayMethods } = createMockApi();
+    register(api as any);
+
+    const createAgent = gatewayMethods.find(
+      (m) => m.method === "agentlife.createAgent",
+    )!.handler;
+    const respond = vi.fn();
+    await createAgent({ params: { id: "test-agent" }, respond });
+
+    expect(respond).toHaveBeenCalledWith(false, {
+      error: "missing workspace path",
+    });
+  });
+
+  it("omits model when not specified (provider-agnostic)", async () => {
+    vi.resetModules();
+    const { default: register } = await import("./index.ts");
+    const { api, services, gatewayMethods } = createMockApi();
+    register(api as any);
+
+    await services
+      .find((s) => s.id === "agentlife-surfaces")!
+      .start({ stateDir: tmpDir, config: {} });
+
+    const createAgent = gatewayMethods.find(
+      (m) => m.method === "agentlife.createAgent",
+    )!.handler;
+    const respond = vi.fn();
+    await createAgent({
+      params: { id: "no-model-agent", workspace: "/tmp/test" },
+      respond,
+    });
+
+    expect(respond).toHaveBeenCalledWith(
+      true,
+      expect.objectContaining({ model: "" }),
+    );
+  });
+});
+
+// ---------------------------------------------------------------------------
+// 7. Gateway: agentlife.agents
+// ---------------------------------------------------------------------------
+
+describe("gateway: agentlife.agents", () => {
+  let tmpDir: string;
+
+  beforeEach(() => {
+    tmpDir = mkdtempSync(path.join(os.tmpdir(), "agentlife-test-"));
+  });
+
+  afterEach(async () => {
+    await fs.rm(tmpDir, { recursive: true, force: true });
+  });
+
+  it("returns empty when no agents registered", async () => {
+    vi.resetModules();
+    const { default: register } = await import("./index.ts");
+    const { api, gatewayMethods } = createMockApi();
+    register(api as any);
+
+    const agentsMethod = gatewayMethods.find(
+      (m) => m.method === "agentlife.agents",
+    )!.handler;
+    const respond = vi.fn();
+    agentsMethod({ respond });
+
+    expect(respond).toHaveBeenCalledWith(true, { agents: {}, count: 0 });
+  });
+
+  it("returns agent with description after createAgent", async () => {
+    vi.resetModules();
+    const { default: register } = await import("./index.ts");
+    const { api, services, gatewayMethods } = createMockApi();
+    register(api as any);
+
+    await services
+      .find((s) => s.id === "agentlife-surfaces")!
+      .start({ stateDir: tmpDir, config: {} });
+
+    const createAgent = gatewayMethods.find(
+      (m) => m.method === "agentlife.createAgent",
+    )!.handler;
+    await createAgent({
+      params: {
+        id: "weather-agent",
+        name: "Weather",
+        workspace: "/tmp/weather",
+        description: "Provides weather info",
+      },
+      respond: vi.fn(),
+    });
+
+    const agentsMethod = gatewayMethods.find(
+      (m) => m.method === "agentlife.agents",
+    )!.handler;
+    const respond = vi.fn();
+    agentsMethod({ respond });
+
+    expect(respond).toHaveBeenCalledWith(
+      true,
+      expect.objectContaining({
+        count: 1,
+        agents: expect.objectContaining({
+          "weather-agent": expect.objectContaining({
+            name: "Weather",
+            description: "Provides weather info",
+          }),
+        }),
+      }),
+    );
+  });
+});
+
+// ---------------------------------------------------------------------------
+// 8. End-to-end flow
+// ---------------------------------------------------------------------------
+
+describe("end-to-end flow", () => {
+  let tmpDir: string;
+
+  beforeEach(() => {
+    tmpDir = mkdtempSync(path.join(os.tmpdir(), "agentlife-test-"));
+    vi.stubEnv("HOME", tmpDir);
+  });
+
+  afterEach(async () => {
+    // Flush any in-flight scheduleSave setImmediate + async saveToDisk
+    await new Promise((r) => setImmediate(r));
+    await new Promise((r) => setTimeout(r, 20));
+    await fs.rm(tmpDir, { recursive: true, force: true });
+  });
+
+  it("register → provision → createAgent → bootstrap orchestrator → bootstrap specialist", async () => {
+    vi.resetModules();
+    const { default: register } = await import("./index.ts");
+    const { api, services, hooks, gatewayMethods } = createMockApi();
+    register(api as any);
+
+    // 1. Start surfaces service
+    await services
+      .find((s) => s.id === "agentlife-surfaces")!
+      .start({ stateDir: tmpDir, config: {} });
+
+    // 2. Start provisioning
+    await services
+      .find((s) => s.id === "agentlife-provisioning")!
+      .start();
+
+    // 3. Create a specialist agent with description
+    const createAgent = gatewayMethods.find(
+      (m) => m.method === "agentlife.createAgent",
+    )!.handler;
+    await createAgent({
+      params: {
+        id: "weather",
+        name: "Weather Bot",
+        workspace: "/tmp/weather",
+        description: "Provides weather forecasts and alerts",
+      },
+      respond: vi.fn(),
+    });
+
+    // 4. Bootstrap orchestrator — should get AGENT_REGISTRY.md
+    const bootstrap = hooks.find(
+      (h) => h.events === "agent:bootstrap",
+    )!.handler;
+    const orchestratorFiles: any[] = [];
+    bootstrap({
+      context: { bootstrapFiles: orchestratorFiles, agentId: "agentlife" },
+    });
+
+    const regFile = orchestratorFiles.find(
+      (f: any) => f.name === "AGENT_REGISTRY.md",
+    );
+    expect(regFile).toBeTruthy();
+    expect(regFile.content).toContain("weather");
+    expect(regFile.content).toContain(
+      "Provides weather forecasts and alerts",
+    );
+
+    // 5. Bootstrap specialist — should get TENAZITAS_GUIDANCE
+    const specialistFiles: any[] = [
+      {
+        name: "TOOLS.md",
+        path: "/path/TOOLS.md",
+        content: "",
+        missing: true,
+      },
+    ];
+    bootstrap({
+      context: { bootstrapFiles: specialistFiles, agentId: "weather" },
+    });
+
+    const toolsFile = specialistFiles.find(
+      (f: any) => f.name === "TOOLS.md",
+    );
+    expect(toolsFile).toBeTruthy();
+    expect(toolsFile.content).toContain("a2ui_push");
+    expect(toolsFile.content).toContain("WidgetDSL");
+  });
+});
+
+// ---------------------------------------------------------------------------
+// 9. after_tool_call hook (surface capture)
+// ---------------------------------------------------------------------------
+
+describe("after_tool_call hook", () => {
+  let afterToolCall: Function;
+  let surfacesMethod: Function;
+
+  beforeEach(async () => {
+    vi.resetModules();
+    const { default: register } = await import("./index.ts");
+    const { api, onHooks, gatewayMethods } = createMockApi();
+    register(api as any);
+
+    afterToolCall = onHooks.find(
+      (h) => h.hookName === "after_tool_call",
+    )!.handler;
+    surfacesMethod = gatewayMethods.find(
+      (m) => m.method === "agentlife.surfaces",
+    )!.handler;
+  });
+
+  function pushDsl(dsl: string) {
+    afterToolCall({
+      toolName: "canvas",
+      params: { action: "a2ui_push", jsonl: dsl },
+    });
+  }
+
+  function getSurfaces(): { surfaceId: string; dsl: string }[] {
+    const respond = vi.fn();
+    surfacesMethod({ respond });
+    return respond.mock.calls[0][1].surfaces;
+  }
+
+  it("stores surface from a2ui_push", () => {
+    pushDsl('surface weather w=6\n  card\n    text "Weather" h3');
+    const surfaces = getSurfaces();
+    expect(surfaces).toHaveLength(1);
+    expect(surfaces[0].surfaceId).toBe("weather");
+  });
+
+  it("stores multiple surfaces separated by ---", () => {
+    pushDsl(
+      'surface weather w=6\n  card\n    text "Weather" h3\n---\nsurface stocks w=4\n  card\n    text "Stocks" h3',
+    );
+    const surfaces = getSurfaces();
+    expect(surfaces).toHaveLength(2);
+    expect(surfaces.map((s) => s.surfaceId).sort()).toEqual([
+      "stocks",
+      "weather",
+    ]);
+  });
+
+  it("deletes surface via delete command", () => {
+    pushDsl('surface weather w=6\n  card\n    text "Weather" h3');
+    expect(getSurfaces()).toHaveLength(1);
+
+    pushDsl("delete weather");
+    expect(getSurfaces()).toHaveLength(0);
+  });
+
+  it("does NOT store overlay surfaces", () => {
+    pushDsl(
+      'surface q1 overlay\n  card\n    text "Question?" h4\n    button "Yes" action=yes',
+    );
+    expect(getSurfaces()).toHaveLength(0);
+  });
+
+  it("clears all surfaces on a2ui_reset", () => {
+    pushDsl('surface weather w=6\n  card\n    text "Weather" h3');
+    pushDsl('surface stocks w=4\n  card\n    text "Stocks" h3');
+    expect(getSurfaces()).toHaveLength(2);
+
+    afterToolCall({
+      toolName: "canvas",
+      params: { action: "a2ui_reset" },
+    });
+    expect(getSurfaces()).toHaveLength(0);
+  });
+
+  it("ignores non-canvas tool calls", () => {
+    afterToolCall({ toolName: "exec", params: { command: "ls" } });
+    expect(getSurfaces()).toHaveLength(0);
+  });
+
+  it("ignores canvas calls with other actions", () => {
+    afterToolCall({
+      toolName: "canvas",
+      params: { action: "a2ui_list" },
+    });
+    expect(getSurfaces()).toHaveLength(0);
+  });
+
+  it("updates surface in place (same surfaceId)", () => {
+    pushDsl('surface weather w=6\n  card\n    text "Loading..." h3');
+    pushDsl('surface weather w=6\n  card\n    text "72F Sunny" h3');
+    const surfaces = getSurfaces();
+    expect(surfaces).toHaveLength(1);
+    expect(surfaces[0].dsl).toContain("72F Sunny");
+    expect(surfaces[0].dsl).not.toContain("Loading");
+  });
+});
+
+// ---------------------------------------------------------------------------
+// 10. Gateway: agentlife.surfaces (with expiry filtering)
+// ---------------------------------------------------------------------------
+
+describe("gateway: agentlife.surfaces (expiry filtering)", () => {
+  let afterToolCall: Function;
+  let surfacesMethod: Function;
+
+  beforeEach(async () => {
+    vi.useFakeTimers();
+    vi.setSystemTime(new Date("2026-03-05T12:00:00Z"));
+    vi.resetModules();
+    const { default: register } = await import("./index.ts");
+    const { api, onHooks, gatewayMethods } = createMockApi();
+    register(api as any);
+
+    afterToolCall = onHooks.find(
+      (h) => h.hookName === "after_tool_call",
+    )!.handler;
+    surfacesMethod = gatewayMethods.find(
+      (m) => m.method === "agentlife.surfaces",
+    )!.handler;
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  function pushDsl(dsl: string) {
+    afterToolCall({
+      toolName: "canvas",
+      params: { action: "a2ui_push", jsonl: dsl },
+    });
+  }
+
+  function getSurfaces(): { surfaceId: string; dsl: string }[] {
+    const respond = vi.fn();
+    surfacesMethod({ respond });
+    return respond.mock.calls[0][1].surfaces;
+  }
+
+  it("filters out expired surfaces (TTL exceeded)", () => {
+    pushDsl('surface weather w=6\n  card\n    text "Weather" h3\n  ttl: 30m');
+    expect(getSurfaces()).toHaveLength(1);
+
+    vi.advanceTimersByTime(31 * 60 * 1000);
+    expect(getSurfaces()).toHaveLength(0);
+  });
+
+  it("surfaces with ttl=none never expire", () => {
+    pushDsl('surface todo w=6\n  card\n    text "Todo" h3\n  ttl: none');
+    vi.advanceTimersByTime(30 * 24 * 60 * 60 * 1000); // 30 days
+    expect(getSurfaces()).toHaveLength(1);
+  });
+
+  it("filters surfaces past absolute expireAt", () => {
+    pushDsl(
+      'surface event w=6\n  card\n    text "Meeting" h3\n  expireAt: 2026-03-05T14:00:00Z',
+    );
+    expect(getSurfaces()).toHaveLength(1);
+
+    vi.advanceTimersByTime(3 * 60 * 60 * 1000); // +3h → 15:00
+    expect(getSurfaces()).toHaveLength(0);
+  });
+
+  it("applies default 7-day ceiling when no lifecycle fields", () => {
+    pushDsl('surface plain w=6\n  card\n    text "Plain" h3');
+    vi.advanceTimersByTime(6 * 24 * 60 * 60 * 1000); // 6 days
+    expect(getSurfaces()).toHaveLength(1);
+
+    vi.advanceTimersByTime(2 * 24 * 60 * 60 * 1000); // 8 days total
+    expect(getSurfaces()).toHaveLength(0);
+  });
+
+  it("expireHint prevents default 7-day ceiling", () => {
+    pushDsl(
+      'surface meeting w=6\n  card\n    text "Meeting" h3\n  expireHint: after the meeting ends',
+    );
+    vi.advanceTimersByTime(8 * 24 * 60 * 60 * 1000); // 8 days
+    expect(getSurfaces()).toHaveLength(1);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// 11. Gateway: agentlife.dismiss
+// ---------------------------------------------------------------------------
+
+describe("gateway: agentlife.dismiss", () => {
+  let afterToolCall: Function;
+  let dismissMethod: Function;
+  let surfacesMethod: Function;
+
+  beforeEach(async () => {
+    vi.resetModules();
+    const { default: register } = await import("./index.ts");
+    const { api, onHooks, gatewayMethods } = createMockApi();
+    register(api as any);
+
+    afterToolCall = onHooks.find(
+      (h) => h.hookName === "after_tool_call",
+    )!.handler;
+    dismissMethod = gatewayMethods.find(
+      (m) => m.method === "agentlife.dismiss",
+    )!.handler;
+    surfacesMethod = gatewayMethods.find(
+      (m) => m.method === "agentlife.surfaces",
+    )!.handler;
+  });
+
+  function pushDsl(dsl: string) {
+    afterToolCall({
+      toolName: "canvas",
+      params: { action: "a2ui_push", jsonl: dsl },
+    });
+  }
+
+  function getSurfaces(): { surfaceId: string; dsl: string }[] {
+    const respond = vi.fn();
+    surfacesMethod({ respond });
+    return respond.mock.calls[0][1].surfaces;
+  }
+
+  it("dismisses existing surface", () => {
+    pushDsl('surface weather w=6\n  card\n    text "Weather" h3');
+    expect(getSurfaces()).toHaveLength(1);
+
+    const respond = vi.fn();
+    dismissMethod({ params: { surfaceId: "weather" }, respond });
+    expect(respond).toHaveBeenCalledWith(true, {
+      surfaceId: "weather",
+      dismissed: true,
+    });
+    expect(getSurfaces()).toHaveLength(0);
+  });
+
+  it("returns dismissed:false for unknown surface", () => {
+    const respond = vi.fn();
+    dismissMethod({ params: { surfaceId: "nonexistent" }, respond });
+    expect(respond).toHaveBeenCalledWith(true, {
+      surfaceId: "nonexistent",
+      dismissed: false,
+    });
+  });
+
+  it("rejects missing surfaceId", () => {
+    const respond = vi.fn();
+    dismissMethod({ params: {}, respond });
+    expect(respond).toHaveBeenCalledWith(false, {
+      error: "missing surfaceId",
+    });
+  });
+});
+
+// ---------------------------------------------------------------------------
+// 12. Dashboard state in bootstrap
+// ---------------------------------------------------------------------------
+
+describe("dashboard state in bootstrap", () => {
+  let afterToolCall: Function;
+  let bootstrapHandler: Function;
+
+  beforeEach(async () => {
+    vi.useFakeTimers();
+    vi.setSystemTime(new Date("2026-03-05T12:00:00Z"));
+    vi.resetModules();
+    const { default: register } = await import("./index.ts");
+    const { api, onHooks, hooks } = createMockApi();
+    register(api as any);
+
+    afterToolCall = onHooks.find(
+      (h) => h.hookName === "after_tool_call",
+    )!.handler;
+    bootstrapHandler = hooks.find(
+      (h) => h.events === "agent:bootstrap",
+    )!.handler;
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  function pushDsl(dsl: string) {
+    afterToolCall({
+      toolName: "canvas",
+      params: { action: "a2ui_push", jsonl: dsl },
+    });
+  }
+
+  function getDashboardState(
+    agentId: string = "some-agent",
+  ): string | undefined {
+    const bootstrapFiles: any[] = [
+      { name: "TOOLS.md", path: "/path/TOOLS.md", content: "", missing: true },
+    ];
+    bootstrapHandler({ context: { bootstrapFiles, agentId } });
+    return bootstrapFiles.find(
+      (f: any) => f.name === "DASHBOARD_STATE.md",
+    )?.content;
+  }
+
+  it("injects empty dashboard guidance when no surfaces exist", () => {
+    const content = getDashboardState();
+    expect(content).toBeDefined();
+    expect(content).toContain("Dashboard is Empty");
+    expect(content).toContain("suggestion cards");
+  });
+
+  it("injects active card details for non-expired surfaces", () => {
+    pushDsl(
+      'surface weather w=6\n  card\n    text "72F Sunny" h3\n  detail: Current weather in San Francisco\n  ttl: 1h',
+    );
+    const content = getDashboardState();
+    expect(content).toContain("Current Dashboard State");
+    expect(content).toContain("Active Cards");
+    expect(content).toContain("[weather]");
+    expect(content).toContain("72F Sunny");
+    expect(content).toContain("ttl: 1h");
+    expect(content).toContain("Current weather in San Francisco");
+  });
+
+  it("shows EXPIRED flag for expired surfaces", () => {
+    pushDsl('surface old w=6\n  card\n    text "Old" h3\n  ttl: 30m');
+    vi.advanceTimersByTime(31 * 60 * 1000);
+    const content = getDashboardState();
+    expect(content).toContain("Dashboard is Empty");
+    expect(content).toContain("EXPIRED");
+    expect(content).toContain("[old]");
+  });
+
+  it("shows both active and expired sections when mixed", () => {
+    pushDsl('surface weather w=6\n  card\n    text "Weather" h3\n  ttl: 2h');
+    pushDsl('surface news w=6\n  card\n    text "News" h3\n  ttl: 30m');
+    vi.advanceTimersByTime(31 * 60 * 1000);
+    const content = getDashboardState();
+    expect(content).toContain("Current Dashboard State");
+    expect(content).toContain("Active Cards");
+    expect(content).toContain("[weather]");
+    expect(content).toContain("Expired Cards");
+    expect(content).toContain("[news]");
+    expect(content).toContain("EXPIRED");
+  });
+
+  it("includes widget size metadata (w= h=)", () => {
+    pushDsl('surface weather w=4 h=3\n  card\n    text "Weather" h3');
+    const content = getDashboardState();
+    expect(content).toContain("w=4");
+    expect(content).toContain("h=3");
+  });
+
+  it("does NOT inject dashboard state for orchestrator", () => {
+    pushDsl('surface weather w=6\n  card\n    text "Weather" h3');
+    const content = getDashboardState("agentlife");
+    expect(content).toBeUndefined();
+  });
+});
+
+// ---------------------------------------------------------------------------
+// 13. Surface lifecycle (TTL, expiry, grace period, disk persistence)
+// ---------------------------------------------------------------------------
+
+describe("surface lifecycle", () => {
+  let tmpDir: string;
+  let afterToolCall: Function;
+  let surfacesMethod: Function;
+  let mock: ReturnType<typeof createMockApi>;
+
+  beforeEach(async () => {
+    tmpDir = mkdtempSync(path.join(os.tmpdir(), "agentlife-test-"));
+    vi.useFakeTimers();
+    vi.setSystemTime(new Date("2026-03-05T12:00:00Z"));
+    vi.resetModules();
+    const { default: register } = await import("./index.ts");
+    mock = createMockApi();
+    register(mock.api as any);
+
+    afterToolCall = mock.onHooks.find(
+      (h) => h.hookName === "after_tool_call",
+    )!.handler;
+    surfacesMethod = mock.gatewayMethods.find(
+      (m) => m.method === "agentlife.surfaces",
+    )!.handler;
+    // NOTE: surfaces service NOT started — avoids scheduleSave disk writes.
+    // Only disk-specific tests start it.
+  });
+
+  afterEach(async () => {
+    vi.useRealTimers();
+    await fs.rm(tmpDir, { recursive: true, force: true });
+  });
+
+  function pushDsl(dsl: string) {
+    afterToolCall({
+      toolName: "canvas",
+      params: { action: "a2ui_push", jsonl: dsl },
+    });
+  }
+
+  function getSurfaces(): { surfaceId: string; dsl: string }[] {
+    const respond = vi.fn();
+    surfacesMethod({ respond });
+    return respond.mock.calls[0][1].surfaces;
+  }
+
+  it("TTL 30m boundary: present at 29m, gone at 31m", () => {
+    pushDsl('surface w w=6\n  card\n    text "W" h3\n  ttl: 30m');
+    vi.advanceTimersByTime(29 * 60 * 1000);
+    expect(getSurfaces()).toHaveLength(1);
+    vi.advanceTimersByTime(2 * 60 * 1000);
+    expect(getSurfaces()).toHaveLength(0);
+  });
+
+  it("TTL 6h boundary", () => {
+    pushDsl('surface d w=6\n  card\n    text "D" h3\n  ttl: 6h');
+    vi.advanceTimersByTime(5 * 60 * 60 * 1000);
+    expect(getSurfaces()).toHaveLength(1);
+    vi.advanceTimersByTime(2 * 60 * 60 * 1000);
+    expect(getSurfaces()).toHaveLength(0);
+  });
+
+  it("TTL none survives indefinitely", () => {
+    pushDsl('surface p w=6\n  card\n    text "P" h3\n  ttl: none');
+    vi.advanceTimersByTime(365 * 24 * 60 * 60 * 1000);
+    expect(getSurfaces()).toHaveLength(1);
+  });
+
+  it("expireAt boundary", () => {
+    pushDsl(
+      'surface ev w=6\n  card\n    text "E" h3\n  expireAt: 2026-03-05T14:00:00Z',
+    );
+    vi.advanceTimersByTime(119 * 60 * 1000); // 1h59m → 13:59
+    expect(getSurfaces()).toHaveLength(1);
+    vi.advanceTimersByTime(2 * 60 * 1000); // → 14:01
+    expect(getSurfaces()).toHaveLength(0);
+  });
+
+  it("default 7-day ceiling boundary", () => {
+    pushDsl('surface x w=6\n  card\n    text "X" h3');
+    vi.advanceTimersByTime(7 * 24 * 60 * 60 * 1000 - 1000);
+    expect(getSurfaces()).toHaveLength(1);
+    vi.advanceTimersByTime(2000);
+    expect(getSurfaces()).toHaveLength(0);
+  });
+
+  it("expireHint prevents default ceiling", () => {
+    pushDsl(
+      'surface m w=6\n  card\n    text "M" h3\n  expireHint: after the meeting',
+    );
+    vi.advanceTimersByTime(8 * 24 * 60 * 60 * 1000);
+    expect(getSurfaces()).toHaveLength(1);
+  });
+
+  it("disk round-trip preserves surface data", async () => {
+    // Start surfaces service so disk writes go through
+    await mock.services
+      .find((s) => s.id === "agentlife-surfaces")!
+      .start({ stateDir: tmpDir, config: {} });
+
+    pushDsl(
+      'surface weather w=6\n  card\n    text "72F" h3\n  ttl: 1h\n  detail: Weather in SF',
+    );
+
+    // Run the fake setImmediate to invoke saveToDisk(), then switch to real
+    // timers and wait for the async I/O to complete.
+    vi.runAllTimers();
+    vi.useRealTimers();
+    await new Promise((r) => setTimeout(r, 100));
+
+    const raw = await fs.readFile(
+      path.join(tmpDir, "agentlife", "surfaces.json"),
+      "utf-8",
+    );
+    const data = JSON.parse(raw);
+    expect(data._version).toBe(2);
+    expect(data.surfaces.weather).toBeDefined();
+    expect(data.surfaces.weather.ttl).toBe("1h");
+    expect(data.surfaces.weather.lines).toContain("surface weather w=6");
+  });
+
+  it("load purges surfaces past 24h grace period", async () => {
+    const now = Date.now();
+    const pastGrace = now - 25 * 60 * 60 * 1000; // 25h ago
+
+    // Write a surfaces file with one stale + one fresh entry
+    const surfacesData = {
+      _version: 2,
+      surfaces: {
+        "stale-card": {
+          lines: [
+            "surface stale-card w=6",
+            "  card",
+            '    text "Stale" h3',
+          ],
+          createdAt: pastGrace - 1000,
+          updatedAt: pastGrace - 1000,
+          ttl: "1h",
+          expiredSince: pastGrace,
+        },
+        "fresh-card": {
+          lines: [
+            "surface fresh-card w=6",
+            "  card",
+            '    text "Fresh" h3',
+          ],
+          createdAt: now - 1000,
+          updatedAt: now - 1000,
+          ttl: "none",
+        },
+      },
+    };
+    const dir = path.join(tmpDir, "agentlife");
+    await fs.mkdir(dir, { recursive: true });
+    await fs.writeFile(
+      path.join(dir, "surfaces.json"),
+      JSON.stringify(surfacesData),
+    );
+
+    // Re-import module to get fresh state, load from disk
+    vi.resetModules();
+    const { default: register2 } = await import("./index.ts");
+    const mock2 = createMockApi();
+    register2(mock2.api as any);
+    await mock2.services
+      .find((s) => s.id === "agentlife-surfaces")!
+      .start({ stateDir: tmpDir, config: {} });
+
+    const respond = vi.fn();
+    mock2.gatewayMethods
+      .find((m) => m.method === "agentlife.surfaces")!
+      .handler({ respond });
+    const surfaces = respond.mock.calls[0][1].surfaces;
+
+    expect(
+      surfaces.some((s: any) => s.surfaceId === "stale-card"),
+    ).toBe(false);
+    expect(
+      surfaces.some((s: any) => s.surfaceId === "fresh-card"),
+    ).toBe(true);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// 14. Gateway: agentlife.db.exec
+// ---------------------------------------------------------------------------
+
+describe("gateway: agentlife.db.exec", () => {
+  let tmpDir: string;
+  let dbExec: Function;
+  let dbQuery: Function;
+  let closeAllDbs: () => void;
+
+  beforeEach(async () => {
+    tmpDir = mkdtempSync(path.join(os.tmpdir(), "agentlife-test-"));
+    vi.resetModules();
+    const mod = await import("./index.ts");
+    const register = mod.default;
+    closeAllDbs = mod._closeAllDbs;
+    const mock = createMockApi();
+    register(mock.api as any);
+
+    await mock.services
+      .find((s) => s.id === "agentlife-surfaces")!
+      .start({ stateDir: tmpDir, config: {} });
+
+    dbExec = mock.gatewayMethods.find(
+      (m) => m.method === "agentlife.db.exec",
+    )!.handler;
+    dbQuery = mock.gatewayMethods.find(
+      (m) => m.method === "agentlife.db.query",
+    )!.handler;
+  });
+
+  afterEach(async () => {
+    closeAllDbs();
+    await fs.rm(tmpDir, { recursive: true, force: true });
+  });
+
+  it("creates table and inserts row", () => {
+    const respond1 = vi.fn();
+    dbExec({
+      params: {
+        agentId: "test-agent",
+        sql: "CREATE TABLE IF NOT EXISTS meals (id INTEGER PRIMARY KEY, name TEXT, calories INTEGER)",
+      },
+      respond: respond1,
+    });
+    expect(respond1).toHaveBeenCalledWith(true, { changes: 0, lastInsertRowid: 0 });
+
+    const respond2 = vi.fn();
+    dbExec({
+      params: {
+        agentId: "test-agent",
+        sql: "INSERT INTO meals (name, calories) VALUES (?, ?)",
+        params: ["Salad", 350],
+      },
+      respond: respond2,
+    });
+    expect(respond2).toHaveBeenCalledWith(true, { changes: 1, lastInsertRowid: 1 });
+  });
+
+  it("rejects SELECT statements", () => {
+    const respond = vi.fn();
+    dbExec({
+      params: { agentId: "test-agent", sql: "SELECT * FROM meals" },
+      respond,
+    });
+    expect(respond).toHaveBeenCalledWith(false, {
+      error: "use agentlife.db.query for SELECT",
+    });
+  });
+
+  it("rejects missing agentId", () => {
+    const respond = vi.fn();
+    dbExec({ params: { sql: "CREATE TABLE t (id INT)" }, respond });
+    expect(respond).toHaveBeenCalledWith(false, { error: "missing agentId" });
+  });
+
+  it("rejects missing sql", () => {
+    const respond = vi.fn();
+    dbExec({ params: { agentId: "test-agent" }, respond });
+    expect(respond).toHaveBeenCalledWith(false, { error: "missing sql" });
+  });
+
+  it("handles SQL errors gracefully", () => {
+    const respond = vi.fn();
+    dbExec({
+      params: {
+        agentId: "test-agent",
+        sql: "INSERT INTO nonexistent_table VALUES (?)",
+        params: [1],
+      },
+      respond,
+    });
+    expect(respond).toHaveBeenCalledWith(false, expect.objectContaining({ error: expect.any(String) }));
+  });
+
+  it("isolates agent databases", () => {
+    // Create table for agent-a
+    dbExec({
+      params: {
+        agentId: "agent-a",
+        sql: "CREATE TABLE IF NOT EXISTS data (id INTEGER PRIMARY KEY, val TEXT)",
+      },
+      respond: vi.fn(),
+    });
+    dbExec({
+      params: {
+        agentId: "agent-a",
+        sql: "INSERT INTO data (val) VALUES (?)",
+        params: ["secret"],
+      },
+      respond: vi.fn(),
+    });
+
+    // agent-b should not see agent-a's table
+    const respond = vi.fn();
+    dbQuery({
+      params: { agentId: "agent-b", sql: "SELECT * FROM data" },
+      respond,
+    });
+    expect(respond).toHaveBeenCalledWith(false, expect.objectContaining({ error: expect.any(String) }));
+  });
+
+  it("creates DB file lazily", async () => {
+    const dbDir = path.join(tmpDir, "agentlife", "db");
+    // No DB file before first exec
+    await expect(fs.stat(path.join(dbDir, "lazy-agent.db"))).rejects.toThrow();
+
+    dbExec({
+      params: {
+        agentId: "lazy-agent",
+        sql: "CREATE TABLE IF NOT EXISTS t (id INTEGER PRIMARY KEY)",
+      },
+      respond: vi.fn(),
+    });
+
+    const stat = await fs.stat(path.join(dbDir, "lazy-agent.db"));
+    expect(stat.isFile()).toBe(true);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// 15. Gateway: agentlife.db.query
+// ---------------------------------------------------------------------------
+
+describe("gateway: agentlife.db.query", () => {
+  let tmpDir: string;
+  let dbExec: Function;
+  let dbQuery: Function;
+  let closeAllDbs: () => void;
+
+  beforeEach(async () => {
+    tmpDir = mkdtempSync(path.join(os.tmpdir(), "agentlife-test-"));
+    vi.resetModules();
+    const mod = await import("./index.ts");
+    const register = mod.default;
+    closeAllDbs = mod._closeAllDbs;
+    const mock = createMockApi();
+    register(mock.api as any);
+
+    await mock.services
+      .find((s) => s.id === "agentlife-surfaces")!
+      .start({ stateDir: tmpDir, config: {} });
+
+    dbExec = mock.gatewayMethods.find(
+      (m) => m.method === "agentlife.db.exec",
+    )!.handler;
+    dbQuery = mock.gatewayMethods.find(
+      (m) => m.method === "agentlife.db.query",
+    )!.handler;
+
+    // Set up test table with data
+    dbExec({
+      params: {
+        agentId: "test-agent",
+        sql: "CREATE TABLE IF NOT EXISTS meals (id INTEGER PRIMARY KEY, name TEXT, calories INTEGER)",
+      },
+      respond: vi.fn(),
+    });
+    dbExec({
+      params: {
+        agentId: "test-agent",
+        sql: "INSERT INTO meals (name, calories) VALUES (?, ?)",
+        params: ["Salad", 350],
+      },
+      respond: vi.fn(),
+    });
+    dbExec({
+      params: {
+        agentId: "test-agent",
+        sql: "INSERT INTO meals (name, calories) VALUES (?, ?)",
+        params: ["Pizza", 900],
+      },
+      respond: vi.fn(),
+    });
+  });
+
+  afterEach(async () => {
+    closeAllDbs();
+    await fs.rm(tmpDir, { recursive: true, force: true });
+  });
+
+  it("returns rows and columns", () => {
+    const respond = vi.fn();
+    dbQuery({
+      params: { agentId: "test-agent", sql: "SELECT name, calories FROM meals ORDER BY id" },
+      respond,
+    });
+    const result = respond.mock.calls[0][1];
+    expect(result.rows).toHaveLength(2);
+    expect(result.columns).toEqual(["name", "calories"]);
+    expect(result.count).toBe(2);
+    expect(result.truncated).toBe(false);
+    expect(result.rows[0]).toEqual({ name: "Salad", calories: 350 });
+    expect(result.rows[1]).toEqual({ name: "Pizza", calories: 900 });
+  });
+
+  it("supports parameterized queries", () => {
+    const respond = vi.fn();
+    dbQuery({
+      params: {
+        agentId: "test-agent",
+        sql: "SELECT name FROM meals WHERE calories > ?",
+        params: [500],
+      },
+      respond,
+    });
+    const result = respond.mock.calls[0][1];
+    expect(result.rows).toHaveLength(1);
+    expect(result.rows[0].name).toBe("Pizza");
+  });
+
+  it("rejects non-SELECT statements", () => {
+    const respond = vi.fn();
+    dbQuery({
+      params: { agentId: "test-agent", sql: "DELETE FROM meals" },
+      respond,
+    });
+    expect(respond).toHaveBeenCalledWith(false, {
+      error: "use agentlife.db.exec for non-SELECT",
+    });
+  });
+
+  it("returns empty rows for no matches", () => {
+    const respond = vi.fn();
+    dbQuery({
+      params: {
+        agentId: "test-agent",
+        sql: "SELECT * FROM meals WHERE calories > ?",
+        params: [2000],
+      },
+      respond,
+    });
+    const result = respond.mock.calls[0][1];
+    expect(result.rows).toHaveLength(0);
+    expect(result.columns).toEqual([]);
+    expect(result.count).toBe(0);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// 16. Gateway: agentlife.history
+// ---------------------------------------------------------------------------
+
+describe("gateway: agentlife.history", () => {
+  let tmpDir: string;
+  let afterToolCall: Function;
+  let historyMethod: Function;
+  let dismissMethod: Function;
+  let closeAllDbs: () => void;
+
+  beforeEach(async () => {
+    tmpDir = mkdtempSync(path.join(os.tmpdir(), "agentlife-test-"));
+    vi.resetModules();
+    const mod = await import("./index.ts");
+    const register = mod.default;
+    closeAllDbs = mod._closeAllDbs;
+    const mock = createMockApi();
+    register(mock.api as any);
+
+    await mock.services
+      .find((s) => s.id === "agentlife-surfaces")!
+      .start({ stateDir: tmpDir, config: {} });
+
+    afterToolCall = mock.onHooks.find(
+      (h) => h.hookName === "after_tool_call",
+    )!.handler;
+    historyMethod = mock.gatewayMethods.find(
+      (m) => m.method === "agentlife.history",
+    )!.handler;
+    dismissMethod = mock.gatewayMethods.find(
+      (m) => m.method === "agentlife.dismiss",
+    )!.handler;
+  });
+
+  afterEach(async () => {
+    // Flush scheduleSave setImmediate + async saveToDisk before cleanup
+    await new Promise((r) => setImmediate(r));
+    await new Promise((r) => setTimeout(r, 20));
+    closeAllDbs();
+    await fs.rm(tmpDir, { recursive: true, force: true });
+  });
+
+  function pushDsl(dsl: string) {
+    afterToolCall({
+      toolName: "canvas",
+      params: { action: "a2ui_push", jsonl: dsl },
+    });
+  }
+
+  it("records 'created' on surface push", () => {
+    pushDsl('surface weather w=6\n  card\n    text "Weather" h3');
+
+    const respond = vi.fn();
+    historyMethod({ params: { surfaceId: "weather" }, respond });
+    const result = respond.mock.calls[0][1];
+    expect(result.events.length).toBeGreaterThanOrEqual(1);
+    expect(result.events.some((e: any) => e.event === "created")).toBe(true);
+  });
+
+  it("records 'updated' on re-push", () => {
+    pushDsl('surface weather w=6\n  card\n    text "Loading" h3');
+    pushDsl('surface weather w=6\n  card\n    text "72F Sunny" h3');
+
+    const respond = vi.fn();
+    historyMethod({ params: { surfaceId: "weather" }, respond });
+    const result = respond.mock.calls[0][1];
+    expect(result.events.some((e: any) => e.event === "created")).toBe(true);
+    expect(result.events.some((e: any) => e.event === "updated")).toBe(true);
+  });
+
+  it("records 'dismissed' on dismiss", () => {
+    pushDsl('surface weather w=6\n  card\n    text "Weather" h3');
+    dismissMethod({ params: { surfaceId: "weather" }, respond: vi.fn() });
+
+    const respond = vi.fn();
+    historyMethod({ params: { surfaceId: "weather" }, respond });
+    const result = respond.mock.calls[0][1];
+    expect(result.events.some((e: any) => e.event === "dismissed")).toBe(true);
+  });
+
+  it("filters by event type", () => {
+    pushDsl('surface weather w=6\n  card\n    text "Weather" h3');
+    pushDsl('surface weather w=6\n  card\n    text "Updated" h3');
+
+    const respond = vi.fn();
+    historyMethod({ params: { event: "created" }, respond });
+    const result = respond.mock.calls[0][1];
+    expect(result.events.every((e: any) => e.event === "created")).toBe(true);
+  });
+
+  it("respects limit param", () => {
+    pushDsl('surface a w=6\n  card\n    text "A" h3');
+    pushDsl('surface b w=6\n  card\n    text "B" h3');
+    pushDsl('surface c w=6\n  card\n    text "C" h3');
+
+    const respond = vi.fn();
+    historyMethod({ params: { limit: 2 }, respond });
+    const result = respond.mock.calls[0][1];
+    expect(result.events).toHaveLength(2);
+  });
+
+  it("returns empty for no matches", () => {
+    const respond = vi.fn();
+    historyMethod({ params: { surfaceId: "nonexistent" }, respond });
+    const result = respond.mock.calls[0][1];
+    expect(result.events).toHaveLength(0);
+    expect(result.count).toBe(0);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// 16. Registry seeding + needsEnrichment
+// ---------------------------------------------------------------------------
+
+describe("registry seeding + needsEnrichment", () => {
+  let tmpDir: string;
+
+  beforeEach(() => {
+    tmpDir = mkdtempSync(path.join(os.tmpdir(), "agentlife-test-"));
+    vi.stubEnv("HOME", tmpDir);
+  });
+
+  afterEach(async () => {
+    await fs.rm(tmpDir, { recursive: true, force: true });
+  });
+
+  it("seeds existing agents into registry with needsEnrichment: true", async () => {
+    // Create a user agent workspace with SOUL.md
+    const workspace = path.join(tmpDir, ".openclaw", "workspace-fitness");
+    await fs.mkdir(workspace, { recursive: true });
+    await fs.writeFile(
+      path.join(workspace, "SOUL.md"),
+      "# Fitness Agent\nYou are a fitness coach tracking workouts and nutrition.\n",
+      "utf-8",
+    );
+
+    vi.resetModules();
+    const { default: register } = await import("./index.ts");
+    const { api, services, gatewayMethods } = createMockApi({
+      agents: {
+        list: [
+          {
+            id: "fitness",
+            name: "Fitness",
+            workspace,
+            model: "sonnet",
+          },
+        ],
+      },
+    });
+    register(api as any);
+
+    // Start surfaces service (for registry file path)
+    await services
+      .find((s) => s.id === "agentlife-surfaces")!
+      .start({ stateDir: tmpDir, config: {} });
+
+    // Run provisioning (seeds built-in + discovers user agents)
+    await services.find((s) => s.id === "agentlife-provisioning")!.start();
+
+    // Check registry via agentlife.agents
+    const agentsMethod = gatewayMethods.find(
+      (m) => m.method === "agentlife.agents",
+    )!.handler;
+    const respond = vi.fn();
+    agentsMethod({ respond });
+
+    const result = respond.mock.calls[0][1];
+    expect(result.agents).toHaveProperty("fitness");
+    expect(result.agents.fitness.name).toBe("Fitness");
+    // Seeding uses name as placeholder — enrichment provides the real description
+    expect(result.agents.fitness.description).toBe("Fitness");
+  });
+
+  it("does not re-seed agents already in registry", async () => {
+    const workspace = path.join(tmpDir, ".openclaw", "workspace-fitness");
+    await fs.mkdir(workspace, { recursive: true });
+    await fs.writeFile(
+      path.join(workspace, "SOUL.md"),
+      "# Fitness Agent\nYou are a fitness coach.\n",
+      "utf-8",
+    );
+
+    vi.resetModules();
+    const { default: register } = await import("./index.ts");
+    const { api, services, gatewayMethods } = createMockApi({
+      agents: {
+        list: [{ id: "fitness", name: "Fitness", workspace }],
+      },
+    });
+    register(api as any);
+
+    await services
+      .find((s) => s.id === "agentlife-surfaces")!
+      .start({ stateDir: tmpDir, config: {} });
+
+    // Pre-populate registry via createAgent
+    const createAgent = gatewayMethods.find(
+      (m) => m.method === "agentlife.createAgent",
+    )!.handler;
+    await createAgent({
+      params: {
+        id: "fitness",
+        name: "Fitness Pro",
+        workspace,
+        description: "Expert fitness tracker",
+      },
+      respond: vi.fn(),
+    });
+
+    // Run provisioning — should NOT overwrite existing registry entry
+    await services.find((s) => s.id === "agentlife-provisioning")!.start();
+
+    const agentsMethod = gatewayMethods.find(
+      (m) => m.method === "agentlife.agents",
+    )!.handler;
+    const respond = vi.fn();
+    agentsMethod({ respond });
+
+    const result = respond.mock.calls[0][1];
+    expect(result.agents.fitness.description).toBe("Expert fitness tracker");
+    expect(result.agents.fitness.name).toBe("Fitness Pro");
+  });
+
+  it("clears needsEnrichment when createAgent called with description", async () => {
+    const workspace = path.join(tmpDir, ".openclaw", "workspace-fitness");
+    await fs.mkdir(workspace, { recursive: true });
+    await fs.writeFile(
+      path.join(workspace, "SOUL.md"),
+      "# Fitness Agent\nYou are a fitness coach tracking workouts.\n",
+      "utf-8",
+    );
+
+    vi.resetModules();
+    const { default: register } = await import("./index.ts");
+    const { api, services, gatewayMethods } = createMockApi({
+      agents: {
+        list: [{ id: "fitness", name: "Fitness", workspace }],
+      },
+    });
+    register(api as any);
+
+    await services
+      .find((s) => s.id === "agentlife-surfaces")!
+      .start({ stateDir: tmpDir, config: {} });
+
+    // Run provisioning — seeds with needsEnrichment: true
+    await services.find((s) => s.id === "agentlife-provisioning")!.start();
+
+    // Now call createAgent with a proper description (simulates builder enrichment)
+    const createAgent = gatewayMethods.find(
+      (m) => m.method === "agentlife.createAgent",
+    )!.handler;
+    await createAgent({
+      params: {
+        id: "fitness",
+        name: "Fitness",
+        workspace,
+        description: "Tracks workouts, nutrition, and sleep. Shows trends and flags concerns.",
+      },
+      respond: vi.fn(),
+    });
+
+    // Verify registry entry has updated description and no needsEnrichment
+    // Read from disk to verify persistence
+    const registryPath = path.join(tmpDir, "agentlife", "agent-registry.json");
+    const raw = JSON.parse(await fs.readFile(registryPath, "utf-8"));
+    const entry = raw.agents.fitness;
+    expect(entry.description).toBe(
+      "Tracks workouts, nutrition, and sleep. Shows trends and flags concerns.",
+    );
+    expect(entry.needsEnrichment).toBeUndefined();
+  });
+});