vgxness 0.1.0

package/dist/memory/repositories/observations.js

@@ -0,0 +1,133 @@
+import { randomUUID } from 'node:crypto';
+import { normalizeLimit, toFtsMatchQuery } from '../search.js';
+export class ObservationRepository {
+    db;
+    constructor(db) {
+        this.db = db;
+    }
+    save(input) {
+        const result = this.db.transaction(() => {
+            const existing = input.topicKey ? this.topic(input) : undefined;
+            const id = existing?.id ?? randomUUID();
+            const now = new Date().toISOString();
+            if (existing)
+                this.db.connection.prepare('UPDATE observations SET title=@title, content=@content, updated_at=@updatedAt WHERE id=@id').run({ id, title: input.title, content: input.content, updatedAt: now });
+            else
+                this.db.connection.prepare(`INSERT INTO observations(id, project, scope, type, title, content, topic_key, created_at, updated_at)
+        VALUES (@id, @project, @scope, @type, @title, @content, @topicKey, @createdAt, @updatedAt)`).run({ ...input, id, topicKey: input.topicKey ?? null, createdAt: now, updatedAt: now });
+            this.appendRevision(id, input.topicKey === undefined
+                ? { type: input.type, title: input.title, content: input.content, createdAt: now }
+                : { type: input.type, title: input.title, content: input.content, topicKey: input.topicKey, createdAt: now });
+            const found = this.getById(id);
+            if (!found.ok)
+                throw new Error(found.error.message);
+            return found.value;
+        });
+        return result.ok ? result : fail(result.error.message, result.error.cause);
+    }
+    getById(id) {
+        try {
+            const row = this.db.connection.prepare('SELECT * FROM observations WHERE id=?').get(id);
+            return row ? ok(map(row)) : missing(`Observation not found: ${id}`);
+        }
+        catch (cause) {
+            return fail('Failed to read observation', cause);
+        }
+    }
+    update(input) {
+        const existing = this.getById(input.id);
+        if (!existing.ok)
+            return existing;
+        const result = this.db.transaction(() => {
+            const next = { ...existing.value, ...input, updatedAt: new Date().toISOString() };
+            this.db.connection.prepare(`UPDATE observations SET type=@type, title=@title, content=@content, topic_key=@topicKey, updated_at=@updatedAt WHERE id=@id`).run({
+                id: input.id,
+                type: next.type,
+                title: next.title,
+                content: next.content,
+                topicKey: next.topicKey ?? null,
+                updatedAt: next.updatedAt,
+            });
+            const found = this.getById(input.id);
+            if (!found.ok)
+                throw new Error(found.error.message);
+            return found.value;
+        });
+        return result.ok ? result : fail(result.error.message, result.error.cause);
+    }
+    getByTopic(input) {
+        try {
+            const row = input.topicKey ? this.topic(input) : undefined;
+            return row ? ok(map(row)) : missing(`Observation topic not found: ${input.topicKey ?? ''}`);
+        }
+        catch (cause) {
+            return fail('Failed to read observation by topic', cause);
+        }
+    }
+    search(filters) {
+        try {
+            const params = { limit: normalizeLimit(filters.limit) };
+            const where = [];
+            let from = 'observations o';
+            if (filters.query?.trim()) {
+                from = 'observations o JOIN observations_fts fts ON fts.rowid=o.rowid';
+                where.push('observations_fts MATCH @query');
+                params.query = toFtsMatchQuery(filters.query);
+            }
+            for (const [key, column] of [['project', 'project'], ['scope', 'scope'], ['type', 'type'], ['topicKey', 'topic_key']]) {
+                const value = filters[key];
+                if (value) {
+                    where.push(`o.${column}=@${key}`);
+                    params[key] = value;
+                }
+            }
+            const rows = this.db.connection.prepare(`SELECT o.* FROM ${from} ${where.length ? `WHERE ${where.join(' AND ')}` : ''} ORDER BY o.updated_at DESC LIMIT @limit`).all(params);
+            return ok(rows.map(map));
+        }
+        catch (cause) {
+            return fail('Failed to search observations', cause);
+        }
+    }
+    searchPreviews(filters) {
+        const result = this.search(filters);
+        if (!result.ok)
+            return result;
+        return ok(result.value.map(toSearchResult));
+    }
+    listRevisions(observationId) {
+        try {
+            const rows = this.db.connection.prepare('SELECT * FROM observation_revisions WHERE observation_id=? ORDER BY revision ASC').all(observationId);
+            return ok(rows.map(mapRevision));
+        }
+        catch (cause) {
+            return fail('Failed to read observation revisions', cause);
+        }
+    }
+    topic(input) {
+        return this.db.connection.prepare('SELECT * FROM observations WHERE project=@project AND scope=@scope AND type=@type AND topic_key=@topicKey').get(input);
+    }
+    appendRevision(observationId, input) {
+        const current = this.db.connection.prepare('SELECT COALESCE(MAX(revision), 0) AS revision FROM observation_revisions WHERE observation_id=?').get(observationId);
+        this.db.connection.prepare(`INSERT INTO observation_revisions(id, observation_id, revision, type, title, content, topic_key, created_at)
+      VALUES (@id, @observationId, @revision, @type, @title, @content, @topicKey, @createdAt)`).run({
+            id: randomUUID(),
+            observationId,
+            revision: Number(current?.revision ?? 0) + 1,
+            type: input.type,
+            title: input.title,
+            content: input.content,
+            topicKey: input.topicKey ?? null,
+            createdAt: input.createdAt,
+        });
+    }
+}
+function map(row) { const value = { id: row.id, project: row.project, scope: row.scope, type: row.type, title: row.title, content: row.content, createdAt: row.created_at, updatedAt: row.updated_at }; if (row.topic_key !== null)
+    value.topicKey = row.topic_key; return value; }
+function mapRevision(row) { const value = { id: row.id, observationId: row.observation_id, revision: row.revision, type: row.type, title: row.title, content: row.content, createdAt: row.created_at }; if (row.topic_key !== null)
+    value.topicKey = row.topic_key; return value; }
+function toSearchResult(observation) { const value = { id: observation.id, project: observation.project, scope: observation.scope, type: observation.type, title: observation.title, preview: preview(observation.content), createdAt: observation.createdAt, updatedAt: observation.updatedAt }; if (observation.topicKey !== undefined)
+    value.topicKey = observation.topicKey; return value; }
+function preview(content) { return content.length <= 160 ? content : `${content.slice(0, 157)}...`; }
+function ok(value) { return { ok: true, value }; }
+function missing(message) { return { ok: false, error: { code: 'not_found', message } }; }
+function fail(message, cause) { return { ok: false, error: { code: 'validation_failed', message, cause } }; }

