availsync 0.1.0

package/src/core/work.ts

@@ -0,0 +1,490 @@
+import type { Pool, PoolClient } from 'pg';
+import { addHours, addMinutes } from 'date-fns';
+import type { Agent, AgentPreferences, Hold, WorkClaim, WorkResource } from '../types';
+import { determineWinnerWithReason, type ConflictRuleApplied } from './conflict';
+
+export type WorkCheckResult = {
+  status: 'available' | 'would_win' | 'would_lose';
+  winning_claim_id: string | null;
+  losing_claim_ids: string[];
+  rule_applied: ConflictRuleApplied;
+  suggested_retry_at: Date | null;
+};
+
+export const MAX_WORK_LOCK_MINUTES = 4 * 60;
+export const DEFAULT_WORK_LEASE_MINUTES = 45;
+export const MAX_WORK_EXTENSION_MINUTES = 120;
+
+export type WorkActor = {
+  actor_type?: string | null;
+  actor_id?: string | null;
+  actor_label?: string | null;
+};
+
+export type ClaimWorkSlotResult =
+  | {
+      outcome: 'blocked';
+      resource: WorkResource;
+      resource_existed: boolean;
+      claim: null;
+      blocking_claim: (WorkClaim & Record<string, unknown>) | null;
+      status: 'would_lose';
+      winning_claim_id: string | null;
+      losing_claim_ids: string[];
+      rule_applied: ConflictRuleApplied;
+      suggested_retry_at: Date | null;
+    }
+  | {
+      outcome: 'claimed';
+      resource: WorkResource;
+      resource_existed: boolean;
+      claim: WorkClaim;
+      status: 'available' | 'would_win';
+      winning_claim_id: null;
+      losing_claim_ids: string[];
+      rule_applied: ConflictRuleApplied;
+      suggested_retry_at: null;
+    }
+  | {
+      outcome: 'aborted';
+      resource: WorkResource;
+      resource_existed: boolean;
+      claim: null;
+      status: WorkCheckResult['status'];
+      winning_claim_id: string | null;
+      losing_claim_ids: string[];
+      rule_applied: ConflictRuleApplied;
+      suggested_retry_at: Date | null;
+    };
+
+export function workWindow(input: { start_at?: string; duration_minutes?: number }) {
+  const startAt = input.start_at ? new Date(input.start_at) : new Date();
+  const duration = input.duration_minutes ?? DEFAULT_WORK_LEASE_MINUTES;
+  return { startAt, endAt: addMinutes(startAt, duration), duration };
+}
+
+export function maxWorkExpiresAt(startAt: Date): Date {
+  return addHours(startAt, 4);
+}
+
+export function initialWorkExpiresAt(startAt: Date, endAt: Date): Date {
+  const max = maxWorkExpiresAt(startAt);
+  return endAt < max ? endAt : max;
+}
+
+export function secondsUntilExpiry(expiresAt: Date): number {
+  return Math.max(0, Math.floor((expiresAt.getTime() - Date.now()) / 1000));
+}
+
+export async function upsertWorkResource(
+  client: PoolClient,
+  input: { org_id: string; resource_type: string; resource_key: string; label?: string },
+): Promise<WorkResource> {
+  const label = input.label || input.resource_key;
+  const result = await client.query<WorkResource>(
+    `INSERT INTO work_resources (org_id, resource_type, resource_key, label)
+     VALUES ($1, $2, $3, $4)
+     ON CONFLICT (org_id, resource_type, resource_key)
+     DO UPDATE SET label = EXCLUDED.label
+     RETURNING *`,
+    [input.org_id, input.resource_type, input.resource_key, label],
+  );
+  return result.rows[0];
+}
+
+export async function insertWorkClaimEvent(input: {
+  db: Pool | PoolClient;
+  claim_id?: string | null;
+  event_type: 'created' | 'blocked' | 'superseded' | 'released' | 'expired' | 'extended' | 'shadow_blocked' | 'shadow_allowed';
+  agent_id: string;
+  org_id: string;
+  resource_id?: string | null;
+  conflicting_claim_id?: string | null;
+  rule_applied?: string | null;
+  metadata?: Record<string, unknown> | null;
+  actor_type?: string | null;
+  actor_id?: string | null;
+  actor_label?: string | null;
+}) {
+  await input.db.query(
+    `INSERT INTO work_claim_events (
+       claim_id,
+       event_type,
+       agent_id,
+       org_id,
+       resource_id,
+       conflicting_claim_id,
+       rule_applied,
+       metadata,
+       actor_type,
+       actor_id,
+       actor_label
+     )
+     VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11)`,
+    [
+      input.claim_id ?? null,
+      input.event_type,
+      input.agent_id,
+      input.org_id,
+      input.resource_id ?? null,
+      input.conflicting_claim_id ?? null,
+      input.rule_applied ?? null,
+      JSON.stringify(input.metadata ?? {}),
+      input.actor_type ?? null,
+      input.actor_id ?? null,
+      input.actor_label ?? null,
+    ],
+  );
+}
+
+export async function expireOldWorkClaims(client: Pool | PoolClient, orgId: string): Promise<WorkClaim[]> {
+  const result = await client.query<WorkClaim>(
+    `UPDATE work_claims
+     SET status = 'expired'
+     WHERE org_id = $1
+       AND status = 'active'
+       AND expires_at < NOW()
+     RETURNING *`,
+    [orgId],
+  );
+  return result.rows;
+}
+
+export async function expireAndLogWorkClaims(client: Pool | PoolClient, orgId: string) {
+  const expired = await expireOldWorkClaims(client, orgId);
+  for (const claim of expired) {
+    await insertWorkClaimEvent({
+      db: client,
+      claim_id: claim.id,
+      event_type: 'expired',
+      agent_id: claim.agent_id,
+      org_id: claim.org_id,
+      resource_id: claim.resource_id,
+      actor_type: 'system',
+      actor_label: 'Availsync',
+      metadata: {
+        expired_at: new Date().toISOString(),
+        expired_by: 'expires_at',
+        previous_expires_at: claim.expires_at.toISOString(),
+        planned_end_at: claim.end_at.toISOString(),
+      },
+    });
+  }
+  return expired;
+}
+
+function asHold(claim: WorkClaim): Hold {
+  return {
+    id: claim.id,
+    agent_id: claim.agent_id,
+    org_id: claim.org_id,
+    start_at: claim.start_at,
+    end_at: claim.end_at,
+    reason: claim.reason,
+    status: claim.status === 'active' ? 'confirmed' : 'released',
+    metadata: claim.metadata,
+    created_at: claim.created_at,
+  };
+}
+
+export async function previewWorkClaim(
+  client: Pool | PoolClient,
+  input: {
+    org_id: string;
+    agent_id: string;
+    resource_id: string;
+    start_at: Date;
+    end_at: Date;
+    reason?: string;
+    metadata?: Record<string, unknown>;
+  },
+): Promise<WorkCheckResult> {
+  const conflicts = await client.query<WorkClaim>(
+    `SELECT *
+     FROM work_claims
+     WHERE org_id = $1
+      AND resource_id = $2
+      AND status = 'active'
+      AND expires_at >= NOW()
+      AND start_at < $4
+      AND expires_at > $3
+     ORDER BY created_at ASC`,
+    [input.org_id, input.resource_id, input.start_at, input.end_at],
+  );
+
+  if (conflicts.rows.length === 0) {
+    return {
+      status: 'available',
+      winning_claim_id: null,
+      losing_claim_ids: [],
+      rule_applied: 'none',
+      suggested_retry_at: null,
+    };
+  }
+
+  const agentIds = Array.from(new Set([input.agent_id, ...conflicts.rows.map((claim) => claim.agent_id)]));
+  const agents = await client.query<Agent>('SELECT * FROM agents WHERE id = ANY($1::uuid[])', [agentIds]);
+  const preferences = await client.query<AgentPreferences>(
+    'SELECT * FROM agent_preferences WHERE agent_id = ANY($1::uuid[])',
+    [agentIds],
+  );
+  const newAgent = agents.rows.find((agent) => agent.id === input.agent_id);
+  if (!newAgent) {
+    throw new Error(`Agent not found: ${input.agent_id}`);
+  }
+
+  const syntheticClaim: WorkClaim = {
+    id: 'new',
+    agent_id: input.agent_id,
+    org_id: input.org_id,
+    resource_id: input.resource_id,
+    start_at: input.start_at,
+    end_at: input.end_at,
+    expires_at: input.end_at,
+    last_renewed_at: new Date(),
+    renewal_count: 0,
+    idempotency_key: null,
+    reason: input.reason,
+    status: 'active',
+    metadata: input.metadata,
+    created_at: new Date(8640000000000000),
+  };
+
+  const losingClaimIds: string[] = [];
+  let lastRule: ConflictRuleApplied = 'none';
+
+  for (const existingClaim of conflicts.rows) {
+    const existingAgent = agents.rows.find((agent) => agent.id === existingClaim.agent_id);
+    if (!existingAgent) {
+      throw new Error(`Agent not found: ${existingClaim.agent_id}`);
+    }
+
+    const result = determineWinnerWithReason(
+      asHold(syntheticClaim),
+      newAgent,
+      asHold(existingClaim),
+      existingAgent,
+      preferences.rows,
+    );
+    lastRule = result.rule_applied;
+
+    if (result.winner.id === existingClaim.id) {
+      return {
+        status: 'would_lose',
+        winning_claim_id: existingClaim.id,
+        losing_claim_ids: [],
+        rule_applied: lastRule,
+        suggested_retry_at: existingClaim.expires_at,
+      };
+    }
+
+    losingClaimIds.push(existingClaim.id);
+  }
+
+  return {
+    status: 'would_win',
+    winning_claim_id: null,
+    losing_claim_ids: losingClaimIds,
+    rule_applied: lastRule,
+    suggested_retry_at: null,
+  };
+}
+
+export async function claimWorkSlot(
+  client: PoolClient,
+  input: {
+    org_id: string;
+    agent_id: string;
+    resource_type: string;
+    resource_key: string;
+    label?: string;
+    start_at: Date;
+    end_at: Date;
+    reason?: string | null;
+    metadata?: Record<string, unknown>;
+    idempotency_key?: string | null;
+    actor?: WorkActor;
+    beforeMutation?: (context: {
+      resource: WorkResource;
+      resource_existed: boolean;
+      result: WorkCheckResult;
+    }) => Promise<boolean>;
+  },
+): Promise<ClaimWorkSlotResult> {
+  await client.query('SELECT pg_advisory_xact_lock(hashtext($1))', [
+    `${input.org_id}:${input.resource_type}:${input.resource_key}`,
+  ]);
+  await expireAndLogWorkClaims(client, input.org_id);
+
+  const existingResource = await client.query<Pick<WorkResource, 'id'>>(
+    `SELECT id
+     FROM work_resources
+     WHERE org_id = $1
+       AND resource_type = $2
+       AND resource_key = $3
+     LIMIT 1`,
+    [input.org_id, input.resource_type, input.resource_key],
+  );
+  const resourceExisted = existingResource.rows.length > 0;
+
+  const resource = await upsertWorkResource(client, {
+    org_id: input.org_id,
+    resource_type: input.resource_type,
+    resource_key: input.resource_key,
+    label: input.label,
+  });
+
+  const result = await previewWorkClaim(client, {
+    org_id: input.org_id,
+    agent_id: input.agent_id,
+    resource_id: resource.id,
+    start_at: input.start_at,
+    end_at: input.end_at,
+    reason: input.reason ?? undefined,
+    metadata: input.metadata,
+  });
+
+  if (input.beforeMutation && !(await input.beforeMutation({ resource, resource_existed: resourceExisted, result }))) {
+    return {
+      outcome: 'aborted',
+      resource,
+      resource_existed: resourceExisted,
+      claim: null,
+      status: result.status,
+      winning_claim_id: result.winning_claim_id,
+      losing_claim_ids: result.losing_claim_ids,
+      rule_applied: result.rule_applied,
+      suggested_retry_at: result.suggested_retry_at,
+    };
+  }
+
+  const metadata = {
+    ...(input.metadata ?? {}),
+    resource_type: resource.resource_type,
+    resource_key: resource.resource_key,
+    start_at: input.start_at.toISOString(),
+    end_at: input.end_at.toISOString(),
+  };
+
+  if (result.status === 'would_lose') {
+    const blocking = result.winning_claim_id
+      ? await client.query<WorkClaim & Record<string, unknown>>(
+          `SELECT
+             work_claims.*,
+             work_resources.resource_type,
+             work_resources.resource_key,
+             work_resources.label AS resource_label,
+             agents.name AS agent_name
+           FROM work_claims
+           JOIN work_resources ON work_resources.id = work_claims.resource_id
+           JOIN agents ON agents.id = work_claims.agent_id
+           WHERE work_claims.id = $1`,
+          [result.winning_claim_id],
+        )
+      : { rows: [] };
+
+    await insertWorkClaimEvent({
+      db: client,
+      event_type: 'blocked',
+      agent_id: input.agent_id,
+      org_id: input.org_id,
+      resource_id: resource.id,
+      conflicting_claim_id: result.winning_claim_id,
+      rule_applied: result.rule_applied,
+      metadata,
+      ...(input.actor ?? {}),
+    });
+
+    return {
+      outcome: 'blocked',
+      resource,
+      resource_existed: resourceExisted,
+      claim: null,
+      blocking_claim: blocking.rows[0] ?? null,
+      status: 'would_lose',
+      winning_claim_id: result.winning_claim_id,
+      losing_claim_ids: result.losing_claim_ids,
+      rule_applied: result.rule_applied,
+      suggested_retry_at: result.suggested_retry_at,
+    };
+  }
+
+  if (result.losing_claim_ids.length > 0) {
+    await client.query(
+      `UPDATE work_claims
+       SET status = 'superseded'
+       WHERE id = ANY($1::uuid[])
+         AND org_id = $2`,
+      [result.losing_claim_ids, input.org_id],
+    );
+  }
+
+  const created = await client.query<WorkClaim>(
+    `INSERT INTO work_claims (
+       org_id,
+       agent_id,
+       resource_id,
+       start_at,
+       end_at,
+       status,
+       reason,
+       metadata,
+       expires_at,
+       last_renewed_at,
+       renewal_count,
+       idempotency_key
+     )
+     VALUES ($1, $2, $3, $4, $5, 'active', $6, $7, $8, NOW(), 0, $9)
+     RETURNING *`,
+    [
+      input.org_id,
+      input.agent_id,
+      resource.id,
+      input.start_at,
+      input.end_at,
+      input.reason ?? null,
+      JSON.stringify(input.metadata ?? {}),
+      initialWorkExpiresAt(input.start_at, input.end_at),
+      input.idempotency_key ?? null,
+    ],
+  );
+
+  await insertWorkClaimEvent({
+    db: client,
+    claim_id: created.rows[0].id,
+    event_type: 'created',
+    agent_id: input.agent_id,
+    org_id: input.org_id,
+    resource_id: resource.id,
+    rule_applied: result.rule_applied,
+    metadata,
+    ...(input.actor ?? {}),
+  });
+
+  for (const losingClaimId of result.losing_claim_ids) {
+    await insertWorkClaimEvent({
+      db: client,
+      claim_id: losingClaimId,
+      event_type: 'superseded',
+      agent_id: input.agent_id,
+      org_id: input.org_id,
+      resource_id: resource.id,
+      conflicting_claim_id: created.rows[0].id,
+      rule_applied: result.rule_applied,
+      metadata: { ...(input.metadata ?? {}), superseded_by_claim_id: created.rows[0].id },
+      ...(input.actor ?? {}),
+    });
+  }
+
+  return {
+    outcome: 'claimed',
+    resource,
+    resource_existed: resourceExisted,
+    claim: created.rows[0],
+    status: result.status,
+    winning_claim_id: null,
+    losing_claim_ids: result.losing_claim_ids,
+    rule_applied: result.rule_applied,
+    suggested_retry_at: null,
+  };
+}

