agent-conveyor 0.1.20 → 0.1.22

package/README.md

@@ -168,8 +168,9 @@ conveyor plugin-status
 
 The per-project default ledger for operator sessions is
 `.codex-workers/workerctl.db`. The initial included skills are
-`conveyor-create-pair`, `conveyor-create-worker-set`, and
-`conveyor-check-status`.
+`conveyor-app-wake-relay`, `conveyor-create-pair`,
+`conveyor-create-worker-set`, `conveyor-check-status`, and
+`conveyor-whats-next-nudger`.
 
 After install, the intended Codex app entry point is natural language. Open a
 new Codex app session in the target repo and say:
@@ -204,6 +205,15 @@ print `CONVEYOR POLL`, `CONVEYOR RECEIVED`, `WORK`, `CONVEYOR SEND`, and
 audit proof, not a replacement for the live session story. Idle polls may be a
 single `CONVEYOR IDLE` line.
 
+For bounded follow-up passes after the first worker result, use
+`Use the conveyor-whats-next-nudger skill`.
+
+For stale Codex app roles, use `Use the conveyor-app-wake-relay skill`. It
+runs `app-wakeup-dispatch`, sends only prepared `send_ready=true` prompts with
+Codex app thread tools, and records `sent`, `skipped`, or `blocked` delivery
+receipts with `app-wakeup-record-delivery`. The app-thread prompt wakes the
+session to poll; it is not durable task truth.
+
 Dispatch is core infrastructure for supervised worker/manager pairs. The
 `pair` workflow starts a detached Dispatch watch process by default so worker
 completion is routed to the bound manager mechanically. For manually bound
