feat: add agent factory runtime ledger

Author: AbrahamGreenman

crates/sparsekernel-core/migrations/0005_agent_factory.sql

@@ -0,0 +1,99 @@
+CREATE TABLE IF NOT EXISTS agent_factory_workflow_observations(
+  id TEXT PRIMARY KEY,
+  source_kind TEXT NOT NULL,
+  source_id TEXT NOT NULL,
+  external_id TEXT,
+  observed_at TEXT NOT NULL,
+  summary TEXT NOT NULL,
+  actor TEXT,
+  signals_json TEXT NOT NULL,
+  payload_json TEXT,
+  artifact_ids_json TEXT NOT NULL DEFAULT '[]',
+  created_at TEXT NOT NULL
+);
+
+CREATE TABLE IF NOT EXISTS agent_factory_agent_specs(
+  id TEXT PRIMARY KEY,
+  name TEXT NOT NULL,
+  objective TEXT NOT NULL,
+  status TEXT NOT NULL,
+  version INTEGER NOT NULL,
+  spec_json TEXT NOT NULL,
+  created_by_agent_id TEXT,
+  created_at TEXT NOT NULL,
+  updated_at TEXT NOT NULL,
+  FOREIGN KEY(created_by_agent_id) REFERENCES agents(id)
+);
+
+CREATE TABLE IF NOT EXISTS agent_factory_candidate_workflows(
+  id TEXT PRIMARY KEY,
+  title TEXT NOT NULL,
+  description TEXT NOT NULL,
+  status TEXT NOT NULL,
+  confidence REAL NOT NULL DEFAULT 0,
+  risk TEXT NOT NULL,
+  observation_ids_json TEXT NOT NULL,
+  workflow_json TEXT NOT NULL,
+  proposed_agent_spec_id TEXT,
+  created_at TEXT NOT NULL,
+  updated_at TEXT NOT NULL,
+  FOREIGN KEY(proposed_agent_spec_id) REFERENCES agent_factory_agent_specs(id)
+);
+
+CREATE TABLE IF NOT EXISTS agent_factory_deployment_plans(
+  id TEXT PRIMARY KEY,
+  agent_spec_id TEXT NOT NULL,
+  candidate_workflow_id TEXT,
+  status TEXT NOT NULL,
+  plan_json TEXT NOT NULL,
+  created_at TEXT NOT NULL,
+  updated_at TEXT NOT NULL,
+  FOREIGN KEY(agent_spec_id) REFERENCES agent_factory_agent_specs(id),
+  FOREIGN KEY(candidate_workflow_id) REFERENCES agent_factory_candidate_workflows(id)
+);
+
+CREATE TABLE IF NOT EXISTS agent_factory_approvals(
+  id TEXT PRIMARY KEY,
+  deployment_plan_id TEXT NOT NULL,
+  approval_type TEXT NOT NULL,
+  status TEXT NOT NULL,
+  requested_by_agent_id TEXT,
+  reviewed_by_agent_id TEXT,
+  decision_json TEXT,
+  requested_at TEXT NOT NULL,
+  reviewed_at TEXT,
+  FOREIGN KEY(deployment_plan_id) REFERENCES agent_factory_deployment_plans(id),
+  FOREIGN KEY(requested_by_agent_id) REFERENCES agents(id),
+  FOREIGN KEY(reviewed_by_agent_id) REFERENCES agents(id)
+);
+
+CREATE TABLE IF NOT EXISTS agent_factory_evaluation_results(
+  id TEXT PRIMARY KEY,
+  agent_spec_id TEXT,
+  deployment_plan_id TEXT,
+  status TEXT NOT NULL,
+  score REAL,
+  result_json TEXT NOT NULL,
+  artifact_id TEXT,
+  created_at TEXT NOT NULL,
+  FOREIGN KEY(agent_spec_id) REFERENCES agent_factory_agent_specs(id),
+  FOREIGN KEY(deployment_plan_id) REFERENCES agent_factory_deployment_plans(id),
+  FOREIGN KEY(artifact_id) REFERENCES artifacts(id)
+);
+
+CREATE TABLE IF NOT EXISTS agent_factory_deployment_history(
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  deployment_plan_id TEXT NOT NULL,
+  event_type TEXT NOT NULL,
+  payload_json TEXT,
+  created_at TEXT NOT NULL,
+  FOREIGN KEY(deployment_plan_id) REFERENCES agent_factory_deployment_plans(id)
+);
+
+CREATE INDEX IF NOT EXISTS agent_factory_workflow_observations_source_idx ON agent_factory_workflow_observations(source_kind, source_id, observed_at);
+CREATE INDEX IF NOT EXISTS agent_factory_candidate_workflows_status_idx ON agent_factory_candidate_workflows(status, updated_at);
+CREATE INDEX IF NOT EXISTS agent_factory_agent_specs_status_idx ON agent_factory_agent_specs(status, updated_at);
+CREATE INDEX IF NOT EXISTS agent_factory_deployment_plans_spec_status_idx ON agent_factory_deployment_plans(agent_spec_id, status, updated_at);
+CREATE INDEX IF NOT EXISTS agent_factory_approvals_plan_status_idx ON agent_factory_approvals(deployment_plan_id, status);
+CREATE INDEX IF NOT EXISTS agent_factory_evaluation_results_plan_idx ON agent_factory_evaluation_results(deployment_plan_id, created_at);
+CREATE INDEX IF NOT EXISTS agent_factory_deployment_history_plan_idx ON agent_factory_deployment_history(deployment_plan_id, created_at);

