@minionry/minion 0.7.36 → 0.7.39

package/dist/server/services/schedule/scheduler.js

@@ -6,7 +6,7 @@ import { resolvePmDir } from '../plan/parser.js';
 import { wireExecutorEvents } from '../websocket/plan-execution-handlers.js';
 import { schedulerCache } from '../websocket/plan-helpers.js';
 import { bootstrapRun } from './run-bootstrap.js';
-import { ScheduleStore } from './schedule-store.js';
+import { computeNextFireAt, exceedsMaxLateness, isRecurringTiming, SCHEDULE_MISSED_LATENESS_ERROR, ScheduleStore, } from './schedule-store.js';
 export const SCHEDULER_TICK_MS = 30_000;
 export const SCHEDULE_ONCE_GRACE_MS = 15 * 60_000;
 export const CONTINUOUS_MIN_SPACING_MS = 60_000;
@@ -88,6 +88,25 @@ export class SchedulerEngine {
         this.runs.reset();
         this.store = null;
     }
+    fireNow(scheduleId) {
+        const store = this.store;
+        if (!store)
+            return { kind: 'not-found' };
+        const before = store.get(scheduleId);
+        if (!before)
+            return { kind: 'not-found' };
+        if (!before.enabled)
+            return { kind: 'disabled' };
+        const plannedNextFireAt = before.nextFireAt;
+        if (this.runs.has(scheduleId)) {
+            this.recordSkippedOverlap(before, Date.now());
+        }
+        else {
+            this.fire(before, Date.now());
+        }
+        store.restoreNextFireAt(scheduleId, plannedNextFireAt);
+        return { kind: 'ok', record: store.get(scheduleId) };
+    }
     tick() {
         const store = this.store;
         if (!store)
@@ -104,6 +123,10 @@ export class SchedulerEngine {
             }
             if (!this.isDue(record, now))
                 continue;
+            if (exceedsMaxLateness(record, now)) {
+                this.recordMissedLate(record, now);
+                continue;
+            }
             this.fire(record, now);
         }
     }
@@ -132,8 +155,8 @@ export class SchedulerEngine {
             if (record.timing.kind === 'once') {
                 this.recoverOnce(record, now);
             }
-            else if (record.timing.kind === 'interval') {
-                this.recoverInterval(record, now);
+            else if (isRecurringTiming(record.timing)) {
+                this.recoverRecurring(record, now);
             }
         }
     }
@@ -154,10 +177,14 @@ export class SchedulerEngine {
         store.setEnabled(record.id, false);
         this.broadcastSchedules();
     }
