bonecode 1.0.0

package/bone/output/agent/src/routes/agent_instance.ts

@@ -0,0 +1,234 @@
+// Generated by BoneScript compiler. DO NOT EDIT.
+// Service: AgentInstanceService
+import { Router, Request, Response } from "express";
+import { v4 as uuid } from "uuid";
+import { query, queryOne, execute, pool } from "../db";
+import { eventBus } from "../events";
+import { requireAuth, AuthContext } from "../auth";
+import rateLimit from "express-rate-limit";
+import { auditLog } from "../audit";
+import { logger } from "../logger";
+import { counter } from "../metrics";
+import * as __algorithms from "../algorithms";
+const { shortestPath, topologicalSort, binarySearch, bipartiteMatching, roundRobin, weightedAverage, percentile, rankBy, consistentHash } = __algorithms as any;
+
+import { transitionAgentInstance, AGENTINSTANCE_INITIAL } from "../state_machines/agent_instance";
+
+export const agentInstancesRouter = Router();
+
+// Rate limiter from policy declaration
+const __routeRateLimit = rateLimit({ windowMs: 60000, max: 200, standardHeaders: true, legacyHeaders: false });
+
+// CREATE
+agentInstancesRouter.post("/", __routeRateLimit, requireAuth, async (req: Request, res: Response) => {
+  try {
+    const id = uuid();
+    const { session_id, model_id, provider_id, system_prompt, temperature, max_tokens, context_window_used, context_window_max, total_cost_usd, total_tokens_in, total_tokens_out, config } = req.body;
+    const state = AGENTINSTANCE_INITIAL;
+    const sql = `INSERT INTO agent_instances (id, session_id, model_id, provider_id, system_prompt, temperature, max_tokens, context_window_used, context_window_max, total_cost_usd, total_tokens_in, total_tokens_out, config, state) VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11, $12, $13, $14) RETURNING *`;
+    const rows = await query(sql, [id, session_id, model_id, provider_id, system_prompt, temperature, max_tokens, context_window_used, context_window_max, total_cost_usd, total_tokens_in, total_tokens_out, config, state]);
+    counter("entity.created", { entity: "AgentInstance" });
+    res.status(201).json(rows[0]);
+  } catch (e: any) {
+    res.status(400).json({ error: { code: "CREATE_FAILED", message: e.message } });
+  }
+});
+
+// READ
+agentInstancesRouter.get("/:id", __routeRateLimit, requireAuth, async (req: Request, res: Response) => {
+  try {
+    const row = await queryOne(`SELECT * FROM agent_instances WHERE id = $1`, [req.params.id]);
+    if (!row) return res.status(404).json({ error: { code: "NOT_FOUND", message: "Not found" } });
+    res.json(row);
+  } catch (e: any) {
+    res.status(500).json({ error: { code: "DB_ERROR", message: e.message } });
+  }
+});
+
+// LIST
+agentInstancesRouter.get("/", __routeRateLimit, requireAuth, async (req: Request, res: Response) => {
+  try {
+    const page = parseInt(req.query.page as string) || 1;
+    const pageSize = Math.min(parseInt(req.query.page_size as string) || 50, 100);
+    const offset = (page - 1) * pageSize;
+    const rows = await query(`SELECT * FROM agent_instances ORDER BY created_at DESC LIMIT $1 OFFSET $2`, [pageSize, offset]);
+    const [{ count }] = await query(`SELECT COUNT(*) as count FROM agent_instances`);
+    res.json({ items: rows, total: parseInt(count), page, page_size: pageSize });
+  } catch (e: any) {
+    res.status(500).json({ error: { code: "DB_ERROR", message: e.message } });
+  }
+});
+
+// UPDATE
+agentInstancesRouter.put("/:id", __routeRateLimit, requireAuth, async (req: Request, res: Response) => {
+  const fields = { ...req.body };
+  // State machine enforcement
+  if (fields.state !== undefined) {
+    const current = await queryOne<{ state: string }>(`SELECT state FROM agent_instances WHERE id = $1`, [req.params.id]);
+    if (!current) return res.status(404).json({ error: { code: "NOT_FOUND", message: "Not found" } });
+    // Find the trigger for this state transition
+    const trigger = `${current.state}_to_${fields.state}`;
+    const tr = transitionAgentInstance(current.state as any, trigger);
+    if (!tr.ok) return res.status(422).json({ error: { code: "INVALID_TRANSITION", message: `Cannot transition from ${current.state} to ${fields.state}` } });
+  }
+  const sets = Object.keys(fields).map((k, i) => `${k} = $${i + 2}`).join(", ");
+  const values = Object.values(fields);
+  const sql = `UPDATE agent_instances SET ${sets}, updated_at = NOW() WHERE id = $1 RETURNING *`;
+  const rows = await query(sql, [req.params.id, ...values]);
+  if (rows.length === 0) return res.status(404).json({ error: { code: "NOT_FOUND", message: "Not found" } });
+  res.json(rows[0]);
+});
+
+// DELETE
+agentInstancesRouter.delete("/:id", __routeRateLimit, requireAuth, async (req: Request, res: Response) => {
+  try {
+    const count = await execute(`DELETE FROM agent_instances WHERE id = $1`, [req.params.id]);
+    if (count === 0) return res.status(404).json({ error: { code: "NOT_FOUND", message: "Not found" } });
+    res.status(204).send();
+  } catch (e: any) {
+    res.status(500).json({ error: { code: "DB_ERROR", message: e.message } });
+  }
+});
+
+// CAPABILITY: complete_agent [transactional]
+agentInstancesRouter.post("/complete-agent", __routeRateLimit, requireAuth, auditLog("complete_agent", "AgentInstance"), async (req: Request, res: Response) => {
+  const auth: AuthContext = (req as any).auth;
+  const __client = await pool.connect();
+  try {
+    await __client.query("BEGIN");
+    // Fetch entities
+    const agent = await queryOne(`SELECT * FROM agent_instances WHERE id = $1`, [req.body.agent_id || req.params.id]);
+    if (!agent) {
+      return res.status(404).json({ error: { code: "NOT_FOUND", message: "agent not found" } });
+    }
+
+    // Preconditions
+    if (!([["running", "waiting_for_tool"]].flat().includes(agent?.state))) {
+      return res.status(422).json({ error: { code: "PRECONDITION_FAILED", message: "agent.state in [\\\"running\\\", \\\"waiting_for_tool\\\"]" } });
+    }
+
+    // Effects (applied in declaration order)
+    const __effect_0 = await query(`UPDATE agents SET state = $1, updated_at = NOW() WHERE id = $2 RETURNING *`, ["done", req.body.agent_id || req.params.id]);
+    if (!__effect_0 || __effect_0.length === 0) {
+      throw new Error("Effect failed: agent.state = \"done\"");
+    }
+
+    // Emit events
+    await eventBus.publish("AgentCompleted", { agent_id: agent?.id, timestamp: new Date().toISOString(), actor_id: auth.actor_id }, "AgentInstanceService", auth.trace_id, __client);
+
+    res.json({ ok: true, action: "complete_agent", entity: agent });
+    await __client.query("COMMIT");
+  } catch (e: any) {
+    await __client.query("ROLLBACK");
+    res.status(400).json({ error: { code: "CAPABILITY_FAILED", message: e.message } });
+  } finally {
+    __client.release();
+  }
+});
+
+// CAPABILITY: fail_agent [transactional]
+agentInstancesRouter.post("/fail-agent", __routeRateLimit, requireAuth, auditLog("fail_agent", "AgentInstance"), async (req: Request, res: Response) => {
+  const auth: AuthContext = (req as any).auth;
+  const __client = await pool.connect();
+  try {
+    await __client.query("BEGIN");
+    const { error } = req.body;
+
+    // Fetch entities
+    const agent = await queryOne(`SELECT * FROM agent_instances WHERE id = $1`, [req.body.agent_id || req.params.id]);
+    if (!agent) {
+      return res.status(404).json({ error: { code: "NOT_FOUND", message: "agent not found" } });
+    }
+
+    // Preconditions
+    if (!([["running", "waiting_for_tool", "compacting"]].flat().includes(agent?.state))) {
+      return res.status(422).json({ error: { code: "PRECONDITION_FAILED", message: "agent.state in [\\\"running\\\", \\\"waiting_for_tool\\\", \\\"compacting\\\"]" } });
+    }
+
+    // Effects (applied in declaration order)
+    const __effect_0 = await query(`UPDATE agents SET state = $1, updated_at = NOW() WHERE id = $2 RETURNING *`, ["failed", req.body.agent_id || req.params.id]);
+    if (!__effect_0 || __effect_0.length === 0) {
+      throw new Error("Effect failed: agent.state = \"failed\"");
+    }
+
+    // Emit events
+    await eventBus.publish("AgentFailed", { agent_id: agent?.id, timestamp: new Date().toISOString(), actor_id: auth.actor_id }, "AgentInstanceService", auth.trace_id, __client);
+
+    res.json({ ok: true, action: "fail_agent", entity: agent });
+    await __client.query("COMMIT");
+  } catch (e: any) {
+    await __client.query("ROLLBACK");
+    res.status(400).json({ error: { code: "CAPABILITY_FAILED", message: e.message } });
+  } finally {
+    __client.release();
+  }
+});
+
+// CAPABILITY: request_tool_call [transactional]
+agentInstancesRouter.post("/request-tool-call", __routeRateLimit, requireAuth, auditLog("request_tool_call", "AgentInstance"), async (req: Request, res: Response) => {
+  const auth: AuthContext = (req as any).auth;
+  const __client = await pool.connect();
+  try {
+    await __client.query("BEGIN");
+    const { tool_name, tool_input } = req.body;
+
+    // Fetch entities
+    const agent = await queryOne(`SELECT * FROM agent_instances WHERE id = $1`, [req.body.agent_id || req.params.id]);
+    if (!agent) {
+      return res.status(404).json({ error: { code: "NOT_FOUND", message: "agent not found" } });
+    }
+
+    // Preconditions
+    if (!(agent?.state === "running")) {
+      return res.status(422).json({ error: { code: "PRECONDITION_FAILED", message: "agent.state == \\\"running\\\"" } });
+    }
+    if (!(tool_name?.length >= 1)) {
+      return res.status(422).json({ error: { code: "PRECONDITION_FAILED", message: "tool_name.length >= 1" } });
+    }
+
+    // Effects (applied in declaration order)
+    const __effect_0 = await query(`UPDATE agents SET state = $1, updated_at = NOW() WHERE id = $2 RETURNING *`, ["waiting_for_tool", req.body.agent_id || req.params.id]);
+    if (!__effect_0 || __effect_0.length === 0) {
+      throw new Error("Effect failed: agent.state = \"waiting_for_tool\"");
+    }
+
+    // Emit events
+    await eventBus.publish("ToolCallRequested", { agent_id: agent?.id, timestamp: new Date().toISOString(), actor_id: auth.actor_id }, "AgentInstanceService", auth.trace_id, __client);
+
+    res.json({ ok: true, action: "request_tool_call", entity: agent });
+    await __client.query("COMMIT");
+  } catch (e: any) {
+    await __client.query("ROLLBACK");
+    res.status(400).json({ error: { code: "CAPABILITY_FAILED", message: e.message } });
+  } finally {
+    __client.release();
+  }
+});
+
+// RELATION: tasks (has_many Task)
+agentInstancesRouter.get("/:id/tasks", requireAuth, async (req: Request, res: Response) => {
+  try {
+    const page = parseInt(req.query.page as string) || 1;
+    const pageSize = Math.min(parseInt(req.query.page_size as string) || 50, 100);
+    const offset = (page - 1) * pageSize;
+    const rows = await query(`SELECT * FROM tasks WHERE agent_id = $1 ORDER BY created_at DESC LIMIT $2 OFFSET $3`, [req.params.id, pageSize, offset]);
+    const [{ count }] = await query(`SELECT COUNT(*) as count FROM tasks WHERE agent_id = $1`, [req.params.id]);
+    res.json({ items: rows, total: parseInt(count), page, page_size: pageSize });
+  } catch (e: any) {
+    res.status(500).json({ error: { code: "DB_ERROR", message: e.message } });
+  }
+});
+
+// RELATION: tool_calls (has_many ToolCall)
+agentInstancesRouter.get("/:id/tool_calls", requireAuth, async (req: Request, res: Response) => {
+  try {
+    const page = parseInt(req.query.page as string) || 1;
+    const pageSize = Math.min(parseInt(req.query.page_size as string) || 50, 100);
+    const offset = (page - 1) * pageSize;
+    const rows = await query(`SELECT * FROM tool_calls WHERE agent_id = $1 ORDER BY created_at DESC LIMIT $2 OFFSET $3`, [req.params.id, pageSize, offset]);
+    const [{ count }] = await query(`SELECT COUNT(*) as count FROM tool_calls WHERE agent_id = $1`, [req.params.id]);
+    res.json({ items: rows, total: parseInt(count), page, page_size: pageSize });
+  } catch (e: any) {
+    res.status(500).json({ error: { code: "DB_ERROR", message: e.message } });
+  }
+});