crates/sparsekernel-core/src/lib.rs

@@ -14,12 +14,13 @@ use std::process::{Command, Stdio};
 use std::time::Duration;
 use uuid::Uuid;
 
-pub const SPARSEKERNEL_SCHEMA_VERSION: i64 = 4;
+pub const SPARSEKERNEL_SCHEMA_VERSION: i64 = 5;
 pub const SPARSEKERNEL_PROTOCOL_VERSION: &str = "2026-04-29.v1";
 const MIGRATION_0001: &str = include_str!("../migrations/0001_initial.sql");
 const MIGRATION_0002: &str = include_str!("../migrations/0002_browser_targets_observations.sql");
 const MIGRATION_0003: &str = include_str!("../migrations/0003_resource_lease_metadata.sql");
 const MIGRATION_0004: &str = include_str!("../migrations/0004_resource_budgets.sql");
+const MIGRATION_0005: &str = include_str!("../migrations/0005_agent_factory.sql");
 type SandboxLeaseReleaseRow = (
     Option<String>,
     Option<String>,
@@ -603,6 +604,13 @@ impl SparseKernelDb {
                     params![4, now_iso()],
                 )?;
             }
+            if current < 5 {
+                self.conn.execute_batch(MIGRATION_0005)?;
+                self.conn.execute(
+                    "INSERT OR IGNORE INTO schema_migrations(version, applied_at) VALUES(?, ?)",
+                    params![5, now_iso()],
+                )?;
+            }
             Ok(())
         })();
         match result {
@@ -657,6 +665,13 @@ impl SparseKernelDb {
             "capabilities",
             "audit_log",
             "usage_records",
+            "agent_factory_workflow_observations",
+            "agent_factory_candidate_workflows",
+            "agent_factory_agent_specs",
+            "agent_factory_deployment_plans",
+            "agent_factory_approvals",
+            "agent_factory_evaluation_results",
+            "agent_factory_deployment_history",
         ];
         let mut counts = BTreeMap::new();
         for table in tables {
@@ -3508,7 +3523,9 @@ mod tests {
         assert_eq!(db.schema_version().unwrap(), SPARSEKERNEL_SCHEMA_VERSION);
         db.migrate().unwrap();
         assert_eq!(db.schema_version().unwrap(), SPARSEKERNEL_SCHEMA_VERSION);
-        assert_eq!(db.inspect().unwrap().counts["trust_zones"], 7);
+        let inspect = db.inspect().unwrap();
+        assert_eq!(inspect.counts["trust_zones"], 7);
+        assert_eq!(inspect.counts["agent_factory_agent_specs"], 0);
     }
 
     #[test]

docs/architecture/local-agent-kernel.md

@@ -64,7 +64,7 @@ openclaw runtime prune --older-than 7d
 
 The DB uses WAL mode, foreign keys, a busy timeout, migrations, and typed runtime APIs. Agents and plugins should not open this database directly.
 
-The initial schema includes agents, sessions, legacy session-entry mirrors, transcript events, messages, tasks, task events, tool calls, trust zones, network policies, resource leases, browser pools and contexts, browser targets, browser observations, artifacts, artifact access, capabilities, audit log, and usage records.
+The initial schema includes agents, sessions, legacy session-entry mirrors, transcript events, messages, tasks, task events, tool calls, trust zones, network policies, resource leases, browser pools and contexts, browser targets, browser observations, artifacts, artifact access, capabilities, audit log, usage records, and Agent Factory state for observed workflows, generated specs, approvals, evaluation results, and deployment history.
 
 ## Artifact store
 

docs/architecture/sparsekernel.md

@@ -27,6 +27,7 @@ Small machines can keep many logical agents parked in durable state, but they ca
 - Artifact Store: content-addressed files for large blobs.
 - Task and Lease Scheduler: bounded active execution.
 - Capability Engine: allow, deny, revoke, and audit sensitive actions.
+- Agent Factory: discovery, spec generation, and policy compilation for agents that should exist.
 - Tool Broker: mediated tool invocation.
 - Browser Broker: process pools by trust zone and contexts by task/session.
 - Sandbox Broker: backend abstraction for local, bwrap, Docker, minijail, smolvm, or VM backends.
@@ -37,11 +38,21 @@ Small machines can keep many logical agents parked in durable state, but they ca
 - `crates/sparsekernel-core`: Rust ledger, artifacts, task leases, capabilities, audit, and mock brokers.
 - `crates/sparsekernel-cli`: `sparsekernel` CLI and `sparsekerneld` local daemon.
 - `crates/sparsekernel-core/migrations/0001_initial.sql`: initial SQLite schema.
+- `packages/agent-factory`: pure TypeScript contracts and helpers for workflow observations, candidate workflows, agent specs, policy compilation, and deployment plans.
+- `packages/agent-factory-connectors`: connector adapter contracts for Gmail, CRM, calendar, accounting, and ticketing discovery surfaces.
 - `packages/browser-broker`: TypeScript CDP adapter that materializes leased browser contexts and artifactizes screenshots/downloads.
 - `packages/openclaw-sparsekernel-adapter`: TypeScript adapter that wraps OpenClaw-shaped tool execution with daemon-backed session upsert, capability grants, tool-call lifecycle transitions, and oversized-output artifactization.
 - `packages/sparsekernel-client`: small TypeScript daemon client.
 - `schemas/`: API and event schema definitions.
 
+## Agent Factory Boundary
+
+Agent Factory decides what should exist. SparseKernel decides how it safely runs.
+
+The factory package turns observed workflows into candidate workflows, agent specs, compiled policy, and deployment plans. It does not allocate browser contexts, open sandboxes, invoke connector tools, or grant capabilities directly. Deployment plans contain kernel requests that the SparseKernel runtime can approve, audit, and materialize through broker APIs.
+
+Agent Factory runtime history uses first-class ledger tables for observed workflows, generated specs, approvals, evaluation results, and deployment history. Large supporting evidence such as screenshots, exports, traces, PDFs, and transcripts remains in the artifact store with SQLite metadata and access records.
+
 ## Local API
 
 The v0 daemon exposes localhost JSON endpoints for health/status, session upsert/list, transcript event append/list, task enqueue/claim-by-id/claim-next/heartbeat/complete/fail, expired lease release, tool-call create/start/complete/fail/list, artifact create/read/metadata, browser context acquire/release/list, loopback CDP endpoint probing, sandbox allocate/release, capability grant/check/list/revoke, task listing, and audit listing. `/health` advertises `protocol_version`, `schema_version`, and feature strings so clients can reject incompatible daemon protocols before making state-changing calls. The TypeScript client uses those endpoints instead of opening the SQLite file directly.

packages/agent-factory-connectors/package.json

@@ -0,0 +1,9 @@
+{
+  "name": "@openclaw/agent-factory-connectors",
+  "version": "0.0.0-private",
+  "private": true,
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts"
+  }
+}

packages/agent-factory-connectors/src/index.test.ts

@@ -0,0 +1,86 @@
+import { describe, expect, it } from "vitest";
+import {
+  createAgentFactoryConnectorRegistry,
+  createStaticConnectorAdapter,
+  workflowObservationFromConnectorEvent,
+} from "./index.js";
+
+describe("@openclaw/agent-factory-connectors", () => {
+  it("registers connectors by id and lists them deterministically", () => {
+    const gmail = createStaticConnectorAdapter({
+      id: "gmail-primary",
+      kind: "gmail",
+      displayName: "Gmail",
+    });
+    const crm = createStaticConnectorAdapter({
+      id: "crm-primary",
+      kind: "crm",
+      displayName: "CRM",
+    });
+    const registry = createAgentFactoryConnectorRegistry([gmail, crm]);
+
+    expect(registry.get("gmail-primary")).toBe(gmail);
+    expect(registry.list().map((adapter) => adapter.id)).toEqual(["crm-primary", "gmail-primary"]);
+    expect(registry.listByKind("gmail")).toEqual([gmail]);
+    expect(() => registry.register(gmail)).toThrow(/already registered/);
+  });
+
+  it("adapts connector events into workflow observations", () => {
+    expect(
+      workflowObservationFromConnectorEvent({
+        id: "thread-1",
+        connectorId: "gmail-primary",
+        connectorKind: "gmail",
+        occurredAt: "2026-05-07T12:00:00.000Z",
+        summary: "Customer asks for appointment availability.",
+        actor: "customer@example.com",
+        signals: [{ kind: "repetition", label: "common support request", confidence: 0.9 }],
+        payload: { subject: "Availability" },
+      }),
+    ).toEqual({
+      id: "thread-1",
+      source: {
+        connectorKind: "gmail",
+        connectorId: "gmail-primary",
+        externalId: "thread-1",
+      },
+      observedAt: "2026-05-07T12:00:00.000Z",
+      summary: "Customer asks for appointment availability.",
+      actor: "customer@example.com",
+      signals: [{ kind: "repetition", label: "common support request", confidence: 0.9 }],
+      payload: { subject: "Availability" },
+    });
+  });
+
+  it("supports static connector observations for deterministic tests and demos", async () => {
+    const adapter = createStaticConnectorAdapter({
+      id: "tickets-primary",
+      kind: "ticketing",
+      displayName: "Ticketing",
+      events: [
+        {
+          id: "ticket-old",
+          connectorId: "tickets-primary",
+          connectorKind: "ticketing",
+          occurredAt: "2026-05-06T12:00:00.000Z",
+          summary: "Old ticket",
+        },
+        {
+          id: "ticket-new",
+          connectorId: "tickets-primary",
+          connectorKind: "ticketing",
+          occurredAt: "2026-05-07T12:00:00.000Z",
+          summary: "New ticket",
+        },
+      ],
+    });
+
+    await expect(adapter.observe({ since: "2026-05-07T00:00:00.000Z", limit: 1 })).resolves.toEqual(
+      [
+        expect.objectContaining({
+          id: "ticket-new",
+        }),
+      ],
+    );
+  });
+});