maestro-agent 0.0.1 → 0.0.3

package/src/api/tasks.ts

@@ -0,0 +1,457 @@
+import { generateId, now } from "../core/db";
+import type { Router } from "../core/router";
+import { body, getIdempotencyKey, json } from "../core/router";
+import type { HubContext } from "../core/server";
+import { required } from "../core/validate";
+import { findProjectExecutionBlocker } from "../ops/project-serial";
+import { resolveAgentForRole } from "../ops/role-dispatch";
+import { getTaskBlockingDetails } from "../ops/task-blocking";
+import { unlockDependents } from "../ops/task-deps";
+import { getWorkflowForTask, listTaskActions, transitionTask, workflowStatusesForProject } from "../workflows";
+import { createSession } from "./sessions";
+
+export interface ClaimTaskOptions {
+  deferIfProjectBusy?: boolean;
+  skipSession?: boolean;  // Just assign, don't spawn session (for autopilot pre-assignment)
+}
+
+export async function claimTaskForAgent(ctx: HubContext, taskId: string, agentId: string, options: ClaimTaskOptions = {}): Promise<
+  | { task: any; session_id: string }
+  | { task: any; deferred: true; blocked_by_task_id: string }
+  | { error: string; status: number }
+> {
+  required({ agent_id: agentId }, ["agent_id"]);
+  const task = ctx.db.query("SELECT * FROM task WHERE id = ?").get(taskId) as any;
+  if (!task) return { error: "Not found", status: 404 };
+  const workflow = getWorkflowForTask(ctx.db, taskId);
+  const claimAction = workflow.actions.find((action) => action.id === "claim" && action.from.includes(task.status));
+  if (!claimAction) return { error: `No claim action is available from ${task.status}`, status: 409 };
+  if (task.status !== workflow.initial_status) return { error: `Task is not ${workflow.initial_status}`, status: 409 };
+
+  const projectBlocker = findProjectExecutionBlocker(ctx.db, {
+    projectId: task.project_id,
+    excludeTaskId: taskId,
+    claimedStatus: claimAction.to,
+  });
+  if (projectBlocker) {
+    if (!options.deferIfProjectBusy) {
+      return { error: `Project already has active task: ${projectBlocker.id}`, status: 409 };
+    }
+    const ts = now();
+    ctx.db.run(
+      "UPDATE task SET assignee_agent_id = ?, updated_at = ? WHERE id = ? AND status = ?",
+      [agentId, ts, taskId, workflow.initial_status],
+    );
+    const row = ctx.db.query("SELECT * FROM task WHERE id = ?").get(taskId) as any;
+    ctx.bus.publish("task.claim_deferred", { id: taskId, agent_id: agentId, blocked_by_task_id: projectBlocker.id });
+    return { task: row, deferred: true, blocked_by_task_id: projectBlocker.id };
+  }
+
+  const token = crypto.randomUUID().slice(0, 8);
+  const ts = now();
+  ctx.db.run(
+    "UPDATE task SET status = ?, assignee_agent_id = ?, claim_token = ?, updated_at = ? WHERE id = ? AND status = ?",
+    [claimAction.to, agentId, token, ts, taskId, workflow.initial_status]
+  );
+
+  if (options.skipSession) {
+    const row = ctx.db.query("SELECT * FROM task WHERE id = ?").get(taskId) as any;
+    ctx.bus.publish("task.claimed", { id: taskId, agent_id: agentId, session_id: null });
+    return { task: row, session_id: "" };
+  }
+
+  const sessionResult = await createSession(ctx, {
+    agent_id: agentId,
+    task_id: taskId,
+  });
+  if ("error" in sessionResult) {
+    ctx.db.run(
+      "UPDATE task SET status = ?, assignee_agent_id = ?, claim_token = NULL, updated_at = ? WHERE id = ? AND claim_token = ?",
+      [workflow.initial_status, task.assignee_agent_id || null, now(), taskId, token]
+    );
+    return { error: sessionResult.error, status: sessionResult.status };
+  }
+
+  const row = ctx.db.query("SELECT * FROM task WHERE id = ?").get(taskId) as any;
+  const session_id = sessionResult.session.id;
+  ctx.bus.publish("task.claimed", { id: taskId, agent_id: agentId, session_id });
+  return { task: row, session_id };
+}
+
+/**
+ * Ensure the agent assigned to a task is awake and has a running session.
+ * Called when a task transitions to an active state (e.g., via Board drag).
+ */
+async function ensureAgentSession(ctx: HubContext, task: any): Promise<void> {
+  const agentId = task.assignee_agent_id;
+  if (!agentId) return;
+
+  const agent = ctx.db.query("SELECT * FROM agent WHERE id = ?").get(agentId) as any;
+  if (!agent) return;
+
+  // Wake up offline agent
+  if (agent.status === "offline") {
+    const ts = now();
+    ctx.db.run("UPDATE agent SET status = 'idle', last_active_at = ? WHERE id = ?", [ts, agentId]);
+    ctx.bus.publish("agent.woken", { id: agentId, task_id: task.id });
+  }
+
+  // Check if there's already a running session for this task
+  const existingSession = ctx.db.query(
+    "SELECT id FROM session WHERE agent_id = ? AND task_id = ? AND status = 'running' LIMIT 1"
+  ).get(agentId, task.id) as any;
+  if (existingSession) return;
+
+  // Create a new session for the task
+  const result = await createSession(ctx, { agent_id: agentId, task_id: task.id });
+  if (!("error" in result)) {
+    ctx.bus.publish("task.session_started", { task_id: task.id, agent_id: agentId, session_id: result.session.id });
+  }
+}
+
+export function registerTaskRoutes(router: Router, ctx: HubContext) {
+  router.post("/api/tasks", async (req) => {
+    const {
+      project_id,
+      title,
+      description,
+      required_capabilities,
+      priority,
+      parent_task_id,
+      created_by,
+      depends_on,
+      assignee_role,
+      assignee_role_id,
+    } = await body(req);
+    required({ project_id, title }, ["project_id", "title"]);
+    const project = ctx.db.query("SELECT * FROM project WHERE id = ?").get(project_id) as any;
+    if (!project) return json({ error: "Project not found" }, 404);
+
+    let assigneeAgentId: string | null = null;
+    let assigneeRoleId: string | null = null;
+    if (assignee_role_id || assignee_role) {
+      const role = assignee_role_id
+        ? ctx.db.query("SELECT * FROM role WHERE id = ? AND workspace_id = ?").get(assignee_role_id, project.workspace_id) as any
+        : ctx.db.query("SELECT * FROM role WHERE workspace_id = ? AND LOWER(name) = LOWER(?)").get(project.workspace_id, assignee_role) as any;
+      if (!role) return json({ error: "Assignee role not found in workspace" }, 400);
+      assigneeRoleId = role.id;
+
+      // Role-centric: find available agent or wake one up
+      const resolved = resolveAgentForRole(ctx.db, role.id);
+      if (!resolved) return json({ error: `No agents exist for role: ${role.name}` }, 409);
+      assigneeAgentId = resolved.id;
+    }
+
+    const id = generateId("task");
+    const ts = now();
+    const lineage_depth = parent_task_id
+      ? ((ctx.db.query("SELECT lineage_depth FROM task WHERE id = ?").get(parent_task_id) as any)?.lineage_depth || 0) + 1
+      : 0;
+    const deps: string[] = Array.isArray(depends_on) ? depends_on : [];
+    const workflowStatuses = workflowStatusesForProject(ctx.db, project_id);
+    const initialStatus = deps.length > 0
+      ? (workflowStatuses.find((status) => status.id === "blocked")?.id || "blocked")
+      : (workflowStatuses[0]?.id || "open");
+    ctx.db.run(
+      `INSERT INTO task (id, project_id, parent_task_id, title, description, status, assignee_role_id, required_capabilities_json, priority, lineage_depth, created_by, created_at, updated_at)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+      [id, project_id, parent_task_id || null, title, description || null, initialStatus, assigneeRoleId, JSON.stringify(required_capabilities || []), priority || 0, lineage_depth, created_by || "user", ts, ts]
+    );
+    for (const depId of deps) {
+      ctx.db.run("INSERT OR IGNORE INTO task_dependency (task_id, depends_on) VALUES (?, ?)", [id, depId]);
+    }
+    if (assigneeAgentId && deps.length === 0) {
+      const result = await claimTaskForAgent(ctx, id, assigneeAgentId, { deferIfProjectBusy: true });
+      if ("error" in result) return json({ error: result.error, id, project_id, title, status: initialStatus }, result.status);
+      ctx.bus.publish("task.created", { id, project_id, title, assignee_agent_id: assigneeAgentId });
+      if ("deferred" in result) {
+        return json({ ...result.task, assignment_deferred: true, blocked_by_task_id: result.blocked_by_task_id }, 201);
+      }
+      return json({ ...result.task, session_id: result.session_id }, 201);
+    }
+    ctx.bus.publish("task.created", { id, project_id, title });
+    return json({ id, project_id, title, status: initialStatus, created_at: ts }, 201);
+  });
+
+  router.get("/api/tasks", (req) => {
+    const url = new URL(req.url);
+    const workspace_id = url.searchParams.get("workspace_id");
+    const project_id = url.searchParams.get("project_id");
+    const status = url.searchParams.get("status");
+    const include_archived = url.searchParams.get("include_archived");
+    let sql = `SELECT task.*, project.name AS project_name, (
+      SELECT session.id
+      FROM session
+      WHERE session.task_id = task.id
+      ORDER BY session.started_at DESC
+      LIMIT 1
+    ) AS session_id, (
+      SELECT session.started_at
+      FROM session
+      WHERE session.task_id = task.id AND session.status = 'running'
+      ORDER BY session.started_at DESC
+      LIMIT 1
+    ) AS session_started_at, (
+      SELECT substr(tti.content, 1, 80)
+      FROM task_thread_item tti
+      WHERE tti.task_id = task.id AND tti.kind = 'agent_output'
+      ORDER BY tti.created_at DESC
+      LIMIT 1
+    ) AS last_output FROM task
+    LEFT JOIN project ON task.project_id = project.id
+    WHERE 1=1`;
+    const params: any[] = [];
+    if (!include_archived) { sql += " AND task.archived_at IS NULL"; }
+    if (workspace_id) { sql += " AND project.workspace_id = ?"; params.push(workspace_id); }
+    if (project_id) { sql += " AND task.project_id = ?"; params.push(project_id); }
+    if (status) { sql += " AND task.status = ?"; params.push(status); }
+    sql += " ORDER BY task.priority DESC, task.created_at DESC";
+    const rows = ctx.db.query(sql).all(...params) as any[];
+    const blockingByTask = getTaskBlockingDetails(ctx.db, rows.map((row) => row.id));
+    return json(rows.map((row) => ({ ...row, ...blockingByTask[row.id] })));
+  });
+
+  router.get("/api/tasks/workflow/statuses", (req) => {
+    const url = new URL(req.url);
+    const projectId = url.searchParams.get("project_id");
+    return json(workflowStatusesForProject(ctx.db, projectId));
+  });
+
+  router.post("/api/tasks/:id/claim", async (req, params) => {
+    const { agent_id } = await body(req);
+    required({ agent_id }, ["agent_id"]);
+    const idemKey = getIdempotencyKey(req);
+    if (idemKey) {
+      const existing = ctx.db.query("SELECT payload_json FROM event_log WHERE type = 'idempotency' AND json_extract(payload_json, '$.key') = ? LIMIT 1").get(idemKey) as any;
+      if (existing) return json(JSON.parse(existing.payload_json).response);
+    }
+    const task = ctx.db.query("SELECT * FROM task WHERE id = ?").get(params.id) as any;
+    if (!task) return json({ error: "Not found" }, 404);
+    const workflow = getWorkflowForTask(ctx.db, params.id);
+    if (task.status !== workflow.initial_status) return json({ error: `Task is not ${workflow.initial_status}` }, 409);
+
+    const result = await claimTaskForAgent(ctx, params.id, agent_id);
+    if ("error" in result) return json({ error: result.error }, result.status);
+
+    const row = result.task;
+    const session_id = "session_id" in result ? result.session_id : undefined;
+    if (idemKey) {
+      ctx.db.run("INSERT INTO event_log (id, type, payload_json, created_at) VALUES (?, 'idempotency', ?, ?)", [
+        generateId("evt"), JSON.stringify({ key: idemKey, response: { ...row, session_id } }), now()
+      ]);
+    }
+    return json({ ...row, session_id });
+  });
+
+  router.get("/api/tasks/:id/actions", (_req, params) => {
+    try {
+      return json(listTaskActions(ctx.db, params.id));
+    } catch (err: any) {
+      if (err.message.includes("not found")) return json({ error: "Not found" }, 404);
+      return json({ error: err.message }, 400);
+    }
+  });
+
+  router.post("/api/tasks/:id/transition", async (req, params) => {
+    const input = await body(req).catch(() => ({}));
+    const actionId = input.action_id || input.action;
+    if (!actionId) return json({ error: "action_id is required" }, 400);
+    const result = transitionTask(ctx, params.id, actionId, input, { actorId: input.actor_id || input.actor || "user" });
+    if (!result.ok) return json({ error: result.error }, result.status);
+
+    // If transitioning to an active (non-terminal, non-initial) status,
+    // ensure the assigned agent is awake and has a running session.
+    const { task, action, workflow } = result;
+    const isActive = action.to !== workflow.initial_status
+      && action.to !== workflow.blocked_status
+      && !action.terminal
+      && !workflow.statuses.find(s => s.id === action.to)?.terminal;
+
+    if (isActive && task.assignee_agent_id) {
+      await ensureAgentSession(ctx, task);
+    }
+
+    return json(result);
+  });
+
+  router.post("/api/tasks/:id/spawn", async (req, params) => {
+    const { title, description, required_capabilities, depends_on, assignee_agent_id } = await body(req);
+    required({ title }, ["title"]);
+    const parent = ctx.db.query("SELECT * FROM task WHERE id = ?").get(params.id) as any;
+    if (!parent) return json({ error: "Parent task not found" }, 404);
+    const newDepth = (parent.lineage_depth || 0) + 1;
+    if (newDepth > 10) {
+      return json({ error: "Max lineage depth (10) exceeded — spawn rejected to prevent avalanche" }, 422);
+    }
+    const id = generateId("task");
+    const ts = now();
+    const deps: string[] = Array.isArray(depends_on) ? depends_on : [];
+    const workflowStatuses = workflowStatusesForProject(ctx.db, parent.project_id);
+    const initialStatus = deps.length > 0
+      ? (workflowStatuses.find((status) => status.id === "blocked")?.id || "blocked")
+      : (workflowStatuses[0]?.id || "open");
+    ctx.db.run(
+      `INSERT INTO task (id, project_id, parent_task_id, title, description, status, required_capabilities_json, assignee_agent_id, priority, lineage_depth, created_by, created_at, updated_at)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+      [id, parent.project_id, params.id, title, description || null, initialStatus, JSON.stringify(required_capabilities || []), assignee_agent_id || null, parent.priority || 0, newDepth, "agent", ts, ts]
+    );
+    for (const depId of deps) {
+      ctx.db.run("INSERT OR IGNORE INTO task_dependency (task_id, depends_on) VALUES (?, ?)", [id, depId]);
+    }
+    // Write spawn record in parent thread
+    ctx.db.run(
+      "INSERT INTO task_thread_item (id, task_id, kind, author, content, ref_id, created_at) VALUES (?, ?, 'spawn_task', 'system', ?, ?, ?)",
+      [generateId("ti"), params.id, `Spawned: ${title}`, id, ts]
+    );
+    ctx.bus.publish("task.created", { id, project_id: parent.project_id, title, parent_task_id: params.id });
+    return json({ id, project_id: parent.project_id, parent_task_id: params.id, title, status: initialStatus, lineage_depth: newDepth, created_at: ts }, 201);
+  });
+
+  router.post("/api/tasks/:id/artifact", async (req, params) => {
+    const { kind, path, url, meta } = await body(req);
+    required({ kind }, ["kind"]);
+    if (!path && !url) return json({ error: "path or url is required" }, 400);
+    const task = ctx.db.query("SELECT * FROM task WHERE id = ?").get(params.id) as any;
+    if (!task) return json({ error: "Not found" }, 404);
+    const id = generateId("art");
+    const ts = now();
+    ctx.db.run(
+      "INSERT INTO artifact (id, task_id, kind, path, url, meta_json, created_at) VALUES (?, ?, ?, ?, ?, ?, ?)",
+      [id, params.id, kind, path || null, url || null, JSON.stringify(meta || {}), ts]
+    );
+    ctx.db.run(
+      "INSERT INTO task_thread_item (id, task_id, kind, author, content, ref_id, created_at) VALUES (?, ?, 'artifact', 'system', ?, ?, ?)",
+      [generateId("ti"), params.id, `Artifact added: ${kind} ${path || url}`, id, ts]
+    );
+    ctx.bus.publish("task.artifact_added", { id, task_id: params.id, kind });
+    return json({ id, task_id: params.id, kind, path, url, created_at: ts }, 201);
+  });
+
+  router.post("/api/tasks/:id/comment", async (req, params) => {
+    const { author, content } = await body(req);
+    required({ content }, ["content"]);
+    const idemKey = getIdempotencyKey(req);
+    if (idemKey) {
+      const existing = ctx.db.query("SELECT payload_json FROM event_log WHERE type = 'idempotency' AND json_extract(payload_json, '$.key') = ? LIMIT 1").get(idemKey) as any;
+      if (existing) return json(JSON.parse(existing.payload_json).response);
+    }
+    const id = generateId("ti");
+    const ts = now();
+    ctx.db.run(
+      "INSERT INTO task_thread_item (id, task_id, kind, author, content, created_at) VALUES (?, ?, 'comment', ?, ?, ?)",
+      [id, params.id, author || "user", content, ts]
+    );
+    if (idemKey) {
+      ctx.db.run("INSERT INTO event_log (id, type, payload_json, created_at) VALUES (?, 'idempotency', ?, ?)", [
+        generateId("evt"), JSON.stringify({ key: idemKey, response: { id, task_id: params.id, kind: "comment", content, created_at: ts } }), now()
+      ]);
+    }
+    return json({ id, task_id: params.id, kind: "comment", content, created_at: ts }, 201);
+  });
+
+  router.get("/api/tasks/:id", (_req, params) => {
+    const task = ctx.db.query(`SELECT task.*, (
+      SELECT session.id
+      FROM session
+      WHERE session.task_id = task.id
+      ORDER BY session.started_at DESC
+      LIMIT 1
+    ) AS session_id FROM task WHERE task.id = ?`).get(params.id);
+    if (!task) return json({ error: "Not found" }, 404);
+    const thread = ctx.db.query("SELECT * FROM task_thread_item WHERE task_id = ? ORDER BY created_at ASC").all(params.id);
+    const blocking = getTaskBlockingDetails(ctx.db, [params.id])[params.id];
+    return json({ ...task as any, ...blocking, thread });
+  });
+
+  router.patch("/api/tasks/:id", async (req, params) => {
+    const updates = await body(req);
+    const existingTask = ctx.db.query("SELECT * FROM task WHERE id = ?").get(params.id) as any;
+    if (!existingTask) return json({ error: "Not found" }, 404);
+    if (updates.status !== undefined) {
+      const workflow = getWorkflowForTask(ctx.db, params.id);
+      const allowed = new Set(workflow.statuses.map((status) => status.id));
+      if (!allowed.has(updates.status)) {
+        return json({ error: `Invalid task status: ${updates.status}. Allowed: ${Array.from(allowed).join(", ")}` }, 400);
+      }
+    }
+    const fields: string[] = [];
+    const values: any[] = [];
+    for (const key of ["title", "description", "status", "priority", "assignee_agent_id", "start_date", "end_date", "progress"]) {
+      if (updates[key] !== undefined) {
+        fields.push(`${key} = ?`);
+        values.push(updates[key]);
+      }
+    }
+    if (fields.length === 0) return json({ error: "No fields" }, 400);
+    fields.push("updated_at = ?");
+    values.push(now());
+    values.push(params.id);
+    ctx.db.run(`UPDATE task SET ${fields.join(", ")} WHERE id = ?`, values);
+    const row = ctx.db.query("SELECT * FROM task WHERE id = ?").get(params.id) as any;
+    if (updates.status !== undefined && updates.status !== existingTask.status) {
+      const workflow = getWorkflowForTask(ctx.db, params.id);
+      const payload = { id: params.id, from_status: existingTask.status, to_status: updates.status };
+      ctx.bus.publish("task.updated", payload);
+      ctx.bus.publish("task.status_changed", payload);
+      if (updates.status === workflow.done_status) {
+        unlockDependents(ctx, params.id, {
+          doneStatus: workflow.done_status,
+          blockedStatus: workflow.blocked_status,
+          openStatus: workflow.initial_status,
+        });
+        // Auto-archive completed scheduled task instances
+        if (existingTask.created_by === "scheduled_task") {
+          ctx.db.run("UPDATE task SET archived_at = ? WHERE id = ?", [now(), params.id]);
+        }
+      }
+      // Auto-claim: when dragged from open to in_progress with an assigned agent, start a session
+      const claimAction = workflow.actions.find((a) => a.id === "claim");
+      if (
+        existingTask.status === workflow.initial_status &&
+        updates.status === claimAction?.to &&
+        row.assignee_agent_id
+      ) {
+        const projectBlocker = findProjectExecutionBlocker(ctx.db, {
+          projectId: existingTask.project_id,
+          excludeTaskId: params.id,
+          claimedStatus: claimAction?.to,
+        });
+        if (!projectBlocker) {
+          const sessionResult = await createSession(ctx, {
+            agent_id: row.assignee_agent_id,
+            task_id: params.id,
+          });
+          if (!("error" in sessionResult)) {
+            ctx.bus.publish("task.claimed", { id: params.id, agent_id: row.assignee_agent_id, session_id: sessionResult.session.id });
+            return json({ ...row, session_id: sessionResult.session.id });
+          }
+        }
+      }
+    }
+    return json(row);
+  });
+
+  // POST /api/tasks/:id/review - create review thread item + inbox notification
+  router.post("/api/tasks/:id/review", async (req, params) => {
+    const { author, body: reviewBody } = await body(req);
+    if (!reviewBody) return json({ error: "body is required" }, 400);
+    const task = ctx.db.query("SELECT * FROM task WHERE id = ?").get(params.id) as any;
+    if (!task) return json({ error: "Not found" }, 404);
+    const tiId = generateId("ti");
+    const ts = now();
+    ctx.db.run(
+      "INSERT INTO task_thread_item (id, task_id, kind, author, content, created_at) VALUES (?, ?, 'review', ?, ?, ?)",
+      [tiId, params.id, author || "reviewer", reviewBody, ts]
+    );
+    // Create inbox message for the assignee
+    if (task.assignee_agent_id) {
+      ctx.db.run(
+        `INSERT INTO inbox_message (id, kind, from_actor, to_actor, subject, body, ref_json, status, created_at)
+         VALUES (?, 'review', ?, ?, ?, ?, ?, 'unread', ?)`,
+        [generateId("msg"), author || "reviewer", task.assignee_agent_id, `Review on: ${task.title}`, reviewBody, JSON.stringify({ task_id: params.id, thread_item_id: tiId }), ts]
+      );
+    }
+    ctx.bus.publish("task.reviewed", { id: params.id, thread_item_id: tiId });
+    return json({ id: tiId, task_id: params.id, kind: "review", content: reviewBody, created_at: ts }, 201);
+  });
+}

