Self-hosted, Self-Improving, Federated Everything App — dev management, agent orchestration, persistent mind, digital twin, second brain, and creative pipeline from a single dashboard over Tailscale to port the user into the OS
JavaScript ai-agentsdashboarddeveloper-toolsdigital-twinquantified-selfsecond-brainself-hostedtailscale
/**
* CoS Agent Management Routes
*/
import { Router } from 'express';
import { z } from 'zod';
import { cleanupZombieAgents, deleteAgent, getAgent, getAgentPrompt, getAgentRecord, getAgents, sendBtwToAgent } from '../services/cosAgentLifecycle.js';
import { getTaskView } from '../services/cosTaskStore.js';
import { clearCompletedAgents } from '../services/cosAgentArchive.js';
import { getAgentDates, getAgentsByDate, getCompletedAgentPage } from '../services/cosAgentIndex.js';
import { getFeedbackStats, getPendingAgentFeedback, getPendingAgentFeedbackCount, getPendingAgentFeedbackPage, submitAgentFeedback } from '../services/cosAgentFeedback.js';
import { getHealthStatus, runHealthCheck } from '../services/cosHealthMonitor.js';
// Lifecycle transitions go through the facade (#3450).
import * as agentOrchestrator from '../services/agentOrchestrator.js';
import { asyncHandler, ServerError } from '../lib/errorHandler.js';
import { toAgentListItems } from '../lib/cosAgentListProjection.js';
import { isDeliveryCleanupHeld } from '../lib/taskRetryHold.js';
import { getDeliveryActivity } from '../services/agentDeliveryActivity.js';
import { securityScanRequestSchema } from '../lib/securityScanEvidence.js';
import { validateRequest, resumeCosAgentSchema, relaunchCosAgentSchema, cosAgentFeedbackBodySchema, cosAgentBtwBodySchema } from '../lib/validation.js';
const router = Router();
router.post('/agents/:id/security-scan', asyncHandler(async (req, res) => {
const input = validateRequest(securityScanRequestSchema, req.body ?? {});
const { runAgentSecurityScan } = await import('../services/agentSecurityScan.js');
res.json(await runAgentSecurityScan(req.params.id, input));
}));
const mergeAdmissionSchema = z.object({
agentId: z.string().min(1).max(200),
action: z.enum(['acquire', 'check', 'release']),
token: z.string().uuid().optional(),
// Mirrors MERGE_ADMISSION_OUTCOMES; the service stays lazily imported.
outcome: z.enum(['merged', 'leave-open', 'resync']).optional(),
});
router.post('/merge-admission', asyncHandler(async (req, res) => {
const input = validateRequest(mergeAdmissionSchema, req.body ?? {});
const { claimMergeAdmission } = await import('../services/cosMergeAdmission.js');
res.json(await claimMergeAdmission(input));
}));
// Outside operators have no CoS agent record. A per-run secret separates
// sessions sharing the agent-key credential; only its principal-bound hash is
// persisted. Neither an agentId nor a PR's prose can select another owner.
const externalMergeAdmissionSchema = z.discriminatedUnion('action', [
z.object({
action: z.literal('acquire'), appId: z.string().min(1).max(200),
worktreePath: z.string().min(1).max(4096), prUrl: z.string().url().max(2048),
baseBranch: z.string().min(1).max(255),
headSha: z.string().regex(/^[a-f0-9]{40}$/), baseSha: z.string().regex(/^[a-f0-9]{40}$/),
}).strict(),
z.object({ action: z.literal('check'), token: z.string().uuid() }).strict(),
z.object({ action: z.literal('release'), token: z.string().uuid(),
outcome: z.enum(['merged', 'leave-open', 'resync']) }).strict(),
]);
router.post('/merge-admission/external', asyncHandler(async (req, res) => {
const input = validateRequest(externalMergeAdmissionSchema, req.body ?? {});
const { externalAdmissionOwner } = await import('../services/externalAdmissionAuth.js');
const { externalMergeAdmission } = await import('../services/cosMergeAdmission.js');
res.json(await externalMergeAdmission(input, () => externalAdmissionOwner(req)));
}));
// A registered run hands its published, reviewed head to the server's
// pending-merge coordinator instead of waiting for CI itself (#12247). The
// repository, branch, checkout and policy come from the run's registration.
const mergeHandoffSchema = z.object({
agentId: z.string().min(1).max(200),
prUrl: z.string().url().max(2048),
headSha: z.string().regex(/^[0-9a-fA-F]{40}$/),
worktreePath: z.string().min(1).max(4096).optional(),
});
router.post('/merge-handoff', asyncHandler(async (req, res) => {
const input = validateRequest(mergeHandoffSchema, req.body ?? {});
const { handoffPendingMerge } = await import('../services/cosMergeHandoff.js');
res.json(await handoffPendingMerge(input));
}));
// A claim run binds (or hands off) the concrete branch it checks out; a
// branch-reconcile worker rechecks live ownership right before mutating (#10089).
const claimBranchSchema = z.string().min(1).max(200);
const claimOwnershipSchema = z.discriminatedUnion('action', [
z.object({ action: z.literal('bind'), agentId: z.string().min(1).max(200), branch: claimBranchSchema }),
z.object({ action: z.literal('release'), agentId: z.string().min(1).max(200), branch: claimBranchSchema }),
z.object({
action: z.literal('check'),
appId: z.string().min(1).max(200),
branch: claimBranchSchema,
worktreePath: z.string().min(1).max(4096).optional(),
agentId: z.string().min(1).max(200).optional(),
}),
]);
router.post('/claim-ownership', asyncHandler(async (req, res) => {
const input = validateRequest(claimOwnershipSchema, req.body ?? {});
const { updateClaimOwnership, checkReconcileOwnership } = await import('../services/cosClaimOwnership.js');
res.json(input.action === 'check' ? await checkReconcileOwnership(input) : await updateClaimOwnership(input));
}));
// `reason` is persisted into task metadata + interpolated into logs; guard the
// shape so a non-string body can't store `[object Object]`.
const pauseBodySchema = z.object({ reason: z.string().max(500).optional() });
// GET /agents/:id?lines=N — how many TAIL transcript lines to hydrate. The
// service defaults to `AGENT_OUTPUT_TAIL_LINES` and the ceiling here keeps a
// hand-written query from re-opening the unbounded read this cap closed (#3498).
const agentQuerySchema = z.object({
lines: z.coerce.number().int().positive().max(10000).optional()
});
// GET /api/cos/health - Get health status
router.get('/health', asyncHandler(async (req, res) => {
const health = await getHealthStatus();
res.json(health);
}));
// POST /api/cos/health/check - Force health check
router.post('/health/check', asyncHandler(async (req, res) => {
const result = await runHealthCheck();
res.json(result);
}));
// GET /api/cos/agents - Get state-resident agents (running + recently completed, auto-cleans zombies)
// Output arrays and over-long task descriptions are stripped from every listing
// here — both are loaded on demand via GET /agents/:id. See cosAgentListProjection.js.
router.get('/agents', asyncHandler(async (req, res) => {
// Zombie cleanup probes the standalone runner and can wait up to its
// transport timeout when that optional process is restarting or offline.
// The state listing is still useful while that repair runs, so keep cleanup
// off the response critical path and let it complete independently; the next
// normal refresh will see any repaired records.
void cleanupZombieAgents().catch((err) => {
console.error(`🧹 Background zombie cleanup failed: ${err.message}`);
});
const { active } = validateRequest(z.object({ active: z.literal('1').optional() }), req.query);
const [agents, taskView] = await Promise.all([
getAgents(),
active ? getTaskView({ kind: 'queue' }) : null,
]);
if (!active) return res.json(toAgentListItems(agents));
const resident = new Map(agents.map(agent => [agent.id, agent]));
const visible = new Map(agents.filter(agent => agent.status !== 'completed').map(agent => [agent.id, agent]));
const runningTasks = new Set(agents.filter(agent => agent.status === 'running').map(agent => agent.taskId));
const tasks = [...(taskView.user?.tasks || []), ...(taskView.cos?.tasks || [])];
// Execution can finish before delivery does. Follow only the task's exact
// cleanup owner, including archived records, without loading transcripts or
// changing the run's terminal status (and therefore scheduler capacity).
await Promise.all(tasks.filter(task => task.status === 'in_progress' && isDeliveryCleanupHeld(task.metadata) && !runningTasks.has(task.id)).map(async task => {
const id = task.metadata.deliveryRecoveryAgentId;
if (visible.has(id)) return;
const agent = resident.get(id) || await getAgentRecord(id);
if (agent?.status === 'completed' && agent.taskId === task.id) {
const deliveryActivity = getDeliveryActivity(id);
visible.set(id, { ...agent, deliveryPending: true, ...(deliveryActivity && { deliveryActivity }) });
}
}));
res.json(toAgentListItems([...visible.values()]));
}));
// Bounded completed history, including state records not yet archived.
const completedQuerySchema = z.object({
limit: z.coerce.number().int().min(1).max(100).default(25),
cursor: z.string().max(512).regex(/^\d{4}-\d{2}-\d{2}\|[^|]*\|[^|]+$/).optional(),
});
router.get('/agents/completed', asyncHandler(async (req, res) => {
const query = validateRequest(completedQuerySchema, req.query);
const page = await getCompletedAgentPage({ ...query, liveAgents: await getAgents() });
res.json({ ...page, items: toAgentListItems(page.items) });
}));
// GET /api/cos/agents/history - Get available date buckets with counts
//
// `?hydrate=1` also returns the newest bucket's agents. The Agents tab always
// wants them, but it cannot ask for them until this response names the date —
// so without this the tab pays two SERIAL round trips before a single archived
// card appears, which is the whole visible delay on a high-latency link.
// It stays opt-in because hydrating reads a whole date bucket off disk, which a
// caller that only wants the counts should not pay for.
const historyQuerySchema = z.object({ hydrate: z.literal('1').optional() });
router.get('/agents/history', asyncHandler(async (req, res) => {
const { hydrate } = validateRequest(historyQuerySchema, req.query);
const dates = await getAgentDates();
if (!hydrate) return res.json({ dates });
// `latest: null` is the answer for an install with no archived runs at all —
// distinct from a bucket that read back empty, which the client must not
// mistake for "not hydrated" and re-request.
const latestDate = dates[0]?.date;
const latest = latestDate
? { date: latestDate, agents: toAgentListItems(await getAgentsByDate(latestDate)) }
: null;
res.json({ dates, latest });
}));
// GET /api/cos/agents/history/:date - Get completed agents for a date
router.get('/agents/history/:date', asyncHandler(async (req, res) => {
const { date } = req.params;
if (!/^\d{4}-\d{2}-\d{2}$/.test(date)) {
throw new ServerError('Invalid date format (expected YYYY-MM-DD)', { status: 400, code: 'VALIDATION_ERROR' });
}
const agents = await getAgentsByDate(date);
res.json(toAgentListItems(agents));
}));
// GET /api/cos/agents/feedback/pending - Reconciled durable feedback actions.
// The queue owns the action mutation; this endpoint feeds the Agents tab with
// the same live/archive predicate and count without loading every date bucket.
//
// The scalar badge and the paged list answer from the completion-order
// eligibility projection and hydrate only the rows they return; the unpaged
// form is the one that also reconciles the durable references and reports the
// archives it could not read.
router.get('/agents/feedback/pending', asyncHandler(async (req, res) => {
const { limit, cursor, countOnly } = validateRequest(z.object({
countOnly: z.literal('1').optional(),
limit: z.coerce.number().int().min(1).max(100).optional(),
cursor: z.string().max(512).optional(),
}), req.query);
if (countOnly) return res.json({ count: await getPendingAgentFeedbackCount() });
if (limit) {
const page = await getPendingAgentFeedbackPage({ limit, cursor });
return res.json({ ...page, items: toAgentListItems(page.items) });
}
const pending = await getPendingAgentFeedback({ includeUnavailable: true });
res.json({
count: pending.count,
agents: toAgentListItems(pending.agents),
unavailable: pending.unavailable,
});
}));
// GET /api/cos/agents/:id - Get agent by ID (transcript hydrated as a capped tail)
router.get('/agents/:id', asyncHandler(async (req, res) => {
const { lines } = validateRequest(agentQuerySchema, req.query);
const agent = await getAgent(req.params.id, lines ? { limit: lines } : {});
if (!agent) {
throw new ServerError('Agent not found', { status: 404, code: 'NOT_FOUND' });
}
res.json(agent);
}));
// GET /api/cos/agents/:id/prompt - Read the prompt.txt saved at spawn time
// The service throws a ServerError (404) when the agent or prompt file is
// missing — asyncHandler renders the standard envelope.
router.get('/agents/:id/prompt', asyncHandler(async (req, res) => {
const result = await getAgentPrompt(req.params.id);
res.json(result);
}));
// POST /api/cos/agents/:id/terminate - Request termination (graceful SIGTERM, then SIGKILL)
// This only emits `agent:terminate` and returns immediately; the spawner's
// handler runs the actual SIGTERM/SIGKILL sequence.
router.post('/agents/:id/terminate', asyncHandler(async (req, res) => {
const result = await agentOrchestrator.requestAgentTermination(req.params.id);
res.json(result);
}));
// POST /api/cos/agents/:id/pause - Stop process, preserve task/worktree for later resume
// pauseAgent throws a ServerError — 404 when the agent is missing, 500 when the
// runner/persist step fails — so no result-shape string-matching here.
router.post('/agents/:id/pause', asyncHandler(async (req, res) => {
const { reason } = validateRequest(pauseBodySchema, req.body ?? {});
const result = await agentOrchestrator.pauseAgent(req.params.id, reason || null);
res.json(result);
}));
// POST /api/cos/agents/:id/resume - Requeue a paused agent's own task on the
// branch/worktree its run left behind, and retire the paused record.
// resumeAgent throws a ServerError — 404 when the agent is missing, 409 when it
// isn't paused, 500 when the requeue write fails.
router.post('/agents/:id/resume', asyncHandler(async (req, res) => {
const overrides = validateRequest(resumeCosAgentSchema, req.body ?? {});
const result = await agentOrchestrator.resumeAgent(req.params.id, overrides);
res.json(result);
}));
// POST /api/cos/agents/:id/relaunch - Stop a RUNNING agent and requeue its own
// task on a different provider/model/effort (see relaunchAgent for why).
// relaunchAgent throws a ServerError — 404 when the agent is missing, 409 when
// it isn't running, 500 when the pause or requeue write fails.
router.post('/agents/:id/relaunch', asyncHandler(async (req, res) => {
const overrides = validateRequest(relaunchCosAgentSchema, req.body ?? {});
const result = await agentOrchestrator.relaunchAgent(req.params.id, overrides);
res.json(result);
}));
// POST /api/cos/agents/:id/kill - Force kill agent (immediate SIGKILL)
// killAgent throws a ServerError — 404 when the agent is missing, 500 when the
// runner termination fails — so no result-shape string-matching here.
router.post('/agents/:id/kill', asyncHandler(async (req, res) => {
const result = await agentOrchestrator.killAgent(req.params.id);
res.json(result);
}));
// GET /api/cos/agents/:id/stats - Get process stats for agent (CPU, memory)
router.get('/agents/:id/stats', asyncHandler(async (req, res) => {
const stats = await agentOrchestrator.getAgentProcessStats(req.params.id);
// Return success with active:false instead of 404 - this is expected when process isn't running
res.json(stats || { active: false, pid: null });
}));
// DELETE /api/cos/agents/completed - Clear completed agents (must be before :id route)
router.delete('/agents/completed', asyncHandler(async (req, res) => {
const result = await clearCompletedAgents();
res.json(result);
}));
// DELETE /api/cos/agents/:id - Delete a single agent
// The service throws a ServerError (404) when the agent doesn't exist.
router.delete('/agents/:id', asyncHandler(async (req, res) => {
const result = await deleteAgent(req.params.id);
res.json(result);
}));
// POST /api/cos/agents/:id/feedback - Submit feedback for completed agent
router.post('/agents/:id/feedback', asyncHandler(async (req, res) => {
const { rating, comment } = validateRequest(cosAgentFeedbackBodySchema, req.body);
// The service throws a ServerError — 404 when the agent is missing, 400
// (INVALID_STATE) when it isn't completed — so no result-shape mapping here.
const result = await submitAgentFeedback(req.params.id, { rating, comment });
res.json(result);
}));
// POST /api/cos/agents/:id/btw - Send additional context to a running agent
router.post('/agents/:id/btw', asyncHandler(async (req, res) => {
const { message } = validateRequest(cosAgentBtwBodySchema, req.body);
// The service throws a ServerError — 404 when the agent is missing, 400
// (INVALID_STATE) for the not-running / not-a-Claude-TUI refusals — so no
// result-shape string-matching here.
const result = await sendBtwToAgent(req.params.id, message);
res.json(result);
}));
// GET /api/cos/feedback/stats - Get feedback statistics
router.get('/feedback/stats', asyncHandler(async (req, res) => {
const stats = await getFeedbackStats();
res.json(stats);
}));
export default router;