agent-conveyor 0.1.8 → 0.1.9

package/README.md

@@ -379,6 +379,21 @@ tmux attach -t codex-live-test
   Codex app thread metadata is normally supplied after a Codex app manager has
   used `create_thread` and `set_thread_title`; terminal-only users can omit it
   and still use the manual no-tmux handoff.
+- `app-heartbeat TASK --role manager|worker [--dispatcher-id ID]
+  [--stale-after N] [--json]` — Record a Codex app/no-tmux manager or worker
+  heartbeat for the active binding and return that role's next poll commands.
+  Use this as the recurring heartbeat command for pull-required app sessions.
+- `app-loop-status TASK [--dispatcher-id ID] [--stale-after N] [--json]` —
+  Summarize manager lease, worker lease, Dispatch heartbeat, and next required
+  actions for an app-native Conveyor loop.
+- `app-wakeup-plan TASK [--dispatcher-id ID] [--stale-after N] [--json]` —
+  Emit exact manager and worker thread wake prompts, including app thread ids
+  and titles when present, for an operator or Codex app automation to send.
+- `app-wakeup-dispatch TASK [--dispatcher-id ID] [--stale-after N] [--json]` —
+  Prepare adapter-ready Codex app wake actions and record a telemetry receipt
+  for prepared, skipped, and blocked role wakeups. This command does not send
+  `send_message_to_thread`; the Codex app/operator layer sends prompts whose
+  actions report `send_ready=true`.
 - `discover [QUERY] [--all] [--limit N]` / `search [QUERY]` — Search tasks,
   registered sessions, active bindings, and recent telemetry in one JSON result.
   Use this for conversational setup when a manager or Codex session needs to
@@ -1017,10 +1032,11 @@ Current dispatch state:
   in `routed_notifications`, and threaded with `correlation_id`.
 - The session inbox is the same `routed_notifications` stream addressed by
   `target_session_id`: tmux push is optional transport. Codex app-based sessions
-  should long-poll with the returned `communication.poll_command`. For
-  disposable Ralph loops, use the generated `worker_handoff` prompt so the
-  worker keeps polling until no inbox item remains or the loop reaches
-  `max_iterations`. For no-tmux Codex app sessions, treat
+  should run `app-heartbeat` as their recurring heartbeat, using the direct
+  `communication.poll_command` only as a fallback or when returned in heartbeat
+  guidance. For disposable Ralph loops, use the generated `worker_handoff`
+  prompt so the worker keeps polling until no inbox item remains or the loop
+  reaches `max_iterations`. For no-tmux Codex app sessions, treat
   `communication.requires_polling=true` as requiring a heartbeat/wake layer:
   a delivered pull inbox item does not by itself wake an idle app thread. Do
   not delete or pause heartbeats because an inbox poll is idle. A terminal

package/dist/cli/typescript-runtime.js