package/src/api/telegram.ts

@@ -0,0 +1,94 @@
+import type { Router } from "../core/router";
+import { body, json } from "../core/router";
+import type { HubContext } from "../core/server";
+import {
+  getBindingForChat,
+  handleTelegramBatchInbox,
+  handleTelegramCommand,
+  isTelegramCommand,
+  pushAgentReplyToTelegram,
+  sendTelegramNotification,
+} from "../bridges/telegram";
+import { insertChatMessage, runAgentLoop } from "./chat";
+
+export function registerTelegramRoutes(router: Router, ctx: HubContext) {
+  router.post("/api/bridges/telegram/events", async (req) => {
+    const input = await body(req).catch(() => ({}));
+    const secretToken = process.env.MAESTRO_TELEGRAM_SECRET_TOKEN;
+    const requestToken = req.headers.get("x-telegram-bot-api-secret-token") || undefined;
+
+    if (input.message || input.edited_message) {
+      const msg = input.message || input.edited_message;
+      const chatId = msg?.chat?.id;
+      const text = msg?.text || "";
+
+      // Validate secret token
+      if (secretToken && requestToken !== secretToken) {
+        return json({ ok: false, error: "Invalid Telegram secret token" }, 401);
+      }
+
+      if (!chatId) return json({ ok: false, error: "Missing chat id" }, 400);
+
+      // If it's a slash command, handle normally
+      if (isTelegramCommand(text)) {
+        const response = handleTelegramCommand(ctx.db, text, chatId);
+        // Execute the sendMessage call
+        await executeTelegramResponse(response);
+        return json({ ok: true, response });
+      }
+
+      // Non-command message: check if this group is bound to a workspace
+      const binding = getBindingForChat(ctx.db, chatId);
+      if (binding) {
+        // Bridge message to workspace chat
+        const humanMsg = insertChatMessage(ctx, binding.workspace_id, "human", "telegram", text);
+        ctx.bus.publish("chat.message", {
+          workspace_id: binding.workspace_id,
+          message_id: humanMsg.id,
+          seq: humanMsg.seq,
+          sender_type: "human",
+          source: "telegram",
+          tg_chat_id: String(chatId),
+        });
+
+        // Trigger the agentic loop
+        runAgentLoop(ctx, binding.workspace_id).catch((err) => {
+          console.error(`[telegram] agent loop error for ${binding.workspace_id}:`, err.message);
+        });
+
+        return json({ ok: true, bridged: true, workspace_id: binding.workspace_id });
+      }
+
+      // Not bound, show help
+      const response = handleTelegramCommand(ctx.db, text, chatId);
+      await executeTelegramResponse(response);
+      return json({ ok: true, response });
+    }
+
+    // Direct API call (non-webhook)
+    return json(handleTelegramCommand(ctx.db, input.text || "", input.chat_id || "user"));
+  });
+
+  router.post("/api/bridges/telegram/inbox/batch", async (req) => {
+    const input = await body(req);
+    return json(handleTelegramBatchInbox(ctx.db, input));
+  });
+
+  router.post("/api/bridges/telegram/notify", async (req) => {
+    const input = await body(req);
+    const botToken = input.bot_token || process.env.MAESTRO_TELEGRAM_BOT_TOKEN;
+    if (!botToken) return json({ error: "Missing Telegram bot token" }, 400);
+    return json(await sendTelegramNotification({ ...input, bot_token: botToken }));
+  });
+}
+
+async function executeTelegramResponse(response: any) {
+  const botToken = process.env.MAESTRO_TELEGRAM_BOT_TOKEN;
+  if (!botToken || !response?.payload) return;
+  const base = "https://api.telegram.org";
+  await fetch(`${base}/bot${botToken}/${response.method}`, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify(response.payload),
+  }).catch(() => {});
+}