package/src/db/client.ts

@@ -0,0 +1,17 @@
+import { Pool } from 'pg';
+
+const connectionString =
+  process.env.NODE_ENV === 'test'
+    ? process.env.TEST_DATABASE_URL || process.env.DATABASE_URL
+    : process.env.DATABASE_URL;
+const useSSL = connectionString?.includes('sslmode=require');
+
+const pool = new Pool({
+  connectionString,
+  max: 10,
+  idleTimeoutMillis: 30000,
+  connectionTimeoutMillis: 10000,
+  ssl: useSSL ? { rejectUnauthorized: false } : false,
+});
+
+export default pool;

package/src/db/migrations/001_init.sql

@@ -0,0 +1,88 @@
+CREATE EXTENSION IF NOT EXISTS "pgcrypto";
+
+CREATE TABLE IF NOT EXISTS orgs (
+  id          UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  name        TEXT NOT NULL,
+  plan        TEXT NOT NULL DEFAULT 'free' CHECK (plan IN ('free', 'individual', 'team')),
+  agent_limit INTEGER NOT NULL DEFAULT 3,
+  created_at  TIMESTAMPTZ NOT NULL DEFAULT NOW()
+);
+
+CREATE TABLE IF NOT EXISTS agents (
+  id           UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  org_id       UUID NOT NULL REFERENCES orgs(id) ON DELETE CASCADE,
+  name         TEXT NOT NULL,
+  api_key_hash TEXT NOT NULL,
+  agent_type   TEXT NOT NULL DEFAULT 'generic'
+                 CHECK (agent_type IN ('external_meeting', 'internal', 'focus', 'generic')),
+  priority     INTEGER NOT NULL DEFAULT 0,
+  created_at   TIMESTAMPTZ NOT NULL DEFAULT NOW()
+);
+CREATE INDEX IF NOT EXISTS idx_agents_org_id ON agents(org_id);
+
+CREATE TABLE IF NOT EXISTS availability_windows (
+  id         UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  agent_id   UUID NOT NULL REFERENCES agents(id) ON DELETE CASCADE,
+  start_at   TIMESTAMPTZ NOT NULL,
+  end_at     TIMESTAMPTZ NOT NULL,
+  window_type TEXT NOT NULL DEFAULT 'available'
+                CHECK (window_type IN ('available', 'focus', 'blocked')),
+  recurrence TEXT,
+  created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+  CONSTRAINT chk_window_order CHECK (end_at > start_at)
+);
+CREATE INDEX IF NOT EXISTS idx_windows_agent_time
+  ON availability_windows(agent_id, start_at, end_at);
+
+CREATE TABLE IF NOT EXISTS holds (
+  id                 UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  agent_id           UUID NOT NULL REFERENCES agents(id) ON DELETE CASCADE,
+  org_id             UUID NOT NULL REFERENCES orgs(id) ON DELETE CASCADE,
+  start_at           TIMESTAMPTZ NOT NULL,
+  end_at             TIMESTAMPTZ NOT NULL,
+  reason             TEXT,
+  status             TEXT NOT NULL DEFAULT 'confirmed'
+                       CHECK (status IN ('confirmed', 'superseded', 'released')),
+  booked_by_agent_id UUID REFERENCES agents(id),
+  metadata           JSONB,
+  created_at         TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+  CONSTRAINT chk_hold_order CHECK (end_at > start_at)
+);
+CREATE INDEX IF NOT EXISTS idx_holds_org_time
+  ON holds(org_id, start_at, end_at) WHERE status = 'confirmed';
+CREATE INDEX IF NOT EXISTS idx_holds_agent_id ON holds(agent_id);
+CREATE UNIQUE INDEX IF NOT EXISTS idx_holds_confirmed_exact_slot
+  ON holds(org_id, start_at, end_at) WHERE status = 'confirmed';
+
+CREATE TABLE IF NOT EXISTS conflict_rules (
+  id          UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  org_id      UUID NOT NULL REFERENCES orgs(id) ON DELETE CASCADE,
+  rule_type   TEXT NOT NULL CHECK (rule_type IN ('priority', 'buffer', 'focus')),
+  config      JSONB NOT NULL DEFAULT '{}',
+  created_at  TIMESTAMPTZ NOT NULL DEFAULT NOW()
+);
+
+CREATE TABLE IF NOT EXISTS agent_preferences (
+  agent_id                  UUID PRIMARY KEY REFERENCES agents(id) ON DELETE CASCADE,
+  buffer_minutes_after      INTEGER NOT NULL DEFAULT 15,
+  buffer_minutes_before     INTEGER NOT NULL DEFAULT 0,
+  focus_blocks              JSONB NOT NULL DEFAULT '[]',
+  priority_over_agents      JSONB NOT NULL DEFAULT '[]',
+  booking_window_days       INTEGER NOT NULL DEFAULT 30,
+  allow_back_to_back        BOOLEAN NOT NULL DEFAULT false,
+  updated_at                TIMESTAMPTZ NOT NULL DEFAULT NOW()
+);
+
+CREATE TABLE IF NOT EXISTS hold_events (
+  id              UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  hold_id         UUID NOT NULL REFERENCES holds(id) ON DELETE CASCADE,
+  event_type      TEXT NOT NULL
+                    CHECK (event_type IN ('created', 'superseded', 'released', 'conflict_won', 'conflict_lost')),
+  agent_id        UUID NOT NULL REFERENCES agents(id),
+  org_id          UUID NOT NULL REFERENCES orgs(id),
+  conflicting_hold_id UUID REFERENCES holds(id),
+  rule_applied    TEXT,
+  metadata        JSONB,
+  created_at      TIMESTAMPTZ NOT NULL DEFAULT NOW()
+);
+CREATE INDEX IF NOT EXISTS idx_hold_events_org ON hold_events(org_id, created_at DESC);

