@yemi33/minions 0.1.2124 → 0.1.2125

package/dashboard.js

@@ -11477,7 +11477,7 @@ What would you like to discuss or change? When you're happy, say "approve" and I
       invalidateStatusCache();
       return jsonReply(res, 200, { ok: true });
     }},
-    { method: 'POST', path: '/api/agents/steer', desc: 'Inject steering message into a running agent', params: 'agent, message', handler: async (req, res) => {
+    { method: 'POST', path: '/api/agents/steer', desc: 'Inject steering message into a running agent', params: 'agent, message, supersede? (all|unacked|<steerId>), scope? (agent|current-dispatch)', handler: async (req, res) => {
       const body = await readBody(req);
       const { agent, message } = body;
       if (!agent || !message) return jsonReply(res, 400, { error: 'agent and message required' });
@@ -11491,7 +11491,54 @@ What would you like to discuss or change? When you're happy, say "approve" and I
         return jsonReply(res, 409, { error: 'Agent session is finishing; retry when the next session starts' });
       }
 
-      const entry = steering.writeSteeringMessage(agentId, text);
+      // W-mq066js7000fff1f-e (Gap E) — supersede prior messages before
+      // writing the new one. Accept 'all', 'unacked', or a specific
+      // steerId. Bad shapes are silently ignored (best-effort).
+      const supersede = body.supersede ? String(body.supersede).trim() : '';
+      let superseded = [];
+      if (supersede) {
+        const provisionalSteerId = `steer-pending-${Date.now()}`;
+        superseded = steering.supersedeMessages(agentId, supersede, { reason: `superseded by new steer (${supersede})`, newSteerId: provisionalSteerId });
+      }
+
+      // W-mq066js7000fff1f-e — dedupe: if no supersede arg AND an
+      // identical body is already pending within the 5-min window, echo
+      // back the existing steerId instead of writing a duplicate file.
+      if (!supersede) {
+        const dup = steering.findRecentDuplicate(agentId, text);
+        if (dup) {
+          const delivery = _steeringDeliveryState(agentId);
+          return jsonReply(res, 200, {
+            ok: true,
+            deduplicated: true,
+            steerId: dup.steerId,
+            status: dup.status || steering.STATUS.QUEUED,
+            file: dup.file,
+            // Gap D observability URL — points at the SQL delivery-state row
+            // for /api/steering/:id (back-compat with master's contract).
+            deliveryUrl: dup.steerId ? `/api/steering/${dup.steerId}` : null,
+            message: 'Identical steering message already pending — returning existing entry',
+            ...delivery,
+            inboxCount: steering.listUnreadSteeringMessages(agentId).length,
+          });
+        }
+      }
+
+      // W-mq066js7000fff1f-f (Gap F) — per-dispatch scoping. With
+      // scope='current-dispatch' we stamp the active dispatch id so the
+      // engine filters this entry out of any future unrelated dispatch's
+      // resume prompt. With scope='agent' (default) the message is
+      // agent-wide and picks up on the next dispatch regardless of id.
+      const scope = body.scope ? String(body.scope).trim().toLowerCase() : 'agent';
+      let targetDispatchId = null;
+      let scopeApplied = scope;
+      if (scope === 'current-dispatch') {
+        const active = (getDispatchQueue().active || []).find(d => d.agent === agentId);
+        if (active?.id) targetDispatchId = String(active.id);
+        else scopeApplied = 'agent'; // no active dispatch → fall back
+      }
+
+      const entry = steering.writeSteeringMessage(agentId, text, { targetDispatchId });
       const delivery = _steeringDeliveryState(agentId);
 
       // Also append to live-output.log so it shows in the chat view
@@ -11506,12 +11553,16 @@ What would you like to discuss or change? When you're happy, say "approve" and I
       const steerId = entry?.steerId || null;
       return jsonReply(res, 200, {
         ok: true,
+        deduplicated: false,
+        steerId,
+        status: entry?.status || (steerId ? steering.STATUS.QUEUED : null),
+        targetDispatchId: entry?.targetDispatchId || null,
+        scope: scopeApplied,
+        superseded: superseded.map(s => ({ steerId: s.steerId, previousStatus: s.previousStatus })),
         message: delivery.pendingDelivery ? 'Steering message pending delivery' : 'Steering message queued',
         ...delivery,
         file: entry?.file || null,
         inboxCount: steering.listUnreadSteeringMessages(agentId).length,
-        steerId,
-        status: steerId ? 'queued' : null,
         deliveryUrl: steerId ? `/api/steering/${steerId}` : null,
       });
     }},

package/engine/steering.js

@@ -19,6 +19,43 @@ function _generateSteerId() {
   return `steer-${crypto.randomBytes(8).toString('hex').slice(0, 10)}`;
 }
 
+// W-mq066js7000fff1f-e (Gap E): identical-text dedupe window. POST
+// /api/agents/steer collapses identical bodies within this window to
+// the existing steerId instead of writing a duplicate inbox file.
+const DEDUPE_WINDOW_MS = 5 * 60 * 1000;
+
+// W-mq066js7000fff1f-e/f: status enum for the inbox frontmatter +
+// supersede operations. Mirrors the steering_deliveries observability
+// table (Gap D) so callers can speak the same vocabulary regardless
+// of which storage backend is live.
+const STATUS = Object.freeze({
+  QUEUED: 'queued',
+  LIVE_KILL: 'live_kill',
+  DEFERRED: 'deferred',
+  RE_SPAWNING: 're_spawning',
+  DELIVERED: 'delivered',
+  ACKNOWLEDGED: 'acknowledged',
+  STRANDED: 'stranded',
+  DROPPED: 'dropped',
+});
+
+const UNACKED_STATUSES = new Set([
+  STATUS.QUEUED,
+  STATUS.LIVE_KILL,
+  STATUS.DEFERRED,
+  STATUS.RE_SPAWNING,
+  STATUS.STRANDED,
+]);
+
+// Statuses that should still appear as "live" in the dedupe lookup.
+const DEDUPE_CANDIDATE_STATUSES = new Set([
+  STATUS.QUEUED,
+  STATUS.LIVE_KILL,
+  STATUS.DEFERRED,
+  STATUS.RE_SPAWNING,
+  STATUS.DELIVERED,
+]);
+
 function agentInboxDir(agentId) {
   return path.join(AGENTS_DIR, agentId, 'inbox');
 }
@@ -73,15 +110,22 @@ function _readEntry(filePath, legacy = false) {
     ? fmCreatedAtMs
     : _createdAtFromPath(filePath, stat);
   const steerId = _frontmatterValue(raw, 'steerId') || null;
+  const status = _frontmatterValue(raw, 'status') || STATUS.QUEUED;
+  const targetDispatchId = _frontmatterValue(raw, 'targetDispatchId') || null;
+  const lastError = _frontmatterValue(raw, 'lastError') || null;
+  const source = _frontmatterValue(raw, 'source') || 'human';
   return {
     path: filePath,
     file: path.basename(filePath),
     createdAtMs,
     createdAt: new Date(createdAtMs).toISOString(),
-    steerId,
     raw,
     message: _messageFromRaw(raw),
     steerId,
+    status,
+    targetDispatchId,
+    lastError,
+    source,
     legacy,
   };
 }
@@ -94,10 +138,6 @@ function _uniqueSteeringPath(inboxDir, createdAtMs) {
   return filePath;
 }
 
-function _generateSteerId() {
-  return crypto.randomBytes(6).toString('hex');
-}
-
 // Contract block describing the ACK-file protocol. Injected into the prompt
 // alongside any pending steering messages so the agent knows how to confirm
 // it has read+addressed a labeled message. Mirrored verbatim into
@@ -111,9 +151,24 @@ function ackContractBlock() {
   ].join('\n');
 }
 