package/src/api/templates.ts

@@ -0,0 +1,36 @@
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "fs";
+import { join } from "path";
+import type { Router } from "../core/router";
+import { json, body } from "../core/router";
+import type { HubContext } from "../core/server";
+
+export function registerTemplateRoutes(router: Router, ctx: HubContext) {
+  const templatesDir = join(ctx.hubDir, "../templates");
+
+  router.get("/api/templates", () => {
+    if (!existsSync(templatesDir)) return json([]);
+    const files = readdirSync(templatesDir).filter(f => f.endsWith(".json"));
+    const templates = files.map(f => {
+      try {
+        return JSON.parse(readFileSync(join(templatesDir, f), "utf-8"));
+      } catch { return null; }
+    }).filter(Boolean);
+    return json(templates);
+  });
+
+  router.post("/api/templates", async (req) => {
+    const template = await body(req);
+    if (!template.name) return json({ error: "name is required" }, 400);
+    mkdirSync(templatesDir, { recursive: true });
+    const filename = template.name.toLowerCase().replace(/[^a-z0-9]+/g, "-") + ".json";
+    writeFileSync(join(templatesDir, filename), JSON.stringify(template, null, 2));
+    return json({ ...template, filename }, 201);
+  });
+
+  router.get("/api/templates/:name", (_req, params) => {
+    const filename = `${params.name}.json`;
+    const filePath = join(templatesDir, filename);
+    if (!existsSync(filePath)) return json({ error: "Template not found" }, 404);
+    return json(JSON.parse(readFileSync(filePath, "utf-8")));
+  });
+}

package/src/api/webhooks.ts

@@ -0,0 +1,20 @@
+import type { Router } from "../core/router";
+import { json, body } from "../core/router";
+import type { HubContext } from "../core/server";
+import { generateId, now } from "../core/db";
+
+export function registerWebhookRoutes(router: Router, ctx: HubContext) {
+  // POST /api/webhooks/:source — generic webhook receiver
+  router.post("/api/webhooks/:source", async (req, params) => {
+    const payload = await body(req);
+    const source = params.source; // github, lark, custom, etc.
+    const id = generateId("evt");
+    const ts = now();
+    ctx.db.run(
+      "INSERT INTO event_log (id, type, payload_json, created_at) VALUES (?, ?, ?, ?)",
+      [id, `webhook.${source}`, JSON.stringify(payload), ts]
+    );
+    ctx.bus.publish(`webhook.${source}`, { id, source, payload });
+    return json({ id, source, received: true }, 201);
+  });
+}