package/src/db/migrations/002_stripe.sql

@@ -0,0 +1,2 @@
+ALTER TABLE orgs ADD COLUMN IF NOT EXISTS stripe_customer_id TEXT;
+ALTER TABLE orgs ADD COLUMN IF NOT EXISTS stripe_subscription_id TEXT;

package/src/db/migrations/003_workspace_auth.sql

@@ -0,0 +1,19 @@
+CREATE TABLE IF NOT EXISTS workspace_users (
+  id            UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  org_id        UUID NOT NULL REFERENCES orgs(id) ON DELETE CASCADE,
+  email         TEXT NOT NULL UNIQUE,
+  password_hash TEXT NOT NULL,
+  role          TEXT NOT NULL DEFAULT 'owner' CHECK (role IN ('owner', 'admin')),
+  created_at    TIMESTAMPTZ NOT NULL DEFAULT NOW()
+);
+CREATE INDEX IF NOT EXISTS idx_workspace_users_org_id ON workspace_users(org_id);
+
+CREATE TABLE IF NOT EXISTS workspace_sessions (
+  id         UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  user_id    UUID NOT NULL REFERENCES workspace_users(id) ON DELETE CASCADE,
+  token_hash TEXT NOT NULL UNIQUE,
+  expires_at TIMESTAMPTZ NOT NULL,
+  created_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
+);
+CREATE INDEX IF NOT EXISTS idx_workspace_sessions_user_id ON workspace_sessions(user_id);
+CREATE INDEX IF NOT EXISTS idx_workspace_sessions_expires_at ON workspace_sessions(expires_at);

