availsync 0.1.0

package/src/routes/orgs.ts

@@ -0,0 +1,981 @@
+import { randomUUID } from 'crypto';
+import express from 'express';
+import { z } from 'zod';
+import pool from '../db/client';
+import { log } from '../lib/logger';
+import { PLAN_CONFIG, enforcePlanLimit } from '../lib/plans';
+import { createAgentApiKey } from '../lib/apiKeys';
+import { getAvailableSlots } from '../core/availability';
+import { previewConflict } from '../core/conflict';
+import {
+  initialWorkExpiresAt,
+  maxWorkExpiresAt,
+  previewWorkClaim,
+  upsertWorkResource,
+  workWindow,
+} from '../core/work';
+import {
+  requireWorkspaceSession,
+  type WorkspaceAuthenticatedRequest,
+} from '../middleware/auth';
+import { durationSince, logActivity, workspaceActor } from '../lib/activity';
+import type { Hold, WorkClaim } from '../types';
+
+const router = express.Router();
+
+const OrgSchema = z.object({
+  name: z.string().min(1),
+});
+
+const AgentSchema = z.object({
+  name: z.string().min(1),
+  agent_type: z
+    .enum(['external_meeting', 'internal', 'focus', 'generic'])
+    .optional()
+    .default('generic'),
+  priority: z.number().int().optional().default(0),
+});
+
+const AgentUpdateSchema = z.object({
+  name: z.string().min(1),
+  agent_type: z.enum(['external_meeting', 'internal', 'focus', 'generic']),
+  priority: z.number().int(),
+  enforcement_mode: z.enum(['enforce', 'observe']).optional(),
+});
+
+const SetupTestSchema = z.object({
+  resource_key: z.string().min(1).max(300).optional().default('setup/demo-repo'),
+});
+
+const AgentSelect = `
+  id,
+  org_id,
+  name,
+  agent_type,
+  priority,
+  enforcement_mode,
+  last_seen_at,
+  mcp_last_seen_at,
+  mcp_client_name,
+  created_at,
+  (SELECT MAX(created_at) FROM agent_activity_events WHERE agent_id = agents.id AND status = 'success') AS last_used_at,
+  (SELECT MAX(created_at) FROM agent_activity_events WHERE agent_id = agents.id) AS last_activity_at,
+  (SELECT MAX(created_at) FROM agent_activity_events WHERE agent_id = agents.id AND status = 'error') AS last_error_at,
+  (SELECT error_code FROM agent_activity_events WHERE agent_id = agents.id AND status = 'error' ORDER BY created_at DESC LIMIT 1) AS last_error_code
+`;
+
+type SetupStepStatus = 'pending' | 'running' | 'success' | 'warning' | 'blocked' | 'error';
+
+type SetupStep = {
+  name: string;
+  status: SetupStepStatus;
+  latency_ms: number;
+  summary: string;
+  next_action: string | null;
+  details?: Record<string, unknown>;
+};
+
+function mcpStatusFromLastSeen(lastSeen: Date | string | null | undefined) {
+  if (!lastSeen) return 'offline';
+  const date = new Date(lastSeen);
+  const diff = Date.now() - date.getTime();
+  if (diff < 2 * 60 * 1000) return 'online';
+  if (diff < 15 * 60 * 1000) return 'recent';
+  return 'offline';
+}
+
+async function insertSetupWorkEvent(input: {
+  claim_id?: string | null;
+  event_type: 'created' | 'blocked' | 'released' | 'extended';
+  agent_id: string;
+  org_id: string;
+  resource_id?: string | null;
+  conflicting_claim_id?: string | null;
+  rule_applied?: string | null;
+  metadata?: Record<string, unknown>;
+  actor_type?: string | null;
+  actor_id?: string | null;
+  actor_label?: string | null;
+}) {
+  await pool.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,
+    ],
+  );
+}
+
+async function logSetupActivity(input: {
+  org_id: string;
+  agent_id: string;
+  setup_type: string;
+  readiness_type?: string;
+  status?: 'success' | 'error';
+  status_code?: number;
+  latency_ms?: number;
+  error_code?: string | null;
+  error_message?: string | null;
+  metadata?: Record<string, unknown>;
+  actor: ReturnType<typeof workspaceActor>;
+}) {
+  const metadata = { source: 'setup_test', ...(input.metadata ?? {}) };
+  await logActivity({
+    org_id: input.org_id,
+    agent_id: input.agent_id,
+    activity_type: input.setup_type,
+    endpoint: '/v1/orgs/:org_id/agents/:agent_id/setup-test',
+    method: 'POST',
+    status_code: input.status_code ?? (input.status === 'error' ? 500 : 200),
+    status: input.status ?? 'success',
+    ...input.actor,
+    latency_ms: input.latency_ms,
+    error_code: input.error_code ?? null,
+    error_message: input.error_message ?? null,
+    client_name: 'dashboard-setup-test',
+    metadata,
+  });
+
+  if (input.readiness_type) {
+    await logActivity({
+      org_id: input.org_id,
+      agent_id: input.agent_id,
+      activity_type: input.readiness_type,
+      endpoint: '/v1/orgs/:org_id/agents/:agent_id/setup-test',
+      method: 'POST',
+      status_code: input.status_code ?? (input.status === 'error' ? 500 : 200),
+      status: input.status ?? 'success',
+      ...input.actor,
+      latency_ms: input.latency_ms,
+      error_code: input.error_code ?? null,
+      error_message: input.error_message ?? null,
+      client_name: 'dashboard-setup-test',
+      metadata,
+    });
+  }
+}
+
+router.post('/orgs', async (req, res) => {
+  const result = OrgSchema.safeParse(req.body);
+  if (!result.success) {
+    return res.status(422).json({ error: 'validation_error', details: result.error.flatten() });
+  }
+
+  try {
+    const created = await pool.query(
+      "INSERT INTO orgs (name, plan, agent_limit, subscription_status) VALUES ($1, 'free', $2, 'free') RETURNING *",
+      [result.data.name, PLAN_CONFIG.free.db_agent_limit],
+    );
+    return res.status(201).json({ org: created.rows[0] });
+  } catch (err) {
+    log.error('[orgs] unexpected error', { error: (err as Error).message });
+    return res.status(500).json({ error: 'internal_error', message: 'An unexpected error occurred' });
+  }
+});
+
+router.post('/orgs/:org_id/agents', requireWorkspaceSession, async (req, res) => {
+  const result = AgentSchema.safeParse(req.body);
+  if (!result.success) {
+    return res.status(422).json({ error: 'validation_error', details: result.error.flatten() });
+  }
+
+  const authReq = req as WorkspaceAuthenticatedRequest;
+  if (authReq.org.id !== req.params.org_id) {
+    return res.status(403).json({ error: 'forbidden', message: 'Organization is outside your workspace' });
+  }
+
+  try {
+    const org = await pool.query('SELECT * FROM orgs WHERE id = $1', [req.params.org_id]);
+    if (org.rows.length === 0) {
+      return res.status(404).json({ error: 'org_not_found', message: 'Organization not found' });
+    }
+
+    if (!(await enforcePlanLimit({
+      org_id: req.params.org_id,
+      limit_type: 'agents',
+      res,
+    }))) {
+      return;
+    }
+
+    const { apiKey, apiKeyHash, apiKeyPrefix } = await createAgentApiKey();
+
+    const client = await pool.connect();
+    try {
+      await client.query('BEGIN');
+      const created = await client.query(
+        `INSERT INTO agents (org_id, name, api_key_hash, api_key_prefix, agent_type, priority)
+         VALUES ($1, $2, $3, $4, $5, $6)
+         RETURNING *`,
+        [
+          req.params.org_id,
+          result.data.name,
+          apiKeyHash,
+          apiKeyPrefix,
+          result.data.agent_type,
+          result.data.priority,
+        ],
+      );
+      await client.query('INSERT INTO agent_preferences (agent_id) VALUES ($1)', [
+        created.rows[0].id,
+      ]);
+      await client.query('COMMIT');
+
+      const { api_key_hash: _apiKeyHash, api_key_prefix: _apiKeyPrefix, ...agent } = created.rows[0];
+      return res.status(201).json({ agent, api_key: apiKey });
+    } catch (err) {
+      await client.query('ROLLBACK');
+      throw err;
+    } finally {
+      client.release();
+    }
+  } catch (err) {
+    log.error('[orgs] unexpected error', { error: (err as Error).message });
+    return res.status(500).json({ error: 'internal_error', message: 'An unexpected error occurred' });
+  }
+});
+
+router.get('/orgs/:org_id/agents', requireWorkspaceSession, async (req, res) => {
+  const authReq = req as WorkspaceAuthenticatedRequest;
+  if (authReq.org.id !== req.params.org_id) {
+    return res.status(403).json({ error: 'forbidden', message: 'Organization is outside your workspace' });
+  }
+
+  try {
+    const agents = await pool.query(
+      `SELECT ${AgentSelect}
+       FROM agents
+       WHERE org_id = $1
+       ORDER BY created_at ASC`,
+      [req.params.org_id],
+    );
+    return res.json({ agents: agents.rows });
+  } catch (err) {
+    log.error('[orgs] unexpected error', { error: (err as Error).message });
+    return res.status(500).json({ error: 'internal_error', message: 'An unexpected error occurred' });
+  }
+});
+
+router.put('/orgs/:org_id/agents/:agent_id', requireWorkspaceSession, async (req, res) => {
+  const authReq = req as WorkspaceAuthenticatedRequest;
+  if (authReq.org.id !== req.params.org_id) {
+    return res.status(403).json({ error: 'forbidden', message: 'Organization is outside your workspace' });
+  }
+
+  const agentId = z.string().uuid().safeParse(req.params.agent_id);
+  if (!agentId.success) {
+    return res.status(400).json({ error: 'validation_error', details: agentId.error.flatten() });
+  }
+
+  const parsed = AgentUpdateSchema.safeParse(req.body);
+  if (!parsed.success) {
+    return res.status(422).json({ error: 'validation_error', details: parsed.error.flatten() });
+  }
+
+  try {
+    const updated = await pool.query(
+      `UPDATE agents
+       SET name = $1,
+           agent_type = $2,
+           priority = $3,
+           enforcement_mode = COALESCE($4, enforcement_mode)
+       WHERE id = $5
+         AND org_id = $6
+       RETURNING id, org_id, name, agent_type, priority, enforcement_mode, last_seen_at, mcp_last_seen_at, mcp_client_name, created_at`,
+      [
+        parsed.data.name,
+        parsed.data.agent_type,
+        parsed.data.priority,
+        parsed.data.enforcement_mode,
+        agentId.data,
+        authReq.org.id,
+      ],
+    );
+
+    if (updated.rows.length === 0) {
+      return res.status(404).json({ error: 'agent_not_found', message: 'Agent not found' });
+    }
+
+    return res.json({ agent: updated.rows[0] });
+  } catch (err) {
+    log.error('[orgs] unexpected error', { error: (err as Error).message });
+    return res.status(500).json({ error: 'internal_error', message: 'An unexpected error occurred' });
+  }
+});
+
+router.delete('/orgs/:org_id/agents/:agent_id', requireWorkspaceSession, async (req, res) => {
+  const authReq = req as WorkspaceAuthenticatedRequest;
+  if (authReq.org.id !== req.params.org_id) {
+    return res.status(403).json({ error: 'forbidden', message: 'Organization is outside your workspace' });
+  }
+
+  const agentId = z.string().uuid().safeParse(req.params.agent_id);
+  if (!agentId.success) {
+    return res.status(400).json({ error: 'validation_error', details: agentId.error.flatten() });
+  }
+
+  try {
+    const count = await pool.query('SELECT COUNT(*)::int AS count FROM agents WHERE org_id = $1', [
+      authReq.org.id,
+    ]);
+    if (count.rows[0].count <= 1) {
+      return res.status(400).json({ error: 'last_agent', message: 'Create another agent before deleting this one' });
+    }
+
+    const deleted = await pool.query(
+      `DELETE FROM agents
+       WHERE id = $1
+         AND org_id = $2
+       RETURNING id, org_id, name, agent_type, priority, enforcement_mode, last_seen_at, mcp_last_seen_at, mcp_client_name, created_at`,
+      [agentId.data, authReq.org.id],
+    );
+
+    if (deleted.rows.length === 0) {
+      return res.status(404).json({ error: 'agent_not_found', message: 'Agent not found' });
+    }
+
+    return res.json({ agent: deleted.rows[0] });
+  } catch (err) {
+    log.error('[orgs] unexpected error', { error: (err as Error).message });
+    return res.status(500).json({ error: 'internal_error', message: 'An unexpected error occurred' });
+  }
+});
+
+router.post('/orgs/:org_id/agents/:agent_id/rotate-key', requireWorkspaceSession, async (req, res) => {
+  const authReq = req as WorkspaceAuthenticatedRequest;
+  if (authReq.org.id !== req.params.org_id) {
+    return res.status(403).json({ error: 'forbidden', message: 'Organization is outside your workspace' });
+  }
+
+  const agentId = z.string().uuid().safeParse(req.params.agent_id);
+  if (!agentId.success) {
+    return res.status(400).json({ error: 'validation_error', details: agentId.error.flatten() });
+  }
+
+  try {
+    const { apiKey, apiKeyHash, apiKeyPrefix } = await createAgentApiKey();
+
+    const updated = await pool.query(
+      `UPDATE agents
+       SET api_key_hash = $1,
+           api_key_prefix = $2
+       WHERE id = $3
+         AND org_id = $4
+       RETURNING id, org_id, name, agent_type, priority, enforcement_mode, last_seen_at, mcp_last_seen_at, mcp_client_name, created_at`,
+      [apiKeyHash, apiKeyPrefix, agentId.data, authReq.org.id],
+    );
+
+    if (updated.rows.length === 0) {
+      return res.status(404).json({ error: 'agent_not_found', message: 'Agent not found' });
+    }
+
+    await logActivity({
+      org_id: authReq.org.id,
+      agent_id: agentId.data,
+      activity_type: 'key_rotated',
+      endpoint: `/v1/orgs/${req.params.org_id}/agents/${agentId.data}/rotate-key`,
+      method: 'POST',
+      status_code: 200,
+      status: 'success',
+      ...workspaceActor(authReq),
+    });
+
+    return res.json({ agent: updated.rows[0], api_key: apiKey });
+  } catch (err) {
+    log.error('[orgs] rotate key error', { error: (err as Error).message });
+    return res.status(500).json({ error: 'internal_error', message: 'An unexpected error occurred' });
+  }
+});
+
+router.post('/orgs/:org_id/agents/:agent_id/setup-test', requireWorkspaceSession, async (req, res) => {
+  const parsed = SetupTestSchema.safeParse(req.body ?? {});
+  if (!parsed.success) {
+    return res.status(422).json({ error: 'validation_error', details: parsed.error.flatten() });
+  }
+
+  const authReq = req as WorkspaceAuthenticatedRequest;
+  if (authReq.org.id !== req.params.org_id) {
+    return res.status(403).json({ error: 'forbidden', message: 'Organization is outside your workspace' });
+  }
+
+  const agentId = z.string().uuid().safeParse(req.params.agent_id);
+  if (!agentId.success) {
+    return res.status(400).json({ error: 'validation_error', details: agentId.error.flatten() });
+  }
+
+  const runId = randomUUID();
+  const startedAt = new Date();
+  const steps: SetupStep[] = [];
+  const actor = workspaceActor(authReq);
+  let createdClaimId: string | null = null;
+  let createdResourceId: string | null = null;
+  let finalStatus: 'success' | 'warning' | 'blocked' | 'error' = 'success';
+
+  const addStep = (step: SetupStep) => {
+    steps.push(step);
+    if (step.status === 'error') finalStatus = 'error';
+    if (step.status === 'blocked' && finalStatus !== 'error') finalStatus = 'blocked';
+    if (step.status === 'warning' && finalStatus === 'success') finalStatus = 'warning';
+  };
+
+  try {
+    const agent = await pool.query(
+      `SELECT ${AgentSelect}
+       FROM agents
+       WHERE id = $1
+         AND org_id = $2`,
+      [agentId.data, authReq.org.id],
+    );
+
+    if (agent.rows.length === 0) {
+      return res.status(404).json({ error: 'agent_not_found', message: 'Agent not found' });
+    }
+
+    const mcpStarted = Date.now();
+    const mcpStatus = mcpStatusFromLastSeen(agent.rows[0].mcp_last_seen_at);
+    addStep({
+      name: 'mcp_status_observed',
+      status: mcpStatus === 'online' ? 'success' : 'warning',
+      latency_ms: durationSince(mcpStarted),
+      summary: `MCP status is ${mcpStatus}.`,
+      next_action: mcpStatus === 'online' ? null : 'Start the MCP server to send a real heartbeat.',
+      details: {
+        mcp_status: mcpStatus,
+        mcp_last_seen_at: agent.rows[0].mcp_last_seen_at ?? null,
+        mcp_client_name: agent.rows[0].mcp_client_name ?? null,
+      },
+    });
+
+    const from = new Date();
+    const to = new Date(from.getTime() + 8 * 60 * 60 * 1000);
+    const availabilityStarted = Date.now();
+    const slots = await getAvailableSlots({
+      agent_id: agentId.data,
+      org_id: authReq.org.id,
+      from,
+      to,
+      duration_minutes: 30,
+      include_competing_agents: true,
+    });
+    await logSetupActivity({
+      org_id: authReq.org.id,
+      agent_id: agentId.data,
+      setup_type: 'setup_test_availability',
+      readiness_type: 'availability_check',
+      latency_ms: durationSince(availabilityStarted),
+      metadata: { run_id: runId, slot_count: slots.length },
+      actor,
+    });
+    addStep({
+      name: 'availability_check',
+      status: slots.length > 0 ? 'success' : 'warning',
+      latency_ms: durationSince(availabilityStarted),
+      summary: slots.length > 0 ? `${slots.length} available slots found.` : 'No availability windows produced open slots.',
+      next_action: slots.length > 0 ? null : 'Create an availability window for this agent.',
+      details: {
+        slot_count: slots.length,
+        first_slot: slots[0]
+          ? { start: slots[0].start.toISOString(), end: slots[0].end.toISOString() }
+          : null,
+      },
+    });
+
+    const previewStart = slots[0]?.start ?? new Date(Date.now() + 30 * 60 * 1000);
+    const previewEnd = slots[0]?.end ?? new Date(previewStart.getTime() + 30 * 60 * 1000);
+    const conflictStarted = Date.now();
+    const conflict = await previewConflict(
+      {
+        agent_id: agentId.data,
+        org_id: authReq.org.id,
+        start_at: previewStart,
+        end_at: previewEnd,
+        reason: 'Availsync setup test',
+        status: 'confirmed',
+        metadata: { source: 'setup_test', run_id: runId },
+      } as Omit<Hold, 'id' | 'created_at'>,
+      pool as never,
+    );
+    await logSetupActivity({
+      org_id: authReq.org.id,
+      agent_id: agentId.data,
+      setup_type: 'setup_test_conflict_preview',
+      readiness_type: 'conflict_preview',
+      latency_ms: durationSince(conflictStarted),
+      metadata: { run_id: runId, status: conflict.status, rule_applied: conflict.rule_applied },
+      actor,
+    });
+    addStep({
+      name: 'conflict_preview',
+      status: conflict.status === 'would_lose' ? 'warning' : 'success',
+      latency_ms: durationSince(conflictStarted),
+      summary: `Conflict preview returned ${conflict.status}.`,
+      next_action: conflict.status === 'would_lose' ? 'Review existing holds or agent priority rules.' : null,
+      details: {
+        status: conflict.status,
+        rule_applied: conflict.rule_applied,
+        winning_hold_id: conflict.winning_hold_id,
+        losing_hold_ids: conflict.losing_hold_ids,
+      },
+    });
+
+    const workCheckStarted = Date.now();
+    const claimWindow = workWindow({ duration_minutes: 45 });
+    const client = await pool.connect();
+    try {
+      await client.query('BEGIN');
+      await client.query('SELECT pg_advisory_xact_lock(hashtext($1))', [
+        `${authReq.org.id}:repo:${parsed.data.resource_key}`,
+      ]);
+
+      const resource = await upsertWorkResource(client, {
+        org_id: authReq.org.id,
+        resource_type: 'repo',
+        resource_key: parsed.data.resource_key,
+        label: parsed.data.resource_key,
+      });
+      createdResourceId = resource.id;
+
+      const workCheck = await previewWorkClaim(client, {
+        org_id: authReq.org.id,
+        agent_id: agentId.data,
+        resource_id: resource.id,
+        start_at: claimWindow.startAt,
+        end_at: claimWindow.endAt,
+        reason: 'Availsync setup test',
+        metadata: { source: 'setup_test', run_id: runId },
+      });
+      await logSetupActivity({
+        org_id: authReq.org.id,
+        agent_id: agentId.data,
+        setup_type: 'setup_test_work_check',
+        readiness_type: 'work_check',
+        latency_ms: durationSince(workCheckStarted),
+        metadata: {
+          run_id: runId,
+          resource_key: parsed.data.resource_key,
+          status: workCheck.status,
+          rule_applied: workCheck.rule_applied,
+        },
+        actor,
+      });
+      addStep({
+        name: 'work_check',
+        status: workCheck.status === 'available' ? 'success' : 'blocked',
+        latency_ms: durationSince(workCheckStarted),
+        summary: `Work check returned ${workCheck.status} for ${parsed.data.resource_key}.`,
+        next_action: workCheck.status === 'available' ? null : 'Use a different setup resource or release the existing active claim.',
+        details: {
+          resource_key: parsed.data.resource_key,
+          status: workCheck.status,
+          winning_claim_id: workCheck.winning_claim_id,
+          losing_claim_ids: workCheck.losing_claim_ids,
+          rule_applied: workCheck.rule_applied,
+        },
+      });
+
+      if (workCheck.status !== 'available') {
+        await insertSetupWorkEvent({
+          event_type: 'blocked',
+          agent_id: agentId.data,
+          org_id: authReq.org.id,
+          resource_id: resource.id,
+          conflicting_claim_id: workCheck.winning_claim_id,
+          rule_applied: workCheck.rule_applied,
+          metadata: { source: 'setup_test', run_id: runId, resource_key: parsed.data.resource_key },
+          ...actor,
+        });
+        await logSetupActivity({
+          org_id: authReq.org.id,
+          agent_id: agentId.data,
+          setup_type: 'setup_test_work_blocked',
+          status: 'error',
+          status_code: 409,
+          error_code: 'work_claim_blocked',
+          error_message: 'Setup test work claim was blocked by an active claim',
+          metadata: { run_id: runId, resource_key: parsed.data.resource_key, winning_claim_id: workCheck.winning_claim_id },
+          actor,
+        });
+        await client.query('COMMIT');
+        const finishedAt = new Date();
+        await logSetupActivity({
+          org_id: authReq.org.id,
+          agent_id: agentId.data,
+          setup_type: 'setup_test',
+          status: 'error',
+          status_code: 409,
+          error_code: 'work_claim_blocked',
+          error_message: 'Setup test blocked by active work claim',
+          latency_ms: finishedAt.getTime() - startedAt.getTime(),
+          metadata: { run_id: runId, final_status: 'blocked' },
+          actor,
+        });
+        return res.status(409).json({
+          run_id: runId,
+          status: 'blocked',
+          steps,
+          started_at: startedAt.toISOString(),
+          finished_at: finishedAt.toISOString(),
+        });
+      }
+
+      const workClaimStarted = Date.now();
+      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
+         )
+         VALUES ($1, $2, $3, $4, $5, 'active', $6, $7, $8, NOW(), 0)
+         RETURNING *`,
+        [
+          authReq.org.id,
+          agentId.data,
+          resource.id,
+          claimWindow.startAt,
+          claimWindow.endAt,
+          'Availsync setup test',
+          JSON.stringify({ source: 'setup_test', run_id: runId }),
+          initialWorkExpiresAt(claimWindow.startAt, claimWindow.endAt),
+        ],
+      );
+      createdClaimId = created.rows[0].id;
+      await insertSetupWorkEvent({
+        claim_id: createdClaimId,
+        event_type: 'created',
+        agent_id: agentId.data,
+        org_id: authReq.org.id,
+        resource_id: resource.id,
+        rule_applied: workCheck.rule_applied,
+        metadata: { source: 'setup_test', run_id: runId, resource_key: parsed.data.resource_key },
+        ...actor,
+      });
+      await logSetupActivity({
+        org_id: authReq.org.id,
+        agent_id: agentId.data,
+        setup_type: 'setup_test_work_claim',
+        readiness_type: 'work_claim',
+        latency_ms: durationSince(workClaimStarted),
+        metadata: { source: 'setup_test', run_id: runId, claim_id: createdClaimId, resource_key: parsed.data.resource_key },
+        actor,
+      });
+      addStep({
+        name: 'work_claim',
+        status: 'success',
+        latency_ms: durationSince(workClaimStarted),
+        summary: 'Temporary setup claim created.',
+        next_action: null,
+        details: { claim_id: createdClaimId, resource_key: parsed.data.resource_key },
+      });
+
+      const extendStarted = Date.now();
+      const maxExpires = maxWorkExpiresAt(created.rows[0].start_at);
+      const requestedExpires = new Date(Date.now() + 15 * 60_000);
+      const nextExpires = requestedExpires < maxExpires ? requestedExpires : maxExpires;
+      const extended = await client.query<WorkClaim>(
+        `UPDATE work_claims
+         SET expires_at = $1,
+             last_renewed_at = NOW(),
+             renewal_count = renewal_count + 1
+         WHERE id = $2
+         RETURNING *`,
+        [nextExpires, createdClaimId],
+      );
+      await insertSetupWorkEvent({
+        claim_id: createdClaimId,
+        event_type: 'extended',
+        agent_id: agentId.data,
+        org_id: authReq.org.id,
+        resource_id: resource.id,
+        metadata: {
+          source: 'setup_test',
+          run_id: runId,
+          expires_at: extended.rows[0].expires_at.toISOString(),
+          renewal_count: extended.rows[0].renewal_count,
+        },
+        ...actor,
+      });
+      await logSetupActivity({
+        org_id: authReq.org.id,
+        agent_id: agentId.data,
+        setup_type: 'setup_test_work_extend',
+        readiness_type: 'work_extend',
+        latency_ms: durationSince(extendStarted),
+        metadata: { run_id: runId, claim_id: createdClaimId, renewal_count: extended.rows[0].renewal_count },
+        actor,
+      });
+      addStep({
+        name: 'work_extend',
+        status: 'success',
+        latency_ms: durationSince(extendStarted),
+        summary: 'Temporary setup claim extended.',
+        next_action: null,
+        details: { claim_id: createdClaimId, renewal_count: extended.rows[0].renewal_count },
+      });
+
+      const releaseStarted = Date.now();
+      const released = await client.query<WorkClaim>(
+        `UPDATE work_claims
+         SET status = 'released'
+         WHERE id = $1
+           AND status = 'active'
+         RETURNING *`,
+        [createdClaimId],
+      );
+      await insertSetupWorkEvent({
+        claim_id: createdClaimId,
+        event_type: 'released',
+        agent_id: agentId.data,
+        org_id: authReq.org.id,
+        resource_id: resource.id,
+        metadata: { source: 'setup_test', run_id: runId, cleanup: true },
+        ...actor,
+      });
+      await logSetupActivity({
+        org_id: authReq.org.id,
+        agent_id: agentId.data,
+        setup_type: 'setup_test_work_release',
+        readiness_type: 'work_release',
+        latency_ms: durationSince(releaseStarted),
+        metadata: { run_id: runId, claim_id: createdClaimId, released: released.rows.length > 0 },
+        actor,
+      });
+      addStep({
+        name: 'work_release',
+        status: 'success',
+        latency_ms: durationSince(releaseStarted),
+        summary: 'Temporary setup claim released.',
+        next_action: null,
+        details: { claim_id: createdClaimId },
+      });
+
+      await client.query('COMMIT');
+    } catch (err) {
+      await client.query('ROLLBACK').catch(() => {});
+      throw err;
+    } finally {
+      client.release();
+    }
+
+    const finishedAt = new Date();
+    await logSetupActivity({
+      org_id: authReq.org.id,
+      agent_id: agentId.data,
+      setup_type: 'setup_test',
+      latency_ms: finishedAt.getTime() - startedAt.getTime(),
+      metadata: { run_id: runId, final_status: finalStatus, resource_id: createdResourceId },
+      actor,
+    });
+
+    return res.json({
+      run_id: runId,
+      status: finalStatus,
+      steps,
+      started_at: startedAt.toISOString(),
+      finished_at: finishedAt.toISOString(),
+    });
+  } catch (err) {
+    if (createdClaimId) {
+      await pool.query(
+        `UPDATE work_claims
+         SET status = 'released'
+         WHERE id = $1
+           AND org_id = $2
+           AND status = 'active'`,
+        [createdClaimId, authReq.org.id],
+      ).catch(() => {});
+      addStep({
+        name: 'work_release',
+        status: 'warning',
+        latency_ms: 0,
+        summary: 'Cleanup attempted after setup test failure.',
+        next_action: 'Check Work Coordination for any active setup/demo-repo claim.',
+        details: { claim_id: createdClaimId },
+      });
+    }
+
+    const message = (err as Error).message;
+    log.error('[orgs] setup test error', { error: message, run_id: runId });
+    const finishedAt = new Date();
+    await logSetupActivity({
+      org_id: authReq.org.id,
+      agent_id: agentId.success ? agentId.data : req.params.agent_id,
+      setup_type: 'setup_test',
+      status: 'error',
+      status_code: 500,
+      error_code: 'setup_test_failed',
+      error_message: message,
+      latency_ms: finishedAt.getTime() - startedAt.getTime(),
+      metadata: { run_id: runId },
+      actor,
+    }).catch(() => {});
+    return res.status(500).json({
+      run_id: runId,
+      status: 'error',
+      steps,
+      started_at: startedAt.toISOString(),
+      finished_at: finishedAt.toISOString(),
+      error: 'setup_test_failed',
+      message: 'Setup test failed before completion',
+    });
+  }
+});
+
+router.post('/orgs/:org_id/agents/:agent_id/test-connection', requireWorkspaceSession, async (req, res) => {
+  const authReq = req as WorkspaceAuthenticatedRequest;
+  if (authReq.org.id !== req.params.org_id) {
+    return res.status(403).json({ error: 'forbidden', message: 'Organization is outside your workspace' });
+  }
+
+  const agentId = z.string().uuid().safeParse(req.params.agent_id);
+  if (!agentId.success) {
+    return res.status(400).json({ error: 'validation_error', details: agentId.error.flatten() });
+  }
+
+  try {
+    const agent = await pool.query(
+      `SELECT ${AgentSelect}
+       FROM agents
+       WHERE id = $1
+         AND org_id = $2`,
+      [agentId.data, authReq.org.id],
+    );
+
+    if (agent.rows.length === 0) {
+      return res.status(404).json({ error: 'agent_not_found', message: 'Agent not found' });
+    }
+
+    const lastSuccess = await pool.query(
+      `SELECT activity_type, endpoint, method, status_code, client_name, created_at
+       FROM agent_activity_events
+       WHERE agent_id = $1
+         AND status = 'success'
+       ORDER BY created_at DESC
+       LIMIT 1`,
+      [agentId.data],
+    );
+    const lastError = await pool.query(
+      `SELECT activity_type, endpoint, method, status_code, error_code, error_message, created_at
+       FROM agent_activity_events
+       WHERE agent_id = $1
+         AND status = 'error'
+       ORDER BY created_at DESC
+       LIMIT 1`,
+      [agentId.data],
+    );
+    const readiness = await pool.query(
+      `SELECT
+         EXISTS(SELECT 1 FROM availability_windows WHERE agent_id = $1) AS availability_window_created,
+         EXISTS(SELECT 1 FROM agent_activity_events WHERE agent_id = $1 AND activity_type = 'mcp_heartbeat') AS mcp_heartbeat_seen,
+         EXISTS(SELECT 1 FROM agent_activity_events WHERE agent_id = $1 AND activity_type = 'availability_check') AS first_availability_check,
+         EXISTS(SELECT 1 FROM agent_activity_events WHERE agent_id = $1 AND activity_type = 'conflict_preview') AS first_conflict_preview,
+         EXISTS(SELECT 1 FROM holds WHERE agent_id = $1) AS first_hold_created,
+         EXISTS(SELECT 1 FROM agent_activity_events WHERE agent_id = $1 AND activity_type = 'work_check') AS first_work_check,
+         EXISTS(SELECT 1 FROM agent_activity_events WHERE agent_id = $1 AND activity_type = 'work_claim') AS first_work_claim,
+         EXISTS(SELECT 1 FROM agent_activity_events WHERE agent_id = $1 AND activity_type = 'work_extend') AS first_work_extend,
+         EXISTS(SELECT 1 FROM agent_activity_events WHERE agent_id = $1 AND activity_type = 'work_release') AS first_work_release,
+         (SELECT created_at FROM agent_activity_events WHERE agent_id = $1 ORDER BY created_at DESC LIMIT 1) AS latest_activity_at,
+         (SELECT activity_type FROM agent_activity_events WHERE agent_id = $1 ORDER BY created_at DESC LIMIT 1) AS latest_activity_type`,
+      [agentId.data],
+    );
+    const readinessRow = readiness.rows[0];
+
+    const mcpLastSeen = agent.rows[0].mcp_last_seen_at ? new Date(agent.rows[0].mcp_last_seen_at) : null;
+    const mcpStatus =
+      mcpLastSeen && Date.now() - mcpLastSeen.getTime() < 2 * 60 * 1000
+        ? 'online'
+        : mcpLastSeen && Date.now() - mcpLastSeen.getTime() < 15 * 60 * 1000
+          ? 'recent'
+          : 'offline';
+
+    await logActivity({
+      org_id: authReq.org.id,
+      agent_id: agentId.data,
+      activity_type: 'connection_test',
+      endpoint: `/v1/orgs/${req.params.org_id}/agents/${agentId.data}/test-connection`,
+      method: 'POST',
+      status_code: 200,
+      status: 'success',
+      ...workspaceActor(authReq),
+    });
+
+    return res.json({
+      agent_id: agentId.data,
+      last_seen_at: agent.rows[0].last_seen_at ?? null,
+      mcp_status: mcpStatus,
+      mcp_last_seen_at: agent.rows[0].mcp_last_seen_at,
+      mcp_client_name: agent.rows[0].mcp_client_name,
+      last_successful_api_call: lastSuccess.rows[0] ?? null,
+      last_error: lastError.rows[0] ?? null,
+      setup_readiness: {
+        agent_created: true,
+        availability_window_created: readinessRow.availability_window_created,
+        mcp_heartbeat_seen: readinessRow.mcp_heartbeat_seen,
+        first_availability_check: readinessRow.first_availability_check,
+        first_conflict_preview: readinessRow.first_conflict_preview,
+        first_hold_created: readinessRow.first_hold_created,
+        first_work_check: readinessRow.first_work_check,
+        first_work_claim: readinessRow.first_work_claim,
+        first_work_extend: readinessRow.first_work_extend,
+        first_work_release: readinessRow.first_work_release,
+        latest_activity_at: readinessRow.latest_activity_at,
+        latest_activity_type: readinessRow.latest_activity_type,
+        mcp: {
+          heartbeat_seen: readinessRow.mcp_heartbeat_seen,
+          status: mcpStatus,
+          last_seen_at: agent.rows[0].mcp_last_seen_at,
+        },
+        calendar: {
+          availability_window_created: readinessRow.availability_window_created,
+          first_availability_check: readinessRow.first_availability_check,
+          first_conflict_preview: readinessRow.first_conflict_preview,
+          first_hold_created: readinessRow.first_hold_created,
+        },
+        work: {
+          first_work_check: readinessRow.first_work_check,
+          first_work_claim: readinessRow.first_work_claim,
+          first_work_extend: readinessRow.first_work_extend,
+          first_work_release: readinessRow.first_work_release,
+        },
+        activity: {
+          latest_activity_at: readinessRow.latest_activity_at,
+          latest_activity_type: readinessRow.latest_activity_type,
+        },
+      },
+    });
+  } catch (err) {
+    log.error('[orgs] test connection error', { error: (err as Error).message });
+    return res.status(500).json({ error: 'internal_error', message: 'An unexpected error occurred' });
+  }
+});
+
+export default router;