@aitne/daemon 0.1.7 → 0.1.9

package/dist/core/routine-fetch-window-retry.js

@@ -1,7 +1,7 @@
 /**
  * Retry-policy helpers for the pre-pass fan-out coordinator.
  *
- * PRE_PASS_FAN_OUT_DESIGN.md §4.4 — the coordinator spawns a fresh Haiku
+ * docs/design/appendices/pre-pass-fan-out.md §4.4 — the coordinator spawns a fresh Haiku
  * sub-session per attempt and consults `defaultRetryDecision` (or any
  * `RetryDecisionFn`) between attempts to choose whether to spawn the
  * next one. Keeping the policy as pure data (decision matrix in
@@ -11,7 +11,7 @@
  * Phase 0 ships these helpers + their unit tests. The fan-out
  * coordinator that consumes them lands in Phase 1.
  */
-// ── Decision matrix (PRE_PASS_FAN_OUT_DESIGN.md §4.4) ─────────────────────
+// ── Decision matrix (docs/design/appendices/pre-pass-fan-out.md §4.4) ─────────────────────
 /**
  * Stable reason identifiers. Centralised so the dashboard / audit feed
  * can render them consistently and so test assertions don't drift from
@@ -26,6 +26,31 @@ export const RETRY_REASONS = {
     FAILED_STATUS: "failed-status",
     UPSTREAM_5XX: "upstream-5xx",
     PARTIAL_NO_POST: "partial-no-post",
+    /**
+     * Errors whose cause is structural rather than transient — retrying with
+     * the same source data will reproduce them byte-for-byte. Today's only
+     * surface:
+     *
+     *   - `{type:"fetch-failed", status:"permission-denied"}` — SDK Bash
+     *     parser rejected the POST command (e.g., Unicode whitespace in a
+     *     mail subject triggered Anthropic's `Ae6` "too-complex" gate, the
+     *     SDK fell through to ask-mode, dontAsk denied). The agent will
+     *     re-emit the same bytes on retry and re-trip the same gate.
+     *
+     * Distinct from `auth-failed` (401/403 — upstream credentials) and from
+     * `upstream-5xx` (transient infra). Only the status=failed and
+     * partial-no-post branches of rule 4 consult this — a `partial-with-
+     * progress` report (`posted > 0`) already doesn't retry by rule 5, so
+     * tagging it with deterministic-failure would misrepresent the audit
+     * trail.
+     *
+     * `validation-error` is intentionally NOT in this class: per-item Zod
+     * rejections from `/observations/batch` are exactly the §1.1 motivating
+     * case — the agent receives `detail` in the prior-attempt-hint and can
+     * correct the payload shape on retry. Classifying them as deterministic
+     * would suppress that recovery path.
+     */
+    DETERMINISTIC_FAILURE: "deterministic-failure",
     SUCCESS: "success",
     PARTIAL_WITH_POST: "partial-with-progress",
     SKIPPED: "skipped",
@@ -56,6 +81,28 @@ function isFetchFailedWithStatus(err, predicate) {
         return false;
     return predicate(status);
 }
