@sixb/sqlite 0.1.6 → 0.1.8

package/src/index.ts

@@ -13,6 +13,7 @@ import { ProviderMaterializationTransactionLifecycle } from "@sixb/core/internal
 import {
   createAgentOperationScope,
   createAuthOperationScope,
+  createObjectOperationScope,
   createOntologyOperationScope,
   createOperationScopedFacade,
   createStorageOperationScope,
@@ -20,14 +21,18 @@ import {
 } from "@sixb/core/internal/storage-operation-scope"
 import {
   type AiCostStorage,
+  type AiLimitStorage,
   type AiUsageStorage,
   createTransactionStorageProxy,
+  type ShareGrantStorage,
+  type ShareSessionStorage,
   StorageTransactionError,
   throwNestedStorageTransaction,
 } from "@sixb/core/storage"
 import { SqliteActionRunStorage } from "./action-run-storage"
 import { SqliteAgentStorage } from "./agents"
 import { SqliteAiCostStorage } from "./ai-cost-storage"
+import { SqliteAiLimitStorage } from "./ai-limit-storage"
 import { SqliteAiUsageStorage } from "./ai-usage-storage"
 import { SqliteAuthStorage } from "./auth-storage"
 import { SqliteConnectorConnectionStorage } from "./connector-connection-storage"
@@ -37,11 +42,13 @@ import {
   installFreshSqliteSchema,
   sqliteStoragePath,
 } from "./migrations"
-import { SqliteObjectStorage } from "./object-storage"
+import { SqliteObjectStorage } from "./objects"
 import { SqliteOntologyStorage, type SqliteOntologyTransactionContext } from "./ontology-storage"
 import { SqlitePipelineRunStorage } from "./pipeline-run-storage"
 import { SqliteProjectionRunStorage } from "./projection-run-storage"
 import { SqliteRulesStorage } from "./rules-storage"
+import { SqliteShareGrantStorage } from "./share-grant-storage"
+import { SqliteShareSessionStorage } from "./share-session-storage"
 import { SqliteSyncRunStorage } from "./sync-run-storage"
 import { registerSqliteStorageTestingAdapter } from "./testing"
 import { SqliteTimeseriesStorage } from "./timeseries-storage"
@@ -84,6 +91,7 @@ export class SqliteStorage implements MigrationCapableStorage {
   readonly agents: SqliteAgentStorage
   readonly aiUsage: AiUsageStorage
   readonly aiCosts: AiCostStorage
+  readonly aiLimits: AiLimitStorage
   readonly actionRuns: SqliteActionRunStorage
   readonly pipelineRuns: SqlitePipelineRunStorage
   readonly syncRuns: SqliteSyncRunStorage
@@ -93,6 +101,8 @@ export class SqliteStorage implements MigrationCapableStorage {
   readonly timeseries: Storage["timeseries"]
   readonly webhookRuns: SqliteWebhookRunStorage
   readonly rules: SqliteRulesStorage
+  readonly shareGrants: ShareGrantStorage
+  readonly shareSessions: ShareSessionStorage
   readonly connectorConnections: SqliteConnectorConnectionStorage
   readonly migrators: readonly StorageMigrator[]
 
@@ -140,13 +150,14 @@ export class SqliteStorage implements MigrationCapableStorage {
     const readTimeseries = path
       ? new SqliteTimeseriesStorage({ connection: this.readConnection })
       : stores.timeseries
-    this.objects = createOperationScopedFacade(readObjects, readScope)
+    this.objects = createObjectOperationScope(readObjects, readScope)
     this.ontology = createOntologyOperationScope(stores.ontology, ontologyScope)
     this.auth = createAuthOperationScope(stores.auth, scope)
     this.executions = createOperationScopedFacade(stores.executions, scope)
     this.agents = createAgentOperationScope(stores.agents, scope)
     this.aiUsage = createOperationScopedFacade(stores.aiUsage, scope)
     this.aiCosts = createOperationScopedFacade(stores.aiCosts, scope)
+    this.aiLimits = createOperationScopedFacade(stores.aiLimits, scope)
     this.actionRuns = createOperationScopedFacade(stores.actionRuns, scope)
     this.pipelineRuns = createOperationScopedFacade(stores.pipelineRuns, scope)
     this.timeseries = createOperationScopedFacade(readTimeseries, readScope)
@@ -156,6 +167,8 @@ export class SqliteStorage implements MigrationCapableStorage {
     this.workflowInterventions = createOperationScopedFacade(stores.workflowInterventions, scope)
     this.webhookRuns = createOperationScopedFacade(stores.webhookRuns, scope)
     this.rules = createOperationScopedFacade(stores.rules, scope)
+    this.shareGrants = createOperationScopedFacade(stores.shareGrants, scope)
+    this.shareSessions = createOperationScopedFacade(stores.shareSessions, scope)
     this.connectorConnections = createOperationScopedFacade(stores.connectorConnections, scope)
     this.migrators = options.path ? createSqliteStorageMigrators(options.path) : []
     registerSqliteStorageTestingAdapter(this, (durationMs) =>
@@ -290,7 +303,9 @@ function createSqliteStores(
   }
 ): SqliteStoreSet {
   const auth = new SqliteAuthStorage({ connection })
-  const executions = new SqliteExecutionStorage(connection.db, auth)
+  const shareGrants = new SqliteShareGrantStorage({ connection })
+  const shareSessions = new SqliteShareSessionStorage({ connection })
+  const executions = new SqliteExecutionStorage(connection.db, auth, shareSessions)
   return {
     objects: new SqliteObjectStorage({ connection }),
     ontology: new SqliteOntologyStorage({
@@ -303,6 +318,7 @@ function createSqliteStores(
     agents: new SqliteAgentStorage({ connection, executions }),
     aiUsage: new SqliteAiUsageStorage({ connection }),
     aiCosts: new SqliteAiCostStorage(connection),
+    aiLimits: new SqliteAiLimitStorage({ connection }),
     actionRuns: new SqliteActionRunStorage({ connection, executions }),
     pipelineRuns: new SqlitePipelineRunStorage({ connection, executions }),
     timeseries: new SqliteTimeseriesStorage({ connection }),
@@ -312,6 +328,8 @@ function createSqliteStores(
     workflowInterventions: new SqliteWorkflowInterventionStorage({ connection }),
     webhookRuns: new SqliteWebhookRunStorage({ connection, executions }),
     rules: new SqliteRulesStorage({ connection }),
+    shareGrants,
+    shareSessions,
     connectorConnections: new SqliteConnectorConnectionStorage(connection),
   }
 }
@@ -324,6 +342,7 @@ interface SqliteStoreSet {
   readonly agents: SqliteAgentStorage
   readonly aiUsage: SqliteAiUsageStorage
   readonly aiCosts: SqliteAiCostStorage
+  readonly aiLimits: SqliteAiLimitStorage
   readonly actionRuns: SqliteActionRunStorage
   readonly pipelineRuns: SqlitePipelineRunStorage
   readonly syncRuns: SqliteSyncRunStorage
@@ -333,6 +352,8 @@ interface SqliteStoreSet {
   readonly timeseries: SqliteTimeseriesStorage
   readonly webhookRuns: SqliteWebhookRunStorage
   readonly rules: SqliteRulesStorage
+  readonly shareGrants: SqliteShareGrantStorage
+  readonly shareSessions: SqliteShareSessionStorage
   readonly connectorConnections: SqliteConnectorConnectionStorage
 }
 

package/src/migrations/029-model-accounting.sql

@@ -0,0 +1,79 @@
+-- Call-time model configuration and provider identity. Historical identity remains unknown.
+ALTER TABLE ai_model_call_usage
+  ADD COLUMN requested_reasoning TEXT
+  CHECK (
+    requested_reasoning IS NULL OR (
+      json_valid(requested_reasoning) AND
+      json_type(requested_reasoning) IN ('text', 'object')
+    )
+  );
+ALTER TABLE ai_model_call_usage ADD COLUMN provider_ids TEXT
+  CHECK (provider_ids IS NULL OR json_valid(provider_ids));
+
+-- Upgrade the shipped valuation reason while retaining the selected-cost projection.
+CREATE TABLE ai_model_call_valuations_next (
+  project_id TEXT NOT NULL CHECK (length(trim(project_id)) > 0),
+  usage_record_id TEXT NOT NULL CHECK (length(trim(usage_record_id)) > 0),
+  status TEXT NOT NULL CHECK (status IN ('rated', 'unpriceable')),
+  provider_id TEXT CHECK (provider_id IS NULL OR length(trim(provider_id)) > 0),
+  model_id TEXT CHECK (model_id IS NULL OR length(trim(model_id)) > 0),
+  currency TEXT CHECK (
+    currency IS NULL OR (length(currency) = 3 AND currency GLOB '[A-Z][A-Z][A-Z]')
+  ),
+  amount_nanos INTEGER CHECK (
+    amount_nanos IS NULL OR (typeof(amount_nanos) = 'integer' AND amount_nanos >= 0)
+  ),
+  reason TEXT CHECK (
+    reason IS NULL OR reason IN (
+      'missingBillingIdentity',
+      'missingRateCard',
+      'missingUsageMeter',
+      'unsupportedPricingDimension',
+      'invalidUsageForFormula'
+    )
+  ),
+  details TEXT NOT NULL CHECK (json_valid(details) AND json_type(details) = 'object'),
+  rated_at TEXT NOT NULL CHECK (length(trim(rated_at)) > 0),
+  PRIMARY KEY (project_id, usage_record_id),
+  FOREIGN KEY (project_id, usage_record_id)
+    REFERENCES ai_model_call_usage(project_id, id)
+    ON DELETE RESTRICT,
+  CHECK (
+    (
+      status = 'rated'
+      AND provider_id IS NOT NULL
+      AND model_id IS NOT NULL
+      AND currency IS NOT NULL
+      AND amount_nanos IS NOT NULL
+      AND reason IS NULL
+    )
+    OR
+    (
+      status = 'unpriceable'
+      AND currency IS NULL
+      AND amount_nanos IS NULL
+      AND reason IS NOT NULL
+      AND (
+        (reason = 'missingBillingIdentity' AND provider_id IS NULL AND model_id IS NULL)
+        OR
+        (reason <> 'missingBillingIdentity' AND provider_id IS NOT NULL AND model_id IS NOT NULL)
+      )
+    )
+  )
+);
+
+INSERT INTO ai_model_call_valuations_next (
+  project_id, usage_record_id, status, provider_id, model_id,
+  currency, amount_nanos, reason, details, rated_at
+)
+SELECT project_id, usage_record_id, status, provider_id, model_id,
+  currency, amount_nanos,
+  CASE WHEN reason = 'missingCatalogEntry' THEN 'missingRateCard' ELSE reason END,
+  details, rated_at
+FROM ai_model_call_valuations;
+
+DROP TABLE ai_model_call_valuations;
+ALTER TABLE ai_model_call_valuations_next RENAME TO ai_model_call_valuations;
+
+CREATE INDEX idx_ai_model_call_valuations_summary
+  ON ai_model_call_valuations (project_id, status, currency, usage_record_id);

package/src/migrations/030-ai-usage-limits.sql

@@ -0,0 +1,100 @@
+CREATE TABLE ai_usage_limits (
+  project_id TEXT NOT NULL CHECK (length(trim(project_id)) > 0),
+  id TEXT NOT NULL CHECK (length(trim(id)) > 0),
+  subject_type TEXT NOT NULL CHECK (
+    subject_type IN ('project', 'group', 'user', 'serviceAccount')
+  ),
+  subject_id TEXT NOT NULL CHECK (
+    (subject_type = 'project' AND subject_id = '')
+    OR (subject_type <> 'project' AND length(trim(subject_id)) > 0)
+  ),
+  meter TEXT NOT NULL CHECK (meter IN ('tokens.total', 'cost.catalogEstimated')),
+  currency TEXT NOT NULL CHECK (
+    (meter = 'tokens.total' AND currency = '')
+    OR (meter = 'cost.catalogEstimated' AND currency = 'USD')
+  ),
+  limit_amount TEXT NOT NULL CHECK (
+    limit_amount = '0'
+    OR (
+      limit_amount NOT GLOB '*[^0-9]*'
+      AND substr(limit_amount, 1, 1) BETWEEN '1' AND '9'
+    )
+  ),
+  period_kind TEXT NOT NULL CHECK (period_kind = 'calendarMonth'),
+  enabled INTEGER NOT NULL CHECK (enabled IN (0, 1)),
+  created_at TEXT NOT NULL,
+  updated_at TEXT NOT NULL,
+  PRIMARY KEY (project_id, id),
+  UNIQUE (project_id, subject_type, subject_id, meter, currency)
+);
+
+CREATE INDEX idx_ai_usage_limits_project_enabled
+  ON ai_usage_limits (project_id, enabled, subject_type, subject_id, meter, currency);
+
+CREATE TABLE ai_usage_limit_periods (
+  project_id TEXT NOT NULL CHECK (length(trim(project_id)) > 0),
+  subject_type TEXT NOT NULL CHECK (
+    subject_type IN ('project', 'group', 'user', 'serviceAccount')
+  ),
+  subject_id TEXT NOT NULL CHECK (
+    (subject_type = 'project' AND subject_id = '')
+    OR (subject_type <> 'project' AND length(trim(subject_id)) > 0)
+  ),
+  meter TEXT NOT NULL CHECK (meter IN ('tokens.total', 'cost.catalogEstimated')),
+  currency TEXT NOT NULL CHECK (
+    (meter = 'tokens.total' AND currency = '')
+    OR (meter = 'cost.catalogEstimated' AND currency = 'USD')
+  ),
+  period_start TEXT NOT NULL,
+  period_end TEXT NOT NULL,
+  actual_amount TEXT NOT NULL DEFAULT '0',
+  reserved_amount TEXT NOT NULL DEFAULT '0',
+  unknown_amount TEXT NOT NULL DEFAULT '0',
+  accounting_status TEXT NOT NULL DEFAULT 'complete' CHECK (
+    accounting_status IN ('complete', 'unavailable')
+  ),
+  updated_at TEXT NOT NULL,
+  PRIMARY KEY (
+    project_id, subject_type, subject_id, meter, currency, period_start
+  )
+);
+
+CREATE INDEX idx_ai_usage_limit_periods_subject_period
+  ON ai_usage_limit_periods (
+    project_id, subject_type, subject_id, period_start, period_end, meter, currency
+  );
+
+CREATE TABLE ai_model_call_reservations (
+  project_id TEXT NOT NULL CHECK (length(trim(project_id)) > 0),
+  execution_id TEXT NOT NULL CHECK (length(trim(execution_id)) > 0),
+  attempt INTEGER NOT NULL CHECK (attempt >= 1),
+  call_id TEXT NOT NULL CHECK (length(trim(call_id)) > 0),
+  buckets TEXT NOT NULL CHECK (json_valid(buckets) AND json_type(buckets) = 'array'),
+  request_key TEXT NOT NULL,
+  period_start TEXT NOT NULL,
+  period_end TEXT NOT NULL,
+  state TEXT NOT NULL CHECK (state IN ('active', 'reconciled', 'unknown')),
+  usage_record_id TEXT,
+  reserved_at TEXT NOT NULL,
+  updated_at TEXT NOT NULL,
+  PRIMARY KEY (project_id, execution_id, attempt, call_id),
+  FOREIGN KEY (project_id, execution_id)
+    REFERENCES executions(project_id, id)
+    ON DELETE RESTRICT,
+  FOREIGN KEY (project_id, usage_record_id)
+    REFERENCES ai_model_call_usage(project_id, id)
+    ON DELETE RESTRICT,
+  CHECK (
+    (
+      state = 'reconciled'
+      AND usage_record_id IS NOT NULL
+    )
+    OR (
+      state <> 'reconciled'
+      AND usage_record_id IS NULL
+    )
+  )
+);
+
+CREATE INDEX idx_ai_model_call_reservations_active
+  ON ai_model_call_reservations (project_id, state, period_end, execution_id, attempt, call_id);

package/src/migrations/031-subagent-runs.sql

@@ -0,0 +1,231 @@
+-- SQLite cannot alter a CHECK constraint in place. Rebuild the execution table to align SQL with
+-- the durable Agent authority model: managed service account or exact inherited user/disabled.
+CREATE TABLE executions_v3 (
+  project_id TEXT NOT NULL CHECK (length(trim(project_id)) > 0),
+  id TEXT NOT NULL CHECK (length(trim(id)) > 0),
+  executor_kind TEXT NOT NULL CHECK (
+    executor_kind IN (
+      'request', 'action', 'pipeline', 'projection', 'rule', 'sync', 'webhook', 'workflow',
+      'agent', 'kernel'
+    )
+  ),
+  executor_id TEXT NOT NULL CHECK (length(trim(executor_id)) > 0),
+  source_kind TEXT NOT NULL CHECK (
+    source_kind IN ('http', 'webhook', 'schedule', 'event', 'datasetVersion', 'execution')
+  ),
+  source_id TEXT NOT NULL CHECK (length(trim(source_id)) > 0),
+  requested_by_user_id TEXT,
+  requested_by_service_account_id TEXT,
+  correlation_id TEXT NOT NULL CHECK (length(trim(correlation_id)) > 0),
+  parent_execution_id TEXT,
+  authority_kind TEXT NOT NULL CHECK (
+    authority_kind IN ('principal', 'trustedPrimitive', 'kernel', 'disabled')
+  ),
+  authority_user_id TEXT,
+  authority_service_account_id TEXT,
+  authority_session_id TEXT,
+  authority_access_token_id TEXT,
+  authority_primitive_kind TEXT CHECK (
+    authority_primitive_kind IS NULL
+      OR authority_primitive_kind IN (
+        'action', 'pipeline', 'projection', 'rule', 'sync', 'webhook', 'workflow'
+      )
+  ),
+  authority_primitive_id TEXT,
+  authority_kernel_operation TEXT CHECK (
+    authority_kernel_operation IS NULL OR authority_kernel_operation = 'ontology.recover'
+  ),
+  created_at TEXT NOT NULL,
+  PRIMARY KEY (project_id, id),
+  FOREIGN KEY (project_id, parent_execution_id) REFERENCES executions (project_id, id),
+  FOREIGN KEY (project_id, requested_by_user_id) REFERENCES auth_users (project_id, id),
+  FOREIGN KEY (project_id, requested_by_service_account_id)
+    REFERENCES auth_service_accounts (project_id, id),
+  FOREIGN KEY (project_id, authority_user_id) REFERENCES auth_users (project_id, id),
+  FOREIGN KEY (project_id, authority_service_account_id)
+    REFERENCES auth_service_accounts (project_id, id),
+  FOREIGN KEY (project_id, authority_session_id) REFERENCES auth_sessions (project_id, id),
+  FOREIGN KEY (project_id, authority_access_token_id)
+    REFERENCES auth_access_tokens (project_id, id),
+  CHECK ((requested_by_user_id IS NOT NULL) + (requested_by_service_account_id IS NOT NULL) <= 1),
+  CHECK (
+    (source_kind = 'execution' AND parent_execution_id = source_id)
+      OR (source_kind <> 'execution' AND parent_execution_id IS NULL)
+  ),
+  CHECK (
+    (
+      authority_kind = 'principal'
+      AND (authority_user_id IS NOT NULL) + (authority_service_account_id IS NOT NULL) = 1
+      AND (authority_session_id IS NOT NULL) + (authority_access_token_id IS NOT NULL) <= 1
+      AND (authority_session_id IS NULL OR authority_user_id IS NOT NULL)
+      AND authority_primitive_kind IS NULL
+      AND authority_primitive_id IS NULL
+      AND authority_kernel_operation IS NULL
+    )
+    OR (
+      authority_kind = 'trustedPrimitive'
+      AND authority_user_id IS NULL
+      AND authority_service_account_id IS NULL
+      AND authority_session_id IS NULL
+      AND authority_access_token_id IS NULL
+      AND authority_primitive_kind IS NOT NULL
+      AND authority_primitive_id IS NOT NULL
+      AND length(trim(authority_primitive_id)) > 0
+      AND authority_kernel_operation IS NULL
+    )
+    OR (
+      authority_kind = 'kernel'
+      AND authority_user_id IS NULL
+      AND authority_service_account_id IS NULL
+      AND authority_session_id IS NULL
+      AND authority_access_token_id IS NULL
+      AND authority_primitive_kind IS NULL
+      AND authority_primitive_id IS NULL
+      AND authority_kernel_operation IS NOT NULL
+    )
+    OR (
+      authority_kind = 'disabled'
+      AND authority_user_id IS NULL
+      AND authority_service_account_id IS NULL
+      AND authority_session_id IS NULL
+      AND authority_access_token_id IS NULL
+      AND authority_primitive_kind IS NULL
+      AND authority_primitive_id IS NULL
+      AND authority_kernel_operation IS NULL
+    )
+  ),
+  CHECK (
+    (
+      executor_kind = 'request'
+      AND source_kind = 'http'
+      AND executor_id = source_id
+      AND (
+        (
+          authority_kind = 'principal'
+          AND requested_by_user_id IS authority_user_id
+          AND requested_by_service_account_id IS authority_service_account_id
+        )
+        OR (
+          authority_kind = 'disabled'
+          AND requested_by_user_id IS NULL
+          AND requested_by_service_account_id IS NULL
+        )
+      )
+    )
+    OR (
+      executor_kind IN ('action', 'pipeline', 'projection', 'rule', 'sync', 'webhook', 'workflow')
+      AND authority_kind = 'trustedPrimitive'
+      AND executor_kind = authority_primitive_kind
+    )
+    OR (
+      executor_kind = 'agent'
+      AND source_kind = 'execution'
+      AND (
+        (
+          authority_kind = 'principal'
+          AND authority_service_account_id IS NOT NULL
+          AND authority_session_id IS NULL
+          AND authority_access_token_id IS NULL
+        )
+        OR (
+          authority_kind = 'principal'
+          AND authority_user_id IS NOT NULL
+          AND (authority_session_id IS NOT NULL) + (authority_access_token_id IS NOT NULL) = 1
+        )
+        OR authority_kind = 'disabled'
+      )
+    )
+    OR (executor_kind = 'kernel' AND authority_kind = 'kernel')
+  )
+);
+
+INSERT INTO executions_v3 SELECT * FROM executions;
+DROP TABLE executions;
+ALTER TABLE executions_v3 RENAME TO executions;
+
+CREATE TABLE agent_runs_v3 (
+  project_id TEXT NOT NULL,
+  id TEXT NOT NULL,
+  execution_id TEXT NOT NULL,
+  kind TEXT NOT NULL DEFAULT 'conversation' CHECK (kind IN ('conversation', 'subagent')),
+  thread_id TEXT,
+  agent_id TEXT,
+  trigger_message_id TEXT,
+  parent_run_id TEXT,
+  spawn_key TEXT,
+  spec TEXT CHECK (spec IS NULL OR json_valid(spec)),
+  result TEXT CHECK (result IS NULL OR json_valid(result)),
+  requester_group_ids TEXT NOT NULL DEFAULT '[]'
+    CHECK (json_valid(requester_group_ids) AND json_type(requester_group_ids) = 'array'),
+  status TEXT NOT NULL CHECK (
+    status IN ('queued', 'running', 'succeeded', 'failed', 'cancelled')
+  ),
+  model_id TEXT,
+  finish_reason TEXT,
+  error TEXT CHECK (error IS NULL OR json_valid(error)),
+  diagnostics TEXT,
+  attempt INTEGER NOT NULL DEFAULT 0 CHECK (attempt >= 0),
+  execution_token TEXT,
+  execution_queue_lease_expires_at TEXT,
+  created_at TEXT NOT NULL,
+  started_at TEXT,
+  completed_at TEXT,
+  PRIMARY KEY (project_id, id),
+  UNIQUE (project_id, execution_id),
+  UNIQUE (project_id, parent_run_id, spawn_key),
+  FOREIGN KEY (project_id, execution_id)
+    REFERENCES executions (project_id, id)
+    ON DELETE RESTRICT,
+  FOREIGN KEY (project_id, parent_run_id)
+    REFERENCES agent_runs_v3 (project_id, id)
+    ON DELETE RESTRICT,
+  CHECK ((execution_token IS NULL) = (execution_queue_lease_expires_at IS NULL)),
+  CHECK (
+    (
+      kind = 'conversation'
+      AND thread_id IS NOT NULL
+      AND agent_id IS NOT NULL
+      AND trigger_message_id IS NOT NULL
+      AND parent_run_id IS NULL
+      AND spawn_key IS NULL
+      AND spec IS NULL
+      AND result IS NULL
+    )
+    OR
+    (
+      kind = 'subagent'
+      AND thread_id IS NULL
+      AND agent_id IS NULL
+      AND trigger_message_id IS NULL
+      AND parent_run_id IS NOT NULL
+      AND spawn_key IS NOT NULL
+      AND spec IS NOT NULL
+    )
+  ),
+  CHECK (kind <> 'subagent' OR status <> 'succeeded' OR result IS NOT NULL)
+);
+
+INSERT INTO agent_runs_v3 (
+  project_id, id, execution_id, kind, thread_id, agent_id, trigger_message_id,
+  requester_group_ids, status, model_id, finish_reason, error, diagnostics, attempt,
+  execution_token, execution_queue_lease_expires_at, created_at, started_at, completed_at
+)
+SELECT
+  project_id, id, execution_id, 'conversation', thread_id, agent_id, trigger_message_id,
+  requester_group_ids, status, model_id, finish_reason, error, diagnostics, attempt,
+  execution_token, execution_queue_lease_expires_at, created_at, started_at, completed_at
+FROM agent_runs;
+
+DROP TABLE agent_runs;
+ALTER TABLE agent_runs_v3 RENAME TO agent_runs;
+
+CREATE INDEX idx_agent_runs_project_started
+  ON agent_runs(project_id, COALESCE(started_at, created_at) DESC);
+CREATE INDEX idx_agent_runs_project_thread_started
+  ON agent_runs(project_id, thread_id, COALESCE(started_at, created_at) DESC);
+CREATE INDEX idx_agent_runs_project_agent_started
+  ON agent_runs(project_id, agent_id, COALESCE(started_at, created_at) DESC);
+CREATE INDEX idx_agent_runs_project_status_started
+  ON agent_runs(project_id, status, COALESCE(started_at, created_at) DESC);
+CREATE INDEX idx_agent_runs_project_parent_started
+  ON agent_runs(project_id, parent_run_id, status, COALESCE(started_at, created_at) DESC);

package/src/migrations/032-conversation-run-spec.sql

@@ -0,0 +1,78 @@
+CREATE TABLE agent_runs_v4 (
+  project_id TEXT NOT NULL,
+  id TEXT NOT NULL,
+  execution_id TEXT NOT NULL,
+  kind TEXT NOT NULL DEFAULT 'conversation' CHECK (kind IN ('conversation', 'subagent')),
+  thread_id TEXT,
+  agent_id TEXT,
+  trigger_message_id TEXT,
+  parent_run_id TEXT,
+  spawn_key TEXT,
+  spec TEXT CHECK (spec IS NULL OR json_valid(spec)),
+  result TEXT CHECK (result IS NULL OR json_valid(result)),
+  requester_group_ids TEXT NOT NULL DEFAULT '[]'
+    CHECK (json_valid(requester_group_ids) AND json_type(requester_group_ids) = 'array'),
+  status TEXT NOT NULL CHECK (
+    status IN ('queued', 'running', 'succeeded', 'failed', 'cancelled')
+  ),
+  model_id TEXT,
+  finish_reason TEXT,
+  error TEXT CHECK (error IS NULL OR json_valid(error)),
+  diagnostics TEXT,
+  attempt INTEGER NOT NULL DEFAULT 0 CHECK (attempt >= 0),
+  execution_token TEXT,
+  execution_queue_lease_expires_at TEXT,
+  created_at TEXT NOT NULL,
+  started_at TEXT,
+  completed_at TEXT,
+  PRIMARY KEY (project_id, id),
+  UNIQUE (project_id, execution_id),
+  UNIQUE (project_id, parent_run_id, spawn_key),
+  FOREIGN KEY (project_id, execution_id)
+    REFERENCES executions (project_id, id)
+    ON DELETE RESTRICT,
+  FOREIGN KEY (project_id, parent_run_id)
+    -- Use the final name: Bun's legacy ALTER mode preserves references when foreign keys are off.
+    REFERENCES agent_runs (project_id, id)
+    ON DELETE RESTRICT,
+  CHECK ((execution_token IS NULL) = (execution_queue_lease_expires_at IS NULL)),
+  CHECK (
+    (
+      kind = 'conversation'
+      AND thread_id IS NOT NULL
+      AND agent_id IS NOT NULL
+      AND trigger_message_id IS NOT NULL
+      AND parent_run_id IS NULL
+      AND spawn_key IS NULL
+      AND result IS NULL
+    )
+    OR
+    (
+      kind = 'subagent'
+      AND thread_id IS NULL
+      AND agent_id IS NULL
+      AND trigger_message_id IS NULL
+      AND parent_run_id IS NOT NULL
+      AND spawn_key IS NOT NULL
+      AND spec IS NOT NULL
+    )
+  ),
+  CHECK (kind <> 'subagent' OR status <> 'succeeded' OR result IS NOT NULL)
+);
+
+INSERT INTO agent_runs_v4 SELECT * FROM agent_runs;
+DROP TABLE agent_runs;
+ALTER TABLE agent_runs_v4 RENAME TO agent_runs;
+
+CREATE INDEX idx_agent_runs_project_thread_started
+  ON agent_runs (project_id, thread_id, COALESCE(started_at, created_at) DESC, id DESC);
+CREATE INDEX idx_agent_runs_project_status_created
+  ON agent_runs (project_id, status, created_at, id);
+CREATE INDEX idx_agent_runs_project_parent_started
+  ON agent_runs (
+    project_id,
+    parent_run_id,
+    status,
+    COALESCE(started_at, created_at) DESC,
+    id DESC
+  );