package/dist/memory/repositories/sessions.js

@@ -0,0 +1,105 @@
+import { randomUUID } from 'node:crypto';
+export class SessionRepository {
+    db;
+    constructor(db) {
+        this.db = db;
+    }
+    save(input) {
+        const result = this.db.transaction(() => {
+            const id = input.id ?? randomUUID();
+            this.db.connection.prepare(`INSERT INTO sessions(id, project, directory, started_at) VALUES (@id, @project, @directory, @startedAt)
+        ON CONFLICT(id) DO UPDATE SET project=excluded.project, directory=excluded.directory`).run({ id, project: input.project, directory: input.directory ?? null, startedAt: new Date().toISOString() });
+            const session = this.getById(id);
+            if (!session.ok)
+                throw new Error(session.error.message);
+            return session.value;
+        });
+        return result.ok ? result : fail(result.error.message, result.error.cause);
+    }
+    getById(id) {
+        try {
+            const row = this.db.connection.prepare('SELECT * FROM sessions WHERE id=?').get(id);
+            if (!row)
+                return { ok: false, error: { code: 'not_found', message: `Session not found: ${id}` } };
+            return { ok: true, value: mapSession(row) };
+        }
+        catch (cause) {
+            return fail('Failed to read session', cause);
+        }
+    }
+    restoreLatest(input) {
+        try {
+            const row = this.db.connection.prepare(`
+        SELECT * FROM sessions
+        WHERE project = @project
+          AND ended_at IS NOT NULL
+          AND summary IS NOT NULL
+          AND TRIM(summary) <> ''
+          AND (@directory IS NULL OR directory = @directory)
+        ORDER BY ended_at DESC
+        LIMIT 1
+      `).get({ project: input.project, directory: input.directory ?? null });
+            if (!row)
+                return missing(`No closed session summary found for project: ${input.project}`);
+            return { ok: true, value: mapSession(row) };
+        }
+        catch (cause) {
+            return fail('Failed to restore session', cause);
+        }
+    }
+    appendActivity(input) {
+        const result = this.db.transaction(() => {
+            const next = this.db.connection.prepare('SELECT COALESCE(MAX(sequence), 0) + 1 AS sequence FROM session_activity WHERE session_id=?').get(input.sessionId);
+            const activity = { id: randomUUID(), sequence: next.sequence, createdAt: new Date().toISOString(), ...input };
+            this.db.connection.prepare(`INSERT INTO session_activity(id, session_id, sequence, actor, kind, payload_json, created_at)
+        VALUES (@id, @sessionId, @sequence, @actor, @kind, @payloadJson, @createdAt)`).run(activity);
+            return activity;
+        });
+        return result.ok ? result : fail(result.error.message, result.error.cause);
+    }
+    closeSession(input) {
+        const summary = input.summary.trim();
+        if (summary.length === 0)
+            return fail('summary must not be empty');
+        const result = this.db.transaction(() => {
+            const existing = this.db.connection.prepare('SELECT 1 FROM sessions WHERE id=?').get(input.sessionId);
+            if (!existing)
+                throw new SessionValidationError(`Session not found: ${input.sessionId}`);
+            const endedAt = new Date().toISOString();
+            this.db.connection.prepare('UPDATE sessions SET summary=@summary, ended_at=@endedAt WHERE id=@sessionId')
+                .run({ sessionId: input.sessionId, summary, endedAt });
+            const next = this.db.connection.prepare('SELECT COALESCE(MAX(sequence), 0) + 1 AS sequence FROM session_activity WHERE session_id=?').get(input.sessionId);
+            this.db.connection.prepare(`INSERT INTO session_activity(id, session_id, sequence, actor, kind, payload_json, created_at)
+        VALUES (@id, @sessionId, @sequence, @actor, 'summary', @payloadJson, @createdAt)`).run({
+                id: randomUUID(),
+                sessionId: input.sessionId,
+                sequence: next.sequence,
+                actor: input.actor,
+                payloadJson: JSON.stringify({ summary }),
+                createdAt: endedAt,
+            });
+            const session = this.getById(input.sessionId);
+            if (!session.ok)
+                throw new SessionValidationError(session.error.message);
+            return session.value;
+        });
+        return result.ok ? result : fail(errorMessage(result.error.cause) ?? result.error.message, result.error.cause);
+    }
+}
+function fail(message, cause) { return { ok: false, error: { code: 'validation_failed', message, cause } }; }
+function missing(message) { return { ok: false, error: { code: 'not_found', message } }; }
+function mapSession(row) {
+    const session = { id: row.id, project: row.project, startedAt: row.started_at };
+    if (row.directory !== null)
+        session.directory = row.directory;
+    if (row.ended_at !== null)
+        session.endedAt = row.ended_at;
+    if (row.summary !== null)
+        session.summary = row.summary;
+    return session;
+}
+class SessionValidationError extends Error {
+}
+function errorMessage(cause) {
+    return cause instanceof SessionValidationError ? cause.message : undefined;
+}