+/**
+ * Sentinel error-status strings the runner classifies as deterministic
+ * (no point retrying — the next attempt re-emits the same bytes and
+ * re-trips the same gate). Centralised so the partial author (who emits
+ * these strings into `errors[*].status`), the runner (which interprets
+ * them here), and any future telemetry that filters on them all reference
+ * the same vocabulary.
+ *
+ * See `RETRY_REASONS.DETERMINISTIC_FAILURE` for the rationale and the
+ * specific gates these sentinels are paired with — and for why
+ * `validation-error` is deliberately absent (recoverable via
+ * prior-attempt-hint, §1.1 motivating case).
+ */
+const DETERMINISTIC_FETCH_FAILED_STATUSES = new Set([
+    "permission-denied",
+]);
+function isDeterministicError(err) {
+    if (err.type !== "fetch-failed")
+        return false;
+    return typeof err.status === "string"
+        && DETERMINISTIC_FETCH_FAILED_STATUSES.has(err.status);
+}
 /**
  * Default retry policy from §4.4. Pure: decision is fully determined by
  * the inputs, no side effects, no shared state. Decision order:
@@ -64,11 +111,24 @@ function isFetchFailedWithStatus(err, predicate) {
  *  2. Per-integration cumulative budget cap.
  *  3. Terminal error classes — flip-lock, budget-exhausted, auth (401/403).
  *  4. Retry-worthy outcomes — failed status, upstream 5xx, partial-no-post.
+ *     Each of these branches consults `isDeterministicError` BEFORE
+ *     emitting its retry decision: when the report carries a
+ *     `permission-denied` error and no 5xx is present, the branch
+ *     short-circuits to `deterministic-failure` instead of looping.
  *  5. Non-retry-by-default — success, partial-with-progress, skipped, no-progress.
  *
  * The motivating §1.1 failure ("Unknown name "limit"") lands
  * as `status="partial"` with `fetched > 0`, `posted === 0` and a
- * `fetch-failed` error — rule (4)'s `partial-no-post` branch catches it.
+ * `fetch-failed` error — rule (4)'s `partial-no-post` branch catches it
+ * and retries (the agent fixes the arg name on retry via the
+ * prior-attempt-hint).
+ *
+ * A Unicode-whitespace-in-mail-body failure lands as `status="partial"`
+ * with `posted === 0` and a `{type:"fetch-failed",
+ * status:"permission-denied", message:"Bash tool blocked..."}` —
+ * rule (4)'s partial-no-post branch sees the deterministic error and
+ * short-circuits to `deterministic-failure` instead of burning two more
+ * attempts on bytes the SDK will keep rejecting.
  */
 export const defaultRetryDecision = (report, attempt, policy, priorAttempts) => {
     // (1) Attempts cap — the loop body checks this before spawning attempt N+1.
@@ -93,20 +153,42 @@ export const defaultRetryDecision = (report, attempt, policy, priorAttempts) =>
             return { retry: false, reason: RETRY_REASONS.AUTH_FAILED };
         }
     }
+    // 5xx presence is consulted by every deterministic-failure short-
+    // circuit below — if ANY error is a transient 5xx, the partial path
+    // may still make progress on those items via retry, so we never
+    // suppress the retry on the basis of co-present deterministic errors.
+    const hasUpstream5xx = report.errors.some((err) => isFetchFailedWithStatus(err, (s) => s >= 500 && s < 600));
     // (4) Retry-worthy.
     if (report.status === "failed") {
+        // status=failed normally retries (an attempt that died without
+        // emitting <fetch_report> may produce one on the next try). When the
+        // attempt EXPLICITLY surfaced a deterministic error (e.g. the agent
+        // tried to POST, the SDK Bash preflight rejected the body, the
+        // session bailed to status=failed), retry re-runs the same shape
+        // and re-trips the same gate.
+        if (!hasUpstream5xx && report.errors.some(isDeterministicError)) {
+            return { retry: false, reason: RETRY_REASONS.DETERMINISTIC_FAILURE };
+        }
         return { retry: true, reason: RETRY_REASONS.FAILED_STATUS };
     }
-    for (const err of report.errors) {
-        if (isFetchFailedWithStatus(err, (s) => s >= 500 && s < 600)) {
-            return { retry: true, reason: RETRY_REASONS.UPSTREAM_5XX };
-        }
+    if (hasUpstream5xx) {
+        return { retry: true, reason: RETRY_REASONS.UPSTREAM_5XX };
     }
     if (policy.retryOnPartial !== false
         &&
             report.status === "partial"
         && report.posted === 0
         && report.fetched > 0) {
+        // Deterministic partial-no-post: every item failed for the same
+        // structural reason (e.g. Unicode whitespace in mail bodies trips
+        // the SDK Bash preflight on every retry). Short-circuit here BEFORE
+        // emitting PARTIAL_NO_POST so the audit row carries the actual
+        // cause and the runner stops burning budget on guaranteed-fail
+        // retries. (5xx presence already returned above, so reaching this
+        // point means no transient mixed in.)
+        if (report.errors.some(isDeterministicError)) {
+            return { retry: false, reason: RETRY_REASONS.DETERMINISTIC_FAILURE };
+        }
         return { retry: true, reason: RETRY_REASONS.PARTIAL_NO_POST };
     }
     // (5) Non-retry-by-default outcomes.
@@ -127,7 +209,7 @@ export const defaultRetryDecision = (report, attempt, policy, priorAttempts) =>
     // `RetryPolicy.retryOn`.
     return { retry: false, reason: RETRY_REASONS.NO_PROGRESS };
 };