@@ -5,6 +5,7 @@ import { homedir, tmpdir } from "node:os";
 import { dirname, join, relative, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { taskAuditSync } from "../runtime/audit.js";
+import { appLoopStatusSync, appWakeupDispatchPlanSync, appWakeupPlanSync, directInboxPollCommand, } from "../runtime/app-autonomy.js";
 import { classifyBusyWait, classifyStartupOutput } from "../runtime/classify.js";
 import { exportTaskSync } from "../runtime/export.js";
 import { ingestSessionSync } from "../runtime/ingest.js";
@@ -118,6 +119,18 @@ export function runTypescriptRuntimeCommand(options) {
         if (parsed.command === "loop-status") {
             return runLoopStatusCommand(parsed, options);
         }
+        if (parsed.command === "app-heartbeat") {
+            return runAppHeartbeatCommand(parsed, options);
+        }
+        if (parsed.command === "app-loop-status") {
+            return runAppLoopStatusCommand(parsed, options);
+        }
+        if (parsed.command === "app-wakeup-plan") {
+            return runAppWakeupPlanCommand(parsed, options);
+        }
+        if (parsed.command === "app-wakeup-dispatch") {
+            return runAppWakeupDispatchCommand(parsed, options);
+        }
         if (parsed.command === "qa-plan") {
             return runQaPlanCommand(parsed);
         }
@@ -417,6 +430,7 @@ function parseRuntimeArgs(args, env) {
         includeLegacy: false,
         help: false,
         redactIdentityToken: false,
+        appStaleAfterSeconds: 180,
         active: false,
         add: false,
         apply: false,
@@ -1469,7 +1483,14 @@ function parseRuntimeArgs(args, env) {
             index += 1;
         }
         else if (arg === "--dispatcher-id") {
-            if (command !== "pair" && command !== "dispatch" && command !== "qa-run" && command !== "dashboard") {
+            if (command !== "pair"
+                && command !== "dispatch"
+                && command !== "qa-run"
+                && command !== "dashboard"
+                && command !== "app-heartbeat"
+                && command !== "app-loop-status"
+                && command !== "app-wakeup-plan"
+                && command !== "app-wakeup-dispatch") {
                 return { command, enabled, error: "Unsupported TypeScript runtime option: --dispatcher-id", explicit, flags, task };
             }
             const value = valueAfter(queue, index, arg);
@@ -2402,6 +2423,21 @@ function parseRuntimeArgs(args, env) {
             flags.statusStaleSeconds = value;
             index += 1;
         }
+        else if (arg === "--stale-after") {
+            if (command !== "app-heartbeat" && command !== "app-loop-status" && command !== "app-wakeup-plan" && command !== "app-wakeup-dispatch") {
+                return { command, enabled, error: "Unsupported TypeScript runtime option: --stale-after", explicit, flags, task };
+            }
+            const parsedValue = valueAfter(queue, index, arg);
+            if (parsedValue.error) {
+                return { command, enabled, error: parsedValue.error, explicit, flags, task };
+            }
+            const value = Number(parsedValue.value);
+            if (!Number.isFinite(value) || value < 0) {
+                return { command, enabled, error: "--stale-after must be a non-negative number.", explicit, flags, task };
+            }
+            flags.appStaleAfterSeconds = value;
+            index += 1;
+        }
         else if (arg === "--terminal-stale-seconds") {
             if (command !== "idle-check") {
                 return { command, enabled, error: "Unsupported TypeScript runtime option: --terminal-stale-seconds", explicit, flags, task };
@@ -3347,6 +3383,233 @@ function runLoopStatusCommand(parsed, options) {
         database.close();
     }
 }
+function runAppHeartbeatCommand(parsed, options) {
+    const taskName = requireTask(parsed);
+    if (parsed.flags.role !== "manager" && parsed.flags.role !== "worker") {
+        return errorResult("app-heartbeat requires --role manager|worker");
+    }
+    const role = parsed.flags.role;
+    const database = openRuntimeDatabase(parsed, options);
+    try {
+        const task = taskRowForDiagnostics(database, taskName);
+        const session = boundAppSessionForRoleSync(database, { role, taskId: task.id });
+        const timestamp = nowIsoSeconds(options);
+        const dbPath = runtimeDbPath(parsed, options);
+        database.prepare("update sessions set last_heartbeat_at = ? where id = ?").run(timestamp, session.id);
+        emitTelemetrySync(database, {
+            actor: role,
+            attributes: {
+                direct_inbox_command: directInboxPollCommand(role, task.name, dbPath),
+                role,
+                session_id: session.id,
+                task: task.name,
+            },
+            correlation: { command: "app-heartbeat" },
+            eventType: "app_heartbeat",
+            severity: "info",
+            summary: `${role} app heartbeat for ${task.name}.`,
+            taskId: task.id,
+            timestamp,
+        });
+        const status = appLoopStatusSync(database, {
+            dbPath,
+            dispatcherId: parsed.flags.dispatcherId ?? "dispatch-local",
+            heartbeatStaleSeconds: parsed.flags.appStaleAfterSeconds,
+            now: timestamp,
+            taskName: task.name,
+        });
+        const roleStatus = role === "manager" ? status.manager : status.worker;
+        const output = {
+            heartbeat: {
+                recorded_at: timestamp,
+                state: "recorded",
+            },
+            next: {
+                direct_inbox_command: roleStatus.direct_inbox_command,
+                poll_command: roleStatus.poll_command,
+            },
+            role,
+            status,
+            task: { id: task.id, name: task.name },
+        };
+        if (parsed.flags.json) {
+            return jsonResult(output);
+        }
+        return {
+            exitCode: 0,
+            handled: true,
+            stdout: `${role} heartbeat recorded for ${task.name}\nNext: ${roleStatus.direct_inbox_command ?? roleStatus.poll_command ?? "(none)"}\n`,
+        };
+    }
+    finally {
+        database.close();
+    }
+}
+function runAppLoopStatusCommand(parsed, options) {
+    const taskName = requireTask(parsed);
+    const database = openRuntimeDatabase(parsed, options);
+    try {
+        const status = appLoopStatusSync(database, {
+            dbPath: runtimeDbPath(parsed, options),
+            dispatcherId: parsed.flags.dispatcherId ?? "dispatch-local",
+            heartbeatStaleSeconds: parsed.flags.appStaleAfterSeconds,
+            now: nowIsoSeconds(options),
+            taskName,
+        });
+        if (parsed.flags.json) {
+            return jsonResult(status);
+        }
+        return {
+            exitCode: 0,
+            handled: true,
+            stdout: renderAppLoopStatusText(status),
+        };
+    }
+    finally {
+        database.close();
+    }
+}
+function runAppWakeupPlanCommand(parsed, options) {
+    const taskName = requireTask(parsed);
+    const database = openRuntimeDatabase(parsed, options);
+    try {
+        const plan = appWakeupPlanSync(database, {
+            dbPath: runtimeDbPath(parsed, options),
+            dispatcherId: parsed.flags.dispatcherId ?? "dispatch-local",
+            heartbeatStaleSeconds: parsed.flags.appStaleAfterSeconds,
+            now: nowIsoSeconds(options),
+            taskName,
+        });
+        if (parsed.flags.json) {
+            return jsonResult(plan);
+        }
+        return {
+            exitCode: 0,
+            handled: true,
+            stdout: renderAppWakeupPlanText(plan),
+        };
+    }
+    finally {
+        database.close();
+    }
+}
+function runAppWakeupDispatchCommand(parsed, options) {
+    const taskName = requireTask(parsed);
+    const database = openRuntimeDatabase(parsed, options);
+    try {
+        const timestamp = nowIsoSeconds(options);
+        const dispatch = appWakeupDispatchPlanSync(database, {
+            dbPath: runtimeDbPath(parsed, options),
+            dispatcherId: parsed.flags.dispatcherId ?? "dispatch-local",
+            heartbeatStaleSeconds: parsed.flags.appStaleAfterSeconds,
+            now: timestamp,
+            taskName,
+        });
+        const eventId = emitTelemetrySync(database, {
+            actor: "manager",
+            attributes: {
+                actions: dispatch.actions.map((action) => ({
+                    blocker: action.blocker,
+                    reason: action.reason,
+                    role: action.role,
+                    send_ready: action.send_ready,
+                    status: action.status,
+                    thread_id: action.thread.id,
+                    thread_title: action.thread.title,
+                })),
+                dispatcher: dispatch.dispatcher,
+                status_ok: dispatch.status.ok,
+                summary: dispatch.summary,
+            },
+            correlation: {
+                command: "app-wakeup-dispatch",
+                dispatcher_id: dispatch.status.dispatch.dispatcher_id,
+            },
+            eventType: "app_wakeup_dispatch_planned",
+            severity: dispatch.summary.blocked > 0 || dispatch.dispatcher.required ? "warning" : "info",
+            summary: `App wakeup dispatch planned for ${dispatch.status.task.name}.`,
+            taskId: dispatch.status.task.id,
+            timestamp,
+        });
+        const output = {
+            ...dispatch,
+            receipt: {
+                event_id: eventId,
+                event_type: "app_wakeup_dispatch_planned",
+                recorded_at: timestamp,
+            },
+        };
+        if (parsed.flags.json) {
+            return jsonResult(output);
+        }
+        return {
+            exitCode: 0,
+            handled: true,
+            stdout: renderAppWakeupDispatchText(output),
+        };
+    }
+    finally {
+        database.close();
+    }
+}
+function renderAppLoopStatusText(status) {
+    const lines = [
+        `App loop ${status.task.name}: ${status.ok ? "ok" : "attention required"}`,
+        `Dispatch ${status.dispatch.dispatcher_id}: ${status.dispatch.state}`,
+        `Manager ${status.manager.name ?? "(missing)"}: ${status.manager.lease.state}`,
+        `Worker ${status.worker.name ?? "(missing)"}: ${status.worker.lease.state}`,
+    ];
+    for (const action of status.next_actions) {
+        lines.push(`Next: ${action.kind} - ${action.reason}`);
+    }
+    return `${lines.join("\n")}\n`;
+}
+function renderAppWakeupDispatchText(plan) {
+    const lines = [
+        `App wakeup dispatch for ${plan.status.task.name}: ${plan.status.ok ? "ok" : "attention required"}`,
+        `Dispatch: ${plan.dispatcher.state}${plan.dispatcher.required ? ` (${plan.dispatcher.command})` : ""}`,
+        `Receipt: ${plan.receipt.event_type} ${plan.receipt.event_id}`,
+    ];
+    for (const action of plan.actions) {
+        lines.push(`${action.role}: ${action.status} - ${action.reason}`);
+        if (action.blocker) {
+            lines.push(`Blocker: ${action.blocker}`);
+        }
+        if (action.send_ready && action.thread.id) {
+            lines.push(`Thread: ${action.thread.title ?? "(untitled)"} ${action.thread.id}`);
+        }
+        if (action.prompt) {
+            lines.push(action.prompt);
+        }
+    }
+    return `${lines.join("\n")}\n`;
+}
+function renderAppWakeupPlanText(plan) {
+    const lines = [
+        `App wakeup plan for ${plan.status.task.name}: ${plan.status.ok ? "ok" : "attention required"}`,
+        `Dispatch: ${plan.dispatcher.state}${plan.dispatcher.required ? ` (${plan.dispatcher.command})` : ""}`,
+    ];
+    for (const wakeup of plan.wakeups) {
+        lines.push(`Wake ${wakeup.role}${wakeup.thread.title ? ` (${wakeup.thread.title})` : ""}: ${wakeup.reason}`);
+        lines.push(wakeup.prompt);
+    }
+    return `${lines.join("\n")}\n`;
+}
+function boundAppSessionForRoleSync(database, options) {
+    const sessionJoin = options.role === "manager" ? "manager_session_id" : "worker_session_id";
+    const row = database.prepare(`
+    select s.id, s.name
+    from bindings b
+    join sessions s on s.id = b.${sessionJoin}
+    where b.task_id = ? and b.state in ('active', 'ending') and s.role = ? and s.state = 'active'
+    order by b.created_at desc
+    limit 1
+  `).get(options.taskId, options.role);
+    if (!row) {
+        throw new Error(`No active bound ${options.role} session for task.`);
+    }
+    return row;
+}
 function runQaPlanCommand(parsed) {
     const unsupported = unsupportedLoopCommandOptions(parsed, {
         allowedFlags: new Set(["json", "subtype"]),
@@ -13623,6 +13886,10 @@ function isDefaultRuntimeCommand(command) {
         || command === "runs"
         || command === "loop-evidence"
         || command === "loop-status"
+        || command === "app-heartbeat"
+        || command === "app-loop-status"
+        || command === "app-wakeup-plan"
+        || command === "app-wakeup-dispatch"
         || command === "loop-templates"
         || command === "loop-triggers"
         || command === "ralph-loop-presets"
@@ -16636,6 +16903,8 @@ function renderDisposableBindingText(result) {
         lines.push(`  interval: every ${result.heartbeat_recommendations.interval_minutes} minutes`);
         lines.push(`  manager: ${result.heartbeat_recommendations.manager.poll_command}`);
         lines.push(`  worker: ${result.heartbeat_recommendations.worker.poll_command}`);
+        lines.push(`  status: ${result.heartbeat_recommendations.status_command}`);
+        lines.push(`  wakeup plan: ${result.heartbeat_recommendations.wakeup_plan_command}`);
         lines.push(`  teardown: ${result.heartbeat_recommendations.teardown_policy.idle_poll}`);
         lines.push(`  closeout: ${result.heartbeat_recommendations.teardown_policy.terminal_closeout_command}`);
     }
@@ -16645,6 +16914,10 @@ function renderDisposableBindingText(result) {
 }
 function disposableHeartbeatRecommendations(taskName, dbPath) {
     const terminalCloseoutCommand = `${conveyorPollInvocation()} finish-task ${shellQuote(taskName)} --reason ${shellQuote("Verified terminal closeout")} --require-criteria-audit --path ${shellQuote(dbPath)}`;
+    const managerHeartbeatCommand = disposableAppHeartbeatCommand("manager", taskName, dbPath);
+    const workerHeartbeatCommand = disposableAppHeartbeatCommand("worker", taskName, dbPath);
+    const managerInboxCommand = sessionPollCommand("manager", taskName, dbPath);
+    const workerInboxCommand = sessionPollCommand("worker", taskName, dbPath);
     return {
         applies_when: {
             can_receive_push: false,
@@ -16654,6 +16927,7 @@ function disposableHeartbeatRecommendations(taskName, dbPath) {
         },
         interval_minutes: 2,
         note: "Dispatch can deliver pull-required inbox items, but Codex app/no-tmux sessions still need a heartbeat or operator wake-up to poll while idle.",
+        status_command: `${conveyorPollInvocation()} app-loop-status ${shellQuote(taskName)} --path ${shellQuote(dbPath)} --json`,
         teardown_policy: {
             idle_poll: "Never delete, pause, or disable a manager or worker heartbeat because an inbox poll returned no item; that is only a quiet poll interval.",
             owner: "manager_or_operator",
@@ -16661,13 +16935,16 @@ function disposableHeartbeatRecommendations(taskName, dbPath) {
             terminal_closeout_command: terminalCloseoutCommand,
             worker_rule: "The worker must not own loop teardown and must not remove heartbeat automation based on idle polling.",
         },
+        wakeup_plan_command: `${conveyorPollInvocation()} app-wakeup-plan ${shellQuote(taskName)} --path ${shellQuote(dbPath)} --json`,
         manager: {
+            direct_inbox_command: managerInboxCommand,
             kind: "thread_heartbeat",
-            poll_command: sessionPollCommand("manager", taskName, dbPath),
+            poll_command: managerHeartbeatCommand,
             prompt: [
                 "Use the manage-codex-workers skill.",
-                `Poll the manager inbox for task ${taskName}.`,
-                `Run: ${sessionPollCommand("manager", taskName, dbPath)}`,
+                `Run the manager app heartbeat for task ${taskName}.`,
+                `Run: ${managerHeartbeatCommand}`,
+                `If the heartbeat output asks for direct inbox polling, run: ${managerInboxCommand}`,
                 "If an item is consumed, execute only that manager instruction, verify worker claims before recording conclusions, update Conveyor state as appropriate, and produce exactly one next worker task.",
                 "If no item is consumed, stop after a one-line idle receipt.",
                 "Do not delete, pause, or disable manager or worker heartbeat automation after an idle poll; an idle poll is only a quiet interval.",
@@ -16676,12 +16953,14 @@ function disposableHeartbeatRecommendations(taskName, dbPath) {
             ].join("\n"),
         },
         worker: {
+            direct_inbox_command: workerInboxCommand,
             kind: "thread_heartbeat",
-            poll_command: sessionPollCommand("worker", taskName, dbPath),
+            poll_command: workerHeartbeatCommand,
             prompt: [
                 "Use the manage-codex-workers skill.",
-                `Poll the worker inbox for task ${taskName}.`,
-                `Run: ${sessionPollCommand("worker", taskName, dbPath)}`,
+                `Run the worker app heartbeat for task ${taskName}.`,
+                `Run: ${workerHeartbeatCommand}`,
+                `If the heartbeat output asks for direct inbox polling, run: ${workerInboxCommand}`,
                 "If an item is consumed, execute only that single worker instruction and return exact commands, compact evidence, blockers/residual risk, and exactly one next recommended worker task.",
                 "If no item is consumed, stop after a one-line idle receipt.",
                 "Do not delete, pause, or disable worker heartbeat automation after an idle poll; the manager or operator owns terminal loop teardown.",
@@ -16689,6 +16968,9 @@ function disposableHeartbeatRecommendations(taskName, dbPath) {
         },
     };
 }
+function disposableAppHeartbeatCommand(role, taskName, dbPath) {
+    return `${conveyorPollInvocation()} app-heartbeat ${shellQuote(taskName)} --role ${role} --path ${shellQuote(dbPath)} --json`;
+}
 function sessionPollCommand(role, taskName, dbPath) {
     const inbox = role === "worker" ? "worker-inbox" : "manager-inbox";
     const task = taskName ? shellQuote(taskName) : "<task>";
@@ -16944,6 +17226,7 @@ function emitTelemetrySync(database, options) {
     )
     values (?, ?, ?, ?, ?, ?, ?)
   `).run(eventId, options.taskId ?? null, options.runId ?? null, options.actor, options.eventType, options.summary, attributesJson);
+    return eventId;
 }
 function latestCodexEventsForSession(database, options) {
     const clauses = ["session_id = ?"];