package/dist/memory/repositories/traces.js

@@ -0,0 +1,58 @@
+import { randomUUID } from 'node:crypto';
+export class TraceRepository {
+    db;
+    constructor(db) {
+        this.db = db;
+    }
+    write(input) {
+        try {
+            const trace = toTrace(input);
+            this.db.connection.prepare(`INSERT INTO traces(id, actor, session_id, operation, target_type, target_id, topic_key, status, error_code, error_message, created_at)
+        VALUES (@id, @actor, @sessionId, @operation, @targetType, @targetId, @topicKey, @status, @errorCode, @errorMessage, @createdAt)`).run({
+                id: trace.id, actor: trace.actor, sessionId: trace.sessionId ?? null, operation: trace.operation, targetType: trace.targetType,
+                targetId: trace.targetId ?? null, topicKey: trace.topicKey ?? null, status: trace.status, errorCode: trace.errorCode ?? null, errorMessage: trace.errorMessage ?? null, createdAt: trace.createdAt,
+            });
+            return { ok: true, value: trace };
+        }
+        catch (cause) {
+            return fail('Failed to write trace', cause);
+        }
+    }
+    list() {
+        try {
+            return { ok: true, value: this.db.connection.prepare('SELECT * FROM traces ORDER BY created_at ASC').all().map(map) };
+        }
+        catch (cause) {
+            return fail('Failed to list traces', cause);
+        }
+    }
+}
+function toTrace(input) {
+    const trace = { id: randomUUID(), actor: input.actor, operation: input.operation, targetType: input.targetType, status: input.status, createdAt: new Date().toISOString() };
+    if (input.sessionId !== undefined)
+        trace.sessionId = input.sessionId;
+    if (input.targetId !== undefined)
+        trace.targetId = input.targetId;
+    if (input.topicKey !== undefined)
+        trace.topicKey = input.topicKey;
+    if (input.errorCode !== undefined)
+        trace.errorCode = input.errorCode;
+    if (input.errorMessage !== undefined)
+        trace.errorMessage = input.errorMessage;
+    return trace;
+}
+function map(row) {
+    const trace = { id: row.id, actor: row.actor, operation: row.operation, targetType: row.target_type, status: row.status, createdAt: row.created_at };
+    if (row.session_id !== null)
+        trace.sessionId = row.session_id;
+    if (row.target_id !== null)
+        trace.targetId = row.target_id;
+    if (row.topic_key !== null)
+        trace.topicKey = row.topic_key;
+    if (row.error_code !== null)
+        trace.errorCode = row.error_code;
+    if (row.error_message !== null)
+        trace.errorMessage = row.error_message;
+    return trace;
+}
+function fail(message, cause) { return { ok: false, error: { code: 'validation_failed', message, cause } }; }