-// ── Prior-attempt hint rendering (PRE_PASS_FAN_OUT_DESIGN.md §4.4) ────────
+// ── Prior-attempt hint rendering (docs/design/appendices/pre-pass-fan-out.md §4.4) ────────
 function xmlAttr(value) {
     return value
         .replace(/&/g, "&amp;")
@@ -207,4 +289,3 @@ export function buildPriorAttemptHintBlock(attempts, integrationKey) {
         .map((att) => renderOnePriorAttempt(att, integrationKey))
         .join("\n");
 }
-//# sourceMappingURL=routine-fetch-window-retry.js.map

package/dist/core/routine-fetch-window-runner.d.ts

@@ -1,7 +1,7 @@
 /**
  * `RoutineFetchWindowRunner` — pre-pass fan-out coordinator.
  *
- * ROUTINE_DATA_ACQUISITION_DESIGN.md §6.1.1 + PRE_PASS_FAN_OUT_DESIGN.md
+ * docs/design/appendices/routine-data-acquisition.md §6.1.1 + docs/design/appendices/pre-pass-fan-out.md
  * — every routine dispatcher (morning_routine, today_refresh,
  * hourly_check, evening / weekly / monthly review) calls this runner
  * immediately before dispatching the parent session. The runner:
@@ -29,7 +29,7 @@
  *     into the parent session's prompt (mirrors the `<gate_decision>`
  *     pattern used by hourly_check Stage 3).
  *
- * Failure-mode contract (PRE_PASS_FAN_OUT_DESIGN.md §5):
+ * Failure-mode contract (docs/design/appendices/pre-pass-fan-out.md §5):
  *
  *  - **No applicable rows** (routine has no windows in `ROUTINE_WINDOWS`,
  *    every integration is disabled, every account list is empty) — the
@@ -84,7 +84,7 @@ export interface FetchReport {
     /** Stable ID for telemetry tie-back; mirrors the fetcher event's correlationId. */
     fetcherCorrelationId?: string;
     /**
-     * PRE_PASS_FAN_OUT_DESIGN.md §4.5 — per-integration breakdown. Top-level
+     * docs/design/appendices/pre-pass-fan-out.md §4.5 — per-integration breakdown. Top-level
      * counts above already aggregate the children; the breakdown lets
      * downstream consumers (parent task-flow prose, dashboard renderers)
      * branch per integration. Absent on the `skipped` / `failed` paths
@@ -94,7 +94,7 @@ export interface FetchReport {
     perIntegration?: ReadonlyArray<SubReport>;
 }
 /**
- * PRE_PASS_FAN_OUT_DESIGN.md §4.3 — one attempt of one integration's
+ * docs/design/appendices/pre-pass-fan-out.md §4.3 — one attempt of one integration's
  * sub-session. The fan-out coordinator records one of these per
  * `agentRouter.execute` invocation; `defaultRetryDecision` consumes
  * the latest record to decide whether to spawn another attempt.
@@ -118,7 +118,7 @@ export interface SubAttemptRecord {
     numTurns: number;
 }
 /**
- * PRE_PASS_FAN_OUT_DESIGN.md §4.3 — final per-integration verdict the
+ * docs/design/appendices/pre-pass-fan-out.md §4.3 — final per-integration verdict the
  * coordinator emits after its retry loop terminates. Mirrors the
  * fields of the last `SubAttemptRecord` (the final attempt's outcome
  * is the integration's effective outcome) plus the integration key
@@ -139,6 +139,29 @@ export interface RoutineFetchWindowResult {
     /** XML block to graft into the parent routine event's `event.data.fetchReportBlock`. */
     block: string;
 }