-    recoverInterval(record, now) {
+    recoverRecurring(record, now) {
         const next = record.nextFireAt ? parseEpoch(record.nextFireAt) : Number.NaN;
         if (Number.isFinite(next) && next > now)
             return;
+        if (exceedsMaxLateness(record, now)) {
+            this.recordMissedLate(record, now);
+            return;
+        }
         this.fire(record, now);
     }
     fire(record, now) {
@@ -243,10 +270,17 @@ export class SchedulerEngine {
         store.recordFire(record.id, { at: new Date(now).toISOString(), status: 'skipped-overlap', boardId: null, error: 'previous run for this schedule is still in flight' }, this.nextFireAtAfterStart(record, now));
         this.broadcastSchedules();
     }
+    recordMissedLate(record, now) {
+        const store = this.store;
+        if (!store)
+            return;
+        store.recordFire(record.id, { at: new Date(now).toISOString(), status: 'missed', boardId: null, error: SCHEDULE_MISSED_LATENESS_ERROR }, this.nextFireAtAfterStart(record, now));
+        this.broadcastSchedules();
+    }
     nextFireAtAfterStart(record, now) {
-        if (record.timing.kind === 'interval')
-            return new Date(now + record.timing.everyMs).toISOString();
-        return null;
+        if (!isRecurringTiming(record.timing))
+            return null;
+        return computeNextFireAt(record.timing, new Date(now));
     }
     nextFireAtAfterFailure(record, now, consecutiveEmptyRuns) {
         if (record.timing.kind === 'once')
@@ -254,7 +288,7 @@ export class SchedulerEngine {
         if (record.timing.kind === 'continuous') {
             return new Date(now + continuousDelayMs(consecutiveEmptyRuns)).toISOString();
         }
-        return new Date(now + record.timing.everyMs).toISOString();
+        return computeNextFireAt(record.timing, new Date(now));
     }
     nextFireAtAfterSettle(record, now, consecutiveEmptyRuns) {
         if (record.timing.kind === 'once')
@@ -263,7 +297,7 @@ export class SchedulerEngine {
             return new Date(now + continuousDelayMs(consecutiveEmptyRuns)).toISOString();
         }
         const store = this.store;
-        return store?.get(record.id)?.nextFireAt ?? new Date(now + record.timing.everyMs).toISOString();
+        return store?.get(record.id)?.nextFireAt ?? computeNextFireAt(record.timing, new Date(now));
     }
     broadcastSchedules() {
         if (!this.store)

package/dist/server/services/sdk/agent-schedule.js

@@ -0,0 +1,294 @@
+// Copyright (c) 2025-present Minionry, Inc.
+// SPDX-License-Identifier: LicenseRef-Minionry-Software
+import { isValidMaxLatenessMs, } from '../schedule/agent-schedule-store.js';
+import { normalizeWallClockTiming } from '../schedule/daily-timing.js';
+import { isValidPromptFilePath, readPromptFile } from '../schedule/prompt-file.js';
+import { logAppAudit } from './audit.js';
+import { guardWorkspacePath, WORKSPACE_PATH_PREFIX } from './files-workspace.js';
+import { SdkMethodError } from './registry.js';
+function toAgentScheduleSnapshot(record) {
+    const snapshot = {
+        id: record.id,
+        createdAt: record.createdAt,
+        prompt: record.prompt,
+        timing: record.timing,
+        enabled: record.enabled,
+        nextFireAt: record.nextFireAt,
+        history: record.history.map((entry) => ({ ...entry })),
+    };
+    if (record.name !== undefined)
+        snapshot.name = record.name;
+    if (record.promptFile !== undefined)
+        snapshot.promptFile = `${WORKSPACE_PATH_PREFIX}/${record.promptFile}`;
+    if (record.lastFire !== undefined)
+        snapshot.lastFire = { ...record.lastFire };
+    if (record.maxLatenessMs !== undefined)
+        snapshot.maxLatenessMs = record.maxLatenessMs;
+    return snapshot;
+}
+function ownedByCaller(record, appId) {
+    return record.initiator?.appId === appId;
+}
+let scheduleHost = null;
+export function setSdkAgentScheduleHost(host) {
+    scheduleHost = host;
+}
+export function resetSdkAgentScheduleHost() {
+    scheduleHost = null;
+}
+function requireScheduleHost(method) {
+    if (!scheduleHost) {
+        throw new SdkMethodError('INTERNAL', `'${method}' host is not wired — the WebSocket handler installs it at startup`);
+    }
+    return scheduleHost;
+}
+function paramsObject(params) {
+    return typeof params === 'object' && params !== null && !Array.isArray(params)
+        ? params
+        : {};
+}
+function parseScheduleIdParams(params, method) {
+    const raw = paramsObject(params);
+    if (typeof raw.scheduleId !== 'string' || raw.scheduleId.trim() === '') {
+        throw new SdkMethodError('BAD_REQUEST', `${method} requires params { scheduleId }`);
+    }
+    return raw.scheduleId;
+}
+function scheduleNotFound(scheduleId) {
+    return new SdkMethodError('BAD_REQUEST', `schedule '${scheduleId}' not found in this Space`);
+}
+function parseTiming(raw, method) {
+    if (raw && typeof raw === 'object') {
+        const t = raw;
+        if (t.kind === 'once' && typeof t.at === 'string' && !Number.isNaN(Date.parse(t.at))) {
+            return { kind: 'once', at: t.at };
+        }
+        if (t.kind === 'interval' && typeof t.everyMs === 'number' && Number.isFinite(t.everyMs)) {
+            return { kind: 'interval', everyMs: t.everyMs };
+        }
+        if (t.kind === 'daily' || t.kind === 'monthly') {
+            const normalized = normalizeWallClockTiming(raw);
+            if (normalized)
+                return normalized;
+        }
+    }
+    throw new SdkMethodError('BAD_REQUEST', `${method}: timing must be {kind:'once',at}, {kind:'interval',everyMs}, {kind:'daily',time,timeZone,days?} or {kind:'monthly',time,timeZone,dayOfMonth} — 'continuous' is not supported for agent-prompt schedules`);
+}
+function parseMaxLatenessCreateField(raw, method) {
+    if (raw === undefined)
+        return undefined;
+    if (!isValidMaxLatenessMs(raw)) {
+        throw new SdkMethodError('BAD_REQUEST', `${method}: maxLatenessMs must be an integer >= the schedule minimum`);
+    }
+    return raw;
+}
+function parseMaxLatenessPatchValue(raw, method) {
+    if (raw === null)
+        return null;
+    if (!isValidMaxLatenessMs(raw)) {
+        throw new SdkMethodError('BAD_REQUEST', `${method}: maxLatenessMs must be an integer >= the schedule minimum, or null to clear it`);
+    }
+    return raw;
+}
+function resolvePromptFileParam(workingDir, raw, method) {
+    if (typeof raw !== 'string' || !raw.startsWith(WORKSPACE_PATH_PREFIX)) {
+        throw new SdkMethodError('BAD_REQUEST', `${method}: promptFile must be a workspace-rooted path ('${WORKSPACE_PATH_PREFIX}/<path>')`);
+    }
+    const rel = raw.slice(WORKSPACE_PATH_PREFIX.length).replace(/^\/+/, '');
+    if (!isValidPromptFilePath(rel)) {
+        throw new SdkMethodError('BAD_REQUEST', `${method}: promptFile '${raw}' must not contain a '..' segment`);
+    }
+    guardWorkspacePath(workingDir, rel);
+    const result = readPromptFile(workingDir, rel);
+    if (!result.ok) {
+        throw new SdkMethodError('BAD_REQUEST', `${method}: ${result.reason}`);
+    }
+    return { prompt: result.content, promptFile: rel };
+}
+function parseCreateParams(args) {
+    const raw = paramsObject(args.params);
+    const hasPrompt = raw.prompt !== undefined;
+    const hasPromptFile = raw.promptFile !== undefined;
+    if (hasPrompt === hasPromptFile) {
+        throw new SdkMethodError('BAD_REQUEST', `${args.method} requires exactly one of params.prompt or params.promptFile`);
+    }
+    let prompt;
+    let promptFile;
+    if (hasPromptFile) {
+        const resolved = resolvePromptFileParam(args.workingDir, raw.promptFile, args.method);
+        prompt = resolved.prompt;
+        promptFile = resolved.promptFile;
+    }
+    else {
+        if (typeof raw.prompt !== 'string' || raw.prompt.trim() === '') {
+            throw new SdkMethodError('BAD_REQUEST', `${args.method}: params.prompt must be a non-empty string`);
+        }
+        prompt = raw.prompt.trim();
+    }
+    const timing = parseTiming(raw.timing, args.method);
+    const parsed = { prompt, timing };
+    if (promptFile !== undefined)
+        parsed.promptFile = promptFile;
+    if (typeof raw.name === 'string')
+        parsed.name = raw.name;
+    if (raw.enabled !== undefined) {
+        if (typeof raw.enabled !== 'boolean') {
+            throw new SdkMethodError('BAD_REQUEST', `${args.method}: enabled must be a boolean when present`);
+        }
+        parsed.enabled = raw.enabled;
+    }
+    const maxLatenessMs = parseMaxLatenessCreateField(raw.maxLatenessMs, args.method);
+    if (maxLatenessMs !== undefined)
+        parsed.maxLatenessMs = maxLatenessMs;
+    return parsed;
+}
+function applyContentPatchFields(args, patchObj, patch) {
+    if (patchObj.prompt !== undefined && patchObj.promptFile !== undefined) {
+        throw new SdkMethodError('BAD_REQUEST', `${args.method}: provide at most one of patch.prompt or patch.promptFile`);
+    }
+    if (patchObj.name !== undefined) {
+        if (typeof patchObj.name !== 'string') {
+            throw new SdkMethodError('BAD_REQUEST', `${args.method}: patch.name must be a string when present`);
+        }
+        patch.name = patchObj.name;
+    }
+    if (patchObj.prompt !== undefined) {
+        if (typeof patchObj.prompt !== 'string' || patchObj.prompt.trim() === '') {
+            throw new SdkMethodError('BAD_REQUEST', `${args.method}: patch.prompt must be a non-empty string`);
+        }
+        patch.prompt = patchObj.prompt.trim();
+    }
+    if (patchObj.promptFile !== undefined) {
+        const resolved = resolvePromptFileParam(args.workingDir, patchObj.promptFile, args.method);
+        patch.prompt = resolved.prompt;
+        patch.promptFile = resolved.promptFile;
+    }
+}
+function applyStructuredPatchFields(args, patchObj, patch) {
+    if (patchObj.enabled !== undefined) {
+        if (typeof patchObj.enabled !== 'boolean') {
+            throw new SdkMethodError('BAD_REQUEST', `${args.method}: patch.enabled must be a boolean when present`);
+        }
+        patch.enabled = patchObj.enabled;
+    }
+    if (patchObj.timing !== undefined)
+        patch.timing = parseTiming(patchObj.timing, args.method);
+    if (patchObj.maxLatenessMs !== undefined) {
+        patch.maxLatenessMs = parseMaxLatenessPatchValue(patchObj.maxLatenessMs, args.method);
+    }
+}
+function parseUpdateParams(args) {
+    const scheduleId = parseScheduleIdParams(args.params, args.method);
+    const raw = paramsObject(args.params);
+    const rawPatch = raw.patch;
+    if (typeof rawPatch !== 'object' || rawPatch === null || Array.isArray(rawPatch)) {
+        throw new SdkMethodError('BAD_REQUEST', `${args.method} requires params.patch to be an object`);
+    }
+    const patchObj = rawPatch;
+    const patch = {};
+    applyContentPatchFields(args, patchObj, patch);
+    applyStructuredPatchFields(args, patchObj, patch);
+    return { scheduleId, patch };
+}
+function paramsCarryPromptFile(params) {
+    const raw = paramsObject(params);
+    if (raw.promptFile !== undefined)
+        return true;
+    const patch = paramsObject(raw.patch);
+    return patch.promptFile !== undefined;
+}
+export function resolveAgentSchedulesScopes(params) {
+    return paramsCarryPromptFile(params) ? ['agents:schedule', 'files:workspace:read'] : ['agents:schedule'];
+}
+export function agentSchedulesListHandler(args) {
+    const host = requireScheduleHost(args.method);
+    const store = host.getStore(args.workingDir);
+    const schedules = store
+        .list()
+        .filter((record) => ownedByCaller(record, args.appId))
+        .map(toAgentScheduleSnapshot);
+    return { schedules };
+}
+export function agentSchedulesCreateHandler(args) {
+    const host = requireScheduleHost(args.method);
+    const { name, prompt, promptFile, timing, enabled, maxLatenessMs } = parseCreateParams(args);
+    const store = host.getStore(args.workingDir);
+    const record = store.create({
+        name,
+        prompt,
+        ...(promptFile !== undefined ? { promptFile } : {}),
+        initiator: { appId: args.appId, origin: args.origin },
+        timing,
+        enabled,
+        maxLatenessMs,
+    });
+    host.notifyAndBroadcast(args.workingDir);
+    logAppAudit({
+        appId: args.appId,
+        origin: args.origin,
+        method: 'agents.schedules.create.created',
+        decision: 'allow',
+        requestId: args.requestId,
+        spaceKey: args.spaceKey,
+        reason: `schedule ${record.id} created (nextFireAt=${record.nextFireAt ?? 'none'})`,
+    });
+    return toAgentScheduleSnapshot(record);
+}
+export function agentSchedulesUpdateHandler(args) {
+    const host = requireScheduleHost(args.method);
+    const { scheduleId, patch } = parseUpdateParams(args);
+    const store = host.getStore(args.workingDir);
+    const existing = store.get(scheduleId);
+    if (!existing || !ownedByCaller(existing, args.appId))
+        throw scheduleNotFound(scheduleId);
+    const record = store.update(scheduleId, patch);
+    if (!record)
+        throw scheduleNotFound(scheduleId);
+    host.notifyAndBroadcast(args.workingDir);
+    return toAgentScheduleSnapshot(record);
+}
+export function agentSchedulesDeleteHandler(args) {
+    const host = requireScheduleHost(args.method);
+    const scheduleId = parseScheduleIdParams(args.params, args.method);
+    const store = host.getStore(args.workingDir);
+    const existing = store.get(scheduleId);
+    if (!existing || !ownedByCaller(existing, args.appId))
+        throw scheduleNotFound(scheduleId);
+    if (!store.delete(scheduleId))
+        throw scheduleNotFound(scheduleId);
+    host.notifyAndBroadcast(args.workingDir);
+    logAppAudit({
+        appId: args.appId,
+        origin: args.origin,
+        method: 'agents.schedules.delete.deleted',
+        decision: 'allow',
+        requestId: args.requestId,
+        spaceKey: args.spaceKey,
+        reason: `schedule ${scheduleId} deleted`,
+    });
+    return null;
+}
+export function agentSchedulesRunNowHandler(args) {
+    const host = requireScheduleHost(args.method);
+    const scheduleId = parseScheduleIdParams(args.params, args.method);
+    const store = host.getStore(args.workingDir);
+    const existing = store.get(scheduleId);
+    if (!existing || !ownedByCaller(existing, args.appId))
+        throw scheduleNotFound(scheduleId);
+    const result = host.fireNow(args.workingDir, scheduleId);
+    if (result.kind === 'not-found')
+        throw scheduleNotFound(scheduleId);
+    if (result.kind === 'disabled') {
+        throw new SdkMethodError('BAD_REQUEST', `schedule '${scheduleId}' is disabled — enable it before running it now`);
+    }
+    logAppAudit({
+        appId: args.appId,
+        origin: args.origin,
+        method: 'agents.schedules.runNow.fired',
+        decision: 'allow',
+        requestId: args.requestId,
+        spaceKey: args.spaceKey,
+        reason: `schedule ${scheduleId} fired on demand`,
+    });
+    return toAgentScheduleSnapshot(result.record);
+}

package/dist/server/services/sdk/agents.js

@@ -7,6 +7,7 @@ import { hermesAvailability, MINIMUM_HERMES_APP_RUN_VERSION } from '../../engine
 import { getQualityEffortLevel, getQualityEngine, getQualityFastMode, getQualityModel } from '../settings.js';
 import { resolveAppOwnedModel } from './app-endpoints.js';
 import { logAppAudit } from './audit.js';
+import { resolveAutomationTarget } from './browser.js';
 import { deregisterLiveRun, findLiveRunByTab, listLiveSubscriptions, registerLiveRun } from './live-registry.js';
 import { SdkMethodError } from './registry.js';
 import { dropSubscription } from './revoke.js';
@@ -90,17 +91,19 @@ function cancelRunRecord(record, cause) {
         record.cancelledBy = cause;
     record.cancelRun();
 }
-const RUN_PARAMS_SHAPE = '{ prompt, title?, model?, modelSelection?, systemPrompt?, budget?: { maxTurns?, maxSeconds? }, sessionId? }';
+const RUN_PARAMS_SHAPE = '{ prompt, title?, model?, modelSelection?, engineSelection?: { engine?, model?, effortLevel?, fastMode? }, systemPrompt?, budget?: { maxTurns?, maxSeconds? }, sessionId? }';
 const RUN_PARAM_KEYS = new Set([
     'prompt',
     'title',
     'model',
     'modelSelection',
+    'engineSelection',
     'systemPrompt',
     'budget',
     'sessionId',
 ]);
 const BUDGET_KEYS = new Set(['maxTurns', 'maxSeconds']);
+const ENGINE_SELECTION_KEYS = new Set(['engine', 'model', 'effortLevel', 'fastMode']);
 function badRequest(message) {
     return new SdkMethodError('BAD_REQUEST', message);
 }
@@ -161,14 +164,50 @@ function parseModelSelection(raw) {
     }
     return name;
 }
-function assertRunFieldsCombine({ model, modelSelection, systemPrompt, budget, sessionId }) {
-    const choosesModel = model !== undefined || modelSelection !== undefined;
+function optionalEngineSelectionString(raw, field) {
+    const value = raw[field];
+    if (value === undefined)
+        return undefined;
+    if (typeof value !== 'string' || value === '') {
+        throw badRequest(`agents.run engineSelection.${field} must be a non-empty string when present`);
+    }
+    return value;
+}
+function parseEngineSelection(raw) {
+    if (raw === undefined)
+        return undefined;
+    if (typeof raw !== 'object' || raw === null || Array.isArray(raw)) {
+        throw badRequest('agents.run engineSelection must be an object { engine?, model?, effortLevel?, fastMode? }');
+    }
+    const obj = raw;
+    refuseUnknownKeys(obj, ENGINE_SELECTION_KEYS, 'agents.run engineSelection', '{ engine?, model?, effortLevel?, fastMode? }');
+    const engine = optionalEngineSelectionString(obj, 'engine');
+    const model = optionalEngineSelectionString(obj, 'model');
+    const effortLevel = optionalEngineSelectionString(obj, 'effortLevel');
+    if (obj.fastMode !== undefined && typeof obj.fastMode !== 'boolean') {
+        throw badRequest('agents.run engineSelection.fastMode must be a boolean when present');
+    }
+    return {
+        ...(engine !== undefined ? { engine } : {}),
+        ...(model !== undefined ? { model } : {}),
+        ...(effortLevel !== undefined ? { effortLevel } : {}),
+        ...(obj.fastMode !== undefined ? { fastMode: obj.fastMode } : {}),
+    };
+}
+function assertRunFieldsCombine({ model, modelSelection, engineSelection, systemPrompt, budget, sessionId }) {
+    const choosesModel = model !== undefined || modelSelection !== undefined || engineSelection !== undefined;
     if (sessionId !== undefined && (choosesModel || systemPrompt !== undefined || budget !== undefined)) {
-        throw badRequest('agents.run with sessionId continues that session on its own model, systemPrompt and budget — omit model, modelSelection, systemPrompt and budget');
+        throw badRequest('agents.run with sessionId continues that session on its own model, systemPrompt and budget — omit model, modelSelection, engineSelection, systemPrompt and budget');
     }
     if (model !== undefined && modelSelection !== undefined) {
         throw badRequest('agents.run takes model or modelSelection, not both');
     }
+    if (model !== undefined && engineSelection !== undefined) {
+        throw badRequest('agents.run takes model or engineSelection, not both');
+    }
+    if (modelSelection !== undefined && engineSelection !== undefined) {
+        throw badRequest('agents.run takes modelSelection or engineSelection, not both');
+    }
     if (model === undefined && (systemPrompt !== undefined || budget !== undefined)) {
         throw badRequest('agents.run systemPrompt and budget apply only to a run on an app-registered model — pass model');
     }
@@ -185,15 +224,17 @@ function parseRunParams(params) {
     const title = optionalString(raw, 'title', false);
     const model = optionalString(raw, 'model', true);
     const modelSelection = parseModelSelection(raw.modelSelection);
+    const engineSelection = parseEngineSelection(raw.engineSelection);
     const sessionId = optionalString(raw, 'sessionId', true);
     const systemPrompt = parseSystemPrompt(raw.systemPrompt);
     const budget = raw.budget === undefined ? undefined : parseBudget(raw.budget);
-    assertRunFieldsCombine({ model, modelSelection, systemPrompt, budget, sessionId });
+    assertRunFieldsCombine({ model, modelSelection, engineSelection, systemPrompt, budget, sessionId });
     return {
         prompt: raw.prompt,
         ...(title !== undefined ? { title } : {}),
         ...(model !== undefined ? { model } : {}),
         ...(modelSelection !== undefined ? { modelSelection } : {}),
+        ...(engineSelection !== undefined ? { engineSelection } : {}),
         ...(systemPrompt !== undefined ? { systemPrompt } : {}),
         ...(budget !== undefined ? { budget } : {}),
         ...(sessionId !== undefined ? { sessionId } : {}),
@@ -226,15 +267,26 @@ async function admitAppOwnedModel(modelValue, args) {
 }
 export function resolveAgentsRunScopes(params) {
     const raw = typeof params === 'object' && params !== null && !Array.isArray(params) ? params : {};
-    return raw.modelSelection === undefined ? ['agents:run'] : ['agents:run', 'quality:read'];
+    const scopes = ['agents:run'];
+    if (raw.modelSelection !== undefined)
+        scopes.push('quality:read');
+    if (raw.engineSelection !== undefined)
+        scopes.push('settings:read');
+    return scopes;
+}
+export function appRunEngines() {
+    return ['claude-code'];
 }
-function assertUserClaudeProfile(model) {
+function engineUnavailableForAppRun(engine) {
+    return new SdkMethodError('ENGINE_UNAVAILABLE', `agents.run: ${engine} cannot run an app session with tools on this host — choose one of ${appRunEngines().join(', ') || '(none)'}`);
+}
+function assertUserOwnedProfile(model, engine) {
     const parsed = parseProfileModelValue(model);
     if (!parsed)
         return;
     const profile = new ModelProfileStore().get(parsed.profileId);
-    if (!profile || profile.owner || profile.engine !== 'claude-code' || parsed.engine !== 'claude-code') {
-        throw new SdkMethodError('MODEL_NOT_ALLOWED', `agents.run: the Quality model '${displayValue(model)}' is not a Claude Code model added on this machine — choose another model for Quality`);
+    if (!profile || profile.owner || profile.engine !== engine || parsed.engine !== engine) {
+        throw new SdkMethodError('MODEL_NOT_ALLOWED', `agents.run: the model '${displayValue(model)}' is not a ${engine} model added on this machine — choose another model`);
     }
 }
 function admitModelSelection(name, args) {
@@ -243,15 +295,16 @@ function admitModelSelection(name, args) {
         throw new SdkMethodError('SCOPE_DENIED', `agents.run: modelSelection '${name}' needs the quality:read scope`);
     }
     const engine = getQualityEngine();
-    if (engine !== 'claude-code') {
-        throw new SdkMethodError('ENGINE_UNAVAILABLE', `agents.run: the Quality model runs on ${engine}, and only Claude Code can run an app session with tools — choose a Claude Code model for Quality`);
+    if (!appRunEngines().includes(engine)) {
+        throw engineUnavailableForAppRun(engine);
     }
     const stored = getQualityModel();
     const model = stored !== 'default' && engineForModel(stored) === engine ? stored : undefined;
     if (model)
-        assertUserClaudeProfile(model);
+        assertUserOwnedProfile(model, engine);
     const effortLevel = getQualityEffortLevel();
     return {
+        origin: 'quality',
         name,
         engine,
         ...(model ? { model } : {}),
@@ -259,6 +312,32 @@ function admitModelSelection(name, args) {
         fastMode: getQualityFastMode(),
     };
 }
+function admitEngineSelection(raw, args) {
+    const granted = args.grant?.scopes ?? [];
+    if (!granted.includes('settings:read')) {
+        throw new SdkMethodError('SCOPE_DENIED', 'agents.run: engineSelection needs the settings:read scope');
+    }
+    const { engine, model } = resolveAutomationTarget(raw.engine, raw.model, 'agents.run engineSelection');
+    if (!appRunEngines().includes(engine)) {
+        throw engineUnavailableForAppRun(engine);
+    }
+    if (model)
+        assertUserOwnedProfile(model, engine);
+    if (raw.effortLevel !== undefined && raw.effortLevel !== 'auto' && !ENGINE_EFFORT_LEVELS[engine].includes(raw.effortLevel)) {
+        const accepted = ENGINE_EFFORT_LEVELS[engine].length > 0 ? ENGINE_EFFORT_LEVELS[engine].join(', ') : 'auto';
+        throw badRequest(`agents.run: engineSelection.effortLevel '${displayValue(raw.effortLevel)}' is not a ${engine} effort level — expected one of ${accepted}`);
+    }
+    if (raw.fastMode === true && engine !== 'claude-code') {
+        throw badRequest(`agents.run: engineSelection.fastMode is a claude-code setting — ${engine} has no fast mode`);
+    }
+    return {
+        origin: 'app',
+        engine,
+        ...(model ? { model } : {}),
+        effortLevel: raw.effortLevel ?? 'auto',
+        fastMode: raw.fastMode === true,
+    };
+}
 function findAppRunSession(args, sessionId) {
     const session = sessionsByTab.get(sessionId);
     if (!session || session.appId !== args.appId || session.spaceKey !== args.spaceKey) {
@@ -299,6 +378,9 @@ export async function admitAgentRun(args, claim = false) {
     if (request.modelSelection !== undefined) {
         return { kind: 'start', request, selection: admitModelSelection(request.modelSelection, args) };
     }
+    if (request.engineSelection !== undefined) {
+        return { kind: 'start', request, selection: admitEngineSelection(request.engineSelection, args) };
+    }
     if (request.model === undefined)
         return { kind: 'start', request };
     const engine = await admitAppOwnedModel(request.model, args);
@@ -448,7 +530,7 @@ function runStartReason(record, ceiling, continued, model) {
 function selectionAuditSuffix(selection) {
     if (!selection)
         return '';
-    return ` selection=${selection.name} engine=${selection.engine} model=${displayValue(selection.model ?? 'default')}`;
+    return ` selection=${selection.origin} engine=${selection.engine} model=${displayValue(selection.model ?? 'default')}`;
 }
 export function agentsResultHandler(args) {
     const raw = (typeof args.params === 'object' && args.params !== null && !Array.isArray(args.params))