+function _renderFrontmatter(data) {
+  const createdAtMs = Number(data.createdAtMs) || Date.now();
+  const lines = [
+    '---',
+    `createdAt: ${new Date(createdAtMs).toISOString()}`,
+    `createdAtMs: ${createdAtMs}`,
+    `source: ${data.source || 'human'}`,
+    `steerId: ${data.steerId}`,
+    `status: ${data.status || STATUS.QUEUED}`,
+  ];
+  if (data.targetDispatchId) lines.push(`targetDispatchId: ${data.targetDispatchId}`);
+  if (data.lastError) lines.push(`lastError: ${String(data.lastError).replace(/[\r\n]+/g, ' ').trim()}`);
+  lines.push('---', '', String(data.message || '').trim(), '');
+  return lines.join('\n');
+}
+
 function writeSteeringMessage(agentId, message, opts = {}) {
   const createdAtMs = Number(opts.createdAtMs) || Date.now();
-  const createdAt = new Date(createdAtMs).toISOString();
   const inboxDir = agentInboxDir(agentId);
   fs.mkdirSync(inboxDir, { recursive: true });
   const filePath = _uniqueSteeringPath(inboxDir, createdAtMs);
@@ -134,17 +189,15 @@ function writeSteeringMessage(agentId, message, opts = {}) {
       steerId,
     }));
   }