+/**
+ * HOURLY_CHECK_GATE_REDESIGN_PLAN.md §3.4 — caller options for `run()`.
+ *
+ * The hourly_check coordinator passes `integrationKeyFilter` to restrict
+ * the fan-out to the subset of integrations whose freshness window has
+ * elapsed. Morning_routine / evening_review / weekly_review call
+ * `run()` without options so they fetch every integration the routine
+ * declares (their windows are larger and the freshness gate would
+ * defeat the purpose of the larger window).
+ */
+export interface RoutineFetchWindowRunOptions {
+    /**
+     * Restrict the fan-out to the listed integration keys. Integrations
+     * whose key is not in the set are dropped after
+     * `splitAcquisitionPlanByIntegration` runs, producing the same
+     * "empty plan → skipped" outcome as if they had no fetch rows.
+     *
+     * Empty set → entire fan-out is skipped (returns a `status='skipped'`
+     * fetch report). Callers that want "fetch everything" should pass
+     * `options=undefined`, not an empty set.
+     */
+    integrationKeyFilter?: ReadonlySet<IntegrationKey>;
+}
 export interface RoutineFetchWindowRunnerDeps {
     db: Database.Database;
     config: AgentConfig;
@@ -337,26 +360,37 @@ export declare class RoutineFetchWindowRunner {
      * the parent event's `event.data.fetchReportBlock` so ContextBuilder
      * injects it into the parent prompt.
      *
-     * `routineKey` overrides the auto-derived window key — used by
-     * morning_routine to opt into `routine.morning_routine_initial`'s
-     * plan when `yesterday.md` is absent (their plans currently coincide,
-     * but the seam exists for future divergence).
+     * `routineKey` overrides the auto-derived window key. After the
+     * variant collapse documented in
+     * `docs/design/appendices/morning-routine-optimization.md`,
+     * morning_routine no longer toggles to a separate
+     * `routine.morning_routine_initial` — both branches share the same
+     * window plan. The override seam is kept for callers that already
+     * know the canonical RoutineWindowKey and want to skip the event-
+     * shape derivation.
      */
-    run(parentEvent: Event, routineKey?: RoutineWindowKey): Promise<RoutineFetchWindowResult>;
+    run(parentEvent: Event, routineKey?: RoutineWindowKey, options?: RoutineFetchWindowRunOptions): Promise<RoutineFetchWindowResult>;
     private runImpl;
     private buildFanOutPlanContext;
     /**
-     * §5 BackendQuotaError row + §4.4 retryEscalationTier — re-derive the
-     * per-integration sub-plan against the CURRENT attempt's binding so a
-     * cross-backend swap (escalation tier flips main backend, or
-     * `prePassRetryEscalationTier` swaps the per-attempt tier) keeps the
-     * plan's `<fetch mode="…">` attribute aligned with the partial body's
-     * remaining mode-branch (the partial is filtered for the new backend
-     * via `renderPartialForFanOut`). Returns null only when the
-     * integration becomes unreachable on the new backend (e.g. native
-     * mode bound to A but the attempt re-resolves to B); the runner
-     * passes the call through to record the original sub-plan and let
-     * the agent emit `no-surface` errors organically.
+     * Defensive re-derivation of the per-integration sub-plan against the
+     * CURRENT attempt's binding. With per-integration backend routing in
+     * place, the attempt's binding is pinned to `subPlan.requiredBackend`
+     * via `BackendRouter.resolveBinding({ requestedBackendId })`, so
+     * `binding.main.backendId` always equals the original plan's backend
+     * and the recomputed block is bit-identical to `input.subPlan.block`
+     * in production. The defensive branch is retained for two reasons:
+     *
+     *  1. Regression test coverage — the runner unit test mocks
+     *     `resolveBinding` to return a different backend mid-loop,
+     *     exercising the rebuild mechanics so a future change that
+     *     re-introduces cross-backend swaps (e.g. dropping the
+     *     requestedBackendId pin or extending escalation to also flip
+     *     backends) cannot silently regress plan-vs-partial alignment.
+     *  2. Graceful degradation — returns null when the integration is
+     *     unreachable on the attempted backend; the caller logs the
+     *     original sub-plan and lets the agent emit `no-surface` errors
+     *     organically rather than throwing.
      *
      * Pure: snapshot inputs (`integrationsSnapshot`, `accounts`,
      * `timestamps`) are frozen at run() entry; only `sessionBackend`
@@ -424,4 +458,3 @@ export declare class RoutineFetchWindowRunner {
      */
     private collectAccounts;
 }
-//# sourceMappingURL=routine-fetch-window-runner.d.ts.map