package/bone/output/agent/src/routes/build_step.ts

@@ -0,0 +1,105 @@
+// Generated by BoneScript compiler. DO NOT EDIT.
+// Service: BuildStepService
+import { Router, Request, Response } from "express";
+import { v4 as uuid } from "uuid";
+import { query, queryOne, execute, pool } from "../db";
+import { eventBus } from "../events";
+import { requireAuth, AuthContext } from "../auth";
+import rateLimit from "express-rate-limit";
+import { auditLog } from "../audit";
+import { logger } from "../logger";
+import { counter } from "../metrics";
+import * as __algorithms from "../algorithms";
+const { shortestPath, topologicalSort, binarySearch, bipartiteMatching, roundRobin, weightedAverage, percentile, rankBy, consistentHash } = __algorithms as any;
+
+import { transitionBuildStep, BUILDSTEP_INITIAL } from "../state_machines/build_step";
+
+export const buildStepsRouter = Router();
+
+// Rate limiter from policy declaration
+const __routeRateLimit = rateLimit({ windowMs: 60000, max: 200, standardHeaders: true, legacyHeaders: false });
+
+// CREATE
+buildStepsRouter.post("/", __routeRateLimit, requireAuth, async (req: Request, res: Response) => {
+  try {
+    const id = uuid();
+    const { task_id, agent_id, session_id, step_type, description, file_path, diff, result, error, order_index } = req.body;
+    const state = BUILDSTEP_INITIAL;
+    const sql = `INSERT INTO build_steps (id, task_id, agent_id, session_id, step_type, description, file_path, diff, result, error, order_index, state) VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11, $12) RETURNING *`;
+    const rows = await query(sql, [id, task_id, agent_id, session_id, step_type, description, file_path, diff, result, error, order_index, state]);
+    counter("entity.created", { entity: "BuildStep" });
+    res.status(201).json(rows[0]);
+  } catch (e: any) {
+    res.status(400).json({ error: { code: "CREATE_FAILED", message: e.message } });
+  }
+});
+
+// READ
+buildStepsRouter.get("/:id", __routeRateLimit, requireAuth, async (req: Request, res: Response) => {
+  try {
+    const row = await queryOne(`SELECT * FROM build_steps WHERE id = $1`, [req.params.id]);
+    if (!row) return res.status(404).json({ error: { code: "NOT_FOUND", message: "Not found" } });
+    res.json(row);
+  } catch (e: any) {
+    res.status(500).json({ error: { code: "DB_ERROR", message: e.message } });
+  }
+});
+
+// LIST
+buildStepsRouter.get("/", __routeRateLimit, requireAuth, async (req: Request, res: Response) => {
+  try {
+    const page = parseInt(req.query.page as string) || 1;
+    const pageSize = Math.min(parseInt(req.query.page_size as string) || 50, 100);
+    const offset = (page - 1) * pageSize;
+    const rows = await query(`SELECT build_steps.*, row_to_json(task.*) as task FROM build_steps LEFT JOIN tasks task ON build_steps.task_id = task.id ORDER BY build_steps.created_at DESC LIMIT $1 OFFSET $2`, [pageSize, offset]);
+    const [{ count }] = await query(`SELECT COUNT(*) as count FROM build_steps`);
+    res.json({ items: rows, total: parseInt(count), page, page_size: pageSize });
+  } catch (e: any) {
+    res.status(500).json({ error: { code: "DB_ERROR", message: e.message } });
+  }
+});
+
+// UPDATE
+buildStepsRouter.put("/:id", __routeRateLimit, requireAuth, async (req: Request, res: Response) => {
+  const fields = { ...req.body };
+  // State machine enforcement
+  if (fields.state !== undefined) {
+    const current = await queryOne<{ state: string }>(`SELECT state FROM build_steps WHERE id = $1`, [req.params.id]);
+    if (!current) return res.status(404).json({ error: { code: "NOT_FOUND", message: "Not found" } });
+    // Find the trigger for this state transition
+    const trigger = `${current.state}_to_${fields.state}`;
+    const tr = transitionBuildStep(current.state as any, trigger);
+    if (!tr.ok) return res.status(422).json({ error: { code: "INVALID_TRANSITION", message: `Cannot transition from ${current.state} to ${fields.state}` } });
+  }
+  const sets = Object.keys(fields).map((k, i) => `${k} = $${i + 2}`).join(", ");
+  const values = Object.values(fields);
+  const sql = `UPDATE build_steps SET ${sets}, updated_at = NOW() WHERE id = $1 RETURNING *`;
+  const rows = await query(sql, [req.params.id, ...values]);
+  if (rows.length === 0) return res.status(404).json({ error: { code: "NOT_FOUND", message: "Not found" } });
+  res.json(rows[0]);
+});
+
+// DELETE
+buildStepsRouter.delete("/:id", __routeRateLimit, requireAuth, async (req: Request, res: Response) => {
+  try {
+    const count = await execute(`DELETE FROM build_steps WHERE id = $1`, [req.params.id]);
+    if (count === 0) return res.status(404).json({ error: { code: "NOT_FOUND", message: "Not found" } });
+    res.status(204).send();
+  } catch (e: any) {
+    res.status(500).json({ error: { code: "DB_ERROR", message: e.message } });
+  }
+});
+
+// RELATION: tool_calls (has_many ToolCall)
+buildStepsRouter.get("/:id/tool_calls", requireAuth, async (req: Request, res: Response) => {
+  try {
+    const page = parseInt(req.query.page as string) || 1;
+    const pageSize = Math.min(parseInt(req.query.page_size as string) || 50, 100);
+    const offset = (page - 1) * pageSize;
+    const rows = await query(`SELECT * FROM tool_calls WHERE build_step_id = $1 ORDER BY created_at DESC LIMIT $2 OFFSET $3`, [req.params.id, pageSize, offset]);
+    const [{ count }] = await query(`SELECT COUNT(*) as count FROM tool_calls WHERE build_step_id = $1`, [req.params.id]);
+    res.json({ items: rows, total: parseInt(count), page, page_size: pageSize });
+  } catch (e: any) {
+    res.status(500).json({ error: { code: "DB_ERROR", message: e.message } });
+  }
+});