package/dist/memory/schema.js

@@ -0,0 +1 @@
+export {};

package/dist/memory/search.js

@@ -0,0 +1,11 @@
+export function toFtsMatchQuery(query) {
+    return query
+        .split(/\s+/)
+        .map((term) => term.trim())
+        .filter(Boolean)
+        .map((term) => `"${term.replaceAll('"', '""')}"`)
+        .join(' ');
+}
+export function normalizeLimit(limit, fallback = 20, max = 100) {
+    return limit === undefined || !Number.isInteger(limit) || limit < 1 ? fallback : Math.min(limit, max);
+}

package/dist/memory/sqlite/database.js

@@ -0,0 +1,97 @@
+import Database from 'better-sqlite3';
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+const migrationsDirectory = join(dirname(fileURLToPath(import.meta.url)), 'migrations');
+export const sqliteBusyTimeoutMs = 5000;
+export class MemoryDatabase {
+    connection;
+    constructor(connection) {
+        this.connection = connection;
+    }
+    static open(options) {
+        try {
+            const connection = new Database(options.path, { readonly: options.readonly ?? false });
+            connection.pragma('foreign_keys = ON');
+            connection.pragma(`busy_timeout = ${sqliteBusyTimeoutMs}`);
+            const memoryDatabase = new MemoryDatabase(connection);
+            if (!(options.readonly ?? false)) {
+                const migration = memoryDatabase.applyMigrations();
+                if (!migration.ok) {
+                    connection.close();
+                    return migration;
+                }
+            }
+            return { ok: true, value: memoryDatabase };
+        }
+        catch (cause) {
+            return {
+                ok: false,
+                error: {
+                    code: 'store_unavailable',
+                    message: `Unable to open local memory store at ${options.path}`,
+                    cause,
+                },
+            };
+        }
+    }
+    applyMigrations() {
+        if (!existsSync(migrationsDirectory)) {
+            return migrationFailure(`Migrations directory not found: ${migrationsDirectory}`);
+        }
+        const migrationFiles = readdirSync(migrationsDirectory)
+            .filter((file) => file.endsWith('.sql'))
+            .sort();
+        try {
+            const run = this.connection.transaction(() => {
+                this.connection.exec(`
+          CREATE TABLE IF NOT EXISTS schema_migrations (
+            version TEXT PRIMARY KEY,
+            applied_at TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ', 'now'))
+          );
+        `);
+                const hasMigration = this.connection.prepare('SELECT 1 FROM schema_migrations WHERE version = ?');
+                const recordMigration = this.connection.prepare('INSERT INTO schema_migrations(version) VALUES (?)');
+                for (const file of migrationFiles) {
+                    if (hasMigration.get(file))
+                        continue;
+                    this.connection.exec(readFileSync(join(migrationsDirectory, file), 'utf8'));
+                    recordMigration.run(file);
+                }
+            });
+            run();
+            return { ok: true, value: undefined };
+        }
+        catch (cause) {
+            return migrationFailure('Failed to apply local memory migrations', cause);
+        }
+    }
+    transaction(operation) {
+        try {
+            const run = this.connection.transaction(operation);
+            return { ok: true, value: run.immediate() };
+        }
+        catch (cause) {
+            return {
+                ok: false,
+                error: {
+                    code: 'transaction_failed',
+                    message: 'Local memory transaction failed and was rolled back',
+                    cause,
+                },
+            };
+        }
+    }
+    close() {
+        this.connection.close();
+    }
+}
+export function openMemoryDatabase(options) {
+    return MemoryDatabase.open(options);
+}
+function migrationFailure(message, cause) {
+    const error = { code: 'migration_failed', message };
+    if (cause !== undefined)
+        error.cause = cause;
+    return { ok: false, error };
+}