@@ -512,7 +522,8 @@ stay out of receipts.
   [--json]` — Record what the Codex app/operator layer did with a wake action.
   `sent` is accepted only when the referenced `app-wakeup-dispatch` receipt has
   a matching `ready_to_send` action with `send_ready=true` and the same thread
-  id; healthy and blocked roles must be recorded as `skipped` or `blocked`.
+  id; healthy roles must be recorded as `skipped`; missing-thread blockers and
+  failed app-thread sends must be recorded as `blocked` with a reason.
 - `app-autopilot start|stop|status TASK [--dispatcher-id ID]
   [--interval SECONDS] [--watch-iterations N] [--stale-after N]
   [--quiet-after N] [--json]` —
@@ -804,6 +815,15 @@ stay out of receipts.
 - `worker-inbox <task> [--consume-next] [--wait] [--timeout N] [--interval N]
   [--limit N] [--json]` — Resolve the task's bound worker session and read its
   dispatcher inbox.
+- `inbox-ack <task> --notification-id N [--json]` — Read durable
+  role-authored acknowledgement history for one routed notification.
+- `inbox-ack <task> --notification-id N --role manager|worker
+  --status received|accepted|blocked --from-stdin [--correlation-id C]
+  [--json]` — Record that the addressed role saw a delivered notification and
+  either received, accepted, or blocked on it. `received` requires delivery;
+  `accepted` and `blocked` require consumption. Use this after visible Codex app
+  sessions print `CONVEYOR RECEIVED`; do not use direct app-thread text as the
+  durable receipt.
 
 ### Actuation
 

package/dist/cli/typescript-runtime.js

@@ -18,7 +18,7 @@ import { executeDispatchCommandSync } from "../runtime/dispatch.js";
 import { deregisterSessionSync, discoverRegistrySync, findRolloutPathForPid, listRegisteredSessionsSync, registerSessionSync, readSessionMeta, sessionRow, } from "../runtime/codex-session.js";
 import { managerConfigPermissionAllowed, managerConfigSync } from "../runtime/manager-config.js";
 import { canonicalManagerPermissionNames, flattenManagerPermissions, normalizeManagerPermissions, } from "../runtime/manager-permissions.js";
-import { deferRoutedNotificationBeforeSideEffectSync, deliveryModeForTargetSessionSync, finishRoutedNotificationSync, insertRoutedNotificationSync, markRoutedNotificationSideEffectStartedSync, consumeNextSessionInboxItemSync, routedNotificationsSync, sessionInboxSync, } from "../runtime/notifications.js";
+import { deferRoutedNotificationBeforeSideEffectSync, deliveryModeForTargetSessionSync, finishRoutedNotificationSync, insertRoutedNotificationSync, insertNotificationAcknowledgementSync, latestNotificationAcknowledgementSync, markRoutedNotificationSideEffectStartedSync, notificationAcknowledgementsSync, consumeNextSessionInboxItemSync, routedNotificationsSync, sessionInboxSync, } from "../runtime/notifications.js";
 import { activeBindingForTaskSync, bindSessionsSync, createTaskSync, listTasksSync, unbindTaskSync, } from "../runtime/tasks.js";
 import { captureTmuxTargetWithRunner, captureTranscriptTmuxTargetWithRunner, currentPaneIdWithRunner, killTmuxSessionWithRunner, sendEnterToTmuxSessionWithRunner, sendTextToSessionWithRunner, sessionExists, startTmuxSessionWithRunner, tmuxCommandFailureMessage, tmuxSession, tmuxSessionRunning, } from "../runtime/tmux.js";
 import { captureMetaPath, configPath, defaultDbPath, eventsPath, loadJsonSync, stateRoot, statusPath, transcriptPath, validateWorkerName, workerDir, writeJsonSync, } from "../state/files.js";
@@ -261,6 +261,9 @@ export function runTypescriptRuntimeCommand(options) {
         if (parsed.command === "manager-ack") {
             return runTaskAckCommand(parsed, options, "manager");
         }
+        if (parsed.command === "inbox-ack") {
+            return runInboxAckCommand(parsed, options);
+        }
         if (parsed.command === "session-inbox") {
             return runSessionInboxCommand(parsed, options, "session");
         }
@@ -420,6 +423,15 @@ function commandHelpText(program, command) {
             "Example JSON:",
             `  {"task":"my-task","manager_session":"mgr","supervision_contract":"I will supervise through Conveyor and verify criteria before finishing.","will_not_edit_project_files":true}`,
         ],
+        "inbox-ack": [
+            `usage: ${program} inbox-ack <task> --notification-id N --role manager|worker --status received|accepted|blocked --from-stdin ${path} [--json]`,
+            `usage: ${program} inbox-ack <task> --notification-id N --json ${path}`,
+            "",
+            "Record or read a notification-scoped manager/worker acknowledgement.",
+            "",
+            "Example JSON:",
+            `  {"summary":"Received manager instruction and will run the bounded task.","evidence":[]}`,
+        ],
         nudge: [
             `usage: ${program} nudge <worker-or-session> <message> ${path} [--dry-run]`,
             `usage: ${program} session-nudge <session> <message> ${path} [--dry-run]`,
@@ -584,6 +596,7 @@ function parseRuntimeArgs(args, env) {
         nextAction: null,
         noFollowup: false,
         nextSteps: [],
+        notificationId: null,
         output: null,
         path: null,
         pid: null,
@@ -1502,7 +1515,7 @@ function parseRuntimeArgs(args, env) {
             index += 1;
         }
         else if (arg === "--from-stdin") {
-            if (command !== "criteria-plan" && command !== "continuation" && command !== "worker-ack" && command !== "manager-ack") {
+            if (command !== "criteria-plan" && command !== "continuation" && command !== "worker-ack" && command !== "manager-ack" && command !== "inbox-ack") {
                 return { command, enabled, error: "Unsupported TypeScript runtime option: --from-stdin", explicit, flags, task };
             }
             flags.fromStdin = true;
@@ -2373,7 +2386,7 @@ function parseRuntimeArgs(args, env) {
                 flags.epilogueStatus = true;
                 continue;
             }
-            if (command !== "criteria" && command !== "runs" && command !== "loop-evidence" && command !== "campaign") {
+            if (command !== "criteria" && command !== "runs" && command !== "loop-evidence" && command !== "campaign" && command !== "inbox-ack") {
                 return { command, enabled, error: "Unsupported TypeScript runtime option: --status", explicit, flags, task };
             }
             const parsedValue = valueAfter(queue, index, arg);
@@ -2383,11 +2396,29 @@ function parseRuntimeArgs(args, env) {
             if (command === "criteria") {
                 flags.statuses.push(parsedValue.value);
             }
+            else if (command === "inbox-ack") {
+                flags.statusState = parsedValue.value;
+            }
             else {
                 flags.statusState = parsedValue.value;
             }
             index += 1;
         }
+        else if (arg === "--notification-id") {
+            if (command !== "inbox-ack") {
+                return { command, enabled, error: "Unsupported TypeScript runtime option: --notification-id", 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.isInteger(value) || value <= 0) {
+                return { command, enabled, error: "--notification-id must be a positive integer.", explicit, flags, task };
+            }
+            flags.notificationId = value;
+            index += 1;
+        }
         else if (arg === "--type") {
             const value = valueAfter(queue, index, arg);
             if (value.error) {
@@ -2537,6 +2568,7 @@ function parseRuntimeArgs(args, env) {
                 && command !== "enqueue-continue-iteration"
                 && command !== "worker-ack"
                 && command !== "manager-ack"
+                && command !== "inbox-ack"
                 && command !== "loop-evidence"
                 && command !== "continuation"
                 && command !== "continuation-reviewer"
@@ -3863,7 +3895,7 @@ function runAppWakeupRecordDeliveryCommand(parsed, options) {
         if (!action) {
             throw new Error(`Receipt ${source.id} has no ${role} wake action.`);
         }
-        validateAppWakeupDelivery({ action, deliveryStatus, role, threadId: parsed.flags.threadId });
+        validateAppWakeupDelivery({ action, deliveryStatus, reason: parsed.flags.reason, role, threadId: parsed.flags.threadId });
         const timestamp = nowIsoSeconds(options);
         const eventId = emitTelemetrySync(database, {
             actor: "manager",
@@ -4383,9 +4415,16 @@ function validateAppWakeupDelivery(options) {
         }
         return;
     }
-    if (sourceStatus !== "blocked_missing_thread") {
-        throw new Error(`Cannot record blocked wakeup for ${options.role}; source action is ${sourceStatus}.`);
+    if (sourceStatus === "blocked_missing_thread") {
+        return;
+    }
+    if (sourceStatus === "ready_to_send" && options.action.send_ready === true) {
+        if (!options.reason?.trim()) {
+            throw new Error(`Cannot record blocked wakeup for ${options.role}; ready-to-send source actions require --reason.`);
+        }
+        return;
     }
+    throw new Error(`Cannot record blocked wakeup for ${options.role}; source action is ${sourceStatus}.`);
 }
 function parseAppWakeupSourceActionStatus(value) {
     if (value === "ready_to_send" || value === "skipped_healthy" || value === "blocked_missing_thread") {
@@ -6697,7 +6736,13 @@ function runInstallSkillsCommand(parsed, options) {
     return { exitCode: 0, handled: true, stdout: `${lines.join("\n")}\n` };
 }
 const AGENT_CONVEYOR_PLUGIN_NAME = "agent-conveyor";
-const AGENT_CONVEYOR_PLUGIN_SKILLS = ["conveyor-create-pair", "conveyor-create-worker-set", "conveyor-check-status"];
+const AGENT_CONVEYOR_PLUGIN_SKILLS = [
+    "conveyor-app-wake-relay",
+    "conveyor-create-pair",
+    "conveyor-create-worker-set",
+    "conveyor-check-status",
+    "conveyor-whats-next-nudger",
+];
 function resolveCodexHome(parsed, options) {
     return resolve(expandUserPath(parsed.flags.codexHome ?? options.env?.CODEX_HOME ?? join(homedir(), ".codex")));
 }
@@ -9087,6 +9132,94 @@ function runTaskAckCommand(parsed, options, role) {
         database.close();
     }
 }
+function runInboxAckCommand(parsed, options) {
+    const unsupported = unsupportedInboxAckOptions(parsed);
+    if (unsupported) {
+        return unsupportedRuntimeResult(parsed, unsupported);
+    }
+    const taskName = requireTask(parsed);
+    const notificationId = parsed.flags.notificationId;
+    if (notificationId === null) {
+        return errorResult("inbox-ack requires --notification-id.");
+    }
+    const database = openRuntimeDatabase(parsed, options);
+    try {
+        const task = taskRowForLifecycle(database, taskName);
+        if (task === null) {
+            throw new Error(`Unknown task: ${taskName}`);
+        }
+        const binding = activeBindingForTaskSync(database, task.name);
+        const notification = notificationForInboxAckSync(database, {
+            notificationId,
+            taskId: task.id,
+            taskName: task.name,
+        });
+        if (notification.binding_id !== binding.binding_id) {
+            throw new Error(`Notification ${notificationId} does not belong to the active binding for task ${task.name}.`);
+        }
+        if (!parsed.flags.fromStdin) {
+            const acknowledgements = notificationAcknowledgementsSync(database, { notificationId, taskId: task.id });
+            return jsonResult({
+                acknowledgements,
+                latest: latestNotificationAcknowledgementSync(database, { notificationId, taskId: task.id }),
+                notification: inboxAckNotificationPayload(notification),
+                task: { id: task.id, name: task.name },
+            });
+        }
+        const role = parsed.flags.role;
+        const status = parseNotificationAcknowledgementStatus(parsed.flags.statusState);
+        if (status instanceof Error) {
+            return errorResult(status.message);
+        }
+        validateInboxAcknowledgement({ notification, role, status });
+        const payload = parseStdinJsonObject(options.stdin);
+        const ack = insertNotificationAcknowledgementSync(database, {
+            bindingId: notification.binding_id,
+            correlationId: parsed.flags.correlationId,
+            notificationId,
+            now: nowIsoSeconds(options),
+            payload,
+            role,
+            status,
+            taskId: task.id,
+        });
+        const eventId = emitTelemetrySync(database, {
+            actor: role,
+            attributes: {
+                binding_id: notification.binding_id,
+                notification_id: notificationId,
+                payload_keys: Object.keys(payload).sort(),
+                role,
+                signal_type: notification.signal_type,
+                status,
+            },
+            correlation: {
+                command: "inbox-ack",
+                correlation_id: parsed.flags.correlationId,
+                notification_id: notificationId,
+                role,
+            },
+            eventType: "dispatch_inbox_ack_recorded",
+            severity: status === "blocked" ? "warning" : "info",
+            summary: `${role} recorded ${status} acknowledgement for notification ${notificationId}.`,
+            taskId: task.id,
+            timestamp: ack.created_at,
+        });
+        return jsonResult({
+            acknowledgement: ack,
+            notification: inboxAckNotificationPayload(notification),
+            receipt: {
+                event_id: eventId,
+                event_type: "dispatch_inbox_ack_recorded",
+                recorded_at: ack.created_at,
+            },
+            task: { id: task.id, name: task.name },
+        });
+    }
+    finally {
+        database.close();
+    }
+}
 function runSessionInboxCommand(parsed, options, kind) {
     const unsupported = unsupportedSessionInboxOptions(parsed, kind);
     if (unsupported) {
@@ -9336,6 +9469,59 @@ function latestTaskAcknowledgementSync(database, options) {
         task_id: row.task_id,
     };
 }
+function notificationForInboxAckSync(database, options) {
+    const row = database.prepare(`
+    select rn.id, rn.task_id, rn.binding_id, rn.signal_type, rn.delivered_at,
+           rn.consumed_at, rn.delivery_mode, rn.state, rn.target_session_id,
+           ts.name as target_session_name, ts.role as target_session_role
+    from routed_notifications rn
+    join sessions ts on ts.id = rn.target_session_id
+    where rn.id = ? and rn.task_id = ?
+    limit 1
+  `).get(options.notificationId, options.taskId);
+    if (!row) {
+        throw new Error(`Unknown routed notification for task ${options.taskName}: ${options.notificationId}`);
+    }
+    return row;
+}
+function inboxAckNotificationPayload(notification) {
+    return {
+        binding_id: notification.binding_id,
+        consumed_at: notification.consumed_at,
+        delivered_at: notification.delivered_at,
+        delivery_mode: notification.delivery_mode,
+        id: notification.id,
+        signal_type: notification.signal_type,
+        state: notification.state,
+        target_session_id: notification.target_session_id,
+        target_session_name: notification.target_session_name,
+        target_session_role: notification.target_session_role,
+        task_id: notification.task_id,
+    };
+}
+function parseNotificationAcknowledgementStatus(value) {
+    if (value === "received" || value === "accepted" || value === "blocked") {
+        return value;
+    }
+    return new Error("inbox-ack --status must be received, accepted, or blocked.");
+}
+function validateInboxAcknowledgement(options) {
+    if (options.notification.target_session_role !== options.role) {
+        throw new Error(`Cannot record ${options.role} acknowledgement for notification ${options.notification.id}; target role is ${options.notification.target_session_role}.`);
+    }
+    if (options.notification.state !== "delivered") {
+        throw new Error(`Cannot acknowledge notification ${options.notification.id}; state is ${options.notification.state}, expected delivered.`);
+    }
+    if (options.status === "received") {
+        if (!options.notification.delivered_at) {
+            throw new Error(`Cannot record received acknowledgement for notification ${options.notification.id}; it has no delivered_at receipt.`);
+        }
+        return;
+    }
+    if (!options.notification.consumed_at) {
+        throw new Error(`Cannot record ${options.status} acknowledgement for notification ${options.notification.id}; it has not been consumed by the target session.`);
+    }
+}
 function sessionInboxResponse(database, options) {
     if (options.timeoutSeconds < 0) {
         throw new Error("--timeout must be non-negative");
@@ -15201,6 +15387,26 @@ function unsupportedTaskAckOptions(parsed) {
     }
     return null;
 }
+function unsupportedInboxAckOptions(parsed) {
+    if (!parsed.task) {
+        return "inbox-ack requires a task.";
+    }
+    if (parsed.flags.notificationId === null) {
+        return "inbox-ack requires --notification-id.";
+    }
+    if (!parsed.flags.fromStdin && !parsed.flags.json) {
+        return "inbox-ack requires --from-stdin to write or --json to read.";
+    }
+    if (parsed.flags.fromStdin) {
+        if (parsed.flags.role !== "manager" && parsed.flags.role !== "worker") {
+            return "inbox-ack write requires --role manager|worker.";
+        }
+        if (parsed.flags.statusState === null) {
+            return "inbox-ack write requires --status received|accepted|blocked.";
+        }
+    }
+    return null;
+}
 function unsupportedSessionInboxOptions(parsed, kind) {
     if (!parsed.task) {
         return kind === "session" ? "session-inbox requires a session name." : `${kind}-inbox requires a task.`;
@@ -15718,6 +15924,7 @@ function isDefaultRuntimeCommand(command) {
         || command === "nudge"
         || command === "worker-ack"
         || command === "manager-ack"
+        || command === "inbox-ack"
         || command === "session-inbox"
         || command === "manager-inbox"
         || command === "worker-inbox"