package/bone/output/agent/src/routes/plan.ts

@@ -0,0 +1,91 @@
+// Generated by BoneScript compiler. DO NOT EDIT.
+// Service: PlanService
+import { Router, Request, Response } from "express";
+import { v4 as uuid } from "uuid";
+import { query, queryOne, execute, pool } from "../db";
+import { eventBus } from "../events";
+import { requireAuth, AuthContext } from "../auth";
+import rateLimit from "express-rate-limit";
+import { auditLog } from "../audit";
+import { logger } from "../logger";
+import { counter } from "../metrics";
+import * as __algorithms from "../algorithms";
+const { shortestPath, topologicalSort, binarySearch, bipartiteMatching, roundRobin, weightedAverage, percentile, rankBy, consistentHash } = __algorithms as any;
+
+import { transitionPlan, PLAN_INITIAL } from "../state_machines/plan";
+
+export const plansRouter = Router();
+
+// Rate limiter from policy declaration
+const __routeRateLimit = rateLimit({ windowMs: 60000, max: 200, standardHeaders: true, legacyHeaders: false });
+
+// CREATE
+plansRouter.post("/", __routeRateLimit, requireAuth, async (req: Request, res: Response) => {
+  try {
+    const id = uuid();
+    const { session_id, agent_id, task_id, steps, rationale, estimated_tokens } = req.body;
+    const state = PLAN_INITIAL;
+    const sql = `INSERT INTO plans (id, session_id, agent_id, task_id, steps, rationale, estimated_tokens, state) VALUES ($1, $2, $3, $4, $5, $6, $7, $8) RETURNING *`;
+    const rows = await query(sql, [id, session_id, agent_id, task_id, steps, rationale, estimated_tokens, state]);
+    counter("entity.created", { entity: "Plan" });
+    res.status(201).json(rows[0]);
+  } catch (e: any) {
+    res.status(400).json({ error: { code: "CREATE_FAILED", message: e.message } });
+  }
+});
+
+// READ
+plansRouter.get("/:id", __routeRateLimit, requireAuth, async (req: Request, res: Response) => {
+  try {
+    const row = await queryOne(`SELECT * FROM plans WHERE id = $1`, [req.params.id]);
+    if (!row) return res.status(404).json({ error: { code: "NOT_FOUND", message: "Not found" } });
+    res.json(row);
+  } catch (e: any) {
+    res.status(500).json({ error: { code: "DB_ERROR", message: e.message } });
+  }
+});
+
+// LIST
+plansRouter.get("/", __routeRateLimit, requireAuth, async (req: Request, res: Response) => {
+  try {
+    const page = parseInt(req.query.page as string) || 1;
+    const pageSize = Math.min(parseInt(req.query.page_size as string) || 50, 100);
+    const offset = (page - 1) * pageSize;
+    const rows = await query(`SELECT * FROM plans ORDER BY created_at DESC LIMIT $1 OFFSET $2`, [pageSize, offset]);
+    const [{ count }] = await query(`SELECT COUNT(*) as count FROM plans`);
+    res.json({ items: rows, total: parseInt(count), page, page_size: pageSize });
+  } catch (e: any) {
+    res.status(500).json({ error: { code: "DB_ERROR", message: e.message } });
+  }
+});
+
+// UPDATE
+plansRouter.put("/:id", __routeRateLimit, requireAuth, async (req: Request, res: Response) => {
+  const fields = { ...req.body };
+  // State machine enforcement
+  if (fields.state !== undefined) {
+    const current = await queryOne<{ state: string }>(`SELECT state FROM plans WHERE id = $1`, [req.params.id]);
+    if (!current) return res.status(404).json({ error: { code: "NOT_FOUND", message: "Not found" } });
+    // Find the trigger for this state transition
+    const trigger = `${current.state}_to_${fields.state}`;
+    const tr = transitionPlan(current.state as any, trigger);
+    if (!tr.ok) return res.status(422).json({ error: { code: "INVALID_TRANSITION", message: `Cannot transition from ${current.state} to ${fields.state}` } });
+  }
+  const sets = Object.keys(fields).map((k, i) => `${k} = $${i + 2}`).join(", ");
+  const values = Object.values(fields);
+  const sql = `UPDATE plans SET ${sets}, updated_at = NOW() WHERE id = $1 RETURNING *`;
+  const rows = await query(sql, [req.params.id, ...values]);
+  if (rows.length === 0) return res.status(404).json({ error: { code: "NOT_FOUND", message: "Not found" } });
+  res.json(rows[0]);
+});
+
+// DELETE
+plansRouter.delete("/:id", __routeRateLimit, requireAuth, async (req: Request, res: Response) => {
+  try {
+    const count = await execute(`DELETE FROM plans WHERE id = $1`, [req.params.id]);
+    if (count === 0) return res.status(404).json({ error: { code: "NOT_FOUND", message: "Not found" } });
+    res.status(204).send();
+  } catch (e: any) {
+    res.status(500).json({ error: { code: "DB_ERROR", message: e.message } });
+  }
+});