package/dist/memory/sqlite/migrations/001_initial.sql

@@ -0,0 +1,128 @@
+PRAGMA foreign_keys = ON;
+
+CREATE TABLE IF NOT EXISTS schema_migrations (
+  version TEXT PRIMARY KEY,
+  applied_at TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ', 'now'))
+);
+
+CREATE TABLE IF NOT EXISTS observations (
+  id TEXT PRIMARY KEY,
+  project TEXT NOT NULL,
+  scope TEXT NOT NULL CHECK (scope IN ('project', 'personal')),
+  type TEXT NOT NULL,
+  title TEXT NOT NULL,
+  content TEXT NOT NULL,
+  topic_key TEXT,
+  created_at TEXT NOT NULL,
+  updated_at TEXT NOT NULL
+);
+
+CREATE UNIQUE INDEX IF NOT EXISTS observations_topic_unique
+  ON observations(project, scope, type, topic_key)
+  WHERE topic_key IS NOT NULL;
+
+CREATE INDEX IF NOT EXISTS observations_project_type_idx
+  ON observations(project, type, updated_at DESC);
+
+CREATE TABLE IF NOT EXISTS observation_revisions (
+  id TEXT PRIMARY KEY,
+  observation_id TEXT NOT NULL REFERENCES observations(id) ON DELETE CASCADE,
+  revision INTEGER NOT NULL,
+  type TEXT NOT NULL,
+  title TEXT NOT NULL,
+  content TEXT NOT NULL,
+  topic_key TEXT,
+  created_at TEXT NOT NULL,
+  UNIQUE(observation_id, revision)
+);
+
+CREATE INDEX IF NOT EXISTS observation_revisions_observation_revision_idx
+  ON observation_revisions(observation_id, revision DESC);
+
+CREATE VIRTUAL TABLE IF NOT EXISTS observations_fts USING fts5(
+  title,
+  content,
+  content='observations',
+  content_rowid='rowid'
+);
+
+CREATE TRIGGER IF NOT EXISTS observations_ai AFTER INSERT ON observations BEGIN
+  INSERT INTO observations_fts(rowid, title, content)
+  VALUES (new.rowid, new.title, new.content);
+END;
+
+CREATE TRIGGER IF NOT EXISTS observations_ad AFTER DELETE ON observations BEGIN
+  INSERT INTO observations_fts(observations_fts, rowid, title, content)
+  VALUES ('delete', old.rowid, old.title, old.content);
+END;
+
+CREATE TRIGGER IF NOT EXISTS observations_au AFTER UPDATE ON observations BEGIN
+  INSERT INTO observations_fts(observations_fts, rowid, title, content)
+  VALUES ('delete', old.rowid, old.title, old.content);
+  INSERT INTO observations_fts(rowid, title, content)
+  VALUES (new.rowid, new.title, new.content);
+END;
+
+CREATE TABLE IF NOT EXISTS sessions (
+  id TEXT PRIMARY KEY,
+  project TEXT NOT NULL,
+  directory TEXT,
+  started_at TEXT NOT NULL,
+  ended_at TEXT,
+  summary TEXT
+);
+
+CREATE INDEX IF NOT EXISTS sessions_project_started_idx
+  ON sessions(project, started_at DESC);
+
+CREATE TABLE IF NOT EXISTS session_activity (
+  id TEXT PRIMARY KEY,
+  session_id TEXT NOT NULL REFERENCES sessions(id) ON DELETE CASCADE,
+  sequence INTEGER NOT NULL,
+  actor TEXT NOT NULL,
+  kind TEXT NOT NULL CHECK (kind IN ('prompt', 'tool_call', 'artifact', 'summary', 'error')),
+  payload_json TEXT NOT NULL,
+  created_at TEXT NOT NULL,
+  UNIQUE(session_id, sequence)
+);
+
+CREATE INDEX IF NOT EXISTS session_activity_session_sequence_idx
+  ON session_activity(session_id, sequence);
+
+CREATE TABLE IF NOT EXISTS artifacts (
+  id TEXT PRIMARY KEY,
+  project TEXT NOT NULL,
+  topic_key TEXT NOT NULL,
+  phase TEXT NOT NULL,
+  content TEXT NOT NULL,
+  observation_id TEXT NOT NULL REFERENCES observations(id) ON DELETE CASCADE,
+  created_at TEXT NOT NULL,
+  updated_at TEXT NOT NULL,
+  UNIQUE(project, topic_key)
+);
+
+CREATE INDEX IF NOT EXISTS artifacts_project_phase_idx
+  ON artifacts(project, phase, updated_at DESC);
+
+CREATE TABLE IF NOT EXISTS traces (
+  id TEXT PRIMARY KEY,
+  actor TEXT NOT NULL,
+  session_id TEXT,
+  operation TEXT NOT NULL,
+  target_type TEXT NOT NULL,
+  target_id TEXT,
+  topic_key TEXT,
+  status TEXT NOT NULL CHECK (status IN ('ok', 'error')),
+  error_code TEXT,
+  error_message TEXT,
+  created_at TEXT NOT NULL
+);
+
+CREATE INDEX IF NOT EXISTS traces_operation_created_idx
+  ON traces(operation, created_at DESC);
+
+CREATE INDEX IF NOT EXISTS traces_target_idx
+  ON traces(target_type, target_id);
+
+CREATE INDEX IF NOT EXISTS traces_session_idx
+  ON traces(session_id, created_at DESC);

