@mrrlin-dev/mcp 0.4.31 → 0.4.33

package/dist/bin.cjs

@@ -37388,6 +37388,22 @@ function isRunnableProposal(item) {
   return true;
 }
 
+// ../../packages/schemas/dist/task-notes.js
+var TASK_NOTES_BRIEF_SECTIONS = [
+  { heading: "Context", description: "why this task exists; link to parent/trigger task if follow-up." },
+  { heading: "Scope", description: "concrete actions and acceptance criteria." },
+  { heading: "References", description: "links, data, relevant findings (omit if nothing to reference)." }
+];
+var TASK_NOTES_JOURNAL_SECTIONS = [
+  { heading: "Result", description: "what was accomplished, key findings or metrics, follow-up tasks created." },
+  {
+    heading: "Recheck",
+    dated: true,
+    description: "what you checked, what you found, and what happens next."
+  }
+];
+var JOURNAL_HEADING_RE = new RegExp(`^##[ \\t]+(${TASK_NOTES_JOURNAL_SECTIONS.map((s) => s.heading).join("|")})\\b[ \\t]*(?:[\u2014\u2013-][ \\t]*(\\S.*?))?[ \\t]*$`);
+
 // ../../packages/schemas/dist/index.js
 var mrrlinTaskStatusSchema = external_exports.enum([
   "backlog",
@@ -37504,6 +37520,12 @@ var mrrlinRunBlockingReasonCodeSchema = external_exports.enum([
   // start (verifyProviderReadiness returned ready:false) — an environment/infrastructure problem,
   // not a task-content one, so it gets its own code rather than reusing task_blocked.
   "provider_not_ready",
+  // The agent provider refused work MID-RUN because its usage quota is exhausted — distinct from
+  // `provider_not_ready`, which is the pre-flight readiness gate refusing to start. A quota is
+  // transient and the run is retriable once the limit resets, so this code must never be conflated
+  // with a task-content block; before it existed such a failure fell through to `unknown` and was
+  // handed off to the operator as though the Director had judged the task.
+  "provider_limit_exhausted",
   "unknown"
 ]);
 var mrrlinExecutionArtifactKindSchema = external_exports.enum([
@@ -39323,6 +39345,36 @@ function detectExhaustedProviderLimit(snapshot, nowMs) {
   const resetAt = candidates.length > 0 ? candidates.reduce((a, b) => a > b ? a : b) : null;
   return { exhausted: true, resetAt };
 }
+var PROVIDER_LIMIT_ERROR_PATTERNS = [
+  // OpenAI / Codex, verbatim from the observed event.
+  /you'?ve hit your usage limit/i,
+  // Anthropic phrasing for the same condition.
+  /you have exceeded your (?:rate limit|usage limit)/i,
+  /credit balance is too low/i,
+  // START-ANCHORED quota wording. Round 2 split on this: the unanchored version was removed in
+  // round 1 for matching task prose ("the quota is being exceeded by another worker"), and a round-2
+  // reviewer then objected that removing it also drops real provider messages that LEAD with the
+  // condition ("Monthly quota exceeded."). Anchoring resolves both — a provider error states the
+  // condition first, prose embeds it — so the pattern is kept, but only at the head of the message.
+  // Note this is a second line of defence either way: a provider that emits a structured
+  // `rate_limits` snapshot is caught by detectExhaustedProviderLimit regardless of wording.
+  // NOTE an unanchored `/usage limit reached/i` used to sit above, and it was the one real leak a
+  // round-4 reviewer's finding pointed at (though not the example they gave): it matched
+  // "[ERROR] memory usage limit reached", where the limit belongs to memory, not the provider. The
+  // anchored pattern below already covers "Usage limit reached …", so the unanchored one was pure
+  // false-positive surface and is gone.
+  //
+  // The optional prefix covers the log decorations providers actually ship with — "Error: ",
+  // "[ERROR] ", "(fatal) " — without letting the condition sit anywhere in a sentence. The noun set
+  // covers "rate limit"/"api limit" forms that carry no "quota" or "credits" at all.
+  /^\s*(?:[[(]?\s*(?:error|fatal|warn(?:ing)?)\s*[\])]?\s*[:-]?\s*)?(?:monthly |daily |monthly\/daily )?(?:quota|usage limit|rate limit|api limit|api credits?|credits?) (?:has been |have been |is |are )?(?:exceeded|exhausted|used up|reached)\b/i
+];
+function detectProviderLimitFromErrorText(text) {
+  if (typeof text !== "string" || text.trim().length === 0)
+    return null;
+  const matched = PROVIDER_LIMIT_ERROR_PATTERNS.some((pattern) => pattern.test(text));
+  return matched ? { exhausted: true, resetAt: null } : null;
+}
 
 // ../../packages/agent-client/dist/providers/codex/adapter.js
 var CodexProviderAdapter = class {
@@ -41837,7 +41889,7 @@ Do NOT derail the current task - if the operator has an in-flight question, answ
 }
 
 // src/_generated/version.ts
-var PKG_VERSION = "0.4.31";
+var PKG_VERSION = "0.4.33";
 
 // src/api-base-url-migrate.ts
 var import_node_fs3 = __toESM(require("node:fs"), 1);
@@ -46039,6 +46091,30 @@ function isDeployGateRunStatus(status) {
   return status === "dev_deploy" || status === "prod_deploy";
 }
 
+// src/prompts/task-notes-contract.ts
+function renderTaskNotesContractLines() {
+  const brief = TASK_NOTES_BRIEF_SECTIONS.map((s) => `    ## ${s.heading} \u2014 ${s.description}`);
+  const [result, recheck] = TASK_NOTES_JOURNAL_SECTIONS;
+  return [
+    "- Notes (markdown): write for a human operator scanning a task list.",
+    "  First line: one plain-text sentence summarizing the task (no heading).",
+    "  Then scale the structure to complexity:",
+    "  For simple tasks \u2014 the one-line summary may be enough. No headings required.",
+    "  For non-trivial tasks, use these sections as needed:",
+    ...brief,
+    "  When closing a task (update_task status=closed_done), APPEND a Result section:",
+    `    ## ${result?.heading} \u2014 ${result?.description}`,
+    "  When you revisit a task that already has a Result \u2014 a later verification, a retry, a status",
+    "  re-check \u2014 APPEND a dated entry instead of rewriting Result:",
+    `    ## ${recheck?.heading} \u2014 YYYY-MM-DD \u2014 ${recheck?.description}`,
+    "    Do NOT remove earlier sections \u2014 they remain useful for context.",
+    "  The sections above the first Result/Recheck are the brief (what the task IS); Result and",
+    "  Recheck are the execution journal (what HAPPENED). The task page renders them separately and",
+    "  collapses the journal, so keep each kind of content under the right heading.",
+    "  Adapt depth to the task: a one-line fix needs one sentence, not four headings."
+  ];
+}
+
 // src/turn-deadline.ts
 var DEFAULT_TURN_INTERRUPT_TIMEOUT_MS = 5e3;
 function withTimeout2(promise2, ms, message) {
@@ -46475,10 +46551,31 @@ function executionTurnBudgetMessage(budgetMs) {
 function isExecutionTurnTimeoutReason(reason) {
   return reason.startsWith(EXECUTION_TURN_TIMEOUT_PREFIX) || reason.startsWith(EXECUTION_TURN_STALL_PREFIX);
 }
+var PROVIDER_LIMIT_RETRY_CURSOR_PREFIX = "provider_limit_retry:";
+var PROVIDER_LIMIT_RETRY_MAX_ATTEMPTS = 1;
+var PROVIDER_LIMIT_RETRY_CODE = "provider_limit_retry";
+var PROVIDER_LIMIT_PAUSE_REASON = "Agent provider usage limit exhausted during an autonomous execution run.";
+var PROVIDER_LIMIT_HANDOFF_REASON = "The agent provider's usage limit stayed exhausted across every automatic retry, so this run could not proceed. This is a provider quota problem, not a problem with the task.";
+function providerLimitRetryCursor(attempt) {
+  return `${PROVIDER_LIMIT_RETRY_CURSOR_PREFIX}${attempt}`;
+}
+function providerLimitRetryAttempt(checkpointCursor) {
+  if (!checkpointCursor || !checkpointCursor.startsWith(PROVIDER_LIMIT_RETRY_CURSOR_PREFIX)) return 0;
+  const parsed = Number.parseInt(checkpointCursor.slice(PROVIDER_LIMIT_RETRY_CURSOR_PREFIX.length), 10);
+  return Number.isInteger(parsed) && parsed > 0 ? parsed : 0;
+}
 function reportAutopilotLimitPause(client, reason, resetAt) {
   void client.pauseAutopilotForLimit({ source: "provider_limit", reason, resetAt }).catch(() => {
   });
 }
+async function applyAutopilotLimitPause(client, reason, resetAt) {
+  try {
+    await client.pauseAutopilotForLimit({ source: "provider_limit", reason, resetAt });
+    return true;
+  } catch {
+    return false;
+  }
+}
 function isDeliverableGateRetryableReason(reason) {
   return DELIVERABLE_GATE_RETRYABLE_REASON_PREFIXES.some((prefix) => reason.startsWith(prefix));
 }
@@ -46612,18 +46709,7 @@ var BASE_INSTRUCTIONS_PREFIX = [
   "- Title: short, actionable, human-readable. Describe what needs to happen, not internal jargon.",
   '  Good: "Audit crawled-not-indexed pages and fix 404 errors"',
   '  Bad: "GSC coverage triage crawled-not-indexed + 404"',
-  "- Notes (markdown): write for a human operator scanning a task list.",
-  "  First line: one plain-text sentence summarizing the task (no heading).",
-  "  Then scale the structure to complexity:",
-  "  For simple tasks \u2014 the one-line summary may be enough. No headings required.",
-  "  For non-trivial tasks, use these sections as needed:",
-  "    ## Context \u2014 why this task exists; link to parent/trigger task if follow-up.",
-  "    ## Scope \u2014 concrete actions and acceptance criteria.",
-  "    ## References \u2014 links, data, relevant findings (omit if nothing to reference).",
-  "  When closing a task (update_task status=closed_done), APPEND a Result section:",
-  "    ## Result \u2014 what was accomplished, key findings or metrics, follow-up tasks created.",
-  "    Do NOT remove earlier sections \u2014 they remain useful for context.",
-  "  Adapt depth to the task: a one-line fix needs one sentence, not four headings.",
+  ...renderTaskNotesContractLines(),
   "",
   // Slice 4 of token-efficient-execution-runs (D8). This is the ONLY way the reasoning behind a
   // decision survives past this conversation: a thread is retired once it has accumulated too many
@@ -47998,6 +48084,62 @@ async function failRun(deps, projectSlug, task, runId, leaseId, reason, reasonCo
     return;
   }
   if (currentRun.status !== "running" || currentRun.leaseId !== leaseId) return;
+  let handoffReason = reason;
+  let handoffReasonCode = reasonCode;
+  const providerLimit = detectProviderLimitFromErrorText(reason);
+  if (providerLimit) {
+    const autopilotPaused = await applyAutopilotLimitPause(
+      deps.client,
+      PROVIDER_LIMIT_PAUSE_REASON,
+      providerLimit.resetAt
+    );
+    const attempt = providerLimitRetryAttempt(currentRun.checkpointCursor) + 1;
+    if (attempt <= PROVIDER_LIMIT_RETRY_MAX_ATTEMPTS) {
+      try {
+        await deps.client.updateExecutionRun(projectSlug, runId, {
+          status: "pending",
+          leaseId: null,
+          checkpointCursor: providerLimitRetryCursor(attempt)
+        });
+        await deps.client.appendExecutionArtifact(projectSlug, runId, {
+          id: newArtifactId(),
+          kind: "error",
+          payload: {
+            code: PROVIDER_LIMIT_RETRY_CODE,
+            source: "execution-consumer",
+            attempt,
+            maxAttempts: PROVIDER_LIMIT_RETRY_MAX_ATTEMPTS,
+            // The provider's raw sentence belongs HERE — diagnostic detail on an error artifact —
+            // and never in a handoff `reason`, which the DB trigger caches as the task's judgement.
+            providerMessage: reason,
+            // Whether the brake actually engaged. If it did not, the requeued run is only held
+            // back by its own attempt budget, so this is the difference between "waiting for the
+            // quota" and "about to fail once more"; it must be visible, not swallowed.
+            autopilotPaused,
+            summary: autopilotPaused ? `Agent provider usage limit exhausted; autopilot paused and the run requeued for retry ${attempt}/${PROVIDER_LIMIT_RETRY_MAX_ATTEMPTS}.` : `Agent provider usage limit exhausted; the run was requeued for retry ${attempt}/${PROVIDER_LIMIT_RETRY_MAX_ATTEMPTS}, but pausing autopilot FAILED, so nothing is holding it back.`
+          }
+        }).catch(() => {
+        });
+        return;
+      } catch {
+      }
+    }
+    handoffReason = PROVIDER_LIMIT_HANDOFF_REASON;
+    handoffReasonCode = "provider_limit_exhausted";
+    await deps.client.appendExecutionArtifact(projectSlug, runId, {
+      id: newArtifactId(),
+      kind: "error",
+      payload: {
+        code: PROVIDER_LIMIT_RETRY_CODE,
+        source: "execution-consumer",
+        attempt: PROVIDER_LIMIT_RETRY_MAX_ATTEMPTS,
+        maxAttempts: PROVIDER_LIMIT_RETRY_MAX_ATTEMPTS,
+        providerMessage: reason,
+        summary: "Agent provider usage limit still exhausted after every retry; handing off to the operator."
+      }
+    }).catch(() => {
+    });
+  }
   if (isExecutionTurnTimeoutReason(reason) && currentRun.checkpointCursor !== EXECUTION_TURN_TIMEOUT_RETRY_CURSOR) {
     try {
       await deps.client.updateExecutionRun(projectSlug, runId, {
@@ -48050,11 +48192,11 @@ async function failRun(deps, projectSlug, task, runId, leaseId, reason, reasonCo
   }
   try {
     await deps.client.createExecutionRunHandoff(projectSlug, runId, {
-      reason,
-      ...reasonCode ? { reasonCode } : {}
+      reason: handoffReason,
+      ...handoffReasonCode ? { reasonCode: handoffReasonCode } : {}
     });
   } catch {
-    await notifyOperatorHandoff(deps, projectSlug, task, runId, reason);
+    await notifyOperatorHandoff(deps, projectSlug, task, runId, handoffReason);
   }
 }
 async function reconcileTaskAwaitingMerge(deps, projectSlug, task, runId, reason) {
@@ -54218,18 +54360,7 @@ function buildThreadStartParams(msg, config2, desiredModel) {
     "- Title: short, actionable, human-readable. Describe what needs to happen, not internal jargon.",
     '  Good: "Audit crawled-not-indexed pages and fix 404 errors"',
     '  Bad: "GSC coverage triage crawled-not-indexed + 404"',
-    "- Notes (markdown): write for a human operator scanning a task list.",
-    "  First line: one plain-text sentence summarizing the task (no heading).",
-    "  Then scale the structure to complexity:",
-    "  For simple tasks \u2014 the one-line summary may be enough. No headings required.",
-    "  For non-trivial tasks, use these sections as needed:",
-    "    ## Context \u2014 why this task exists; link to parent/trigger task if follow-up.",
-    "    ## Scope \u2014 concrete actions and acceptance criteria.",
-    "    ## References \u2014 links, data, relevant findings (omit if nothing to reference).",
-    "  When closing a task (update_task status=closed_done), APPEND a Result section:",
-    "    ## Result \u2014 what was accomplished, key findings or metrics, follow-up tasks created.",
-    "    Do NOT remove earlier sections \u2014 they remain useful for context.",
-    "  Adapt depth to the task: a one-line fix needs one sentence, not four headings.",
+    ...renderTaskNotesContractLines(),
     // early-intent-confirmation (design.md, "The chat contract"): the core block below is copied
     // VERBATIM from design.md, per tasks.md 10.1. It replaces an older sentence that also carried
     // "omit operatorSeedRequest only when there is genuinely no operator request behind the task

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mrrlin-dev/mcp",
-  "version": "0.4.31",
+  "version": "0.4.33",
   "type": "module",
   "bin": {
     "mrrlin-mcp": "dist/bin.cjs"
@@ -22,11 +22,11 @@
     "esbuild": "^0.24.0",
     "tsx": "^4.22.3",
     "@mrrlin/client": "0.0.0",
-    "@mrrlin/agent-client": "0.0.0",
     "@mrrlin/director-e2e": "0.0.0",
     "@mrrlin/schemas": "0.0.0",
     "@mrrlin/tsconfig": "0.0.0",
-    "@mrrlin/wiki": "0.0.0"
+    "@mrrlin/wiki": "0.0.0",
+    "@mrrlin/agent-client": "0.0.0"
   },
   "dependencies": {
     "@iarna/toml": "^2.2.5",