package/src/db/migrations/004_agent_mcp_status.sql

@@ -0,0 +1,2 @@
+ALTER TABLE agents ADD COLUMN IF NOT EXISTS mcp_last_seen_at TIMESTAMPTZ;
+ALTER TABLE agents ADD COLUMN IF NOT EXISTS mcp_client_name TEXT;

package/src/db/migrations/005_hold_event_actor.sql

@@ -0,0 +1,4 @@
+ALTER TABLE hold_events ADD COLUMN IF NOT EXISTS actor_type TEXT;
+ALTER TABLE hold_events ADD COLUMN IF NOT EXISTS actor_id TEXT;
+ALTER TABLE hold_events ADD COLUMN IF NOT EXISTS actor_label TEXT;
+

package/src/db/migrations/006_agent_activity.sql

@@ -0,0 +1,35 @@
+CREATE TABLE IF NOT EXISTS agent_activity_events (
+  id                 UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  org_id             UUID REFERENCES orgs(id) ON DELETE CASCADE,
+  agent_id           UUID REFERENCES agents(id) ON DELETE SET NULL,
+  activity_type      TEXT NOT NULL,
+  endpoint           TEXT,
+  method             TEXT,
+  status_code        INTEGER,
+  status             TEXT NOT NULL DEFAULT 'success' CHECK (status IN ('success', 'error')),
+  actor_type         TEXT,
+  actor_id           TEXT,
+  actor_label        TEXT,
+  client_name        TEXT,
+  latency_ms         INTEGER,
+  error_code         TEXT,
+  error_message      TEXT,
+  provider           TEXT,
+  model              TEXT,
+  input_tokens       INTEGER,
+  output_tokens      INTEGER,
+  total_tokens       INTEGER,
+  estimated_cost_usd NUMERIC(12, 6),
+  metadata           JSONB NOT NULL DEFAULT '{}',
+  created_at         TIMESTAMPTZ NOT NULL DEFAULT NOW()
+);
+
+CREATE INDEX IF NOT EXISTS idx_agent_activity_org_created
+  ON agent_activity_events(org_id, created_at DESC);
+
+CREATE INDEX IF NOT EXISTS idx_agent_activity_agent_created
+  ON agent_activity_events(agent_id, created_at DESC);
+
+CREATE INDEX IF NOT EXISTS idx_agent_activity_org_type_created
+  ON agent_activity_events(org_id, activity_type, created_at DESC);
+