package/bone/output/agent/src/routes/task.ts

@@ -0,0 +1,105 @@
+// Generated by BoneScript compiler. DO NOT EDIT.
+// Service: TaskService
+import { Router, Request, Response } from "express";
+import { v4 as uuid } from "uuid";
+import { query, queryOne, execute, pool } from "../db";
+import { eventBus } from "../events";
+import { requireAuth, AuthContext } from "../auth";
+import rateLimit from "express-rate-limit";
+import { auditLog } from "../audit";
+import { logger } from "../logger";
+import { counter } from "../metrics";
+import * as __algorithms from "../algorithms";
+const { shortestPath, topologicalSort, binarySearch, bipartiteMatching, roundRobin, weightedAverage, percentile, rankBy, consistentHash } = __algorithms as any;
+
+import { transitionTask, TASK_INITIAL } from "../state_machines/task";
+
+export const tasksRouter = Router();
+
+// Rate limiter from policy declaration
+const __routeRateLimit = rateLimit({ windowMs: 60000, max: 200, standardHeaders: true, legacyHeaders: false });
+
+// CREATE
+tasksRouter.post("/", __routeRateLimit, requireAuth, async (req: Request, res: Response) => {
+  try {
+    const id = uuid();
+    const { agent_id, session_id, description, priority, result, error } = req.body;
+    const state = TASK_INITIAL;
+    const sql = `INSERT INTO tasks (id, agent_id, session_id, description, priority, result, error, state) VALUES ($1, $2, $3, $4, $5, $6, $7, $8) RETURNING *`;
+    const rows = await query(sql, [id, agent_id, session_id, description, priority, result, error, state]);
+    counter("entity.created", { entity: "Task" });
+    res.status(201).json(rows[0]);
+  } catch (e: any) {
+    res.status(400).json({ error: { code: "CREATE_FAILED", message: e.message } });
+  }
+});
+
+// READ
+tasksRouter.get("/:id", __routeRateLimit, requireAuth, async (req: Request, res: Response) => {
+  try {
+    const row = await queryOne(`SELECT * FROM tasks WHERE id = $1`, [req.params.id]);
+    if (!row) return res.status(404).json({ error: { code: "NOT_FOUND", message: "Not found" } });
+    res.json(row);
+  } catch (e: any) {
+    res.status(500).json({ error: { code: "DB_ERROR", message: e.message } });
+  }
+});
+
+// LIST
+tasksRouter.get("/", __routeRateLimit, requireAuth, async (req: Request, res: Response) => {
+  try {
+    const page = parseInt(req.query.page as string) || 1;
+    const pageSize = Math.min(parseInt(req.query.page_size as string) || 50, 100);
+    const offset = (page - 1) * pageSize;
+    const rows = await query(`SELECT tasks.*, row_to_json(agent_instance.*) as agent FROM tasks LEFT JOIN agent_instances agent_instance ON tasks.agent_id = agent_instance.id ORDER BY tasks.created_at DESC LIMIT $1 OFFSET $2`, [pageSize, offset]);
+    const [{ count }] = await query(`SELECT COUNT(*) as count FROM tasks`);
+    res.json({ items: rows, total: parseInt(count), page, page_size: pageSize });
+  } catch (e: any) {
+    res.status(500).json({ error: { code: "DB_ERROR", message: e.message } });
+  }
+});
+
+// UPDATE
+tasksRouter.put("/:id", __routeRateLimit, requireAuth, async (req: Request, res: Response) => {
+  const fields = { ...req.body };
+  // State machine enforcement
+  if (fields.state !== undefined) {
+    const current = await queryOne<{ state: string }>(`SELECT state FROM tasks WHERE id = $1`, [req.params.id]);
+    if (!current) return res.status(404).json({ error: { code: "NOT_FOUND", message: "Not found" } });
+    // Find the trigger for this state transition
+    const trigger = `${current.state}_to_${fields.state}`;
+    const tr = transitionTask(current.state as any, trigger);
+    if (!tr.ok) return res.status(422).json({ error: { code: "INVALID_TRANSITION", message: `Cannot transition from ${current.state} to ${fields.state}` } });
+  }
+  const sets = Object.keys(fields).map((k, i) => `${k} = $${i + 2}`).join(", ");
+  const values = Object.values(fields);
+  const sql = `UPDATE tasks SET ${sets}, updated_at = NOW() WHERE id = $1 RETURNING *`;
+  const rows = await query(sql, [req.params.id, ...values]);
+  if (rows.length === 0) return res.status(404).json({ error: { code: "NOT_FOUND", message: "Not found" } });
+  res.json(rows[0]);
+});
+
+// DELETE
+tasksRouter.delete("/:id", __routeRateLimit, requireAuth, async (req: Request, res: Response) => {
+  try {
+    const count = await execute(`DELETE FROM tasks WHERE id = $1`, [req.params.id]);
+    if (count === 0) return res.status(404).json({ error: { code: "NOT_FOUND", message: "Not found" } });
+    res.status(204).send();
+  } catch (e: any) {
+    res.status(500).json({ error: { code: "DB_ERROR", message: e.message } });
+  }
+});
+
+// RELATION: steps (has_many BuildStep)
+tasksRouter.get("/:id/steps", requireAuth, async (req: Request, res: Response) => {
+  try {
+    const page = parseInt(req.query.page as string) || 1;
+    const pageSize = Math.min(parseInt(req.query.page_size as string) || 50, 100);
+    const offset = (page - 1) * pageSize;
+    const rows = await query(`SELECT * FROM build_steps WHERE task_id = $1 ORDER BY created_at DESC LIMIT $2 OFFSET $3`, [req.params.id, pageSize, offset]);
+    const [{ count }] = await query(`SELECT COUNT(*) as count FROM build_steps WHERE task_id = $1`, [req.params.id]);
+    res.json({ items: rows, total: parseInt(count), page, page_size: pageSize });
+  } catch (e: any) {
+    res.status(500).json({ error: { code: "DB_ERROR", message: e.message } });
+  }
+});