openclaw-scheduler 0.2.9 → 0.2.10

package/dispatcher-strategies.js

@@ -1214,6 +1214,93 @@ export async function executeShell(job, ctx, deps) {
 
 // -- Strategy: Agent (isolated session) ----------------------
 
+function describeAgentSelection(selection) {
+  return {
+    model: selection?.model || null,
+    auth_profile: selection?.authProfile || null,
+  };
+}
+
+function sameAgentSelection(left, right) {
+  return (left?.model || undefined) === (right?.model || undefined)
+    && (left?.authProfile || undefined) === (right?.authProfile || undefined);
+}
+
+async function resolveConfiguredAuthProfile(authProfile, deps, jobId, fieldName = 'auth_profile') {
+  const { listSessions, log } = deps;
+  let resolvedAuthProfile = authProfile || undefined;
+  if (resolvedAuthProfile !== 'inherit') return resolvedAuthProfile;
+
+  try {
+    const sessions = await listSessions({ kinds: ['main'], activeMinutes: 120, limit: 10 });
+    const sessionList = sessions?.result?.details?.sessions || sessions?.result?.sessions || sessions?.sessions || sessions || [];
+    const mainSession = Array.isArray(sessionList)
+      ? sessionList.find(s => {
+          const key = s.key || s.sessionKey || '';
+          return key.includes(':main:') || key.endsWith(':main') || key === 'main';
+        })
+      : null;
+    const profileId = mainSession?.authProfileOverride || mainSession?.authProfile || mainSession?.profile;
+    if (profileId) {
+      resolvedAuthProfile = profileId;
+      log('debug', `Resolved ${fieldName} 'inherit' -> '${profileId}'`, { jobId });
+    } else {
+      log('debug', `${fieldName} 'inherit' -- no main session profile found, passing 'inherit' as-is`, { jobId });
+    }
+  } catch (err) {
+    log('warn', `Failed to resolve ${fieldName} 'inherit': ${err.message}`, { jobId });
+    // Fall through with 'inherit' -- gateway may handle it.
+  }
+
+  return resolvedAuthProfile;
+}
+
+async function runAgentTurnForSelection(job, deps, prompt, sessionKey, selection, dispatchAgentTurn) {
+  const { log } = deps;
+  const { syncAuthStoreToSession: syncAuth, applySessionOverridesToSessionStore: applySessionOverrides } = deps;
+
+  // Always sync the live auth store before each attempt so refreshed credentials
+  // are visible to any embedded/isolated runner startup.
+  if (typeof syncAuth === 'function') {
+    const syncResult = syncAuth(job.agent_id || 'main');
+    if (syncResult.ok) {
+      log('debug', `Synced live auth store to agent '${job.agent_id || 'main'}'`, { jobId: job.id });
+    } else {
+      log('warn', `Failed to sync auth store: ${syncResult.error}`, { jobId: job.id });
+    }
+  }
+
+  if (typeof applySessionOverrides === 'function') {
+    const applyResult = applySessionOverrides(
+      sessionKey,
+      {
+        authProfile: selection.authProfile,
+        modelRef: selection.model || null,
+      },
+      job.agent_id || 'main',
+    );
+    if (applyResult.ok) {
+      log('debug', `Applied session overrides for ${sessionKey}`, {
+        jobId: job.id,
+        authProfile: selection.authProfile || null,
+        modelRef: selection.model || null,
+      });
+    } else {
+      log('warn', `Failed to apply session overrides: ${applyResult.error}`, { jobId: job.id, sessionKey });
+    }
+  }
+
+  return dispatchAgentTurn({
+    message: prompt,
+    agentId: job.agent_id || 'main',
+    sessionKey,
+    authProfile: selection.authProfile,
+    idleTimeoutMs: (job.payload_timeout_seconds || 120) * 1000,
+    pollIntervalMs: 60000,
+    absoluteTimeoutMs: job.run_timeout_ms || 300000,
+  });
+}
+
 export async function executeAgent(job, ctx, deps) {
   const {
     waitForGateway, updateRunSession, setAgentStatus,
@@ -1224,7 +1311,6 @@ export async function executeAgent(job, ctx, deps) {
     runIsolatedAgentTurn,
     updateContextSummary, releaseDispatch, releaseIdempotencyKey,
     updateJob, matchesSentinel, detectTransientError,
-    listSessions,
     sqliteNow, log,
   } = deps;
   const dispatchAgentTurn = runIsolatedAgentTurn || runAgentTurnWithActivityTimeout;
@@ -1264,82 +1350,45 @@ export async function executeAgent(job, ctx, deps) {
   const { prompt, contextMeta } = buildJobPrompt(job, ctx.run);
   try { updateContextSummary(ctx.run.id, contextMeta); } catch (_e) { /* column may not exist yet */ }
 
-  // Resolve auth_profile: use effective profile from child credential policy
-  // if available (set by 'inherit' policy), otherwise fall back to the job's own.
-  let resolvedAuthProfile = ctx.v02Outcomes?.effective_auth_profile || job.auth_profile || undefined;
-  if (resolvedAuthProfile === 'inherit') {
-    try {
-      const sessions = await listSessions({ kinds: ['main'], activeMinutes: 120, limit: 10 });
-      const sessionList = sessions?.result?.details?.sessions || sessions?.result?.sessions || sessions?.sessions || sessions || [];
-      const mainSession = Array.isArray(sessionList)
-        ? sessionList.find(s => {
-            const key = s.key || s.sessionKey || '';
-            return key.includes(':main:') || key.endsWith(':main') || key === 'main';
-          })
-        : null;
-      const profileId = mainSession?.authProfileOverride || mainSession?.authProfile || mainSession?.profile;
-      if (profileId) {
-        resolvedAuthProfile = profileId;
-        log('debug', `Resolved auth_profile 'inherit' -> '${profileId}'`, { jobId: job.id });
-      } else {
-        log('debug', `auth_profile 'inherit' -- no main session profile found, passing 'inherit' as-is`, { jobId: job.id });
-      }
-    } catch (err) {
-      log('warn', `Failed to resolve 'inherit' auth_profile: ${err.message}`, { jobId: job.id });
-      // Fall through with 'inherit' -- gateway may handle it
-    }
-  }
+  const primarySelection = {
+    model: job.payload_model || undefined,
+    authProfile: await resolveConfiguredAuthProfile(
+      ctx.v02Outcomes?.effective_auth_profile || job.auth_profile || undefined,
+      deps,
+      job.id,
+      ctx.v02Outcomes?.effective_auth_profile ? 'effective_auth_profile' : 'auth_profile'
+    ),
+  };
+  const hasConfiguredFallback = job.payload_model_fallback != null || job.auth_profile_fallback != null;
+  const fallbackSelection = hasConfiguredFallback ? {
+    model: job.payload_model_fallback || primarySelection.model || undefined,
+    authProfile: job.auth_profile_fallback != null
+      ? await resolveConfiguredAuthProfile(job.auth_profile_fallback, deps, job.id, 'auth_profile_fallback')
+      : primarySelection.authProfile,
+  } : null;
+
+  let turnResult;
+  try {
+    turnResult = await runAgentTurnForSelection(job, deps, prompt, sessionKey, primarySelection, dispatchAgentTurn);
+  } catch (primaryError) {
+    const canTryConfiguredFallback = fallbackSelection && !sameAgentSelection(primarySelection, fallbackSelection);
+    if (!canTryConfiguredFallback) throw primaryError;
 
-  // Always sync the live auth store to the agent's auth-profiles.json BEFORE
-  // every agent turn. This ensures sessions that reuse a stable key (scheduler:<jobId>)
-  // always have fresh credentials -- token refreshes, order changes, and new
-  // profiles are picked up automatically without requiring an explicit auth_profile
-  // on every job.
-  const { syncAuthStoreToSession: syncAuth } = deps;
-  if (typeof syncAuth === 'function') {
-    const syncResult = syncAuth(job.agent_id || 'main');
-    if (syncResult.ok) {
-      log('debug', `Synced live auth store to agent '${job.agent_id || 'main'}'`, { jobId: job.id });
-    } else {
-      log('warn', `Failed to sync auth store: ${syncResult.error}`, { jobId: job.id });
-    }
-  }
+    log('warn', 'Primary agent selection failed; retrying with configured fallback', {
+      jobId: job.id,
+      primary: describeAgentSelection(primarySelection),
+      fallback: describeAgentSelection(fallbackSelection),
+      error: primaryError.message,
+    });
 
-  // Apply auth profile to session store BEFORE the agent turn.
-  // The x-openclaw-auth-profile HTTP header is not read by the gateway (dead header).
-  // Writing authProfileOverride directly to sessions.json is the effective mechanism
-  // for auth profile propagation to isolated/embedded sessions.
-  if (resolvedAuthProfile && resolvedAuthProfile !== 'inherit') {
-    const { applyAuthProfileToSessionStore: applyAuthProfile } = deps;
-    if (typeof applyAuthProfile === 'function') {
-      const applyResult = applyAuthProfile(sessionKey, resolvedAuthProfile, job.agent_id || 'main');
-      if (applyResult.ok) {
-        log('debug', `Applied auth profile '${resolvedAuthProfile}' to session store for ${sessionKey}`, { jobId: job.id });
-      } else {
-        log('warn', `Failed to apply auth profile to session store: ${applyResult.error}`, { jobId: job.id, sessionKey });
-      }
+    try {
+      turnResult = await runAgentTurnForSelection(job, deps, prompt, sessionKey, fallbackSelection, dispatchAgentTurn);
+      log('info', 'Configured agent fallback succeeded', { jobId: job.id, fallback: describeAgentSelection(fallbackSelection) });
+    } catch (fallbackError) {
+      throw new Error(`Primary agent selection failed: ${primaryError.message}; configured fallback also failed: ${fallbackError.message}`, { cause: fallbackError });
     }
   }
 
-  // Isolated dispatch primitive: HTTP-only chat completions call. The
-  // scheduler must never fork a sibling `openclaw` process to spawn an
-  // isolated session -- that variant has historically SIGTERM'd the
-  // launchd-tracked gateway parent and orphaned a node process on port
-  // 18789 (see ISOLATED_DISPATCH_PRIMITIVE in gateway.js).
-  const turnResult = await dispatchAgentTurn({
-    message: prompt,
-    agentId: job.agent_id || 'main',
-    sessionKey,
-    model: job.payload_model || undefined,
-    authProfile: resolvedAuthProfile,
-    // materializedEnv deferred: the x-openclaw-env-inject header is not sent
-    // until the OpenClaw gateway implements the receiver side. See
-    // openclaw/docs/env-inject-proposal.md for the gateway spec.
-    idleTimeoutMs: (job.payload_timeout_seconds || 120) * 1000,
-    pollIntervalMs: 60000,
-    absoluteTimeoutMs: job.run_timeout_ms || 300000,
-  });
-
   const content = turnResult.content || '';
   const trimmed = content.trim();
 

package/dispatcher.js

@@ -54,7 +54,7 @@ import {
   runAgentTurnWithActivityTimeout, runIsolatedAgentTurn,
   sendSystemEvent, getAllSubAgentSessions, listSessions,
   deliverMessage, checkGatewayHealth, waitForGateway, resolveDeliveryAlias,
-  applyAuthProfileToSessionStore,
+  applySessionOverridesToSessionStore,
   syncAuthStoreToSession,
 } from './gateway.js';
 import { normalizeShellResult } from './shell-result.js';
@@ -314,7 +314,7 @@ function buildDispatchDeps() {
     updateContextSummary, releaseIdempotencyKey,
     matchesSentinel, detectTransientError,
     listSessions,
-    applyAuthProfileToSessionStore,
+    applySessionOverridesToSessionStore,
     syncAuthStoreToSession,
     // Finalize
     updateIdempotencyResultHash,
@@ -430,8 +430,10 @@ function buildJobPrompt(job, run) {
     execution_intent: job.execution_intent || 'execute',
     execution_read_only: Boolean(job.execution_read_only),
     payload_model: job.payload_model || null,
+    payload_model_fallback: job.payload_model_fallback || null,
     payload_thinking: job.payload_thinking || null,
     auth_profile: job.auth_profile || null,
+    auth_profile_fallback: job.auth_profile_fallback || null,
   };
 
   const triggerContext = buildTriggeredRunContext(run);

package/docs/gateway-contract.md

@@ -90,6 +90,10 @@ single user message to an agent and receives the complete assistant response.
 The `model` field defaults to `openclaw:<agentId>` but can be overridden via
 `job.payload_model`.
 
+If `job.payload_model_fallback` and/or `job.auth_profile_fallback` are set, the
+scheduler retries once in the same run with the configured fallback selection
+after a primary selection error.
+
 **Response body** (expected):
 
 ```json
@@ -653,6 +657,23 @@ directly as the `x-openclaw-auth-profile` header value without resolution.
 
 ---
 
+## Fallback Model / Auth Selection
+
+Jobs can optionally persist `payload_model_fallback` and `auth_profile_fallback`
+alongside the primary `payload_model` / `auth_profile` fields.
+
+Runtime behavior:
+
+- The scheduler attempts the primary selection first.
+- If the primary chat-completions request errors before a usable assistant
+  reply is returned, `executeAgent()` retries once in the same run using the
+  configured fallback overrides.
+- Any fallback dimension left unset keeps the primary effective value.
+- Existing jobs remain backward-compatible because both fallback fields default
+  to `NULL` and no retry is attempted unless a fallback override is configured.
+
+---
+
 ## Env-Inject Forwarding
 
 When credential materialization for an agent task produces a non-empty plain

package/gateway.js

@@ -144,6 +144,7 @@ export async function runAgentTurn(opts) {
  * @param {number} opts.pollIntervalMs    - How often to poll session activity (default: 60000)
  * @param {number} opts.absoluteTimeoutMs - Hard ceiling regardless of activity (default: 300000)
  * @param {string} opts.authProfile       - Auth profile override (null, 'inherit', or 'provider:label')
+ * @param {string[]} [opts.sessionKinds]  - Optional session kinds to track for activity polling
  */
 export async function runAgentTurnWithActivityTimeout(opts) {
   const {
@@ -155,10 +156,46 @@ export async function runAgentTurnWithActivityTimeout(opts) {
     idleTimeoutMs = 120000,       // per-check idle threshold (from payload_timeout_seconds)
     pollIntervalMs = 60000,       // check activity every 60s
     absoluteTimeoutMs = 300000,   // hard ceiling (run_timeout_ms)
+    sessionKinds,
   } = opts;
 
   const controller = new AbortController();
   let abortReason = null;
+  const normalizedAgentId = (agentId || 'main').toLowerCase();
+  const normalizedSessionKey = String(sessionKey || '').toLowerCase();
+
+  const inferSessionKinds = () => {
+    if (Array.isArray(sessionKinds) && sessionKinds.length > 0) {
+      return [...new Set(sessionKinds.map(k => String(k).toLowerCase()).filter(Boolean))];
+    }
+
+    // Explicitly isolated/subagent sessions should not be pinned to main session
+    // so they can report idleness based on their own active session records.
+    if (
+      normalizedSessionKey === 'isolated' ||
+      normalizedSessionKey.startsWith('isolated:') ||
+      normalizedSessionKey.endsWith(':isolated') ||
+      normalizedSessionKey.includes(':isolated:') ||
+      normalizedAgentId === 'subagent'
+    ) {
+      return ['subagent', 'isolated'];
+    }
+
+    // Default to including main unless we can clearly infer this is an isolated run.
+    if (
+      normalizedAgentId === 'main' ||
+      normalizedSessionKey === 'main' ||
+      normalizedSessionKey.startsWith('main:') ||
+      normalizedSessionKey.includes(':main:') ||
+      normalizedSessionKey.endsWith(':main')
+    ) {
+      return ['main', 'subagent', 'isolated'];
+    }
+
+    return ['main', 'subagent', 'isolated'];
+  };
+
+  const resolvedSessionKinds = inferSessionKinds();
 
   // Hard absolute ceiling -- always fires regardless of activity
   const absoluteTimer = setTimeout(() => {
@@ -171,7 +208,7 @@ export async function runAgentTurnWithActivityTimeout(opts) {
 
   const checkActivity = async () => {
     try {
-      const result = await listSessions({ kinds: ['subagent', 'isolated'], activeMinutes: 60 });
+      const result = await listSessions({ kinds: resolvedSessionKinds, activeMinutes: 60 });
       // Normalise: gateway wraps result in several layers
       const sessions =
         result?.result?.details?.sessions ||
@@ -551,20 +588,55 @@ export async function waitForGateway(timeoutMs = 30000, intervalMs = 2000) {
  * @param {string} [agentId='main'] - Agent ID for store path resolution
  * @returns {{ ok: boolean, error?: string }}
  */
-export function applyAuthProfileToSessionStore(sessionKey, authProfile, agentId = 'main') {
-  if (!sessionKey || !authProfile) {
-    return { ok: false, error: 'sessionKey and authProfile are required' };
-  }
-
-  // The gateway may persist session state under either the canonical agent-scoped
-  // key or the flat transport key, depending on which path created the session.
-  // Keep both aliases in sync so isolated scheduler jobs cannot miss the override.
+function resolveSessionKeyAliases(sessionKey, agentId = 'main') {
   const canonicalMatch = sessionKey.match(/^agent:[^:]+:(.+)$/);
   const canonicalKey = sessionKey.startsWith('agent:')
     ? sessionKey
     : `agent:${agentId}:${sessionKey}`;
   const flatSessionKey = canonicalMatch?.[1] || sessionKey;
-  const keyAliases = Array.from(new Set([canonicalKey, flatSessionKey]));
+  return Array.from(new Set([canonicalKey, flatSessionKey]));
+}
+
+function parseSessionModelRef(modelRef) {
+  const trimmed = typeof modelRef === 'string' ? modelRef.trim() : '';
+  if (!trimmed) {
+    return { providerOverride: undefined, modelOverride: undefined };
+  }
+  const slashIndex = trimmed.indexOf('/');
+  if (slashIndex <= 0 || slashIndex >= trimmed.length - 1) {
+    return { providerOverride: undefined, modelOverride: trimmed };
+  }
+  const providerOverride = trimmed.slice(0, slashIndex).trim();
+  const modelOverride = trimmed.slice(slashIndex + 1).trim();
+  return {
+    providerOverride: providerOverride || undefined,
+    modelOverride: modelOverride || undefined,
+  };
+}
+
+/**
+ * Write scheduler-managed session overrides directly to the gateway's sessions.json store.
+ *
+ * The gateway reads sessions.json on each agent turn (with mtime-based cache
+ * invalidation), so writing here before dispatch ensures the embedded runner
+ * picks up the correct auth profile and model selection.
+ *
+ * @param {string} sessionKey - Session key as used in the HTTP request (e.g. 'scheduler:<jobId>')
+ * @param {{ authProfile?: string | null, modelRef?: string | null }} overrides - Desired session overrides
+ * @param {string} [agentId='main'] - Agent ID for store path resolution
+ * @returns {{ ok: boolean, error?: string }}
+ */
+export function applySessionOverridesToSessionStore(sessionKey, overrides = {}, agentId = 'main') {
+  if (!sessionKey) {
+    return { ok: false, error: 'sessionKey is required' };
+  }
+
+  const authProfile = typeof overrides.authProfile === 'string' ? overrides.authProfile.trim() : '';
+  const shouldSetAuthProfile = Boolean(authProfile) && authProfile !== 'inherit';
+  const { providerOverride, modelOverride } = parseSessionModelRef(overrides.modelRef);
+  const shouldSetModelOverride = Boolean(modelOverride);
+
+  const keyAliases = resolveSessionKeyAliases(sessionKey, agentId);
   const sessionsPath = join(HOME_DIR, '.openclaw', 'agents', agentId, 'sessions', 'sessions.json');
 
   try {
@@ -579,28 +651,59 @@ export function applyAuthProfileToSessionStore(sessionKey, authProfile, agentId
     let changed = false;
 
     for (const key of keyAliases) {
-      const entry = store[key];
-      if (!entry) {
-        // Session doesn't exist yet -- create a minimal entry.
-        // The gateway will populate the rest on the first agent turn.
-        store[key] = {
-          updatedAt: now,
-          authProfileOverride: authProfile,
-          authProfileOverrideSource: 'user',
-        };
-        changed = true;
+      const existingEntry = store[key];
+      if (!existingEntry && !shouldSetAuthProfile && !shouldSetModelOverride) {
         continue;
       }
 
-      if (entry.authProfileOverride !== authProfile || entry.authProfileOverrideSource !== 'user') {
-        // Update existing entry
-        entry.authProfileOverride = authProfile;
-        entry.authProfileOverrideSource = 'user';
-        entry.updatedAt = now;
-        // Clear compaction count so the override sticks across compactions
+      const entry = existingEntry || { updatedAt: now };
+      let entryChanged = false;
+
+      if (shouldSetAuthProfile) {
+        if (entry.authProfileOverride !== authProfile || entry.authProfileOverrideSource !== 'user') {
+          entry.authProfileOverride = authProfile;
+          entry.authProfileOverrideSource = 'user';
+          delete entry.authProfileOverrideCompactionCount;
+          entryChanged = true;
+        }
+      } else if (
+        entry.authProfileOverride !== undefined ||
+        entry.authProfileOverrideSource !== undefined ||
+        entry.authProfileOverrideCompactionCount !== undefined
+      ) {
+        delete entry.authProfileOverride;
+        delete entry.authProfileOverrideSource;
         delete entry.authProfileOverrideCompactionCount;
-        changed = true;
+        entryChanged = true;
       }
+
+      if (shouldSetModelOverride) {
+        if (entry.modelOverride !== modelOverride) {
+          entry.modelOverride = modelOverride;
+          entryChanged = true;
+        }
+        if (providerOverride) {
+          if (entry.providerOverride !== providerOverride) {
+            entry.providerOverride = providerOverride;
+            entryChanged = true;
+          }
+        } else if (entry.providerOverride !== undefined) {
+          delete entry.providerOverride;
+          entryChanged = true;
+        }
+      } else if (entry.modelOverride !== undefined || entry.providerOverride !== undefined) {
+        delete entry.modelOverride;
+        delete entry.providerOverride;
+        entryChanged = true;
+      }
+
+      if (!entryChanged) {
+        continue;
+      }
+
+      entry.updatedAt = now;
+      store[key] = entry;
+      changed = true;
     }
 
     if (!changed) {
@@ -614,9 +717,16 @@ export function applyAuthProfileToSessionStore(sessionKey, authProfile, agentId
   }
 }
 
+export function applyAuthProfileToSessionStore(sessionKey, authProfile, agentId = 'main') {
+  if (!sessionKey || !authProfile) {
+    return { ok: false, error: 'sessionKey and authProfile are required' };
+  }
+  return applySessionOverridesToSessionStore(sessionKey, { authProfile }, agentId);
+}
+
 /**
- * Sync the live auth-profiles.json from ~/.openclaw/credentials/ to the agent's
- * auth store at ~/.openclaw/agents/<agentId>/agent/auth-profiles.json.
+ * Sync the live auth-profiles.json from the main agent store to the target
+ * agent store at ~/.openclaw/agents/<agentId>/agent/auth-profiles.json.
  *
  * This ensures scheduler sessions always use fresh credentials (tokens, order,
  * default profile) even when no explicit auth_profile is set on the job.
@@ -630,7 +740,7 @@ export function applyAuthProfileToSessionStore(sessionKey, authProfile, agentId
  * @returns {{ ok: boolean, error?: string }}
  */
 export function syncAuthStoreToSession(agentId = 'main') {
-  const livePath = join(HOME_DIR, '.openclaw', 'credentials', 'auth-profiles.json');
+  const livePath = join(HOME_DIR, '.openclaw', 'agents', 'main', 'agent', 'auth-profiles.json');
   const agentStorePath = join(HOME_DIR, '.openclaw', 'agents', agentId, 'agent', 'auth-profiles.json');
 
   try {

package/index.d.ts

@@ -33,6 +33,7 @@ export interface JobSpec {
   payload_kind?: 'systemEvent' | 'agentTurn' | 'shellCommand';
   payload_message: string;
   payload_model?: string | null;
+  payload_model_fallback?: string | null;
   payload_thinking?: string | null;
   payload_timeout_seconds?: number;
   payload_scope?: 'own' | 'global';
@@ -87,6 +88,7 @@ export interface JobSpec {
 
   // Auth profile override
   auth_profile?: string | null;
+  auth_profile_fallback?: string | null;
 
   // Delivery opt-out
   delivery_opt_out_reason?: string | null;
@@ -150,6 +152,8 @@ export interface JobRecord extends JobSpec {
   schedule_cron: string | null;
   schedule_at: string | null;
   schedule_tz: string;
+  payload_model_fallback?: string | null;
+  auth_profile_fallback?: string | null;
   payload_kind: 'systemEvent' | 'agentTurn' | 'shellCommand';
   payload_message: string;
   ttl_hours: number | null;
@@ -455,6 +459,7 @@ export interface AgentTurnWithTimeoutOpts {
   sessionKey?: string;
   model?: string;
   authProfile?: string | null;
+  sessionKinds?: string[];
   idleTimeoutMs?: number;
   pollIntervalMs?: number;
   absoluteTimeoutMs?: number;

package/jobs.js

@@ -35,11 +35,11 @@ function sqliteNow(offsetMs = 0) {
 
 const PATCHABLE_COLUMNS = new Set([
   'enabled', 'name', 'schedule_cron', 'schedule_tz', 'schedule_at', 'schedule_kind',
-  'next_run_at', 'last_run_at', 'last_status', 'payload_message', 'payload_model',
+  'next_run_at', 'last_run_at', 'last_status', 'payload_message', 'payload_model', 'payload_model_fallback',
   'payload_thinking', 'payload_timeout_seconds', 'session_target', 'run_timeout_ms',
   'max_retries', 'consecutive_errors',
   'delivery_mode', 'delivery_channel', 'delivery_to', 'delivery_opt_out_reason',
-  'delete_after_run', 'ttl_hours', 'auth_profile', 'origin',
+  'delete_after_run', 'ttl_hours', 'auth_profile', 'auth_profile_fallback', 'origin',
   'output_excerpt_limit_bytes', 'output_summary_limit_bytes',
   'watchdog_check_cmd', 'watchdog_timeout_min', 'watchdog_started_at',
   'watchdog_target_label', 'watchdog_alert_channel', 'watchdog_alert_target',
@@ -192,9 +192,11 @@ export function validateJobSpec(opts, currentJob = null, mode = 'create') {
     'resource_pool',
     'preferred_session_key',
     'payload_model',
+    'payload_model_fallback',
     'payload_thinking',
     'trigger_condition',
     'auth_profile',
+    'auth_profile_fallback',
     'delivery_opt_out_reason',
     'origin',
     // v0.2 nullable strings
@@ -397,6 +399,9 @@ export function validateJobSpec(opts, currentJob = null, mode = 'create') {
   if (mode === 'create' || 'payload_model' in normalized) {
     assertSafeString('payload_model', merged.payload_model, { allowEmpty: false, maxLength: 256 });
   }
+  if (mode === 'create' || 'payload_model_fallback' in normalized) {
+    assertSafeString('payload_model_fallback', merged.payload_model_fallback, { allowEmpty: false, maxLength: 256 });
+  }
   if (mode === 'create' || 'payload_thinking' in normalized) {
     assertSafeString('payload_thinking', merged.payload_thinking, { allowEmpty: false, maxLength: 64 });
   }
@@ -408,6 +413,14 @@ export function validateJobSpec(opts, currentJob = null, mode = 'create') {
       assertSafeString('auth_profile', merged.auth_profile, { allowEmpty: false, maxLength: 256 });
     }
   }
+  if (mode === 'create' || 'auth_profile_fallback' in normalized) {
+    if (merged.auth_profile_fallback != null) {
+      if (typeof merged.auth_profile_fallback !== 'string') {
+        throw new Error('auth_profile_fallback must be a string or null');
+      }
+      assertSafeString('auth_profile_fallback', merged.auth_profile_fallback, { allowEmpty: false, maxLength: 256 });
+    }
+  }
 
   // Origin tracking (v20): required on creation for root (non-child) jobs.
   // Format convention: "<channel>:<id>" e.g. "telegram:<your-user-id>", "telegram:<your-group-id>", or "system" for automated jobs.
@@ -651,7 +664,7 @@ export function createJob(opts) {
     INSERT INTO jobs (
       id, name, enabled, schedule_kind, schedule_at, schedule_cron, schedule_tz,
       session_target, agent_id, payload_kind, payload_message,
-      payload_model, payload_thinking, payload_timeout_seconds,
+      payload_model, payload_model_fallback, payload_thinking, payload_timeout_seconds,
       execution_intent, execution_read_only,
       overlap_policy, run_timeout_ms, max_queued_dispatches, max_pending_approvals, max_trigger_fanout,
       delivery_mode, delivery_channel, delivery_to,
@@ -668,7 +681,7 @@ export function createJob(opts) {
       watchdog_timeout_min, watchdog_alert_channel, watchdog_alert_target,
       watchdog_self_destruct, watchdog_started_at,
       ttl_hours,
-      auth_profile,
+      auth_profile, auth_profile_fallback,
       delivery_opt_out_reason,
       origin,
       identity_principal, identity_run_as, identity_attestation, identity_ref,
@@ -684,7 +697,7 @@ export function createJob(opts) {
 ) VALUES (
       ?, ?, ?, ?, ?, ?, ?,
       ?, ?, ?, ?,
-      ?, ?, ?,
+      ?, ?, ?, ?,
       ?, ?,
       ?, ?, ?, ?, ?,
       ?, ?, ?,
@@ -698,7 +711,7 @@ export function createJob(opts) {
       ?, ?, ?,
       ?, ?, ?,
       ?, ?,
-      ?,
+      ?, ?,
       ?,
       ?,
       ?,
@@ -728,6 +741,7 @@ export function createJob(opts) {
     finalKind,
     normalized.payload_message,
     normalized.payload_model || null,
+    normalized.payload_model_fallback || null,
     normalized.payload_thinking || null,
     normalized.payload_timeout_seconds ?? 120,
     normalized.execution_intent || 'execute',
@@ -771,6 +785,7 @@ export function createJob(opts) {
     normalized.watchdog_started_at || null,
     normalized.ttl_hours || null,
     normalized.auth_profile || null,
+    normalized.auth_profile_fallback || null,
     normalized.delivery_opt_out_reason || null,
     normalized.origin || null,
     normalized.identity_principal || null,
@@ -830,7 +845,7 @@ export function updateJob(id, patch) {
   const allowed = [
     'name', 'enabled', 'schedule_kind', 'schedule_at', 'schedule_cron', 'schedule_tz',
     'session_target', 'agent_id', 'payload_kind', 'payload_message',
-    'payload_model', 'payload_thinking', 'payload_timeout_seconds',
+    'payload_model', 'payload_model_fallback', 'payload_thinking', 'payload_timeout_seconds',
     'execution_intent', 'execution_read_only',
     'overlap_policy', 'run_timeout_ms', 'max_queued_dispatches', 'max_pending_approvals', 'max_trigger_fanout',
     'delivery_mode', 'delivery_channel', 'delivery_to',
@@ -846,7 +861,7 @@ export function updateJob(id, patch) {
     'watchdog_timeout_min', 'watchdog_alert_channel', 'watchdog_alert_target',
     'watchdog_self_destruct', 'watchdog_started_at',
     'ttl_hours',
-    'auth_profile',
+    'auth_profile', 'auth_profile_fallback',
     'delivery_opt_out_reason',
     'origin',
     // v0.2 fields