package/dist/memory/sqlite/migrations/002_observation_revisions.sql

@@ -0,0 +1,14 @@
+CREATE TABLE IF NOT EXISTS observation_revisions (
+  id TEXT PRIMARY KEY,
+  observation_id TEXT NOT NULL REFERENCES observations(id) ON DELETE CASCADE,
+  revision INTEGER NOT NULL,
+  type TEXT NOT NULL,
+  title TEXT NOT NULL,
+  content TEXT NOT NULL,
+  topic_key TEXT,
+  created_at TEXT NOT NULL,
+  UNIQUE(observation_id, revision)
+);
+
+CREATE INDEX IF NOT EXISTS observation_revisions_observation_revision_idx
+  ON observation_revisions(observation_id, revision DESC);

package/dist/memory/sqlite/migrations/003_agent_registry.sql

@@ -0,0 +1,26 @@
+CREATE TABLE IF NOT EXISTS agents (
+  id TEXT PRIMARY KEY,
+  project TEXT NOT NULL,
+  scope TEXT NOT NULL CHECK (scope IN ('project', 'personal')),
+  mode TEXT NOT NULL CHECK (mode IN ('agent', 'subagent')),
+  name TEXT NOT NULL,
+  description TEXT NOT NULL,
+  instructions_json TEXT NOT NULL,
+  capabilities_json TEXT NOT NULL,
+  permissions_json TEXT NOT NULL,
+  memory_json TEXT NOT NULL,
+  workflows_json TEXT NOT NULL,
+  skills_json TEXT NOT NULL,
+  adapters_json TEXT NOT NULL,
+  parent_agent_id TEXT REFERENCES agents(id) ON DELETE CASCADE,
+  created_at TEXT NOT NULL,
+  updated_at TEXT NOT NULL,
+  UNIQUE(project, scope, name),
+  CHECK ((mode = 'agent' AND parent_agent_id IS NULL) OR (mode = 'subagent' AND parent_agent_id IS NOT NULL))
+);
+
+CREATE INDEX IF NOT EXISTS agents_project_scope_mode_idx
+  ON agents(project, scope, mode, name);
+
+CREATE INDEX IF NOT EXISTS agents_parent_idx
+  ON agents(parent_agent_id, name);

package/dist/memory/sqlite/migrations/004_run_runtime.sql

