bopodev-api 0.1.30 → 0.1.31

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bopodev-api",
-  "version": "0.1.30",
+  "version": "0.1.31",
   "license": "MIT",
   "type": "module",
   "files": [
@@ -17,9 +17,9 @@
     "nanoid": "^5.1.5",
     "ws": "^8.19.0",
     "zod": "^4.1.5",
-    "bopodev-contracts": "0.1.30",
-    "bopodev-db": "0.1.30",
-    "bopodev-agent-sdk": "0.1.30"
+    "bopodev-db": "0.1.31",
+    "bopodev-agent-sdk": "0.1.31",
+    "bopodev-contracts": "0.1.31"
   },
   "devDependencies": {
     "@types/cors": "^2.8.19",

package/src/app.ts

@@ -10,6 +10,7 @@ import { createGoalsRouter } from "./routes/goals";
 import { createGovernanceRouter } from "./routes/governance";
 import { createHeartbeatRouter } from "./routes/heartbeats";
 import { createIssuesRouter } from "./routes/issues";
+import { createLoopsRouter } from "./routes/loops";
 import { createObservabilityRouter } from "./routes/observability";
 import { createProjectsRouter } from "./routes/projects";
 import { createPluginsRouter } from "./routes/plugins";
@@ -64,6 +65,7 @@ export function createApp(ctx: AppContext) {
   app.use("/companies", createCompaniesRouter(ctx));
   app.use("/projects", createProjectsRouter(ctx));
   app.use("/issues", createIssuesRouter(ctx));
+  app.use("/loops", createLoopsRouter(ctx));
   app.use("/goals", createGoalsRouter(ctx));
   app.use("/agents", createAgentsRouter(ctx));
   app.use("/governance", createGovernanceRouter(ctx));

package/src/lib/instance-paths.ts

@@ -78,6 +78,11 @@ export function resolveAgentMemoryRootPath(companyId: string, agentId: string) {
   return join(resolveAgentFallbackWorkspacePath(companyId, agentId), "memory");
 }
 
+/** Agent operating docs (AGENTS.md, HEARTBEAT.md, etc.) — matches `BOPODEV_AGENT_OPERATING_DIR` at runtime. */
+export function resolveAgentOperatingPath(companyId: string, agentId: string) {
+  return join(resolveAgentFallbackWorkspacePath(companyId, agentId), "operating");
+}
+
 export function resolveCompanyMemoryRootPath(companyId: string) {
   const safeCompanyId = assertPathSegment(companyId, "companyId");
   return join(resolveBopoInstanceRoot(), "workspaces", safeCompanyId, "memory");

package/src/middleware/cors-config.ts

@@ -22,7 +22,7 @@ export function createCorsMiddleware(deploymentMode: DeploymentMode, allowedOrig
       callback(new Error(`CORS origin denied: ${origin}`));
     },
     credentials: true,
-    methods: ["GET", "POST", "PUT", "DELETE", "OPTIONS"],
+    methods: ["GET", "POST", "PUT", "PATCH", "DELETE", "OPTIONS"],
     allowedHeaders: [
       "content-type",
       "x-company-id",

package/src/routes/loops.ts

@@ -0,0 +1,360 @@
+import { Router } from "express";
+import { appendAuditEvent, listAuditEvents } from "bopodev-db";
+import {
+  WorkLoopCreateRequestSchema,
+  WorkLoopTriggerCreateRequestSchema,
+  WorkLoopUpdateRequestSchema,
+  WorkLoopTriggerUpdateRequestSchema
+} from "bopodev-contracts";
+import type { AppContext } from "../context";
+import { sendError, sendOk } from "../http";
+import { requireCompanyScope } from "../middleware/company-scope";
+import { enforcePermission } from "../middleware/request-actor";
+import {
+  workLoopRuns,
+  workLoops,
+  workLoopTriggers
+} from "bopodev-db";
+import {
+  addWorkLoopTrigger,
+  addWorkLoopTriggerFromPreset,
+  dispatchLoopRun,
+  getWorkLoop,
+  listWorkLoopRuns,
+  listWorkLoops,
+  listWorkLoopTriggers,
+  createWorkLoop,
+  updateWorkLoop,
+  updateWorkLoopTrigger,
+  deleteWorkLoopTrigger
+} from "../services/work-loop-service";
+
+function serializeLoop(row: typeof workLoops.$inferSelect) {
+  let goalIds: string[] = [];
+  try {
+    goalIds = JSON.parse(row.goalIdsJson || "[]") as string[];
+  } catch {
+    goalIds = [];
+  }
+  return {
+    id: row.id,
+    companyId: row.companyId,
+    projectId: row.projectId,
+    parentIssueId: row.parentIssueId,
+    goalIds,
+    title: row.title,
+    description: row.description,
+    assigneeAgentId: row.assigneeAgentId,
+    priority: row.priority,
+    status: row.status,
+    concurrencyPolicy: row.concurrencyPolicy,
+    catchUpPolicy: row.catchUpPolicy,
+    lastTriggeredAt: row.lastTriggeredAt ? row.lastTriggeredAt.toISOString() : null,
+    createdAt: row.createdAt.toISOString(),
+    updatedAt: row.updatedAt.toISOString()
+  };
+}
+
+function serializeTrigger(row: typeof workLoopTriggers.$inferSelect) {
+  return {
+    id: row.id,
+    companyId: row.companyId,
+    workLoopId: row.workLoopId,
+    kind: row.kind,
+    label: row.label,
+    enabled: row.enabled,
+    cronExpression: row.cronExpression,
+    timezone: row.timezone,
+    nextRunAt: row.nextRunAt ? row.nextRunAt.toISOString() : null,
+    lastFiredAt: row.lastFiredAt ? row.lastFiredAt.toISOString() : null,
+    lastResult: row.lastResult,
+    createdAt: row.createdAt.toISOString(),
+    updatedAt: row.updatedAt.toISOString()
+  };
+}
+
+function serializeRun(row: typeof workLoopRuns.$inferSelect) {
+  return {
+    id: row.id,
+    companyId: row.companyId,
+    workLoopId: row.workLoopId,
+    triggerId: row.triggerId,
+    source: row.source,
+    status: row.status,
+    triggeredAt: row.triggeredAt.toISOString(),
+    idempotencyKey: row.idempotencyKey,
+    linkedIssueId: row.linkedIssueId,
+    coalescedIntoRunId: row.coalescedIntoRunId,
+    failureReason: row.failureReason,
+    completedAt: row.completedAt ? row.completedAt.toISOString() : null,
+    createdAt: row.createdAt.toISOString(),
+    updatedAt: row.updatedAt.toISOString()
+  };
+}
+
+export function createLoopsRouter(ctx: AppContext) {
+  const router = Router();
+  router.use(requireCompanyScope);
+
+  router.get("/", async (req, res) => {
+    if (!enforcePermission(req, res, "loops:read")) {
+      return;
+    }
+    const rows = await listWorkLoops(ctx.db, req.companyId!);
+    return sendOk(res, { data: rows.map(serializeLoop) });
+  });
+
+  router.post("/", async (req, res) => {
+    if (!enforcePermission(req, res, "loops:write")) {
+      return;
+    }
+    const parsed = WorkLoopCreateRequestSchema.safeParse(req.body);
+    if (!parsed.success) {
+      return sendError(res, parsed.error.message, 422);
+    }
+    try {
+      const row = await createWorkLoop(ctx.db, {
+        companyId: req.companyId!,
+        projectId: parsed.data.projectId,
+        parentIssueId: parsed.data.parentIssueId,
+        goalIds: parsed.data.goalIds,
+        title: parsed.data.title,
+        description: parsed.data.description,
+        assigneeAgentId: parsed.data.assigneeAgentId,
+        priority: parsed.data.priority,
+        status: parsed.data.status,
+        concurrencyPolicy: parsed.data.concurrencyPolicy,
+        catchUpPolicy: parsed.data.catchUpPolicy
+      });
+      if (!row) {
+        return sendError(res, "Failed to create work loop.", 500);
+      }
+      await appendAuditEvent(ctx.db, {
+        companyId: req.companyId!,
+        actorType: "human",
+        actorId: req.actor?.id ?? null,
+        eventType: "work_loop.created",
+        entityType: "work_loop",
+        entityId: row.id,
+        correlationId: req.requestId ?? null,
+        payload: { loopId: row.id, title: row.title }
+      });
+      return sendOk(res, { data: serializeLoop(row) });
+    } catch (e) {
+      return sendError(res, e instanceof Error ? e.message : "Failed to create work loop.", 422);
+    }
+  });
+
+  router.get("/:loopId", async (req, res) => {
+    if (!enforcePermission(req, res, "loops:read")) {
+      return;
+    }
+    const loopId = req.params.loopId;
+    const row = await getWorkLoop(ctx.db, req.companyId!, loopId);
+    if (!row) {
+      return sendError(res, "Work loop not found.", 404);
+    }
+    const [triggers, recentRuns] = await Promise.all([
+      listWorkLoopTriggers(ctx.db, req.companyId!, loopId),
+      listWorkLoopRuns(ctx.db, req.companyId!, loopId, 30)
+    ]);
+    return sendOk(res, {
+      data: {
+        ...serializeLoop(row),
+        triggers: triggers.map(serializeTrigger),
+        recentRuns: recentRuns.map(serializeRun)
+      }
+    });
+  });
+
+  router.patch("/:loopId", async (req, res) => {
+    if (!enforcePermission(req, res, "loops:write")) {
+      return;
+    }
+    const parsed = WorkLoopUpdateRequestSchema.safeParse(req.body);
+    if (!parsed.success) {
+      return sendError(res, parsed.error.message, 422);
+    }
+    const row = await updateWorkLoop(ctx.db, req.companyId!, req.params.loopId, parsed.data);
+    if (!row) {
+      return sendError(res, "Work loop not found.", 404);
+    }
+    await appendAuditEvent(ctx.db, {
+      companyId: req.companyId!,
+      actorType: "human",
+      actorId: req.actor?.id ?? null,
+      eventType: "work_loop.updated",
+      entityType: "work_loop",
+      entityId: row.id,
+      correlationId: req.requestId ?? null,
+      payload: { patch: parsed.data }
+    });
+    return sendOk(res, { data: serializeLoop(row) });
+  });
+
+  router.post("/:loopId/run", async (req, res) => {
+    if (!enforcePermission(req, res, "loops:run")) {
+      return;
+    }
+    const loopId = req.params.loopId;
+    const loop = await getWorkLoop(ctx.db, req.companyId!, loopId);
+    if (!loop) {
+      return sendError(res, "Work loop not found.", 404);
+    }
+    const run = await dispatchLoopRun(ctx.db, {
+      companyId: req.companyId!,
+      loopId,
+      triggerId: null,
+      source: "manual",
+      idempotencyKey: req.requestId ? `manual:${loopId}:${req.requestId}` : `manual:${loopId}:${Date.now()}`,
+      realtimeHub: ctx.realtimeHub,
+      requestId: req.requestId
+    });
+    if (!run) {
+      return sendError(res, "Work loop is not active or could not be dispatched.", 409);
+    }
+    await appendAuditEvent(ctx.db, {
+      companyId: req.companyId!,
+      actorType: "human",
+      actorId: req.actor?.id ?? null,
+      eventType: "work_loop.manual_run",
+      entityType: "work_loop",
+      entityId: loopId,
+      correlationId: req.requestId ?? null,
+      payload: { runId: run.id, status: run.status }
+    });
+    return sendOk(res, { data: serializeRun(run) });
+  });
+
+  router.get("/:loopId/runs", async (req, res) => {
+    if (!enforcePermission(req, res, "loops:read")) {
+      return;
+    }
+    const loop = await getWorkLoop(ctx.db, req.companyId!, req.params.loopId);
+    if (!loop) {
+      return sendError(res, "Work loop not found.", 404);
+    }
+    const limit = Math.min(500, Math.max(1, Number(req.query.limit) || 100));
+    const runs = await listWorkLoopRuns(ctx.db, req.companyId!, req.params.loopId, limit);
+    return sendOk(res, { data: runs.map(serializeRun) });
+  });
+
+  router.get("/:loopId/activity", async (req, res) => {
+    if (!enforcePermission(req, res, "loops:read")) {
+      return;
+    }
+    const loopId = req.params.loopId;
+    const loop = await getWorkLoop(ctx.db, req.companyId!, loopId);
+    if (!loop) {
+      return sendError(res, "Work loop not found.", 404);
+    }
+    const events = await listAuditEvents(ctx.db, req.companyId!, 200);
+    const filtered = events.filter((e) => e.entityType === "work_loop" && e.entityId === loopId);
+    return sendOk(res, {
+      data: filtered.map((e) => ({
+        id: e.id,
+        eventType: e.eventType,
+        actorType: e.actorType,
+        actorId: e.actorId,
+        payload: JSON.parse(e.payloadJson || "{}") as Record<string, unknown>,
+        createdAt: e.createdAt.toISOString()
+      }))
+    });
+  });
+
+  router.post("/:loopId/triggers", async (req, res) => {
+    if (!enforcePermission(req, res, "loops:write")) {
+      return;
+    }
+    const loopId = req.params.loopId;
+    const loop = await getWorkLoop(ctx.db, req.companyId!, loopId);
+    if (!loop) {
+      return sendError(res, "Work loop not found.", 404);
+    }
+    const parsed = WorkLoopTriggerCreateRequestSchema.safeParse(req.body);
+    if (!parsed.success) {
+      return sendError(res, parsed.error.message, 422);
+    }
+    try {
+      const body = parsed.data;
+      const trigger =
+        body.mode === "cron"
+          ? await addWorkLoopTrigger(ctx.db, {
+              companyId: req.companyId!,
+              workLoopId: loopId,
+              cronExpression: body.cronExpression,
+              timezone: body.timezone,
+              label: body.label ?? null,
+              enabled: body.enabled
+            })
+          : await addWorkLoopTriggerFromPreset(ctx.db, {
+              companyId: req.companyId!,
+              workLoopId: loopId,
+              preset: body.preset,
+              hour24: body.hour24,
+              minute: body.minute,
+              dayOfWeek: body.preset === "weekly" ? (body.dayOfWeek ?? 1) : undefined,
+              timezone: body.timezone,
+              label: body.label ?? null,
+              enabled: body.enabled
+            });
+      if (!trigger) {
+        return sendError(res, "Failed to create trigger.", 500);
+      }
+      return sendOk(res, { data: serializeTrigger(trigger) });
+    } catch (e) {
+      return sendError(res, e instanceof Error ? e.message : "Failed to create trigger.", 422);
+    }
+  });
+
+  router.patch("/:loopId/triggers/:triggerId", async (req, res) => {
+    if (!enforcePermission(req, res, "loops:write")) {
+      return;
+    }
+    const parsed = WorkLoopTriggerUpdateRequestSchema.safeParse(req.body);
+    if (!parsed.success) {
+      return sendError(res, parsed.error.message, 422);
+    }
+    const loop = await getWorkLoop(ctx.db, req.companyId!, req.params.loopId);
+    if (!loop) {
+      return sendError(res, "Work loop not found.", 404);
+    }
+    try {
+      const row = await updateWorkLoopTrigger(ctx.db, req.companyId!, req.params.triggerId, parsed.data);
+      if (!row || row.workLoopId !== req.params.loopId) {
+        return sendError(res, "Trigger not found.", 404);
+      }
+      return sendOk(res, { data: serializeTrigger(row) });
+    } catch (e) {
+      return sendError(res, e instanceof Error ? e.message : "Failed to update trigger.", 422);
+    }
+  });
+
+  router.delete("/:loopId/triggers/:triggerId", async (req, res) => {
+    if (!enforcePermission(req, res, "loops:write")) {
+      return;
+    }
+    const { loopId, triggerId } = req.params;
+    const loop = await getWorkLoop(ctx.db, req.companyId!, loopId);
+    if (!loop) {
+      return sendError(res, "Work loop not found.", 404);
+    }
+    const deleted = await deleteWorkLoopTrigger(ctx.db, req.companyId!, loopId, triggerId);
+    if (!deleted) {
+      return sendError(res, "Trigger not found.", 404);
+    }
+    await appendAuditEvent(ctx.db, {
+      companyId: req.companyId!,
+      actorType: "human",
+      actorId: req.actor?.id ?? null,
+      eventType: "work_loop.trigger_deleted",
+      entityType: "work_loop",
+      entityId: loopId,
+      correlationId: req.requestId ?? null,
+      payload: { triggerId }
+    });
+    return sendOk(res, { deleted: true });
+  });
+
+  return router;
+}

package/src/routes/observability.ts

@@ -16,7 +16,18 @@ import type { AppContext } from "../context";
 import { sendError, sendOk } from "../http";
 import { resolveRunArtifactAbsolutePath } from "../lib/run-artifact-paths";
 import { requireCompanyScope } from "../middleware/company-scope";
-import { listAgentMemoryFiles, loadAgentMemoryContext, readAgentMemoryFile } from "../services/memory-file-service";
+import { enforcePermission } from "../middleware/request-actor";
+import {
+  listAgentOperatingMarkdownFiles,
+  readAgentOperatingFile,
+  writeAgentOperatingFile
+} from "../services/agent-operating-file-service";
+import {
+  listAgentMemoryFiles,
+  loadAgentMemoryContext,
+  readAgentMemoryFile,
+  writeAgentMemoryFile
+} from "../services/memory-file-service";
 
 export function createObservabilityRouter(ctx: AppContext) {
   const router = Router();
@@ -259,6 +270,117 @@ export function createObservabilityRouter(ctx: AppContext) {
     }
   });
 
+  router.put("/memory/:agentId/file", async (req, res) => {
+    if (!enforcePermission(req, res, "agents:write")) {
+      return;
+    }
+    const companyId = req.companyId!;
+    const agentId = req.params.agentId;
+    const relativePath = typeof req.query.path === "string" ? req.query.path.trim() : "";
+    if (!relativePath) {
+      return sendError(res, "Query parameter 'path' is required.", 422);
+    }
+    const body = req.body as { content?: unknown };
+    if (typeof body?.content !== "string") {
+      return sendError(res, "Expected JSON body with string 'content'.", 422);
+    }
+    const agents = await listAgents(ctx.db, companyId);
+    if (!agents.some((entry) => entry.id === agentId)) {
+      return sendError(res, "Agent not found", 404);
+    }
+    try {
+      const result = await writeAgentMemoryFile({
+        companyId,
+        agentId,
+        relativePath,
+        content: body.content
+      });
+      return sendOk(res, result);
+    } catch (error) {
+      return sendError(res, String(error), 422);
+    }
+  });
+
+  router.get("/agent-operating/:agentId/files", async (req, res) => {
+    const companyId = req.companyId!;
+    const agentId = req.params.agentId;
+    const agents = await listAgents(ctx.db, companyId);
+    if (!agents.some((entry) => entry.id === agentId)) {
+      return sendError(res, "Agent not found", 404);
+    }
+    const rawLimit = Number(req.query.limit ?? 100);
+    const limit = Number.isFinite(rawLimit) ? Math.min(Math.max(Math.floor(rawLimit), 1), 500) : 100;
+    try {
+      const files = await listAgentOperatingMarkdownFiles({
+        companyId,
+        agentId,
+        maxFiles: limit
+      });
+      return sendOk(res, {
+        items: files.map((file) => ({
+          relativePath: file.relativePath,
+          path: file.path
+        }))
+      });
+    } catch (error) {
+      return sendError(res, String(error), 422);
+    }
+  });
+
+  router.get("/agent-operating/:agentId/file", async (req, res) => {
+    const companyId = req.companyId!;
+    const agentId = req.params.agentId;
+    const relativePath = typeof req.query.path === "string" ? req.query.path.trim() : "";
+    if (!relativePath) {
+      return sendError(res, "Query parameter 'path' is required.", 422);
+    }
+    const agents = await listAgents(ctx.db, companyId);
+    if (!agents.some((entry) => entry.id === agentId)) {
+      return sendError(res, "Agent not found", 404);
+    }
+    try {
+      const file = await readAgentOperatingFile({
+        companyId,
+        agentId,
+        relativePath
+      });
+      return sendOk(res, file);
+    } catch (error) {
+      return sendError(res, String(error), 422);
+    }
+  });
+
+  router.put("/agent-operating/:agentId/file", async (req, res) => {
+    if (!enforcePermission(req, res, "agents:write")) {
+      return;
+    }
+    const companyId = req.companyId!;
+    const agentId = req.params.agentId;
+    const relativePath = typeof req.query.path === "string" ? req.query.path.trim() : "";
+    if (!relativePath) {
+      return sendError(res, "Query parameter 'path' is required.", 422);
+    }
+    const body = req.body as { content?: unknown };
+    if (typeof body?.content !== "string") {
+      return sendError(res, "Expected JSON body with string 'content'.", 422);
+    }
+    const agents = await listAgents(ctx.db, companyId);
+    if (!agents.some((entry) => entry.id === agentId)) {
+      return sendError(res, "Agent not found", 404);
+    }
+    try {
+      const result = await writeAgentOperatingFile({
+        companyId,
+        agentId,
+        relativePath,
+        content: body.content
+      });
+      return sendOk(res, result);
+    } catch (error) {
+      return sendError(res, String(error), 422);
+    }
+  });
+
   router.get("/memory/:agentId/context-preview", async (req, res) => {
     const companyId = req.companyId!;
     const agentId = req.params.agentId;

package/src/services/agent-operating-file-service.ts

@@ -0,0 +1,116 @@
+import { mkdir, readdir, readFile, stat, writeFile } from "node:fs/promises";
+import { dirname, join, relative, resolve } from "node:path";
+import { isInsidePath, resolveAgentOperatingPath } from "../lib/instance-paths";
+
+const MAX_OBSERVABILITY_FILES = 200;
+const MAX_OBSERVABILITY_FILE_BYTES = 512 * 1024;
+
+function isMarkdownFileName(name: string) {
+  return name.toLowerCase().endsWith(".md");
+}
+
+async function walkMarkdownFiles(root: string, maxFiles: number) {
+  const collected: string[] = [];
+  const queue = [root];
+  while (queue.length > 0 && collected.length < maxFiles) {
+    const current = queue.shift();
+    if (!current) {
+      continue;
+    }
+    const entries = await readdir(current, { withFileTypes: true });
+    for (const entry of entries) {
+      const absolutePath = join(current, entry.name);
+      if (entry.isDirectory()) {
+        queue.push(absolutePath);
+        continue;
+      }
+      if (entry.isFile() && isMarkdownFileName(entry.name)) {
+        collected.push(absolutePath);
+        if (collected.length >= maxFiles) {
+          break;
+        }
+      }
+    }
+  }
+  return collected.sort();
+}
+
+export async function listAgentOperatingMarkdownFiles(input: {
+  companyId: string;
+  agentId: string;
+  maxFiles?: number;
+}) {
+  const root = resolveAgentOperatingPath(input.companyId, input.agentId);
+  await mkdir(root, { recursive: true });
+  const maxFiles = Math.max(1, Math.min(MAX_OBSERVABILITY_FILES, input.maxFiles ?? 100));
+  const files = await walkMarkdownFiles(root, maxFiles);
+  return files.map((filePath) => ({
+    path: filePath,
+    relativePath: relative(root, filePath),
+    operatingRoot: root
+  }));
+}
+
+export async function readAgentOperatingFile(input: {
+  companyId: string;
+  agentId: string;
+  relativePath: string;
+}) {
+  const root = resolveAgentOperatingPath(input.companyId, input.agentId);
+  await mkdir(root, { recursive: true });
+  const candidate = resolve(root, input.relativePath);
+  if (!isInsidePath(root, candidate)) {
+    throw new Error("Requested operating path is outside of operating root.");
+  }
+  const info = await stat(candidate);
+  if (!info.isFile()) {
+    throw new Error("Requested operating path is not a file.");
+  }
+  if (info.size > MAX_OBSERVABILITY_FILE_BYTES) {
+    throw new Error("Requested operating file exceeds size limit.");
+  }
+  const content = await readFile(candidate, "utf8");
+  return {
+    path: candidate,
+    relativePath: relative(root, candidate),
+    content,
+    sizeBytes: info.size
+  };
+}
+
+export async function writeAgentOperatingFile(input: {
+  companyId: string;
+  agentId: string;
+  relativePath: string;
+  content: string;
+}) {
+  const root = resolveAgentOperatingPath(input.companyId, input.agentId);
+  await mkdir(root, { recursive: true });
+  const normalizedRel = input.relativePath.trim();
+  if (!normalizedRel || normalizedRel.includes("..")) {
+    throw new Error("Invalid relative path.");
+  }
+  if (!isMarkdownFileName(normalizedRel)) {
+    throw new Error("Only .md files can be written under the operating directory.");
+  }
+  const candidate = resolve(root, normalizedRel);
+  if (!isInsidePath(root, candidate)) {
+    throw new Error("Requested operating path is outside of operating root.");
+  }
+  const bytes = Buffer.byteLength(input.content, "utf8");
+  if (bytes > MAX_OBSERVABILITY_FILE_BYTES) {
+    throw new Error("Content exceeds size limit.");
+  }
+  const parent = dirname(candidate);
+  if (!isInsidePath(root, parent)) {
+    throw new Error("Invalid parent directory.");
+  }
+  await mkdir(parent, { recursive: true });
+  await writeFile(candidate, input.content, { encoding: "utf8" });
+  const info = await stat(candidate);
+  return {
+    path: candidate,
+    relativePath: relative(root, candidate),
+    sizeBytes: info.size
+  };
+}

package/src/services/heartbeat-service/heartbeat-run.ts

@@ -669,7 +669,9 @@ export async function runHeartbeatForAgent(
       },
       failClosed: false
     });
-    const isCommentOrderWake = options?.wakeContext?.reason === "issue_comment_recipient";
+    const isCommentOrderWake =
+      options?.wakeContext?.reason === "issue_comment_recipient" ||
+      options?.wakeContext?.reason === "loop_execution";
     const heartbeatIdlePolicy = resolveHeartbeatIdlePolicy();
     const workItems = isCommentOrderWake ? [] : await claimIssuesForAgent(db, companyId, agentId, runId);
     const wakeWorkItems = await loadWakeContextWorkItems(db, companyId, options?.wakeContext?.issueIds);
@@ -1941,7 +1943,10 @@ function resolveExecutionWorkItems(
   wakeContextItems: IssueWorkItemRow[],
   wakeContext?: HeartbeatWakeContext
 ) {
-  if (wakeContext?.reason === "issue_comment_recipient" && wakeContextItems.length > 0) {
+  if (
+    (wakeContext?.reason === "issue_comment_recipient" || wakeContext?.reason === "loop_execution") &&
+    wakeContextItems.length > 0
+  ) {
     return wakeContextItems;
   }
   return mergeContextWorkItems(assigned, wakeContextItems);