-  const body = [
-    '---',
-    `createdAt: ${createdAt}`,
-    `createdAtMs: ${createdAtMs}`,
-    `source: ${source}`,
-    `steerId: ${steerId}`,
-    '---',
-    '',
-    bodyText,
-    '',
-  ].join('\n');
+  const body = _renderFrontmatter({
+    createdAtMs,
+    source,
+    steerId,
+    status: opts.status || STATUS.QUEUED,
+    targetDispatchId: opts.targetDispatchId || null,
+    lastError: opts.lastError || null,
+    message: bodyText,
+  });
   shared.safeWrite(filePath, body);
 
   // W-mq066js7000fff1f-a (Gap D): insert a 'queued' row into the
@@ -169,7 +222,22 @@ function writeSteeringMessage(agentId, message, opts = {}) {
   return _readEntry(filePath);
 }
 
-function listUnreadSteeringMessages(agentId, opts = {}) {
+function _updateEntryStatus(entry, newStatus, opts = {}) {
+  if (!entry?.path) return null;
+  const body = _renderFrontmatter({
+    createdAtMs: entry.createdAtMs,
+    source: entry.source || 'human',
+    steerId: entry.steerId,
+    status: newStatus,
+    targetDispatchId: entry.targetDispatchId,
+    lastError: opts.lastError !== undefined ? opts.lastError : entry.lastError,
+    message: entry.message,
+  });
+  shared.safeWrite(entry.path, body);
+  return _readEntry(entry.path);
+}
+
+function listAllSteeringEntries(agentId, opts = {}) {
   const includeLegacy = opts.includeLegacy !== false;
   const entries = [];
   const inboxDir = agentInboxDir(agentId);
@@ -189,8 +257,40 @@ function listUnreadSteeringMessages(agentId, opts = {}) {
   return entries;
 }
 
-function buildPendingSteeringPrompt(agentId) {
-  const entries = listUnreadSteeringMessages(agentId).filter(entry => entry.message.trim());
+function listUnreadSteeringMessages(agentId, opts = {}) {
+  // Back-compat shape: "unread" = anything still pending agent attention
+  // (queued/live_kill/deferred/re_spawning/delivered/stranded). Explicit
+  // 'dropped' or 'acknowledged' rows are filtered so supersede/ack don't
+  // resurrect carry-over messages on the next dispatch.
+  return listAllSteeringEntries(agentId, opts).filter(entry => {
+    const status = entry.status || STATUS.QUEUED;
+    return status !== STATUS.DROPPED && status !== STATUS.ACKNOWLEDGED;
+  });
+}
+
+// W-mq066js7000fff1f-f (Gap F): per-dispatch scoping. Callers that know
+// which dispatch they're about to spawn can pass {currentDispatchId} so
+// messages tagged for a different (older) dispatch are filtered out.
+// Pre-spawn messages (targetDispatchId null) always pass through.
+// Without currentDispatchId, no filtering happens — back-compat for
+// callers that haven't been updated to pass the dispatch id yet.
+function buildPendingSteeringPrompt(agentId, opts = {}) {
+  const includePrior = opts.includePrior === true;
+  const currentDispatchId = opts.currentDispatchId || null;
+  const allEntries = listUnreadSteeringMessages(agentId).filter(entry => entry.message.trim());
+  const entries = includePrior
+    ? allEntries
+    : allEntries.filter(entry => {
+        // Pre-spawn / agent-scoped messages (null targetDispatchId) always
+        // pick up on the next dispatch — the agent never had a chance to
+        // hear them yet.
+        if (!entry.targetDispatchId) return true;
+        // No dispatch context → don't try to filter (back-compat).
+        if (!currentDispatchId) return true;
+        // Per-dispatch messages only belong to their tagged dispatch.
+        return entry.targetDispatchId === currentDispatchId;
+      });
+
   if (entries.length === 0) return { entries, prompt: '' };
 
   const sections = [
@@ -206,6 +306,69 @@ function buildPendingSteeringPrompt(agentId) {
   return { entries, prompt: sections.join('\n') };
 }
 
+// W-mq066js7000fff1f-e (Gap E): dedupe lookup for POST /api/agents/steer.
+// Returns the existing entry whose normalized body matches `message` and
+// was created within `opts.windowMs` (default 5 min); null otherwise.
+// Only entries in "live" delivery states qualify — dropped/acknowledged
+// rows are ignored so a previously-superseded duplicate body is allowed
+// to be re-sent.
+function findRecentDuplicate(agentId, message, opts = {}) {
+  const trimmed = String(message || '').trim();
+  if (!trimmed) return null;
+  const windowMs = Number(opts.windowMs) > 0 ? Number(opts.windowMs) : DEDUPE_WINDOW_MS;
+  const now = Number(opts.now) > 0 ? Number(opts.now) : Date.now();
+  const entries = listAllSteeringEntries(agentId);
+  // Newest first — UI usually steers in a tight loop, the most recent
+  // identical message is the one we want to deduplicate against.
+  entries.sort((a, b) => b.createdAtMs - a.createdAtMs);
+  for (const entry of entries) {
+    const status = entry.status || STATUS.QUEUED;
+    if (!DEDUPE_CANDIDATE_STATUSES.has(status)) continue;
+    if (now - entry.createdAtMs > windowMs) continue;
+    if (entry.message.trim() !== trimmed) continue;
+    return entry;
+  }
+  return null;
+}
+
+// W-mq066js7000fff1f-e (Gap E): supersede prior steering messages.
+// mode:
+//   'all'      — drop every entry whose status is neither dropped nor
+//                acknowledged (queued/live_kill/deferred/re_spawning/
+//                delivered/stranded).
+//   'unacked'  — drop queued/live_kill/deferred/re_spawning/stranded but
+//                leave 'delivered' alone (agent already saw it).
+//   <steerId>  — drop the single entry with that steerId.
+// Returns the list of dropped {steerId, file, path, previousStatus}.
+function supersedeMessages(agentId, mode, opts = {}) {
+  if (!mode) return [];
+  const newSteerId = opts.newSteerId || null;
+  const reason = opts.reason || (newSteerId ? `superseded by ${newSteerId}` : 'superseded');
+  const entries = listAllSteeringEntries(agentId);
+  const dropped = [];
+  for (const entry of entries) {
+    const status = entry.status || STATUS.QUEUED;
+    let target = false;
+    if (mode === 'all') {
+      if (status !== STATUS.ACKNOWLEDGED && status !== STATUS.DROPPED) target = true;
+    } else if (mode === 'unacked') {
+      if (UNACKED_STATUSES.has(status)) target = true;
+    } else {
+      // Specific steerId
+      if (entry.steerId && entry.steerId === mode) target = true;
+    }
+    if (!target) continue;
+    _updateEntryStatus(entry, STATUS.DROPPED, { lastError: reason });
+    dropped.push({
+      steerId: entry.steerId,
+      file: entry.file,
+      path: entry.path,
+      previousStatus: status,
+    });
+  }
+  return dropped;
+}
+
 function _eventTimestampMs(obj, observedAtMs) {
   const value = obj?.timestamp || obj?.createdAt || obj?.created_at || obj?.time || obj?.data?.timestamp;
   const parsed = value ? Date.parse(value) : NaN;
@@ -342,9 +505,17 @@ module.exports = {
   ackContractBlock,
   writeSteeringMessage,
   listUnreadSteeringMessages,
+  listAllSteeringEntries,
   buildPendingSteeringPrompt,
+  findRecentDuplicate,
+  supersedeMessages,
   sessionIdFromEvent,
   sessionIdFromOutputLine,
   ackProcessedSteeringMessages,
   ackSteeringFromAckDir,
+  STATUS,
+  DEDUPE_WINDOW_MS,
+  // Exposed for unit tests only.
+  _updateEntryStatus,
+  _generateSteerId,
 };

package/engine.js

@@ -1326,7 +1326,7 @@ async function spawnAgent(dispatchItem, config) {
   // work-item prompts after setup because reused worktrees can live at arbitrary paths.
   const systemPrompt = buildSystemPrompt(agentId, config, project);
   const agentContext = buildAgentContext(agentId, config, project);
-  const pendingSteering = steering.buildPendingSteeringPrompt(agentId);
+  const pendingSteering = steering.buildPendingSteeringPrompt(agentId, { currentDispatchId: id });
   const completionReportPath = shared.dispatchCompletionReportPath(id);
   if (completionReportPath) {
     try {
@@ -2793,7 +2793,7 @@ async function spawnAgent(dispatchItem, config) {
       // Write new prompt with all unACKed steering messages. This keeps delivery
       // durable if the killed process had older pending messages that never
       // produced processing evidence before the resume.
-      const pendingForResume = steering.buildPendingSteeringPrompt(agentId);
+      const pendingForResume = steering.buildPendingSteeringPrompt(agentId, { currentDispatchId: id });
       const steerPromptBody = pendingForResume.prompt || steerMsg;
       const steerPrompt = `Message from your human teammate:\n\n${steerPromptBody}\n\nRespond to this, then continue working on your current task.`;
       const steerPromptPath = path.join(dispatchTmpDir, `prompt-steer-${safeId}.md`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yemi33/minions",
-  "version": "0.1.2124",
+  "version": "0.1.2125",
   "description": "Multi-agent AI dev team that runs from ~/.minions/ — five autonomous agents share a single engine, dashboard, and knowledge base",
   "bin": {
     "minions": "bin/minions.js"