@@ -0,0 +1,62 @@
+CREATE TABLE IF NOT EXISTS runs (
+  id TEXT PRIMARY KEY,
+  project TEXT NOT NULL,
+  user_intent TEXT NOT NULL,
+  workflow TEXT NOT NULL,
+  phase TEXT NOT NULL,
+  selected_agent_id TEXT NOT NULL,
+  provider_adapter TEXT NOT NULL,
+  model TEXT NOT NULL,
+  status TEXT NOT NULL CHECK (status IN ('created', 'planned', 'running', 'needs-human', 'completed', 'failed', 'blocked', 'cancelled')),
+  outcome TEXT CHECK (outcome IN ('success', 'partial', 'failure', 'blocked', 'cancelled')),
+  outcome_reason TEXT,
+  latest_checkpoint_id TEXT REFERENCES run_checkpoints(id) ON DELETE SET NULL,
+  created_at TEXT NOT NULL,
+  updated_at TEXT NOT NULL,
+  completed_at TEXT,
+  CHECK (
+    (status IN ('created', 'planned', 'running', 'needs-human') AND outcome IS NULL AND completed_at IS NULL)
+    OR (status = 'completed' AND outcome IN ('success', 'partial') AND completed_at IS NOT NULL)
+    OR (status = 'failed' AND outcome = 'failure' AND completed_at IS NOT NULL)
+    OR (status = 'blocked' AND outcome = 'blocked' AND completed_at IS NOT NULL)
+    OR (status = 'cancelled' AND outcome = 'cancelled' AND completed_at IS NOT NULL)
+  )
+);
+
+CREATE INDEX IF NOT EXISTS runs_project_created_idx
+  ON runs(project, created_at DESC);
+
+CREATE INDEX IF NOT EXISTS runs_status_updated_idx
+  ON runs(status, updated_at DESC);
+
+CREATE TABLE IF NOT EXISTS run_events (
+  id TEXT PRIMARY KEY,
+  run_id TEXT NOT NULL REFERENCES runs(id) ON DELETE CASCADE,
+  sequence INTEGER NOT NULL,
+  kind TEXT NOT NULL CHECK (kind IN ('timeline', 'evidence', 'memory-operation', 'artifact-reference', 'tool-call', 'permission-decision', 'operation-execution', 'approval', 'verification')),
+  title TEXT NOT NULL,
+  payload_json TEXT NOT NULL,
+  related_type TEXT,
+  related_id TEXT,
+  created_at TEXT NOT NULL,
+  UNIQUE(run_id, sequence)
+);
+
+CREATE INDEX IF NOT EXISTS run_events_run_sequence_idx
+  ON run_events(run_id, sequence);
+
+CREATE INDEX IF NOT EXISTS run_events_related_idx
+  ON run_events(related_type, related_id);
+
+CREATE TABLE IF NOT EXISTS run_checkpoints (
+  id TEXT PRIMARY KEY,
+  run_id TEXT NOT NULL REFERENCES runs(id) ON DELETE CASCADE,
+  sequence INTEGER NOT NULL,
+  label TEXT NOT NULL,
+  state_json TEXT NOT NULL,
+  created_at TEXT NOT NULL,
+  UNIQUE(run_id, sequence)
+);
+
+CREATE INDEX IF NOT EXISTS run_checkpoints_run_sequence_idx
+  ON run_checkpoints(run_id, sequence);

package/dist/memory/sqlite/migrations/005_run_approvals.sql

@@ -0,0 +1,20 @@
+CREATE TABLE IF NOT EXISTS run_approvals (
+  id TEXT PRIMARY KEY,
+  run_id TEXT NOT NULL REFERENCES runs(id) ON DELETE CASCADE,
+  decision_event_id TEXT NOT NULL REFERENCES run_events(id) ON DELETE CASCADE,
+  status TEXT NOT NULL CHECK (status IN ('pending', 'approved', 'rejected', 'cancelled')),
+  requested_at TEXT NOT NULL,
+  resolved_at TEXT,
+  resolved_by TEXT,
+  resolution_reason TEXT,
+  CHECK (
+    (status = 'pending' AND resolved_at IS NULL AND resolved_by IS NULL AND resolution_reason IS NULL)
+    OR (status IN ('approved', 'rejected', 'cancelled') AND resolved_at IS NOT NULL AND resolved_by IS NOT NULL)
+  )
+);
+
+CREATE UNIQUE INDEX IF NOT EXISTS run_approvals_decision_event_idx
+  ON run_approvals(decision_event_id);
+
+CREATE INDEX IF NOT EXISTS run_approvals_run_status_idx
+  ON run_approvals(run_id, status, requested_at DESC);