newmark-agent 0.6.4 → 0.6.8

package/dist/core/routeDecisionValidator.js

@@ -0,0 +1,249 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.JevDecisionValidationError = void 0;
+exports.validateJevDecision = validateJevDecision;
+exports.buildRouteDecision = buildRouteDecision;
+exports.resolveAutoRouteDecision = resolveAutoRouteDecision;
+const autoRouter_1 = require("./autoRouter");
+const jevDecision_1 = require("./jevDecision");
+const routeEligibility_1 = require("./routeEligibility");
+class JevDecisionValidationError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = 'JevDecisionValidationError';
+    }
+}
+exports.JevDecisionValidationError = JevDecisionValidationError;
+function validDeployment(deployment) {
+    if (!deployment || typeof deployment !== 'object')
+        return false;
+    const candidate = deployment;
+    return !!String(candidate.providerId || '').trim() && !!String(candidate.modelId || '').trim();
+}
+function normalizeDeployment(deployment) {
+    const logicalModelGroupId = String(deployment.logicalModelGroupId || '').trim();
+    return {
+        providerId: String(deployment.providerId),
+        modelId: String(deployment.modelId),
+        ...(logicalModelGroupId ? { logicalModelGroupId } : {}),
+    };
+}
+/**
+ * Validate a decision engine output against the Guard result.
+ *
+ * The engine may only choose inside the space the Guard allowed. Alternates
+ * that leave that space are dropped (they are recovery hints, not primary
+ * decisions), while an ineligible primary is a hard failure: routing must fall
+ * back deterministically instead of silently executing something the Guard
+ * excluded.
+ */
+function validateJevDecision(decision, eligible, options = {}) {
+    if (!eligible.length) {
+        throw new JevDecisionValidationError('no_eligible_candidates', 'No eligible candidate was available for Auto selection');
+    }
+    if (!decision || typeof decision !== 'object') {
+        throw new JevDecisionValidationError('missing_primary', 'The decision engine returned no decision');
+    }
+    if (!validDeployment(decision.primary)) {
+        throw new JevDecisionValidationError('missing_primary', 'The decision engine returned no usable primary deployment');
+    }
+    const allowed = new Map(eligible.map(candidate => [
+        `${candidate.deployment.providerId}\u0000${candidate.deployment.modelId}`,
+        candidate,
+    ]));
+    const primary = normalizeDeployment(decision.primary);
+    const allowedPrimary = allowed.get(`${primary.providerId}\u0000${primary.modelId}`);
+    if (!allowedPrimary) {
+        throw new JevDecisionValidationError('primary_not_eligible', `The decision engine selected ${primary.providerId}/${primary.modelId}, which the eligibility guard excluded`);
+    }
+    const maxAlternates = Math.max(0, options.maxAlternates ?? jevDecision_1.DEFAULT_JEV_MAX_ALTERNATES);
+    const alternates = [];
+    const droppedAlternates = [];
+    const rawAlternates = Array.isArray(decision.alternates) ? decision.alternates : [];
+    for (const raw of rawAlternates) {
+        if (!validDeployment(raw)) {
+            droppedAlternates.push({ deployment: { providerId: String(raw?.providerId || ''), modelId: String(raw?.modelId || '') }, reason: 'invalid_deployment' });
+            continue;
+        }
+        const alternate = normalizeDeployment(raw);
+        if ((0, routeEligibility_1.sameDeploymentRef)(alternate, primary)) {
+            droppedAlternates.push({ deployment: alternate, reason: 'primary_duplicate' });
+            continue;
+        }
+        if (!allowed.get(`${alternate.providerId}\u0000${alternate.modelId}`)) {
+            droppedAlternates.push({ deployment: alternate, reason: 'not_eligible' });
+            continue;
+        }
+        if (alternates.some(existing => (0, routeEligibility_1.sameDeploymentRef)(existing, alternate))) {
+            droppedAlternates.push({ deployment: alternate, reason: 'duplicate' });
+            continue;
+        }
+        if (alternates.length >= maxAlternates) {
+            droppedAlternates.push({ deployment: alternate, reason: 'over_limit' });
+            continue;
+        }
+        alternates.push(alternate);
+    }
+    return {
+        primary: { ...allowedPrimary.deployment, ...primary, ...(allowedPrimary.deployment.logicalModelGroupId && !primary.logicalModelGroupId
+                ? { logicalModelGroupId: allowedPrimary.deployment.logicalModelGroupId }
+                : {}) },
+        alternates,
+        reasonCodes: Array.isArray(decision.reasonCodes) ? decision.reasonCodes.map(code => String(code)) : [],
+        ...(typeof decision.confidence === 'number' && Number.isFinite(decision.confidence) ? { confidence: decision.confidence } : {}),
+        modelVersion: String(decision.modelVersion || 'unknown'),
+        droppedAlternates,
+    };
+}
+function buildRouteDecision(input) {
+    return {
+        routeId: input.routeId,
+        requestedSelection: input.selection,
+        policyVersion: input.policyVersion,
+        decisionSource: input.decisionSource,
+        catalogSnapshotHash: input.catalogSnapshotHash,
+        taskClasses: [...input.taskClasses],
+        excludedCandidates: input.excluded.map(entry => ({ deployment: { ...entry.deployment }, reasons: [...entry.reasons] })),
+        resolvedDeployment: { ...input.decision.primary },
+        alternatives: input.decision.alternates.map(deployment => ({ ...deployment })),
+        jev: input.jev,
+        ...(input.decisionError ? { decisionError: input.decisionError } : {}),
+        ...(input.pinReason ? { pinReason: input.pinReason } : {}),
+        attempts: input.attempts ? input.attempts.map(attempt => ({ ...attempt })) : [],
+        finalStatus: input.finalStatus || 'resolved',
+        ...(input.retryBudgetMs === undefined ? {} : { retryBudgetMs: input.retryBudgetMs }),
+    };
+}
+/**
+ * The single Auto decision pipeline used by the Agent and by the verification
+ * suite. Keeping it here (instead of inline in the Agent) is what guarantees
+ * that tests exercise the shipping order of stages:
+ *
+ *   guard → decision engine → validator → optional transaction pin
+ */
+async function resolveAutoRouteDecision(input) {
+    const { selection, policy, taskText, request, candidates, taskClasses, } = input;
+    const routeId = input.routeId || (0, autoRouter_1.createRouteId)();
+    const policyVersion = input.policyVersion || 'newmark-auto-v2';
+    const base = {
+        routeId,
+        policyVersion,
+        taskClasses,
+        retryBudgetMs: request.batch ? 15_000 : 5_000,
+    };
+    const eligibility = (0, routeEligibility_1.evaluateRouteEligibility)({ selection, policy, request, candidates });
+    const catalogHash = (0, autoRouter_1.catalogSnapshotHash)(candidates);
+    if (!eligibility.eligible.length) {
+        return {
+            routeId: base.routeId,
+            requestedSelection: selection,
+            policyVersion: base.policyVersion,
+            decisionSource: 'jev',
+            catalogSnapshotHash: catalogHash,
+            taskClasses,
+            excludedCandidates: eligibility.excluded,
+            alternatives: [],
+            jev: { modelVersion: jevDecision_1.JEV_ROUTE_MODEL_VERSION, reasonCodes: [...taskClasses, 'no_eligible_candidate'], latencyMs: 0 },
+            attempts: [],
+            finalStatus: 'no_candidate',
+            retryBudgetMs: base.retryBudgetMs,
+        };
+    }
+    const timeoutMs = Number.isFinite(input.timeoutMs) && Number(input.timeoutMs) > 0
+        ? Math.min(5_000, Number(input.timeoutMs))
+        : jevDecision_1.DEFAULT_JEV_TIMEOUT_MS;
+    let decisionError = '';
+    let failureCode = '';
+    let validated = null;
+    let jevLatencyMs = 0;
+    if (input.engine) {
+        const jevRequest = (0, jevDecision_1.buildJevRouteRequest)({
+            transactionId: request.transactionId,
+            taskText,
+            taskClasses,
+            estimatedInputTokens: request.estimatedInputTokens,
+            expectedOutputTokens: request.expectedOutputTokens,
+            requiredCapabilities: request.requiredCapabilities,
+            intelligence: input.intelligence || 'default',
+            policy,
+            request,
+            candidates: eligibility.eligible,
+            previousDeployment: input.previousDeployment,
+        });
+        const outcome = await (0, jevDecision_1.decideWithinBudget)(input.engine, jevRequest, timeoutMs);
+        jevLatencyMs = outcome.latencyMs;
+        try {
+            if (!outcome.decision)
+                throw new Error(outcome.error?.message || 'The current model returned no JEV decision');
+            validated = validateJevDecision(outcome.decision, eligibility.eligible);
+        }
+        catch (error) {
+            failureCode = outcome.error?.code
+                || (error instanceof JevDecisionValidationError ? error.code : 'invalid_output');
+            decisionError = `${failureCode}: ${error instanceof Error ? error.message : String(error)}`;
+        }
+    }
+    else {
+        failureCode = input.unavailableReason || 'runtime_unavailable';
+        decisionError = `${failureCode}: current-model JEV routing is not available`;
+    }
+    if (!validated) {
+        return {
+            routeId: base.routeId,
+            requestedSelection: selection,
+            policyVersion: base.policyVersion,
+            decisionSource: 'jev',
+            catalogSnapshotHash: catalogHash,
+            taskClasses,
+            excludedCandidates: eligibility.excluded,
+            alternatives: [],
+            jev: { modelVersion: jevDecision_1.JEV_ROUTE_MODEL_VERSION, reasonCodes: [...taskClasses, `decision_failed:${failureCode || 'unknown'}`], latencyMs: jevLatencyMs },
+            decisionError: decisionError || 'current-model decision did not produce a valid JSON route',
+            attempts: [],
+            finalStatus: 'no_candidate',
+            retryBudgetMs: base.retryBudgetMs,
+        };
+    }
+    // Transaction pinning keeps one Build on one deployment. It is execution
+    // consistency, not a second routing decision: the pin can only ever hold a
+    // deployment the guard already accepted, and a fresh Auto route outside the
+    // transaction is decided by JEV alone.
+    let primary = validated.primary;
+    let alternates = validated.alternates;
+    let pinReason;
+    const pinned = input.pinnedDeployment;
+    if (pinned
+        && !(0, routeEligibility_1.sameDeploymentRef)(pinned, primary)
+        && eligibility.eligible.some(candidate => (0, routeEligibility_1.sameDeploymentRef)(candidate.deployment, pinned))) {
+        const previousPrimary = validated.primary;
+        primary = { ...pinned };
+        pinReason = 'transaction';
+        alternates = [previousPrimary, ...validated.alternates]
+            .filter(deployment => !(0, routeEligibility_1.sameDeploymentRef)(deployment, primary))
+            .filter((deployment, index, list) => list.findIndex(item => (0, routeEligibility_1.sameDeploymentRef)(item, deployment)) === index)
+            .slice(0, jevDecision_1.DEFAULT_JEV_MAX_ALTERNATES);
+    }
+    return buildRouteDecision({
+        routeId: base.routeId,
+        selection,
+        policyVersion: base.policyVersion,
+        decisionSource: 'jev',
+        catalogSnapshotHash: catalogHash,
+        taskClasses,
+        excluded: eligibility.excluded,
+        decision: { ...validated, primary, alternates },
+        jev: {
+            modelVersion: validated.modelVersion,
+            ...(validated.confidence === undefined ? {} : { confidence: validated.confidence }),
+            reasonCodes: validated.reasonCodes,
+            latencyMs: jevLatencyMs,
+        },
+        ...(pinReason ? { pinReason } : {}),
+        attempts: [{ deployment: { ...primary }, kind: 'initial', status: 'planned' }],
+        finalStatus: 'resolved',
+        retryBudgetMs: base.retryBudgetMs,
+    });
+}
+//# sourceMappingURL=routeDecisionValidator.js.map

package/dist/core/routeEligibility.d.ts

@@ -0,0 +1,52 @@
+/**
+ * RouteEligibilityGuard — Auto Router v2 hard-eligibility stage.
+ *
+ * This module answers exactly one question: "which candidate deployments may
+ * the decision engine even see?". It never answers "which candidate is
+ * better". Ranking, scoring, learned preference, cost/speed utility and cache
+ * affinity are therefore absent by design; the only decision source downstream
+ * of this file is the JEV decision engine.
+ *
+ * Keep this file free of history: no feedback log, no quality_by_task, no
+ * user-rating history, no endpoint statistics. Endpoint health is operational
+ * input for the decision engine, not an eligibility rule (an endpoint that is
+ * currently failing must stay visible so the system can still probe it).
+ */
+import type { AutoRouteCandidate, AutoScope, DeploymentRef, ModelSelection, RoutePolicy, RouteRequest } from './autoRouter';
+export interface RouteExclusion {
+    deployment: DeploymentRef;
+    reasons: string[];
+}
+export interface RouteEligibilityRequest {
+    selection: ModelSelection;
+    policy: RoutePolicy;
+    request: RouteRequest;
+    candidates: AutoRouteCandidate[];
+}
+export interface RouteEligibilityResult {
+    eligible: AutoRouteCandidate[];
+    excluded: RouteExclusion[];
+}
+export declare function deploymentKey(deployment: DeploymentRef): string;
+export declare function sameDeploymentRef(left: DeploymentRef, right: DeploymentRef): boolean;
+export declare function inAutoScope(deployment: DeploymentRef, scope: AutoScope): boolean;
+export declare function inAutoSubset(deployment: DeploymentRef, subset: DeploymentRef[] | undefined): boolean;
+export declare function expectedRequestCost(candidate: AutoRouteCandidate, request: RouteRequest): number | undefined;
+/**
+ * The single authoritative implementation of Auto hard eligibility.
+ *
+ * `Agent.autoRouteCandidates()` only projects configuration into candidate
+ * facts (enabled flag, capability list, prices, context window, privacy and
+ * region declarations, observed endpoint health). Every hard rule that can
+ * remove a candidate lives here so there is never a second copy of the rules
+ * in the Agent or in the execution controller.
+ */
+export declare function evaluateRouteEligibility(input: RouteEligibilityRequest): RouteEligibilityResult;
+/**
+ * A candidate excluded by the Guard may still be used by provider-local
+ * recovery when *only* the fallback-only marker removed it. This mirrors the
+ * pre-existing behaviour: fallback-only deployments are never primary
+ * candidates but may serve as an explicit recovery pool.
+ */
+export declare function excludedOnlyForFallbackPool(exclusion: RouteExclusion | undefined): boolean;
+//# sourceMappingURL=routeEligibility.d.ts.map

package/dist/core/routeEligibility.js

@@ -0,0 +1,108 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.deploymentKey = deploymentKey;
+exports.sameDeploymentRef = sameDeploymentRef;
+exports.inAutoScope = inAutoScope;
+exports.inAutoSubset = inAutoSubset;
+exports.expectedRequestCost = expectedRequestCost;
+exports.evaluateRouteEligibility = evaluateRouteEligibility;
+exports.excludedOnlyForFallbackPool = excludedOnlyForFallbackPool;
+function deploymentKey(deployment) {
+    return `${deployment.providerId}\u0000${deployment.modelId}\u0000${deployment.logicalModelGroupId || ''}`;
+}
+function sameDeploymentRef(left, right) {
+    return left.providerId === right.providerId && left.modelId === right.modelId;
+}
+function inAutoScope(deployment, scope) {
+    return scope.kind === 'global' || deployment.providerId === scope.providerId;
+}
+function inAutoSubset(deployment, subset) {
+    if (!subset?.length)
+        return true;
+    return subset.some(item => sameDeploymentRef(item, deployment));
+}
+function expectedRequestCost(candidate, request) {
+    const input = finiteNumber(candidate.expectedInputCostUsdPerM);
+    const output = finiteNumber(candidate.expectedOutputCostUsdPerM);
+    if (input === undefined || output === undefined)
+        return undefined;
+    return input * Math.max(0, request.estimatedInputTokens) / 1_000_000
+        + output * Math.max(0, request.expectedOutputTokens) / 1_000_000;
+}
+function finiteNumber(value) {
+    const number = Number(value);
+    return Number.isFinite(number) ? number : undefined;
+}
+/**
+ * The single authoritative implementation of Auto hard eligibility.
+ *
+ * `Agent.autoRouteCandidates()` only projects configuration into candidate
+ * facts (enabled flag, capability list, prices, context window, privacy and
+ * region declarations, observed endpoint health). Every hard rule that can
+ * remove a candidate lives here so there is never a second copy of the rules
+ * in the Agent or in the execution controller.
+ */
+function evaluateRouteEligibility(input) {
+    const { selection, policy, request, candidates } = input;
+    const eligible = [];
+    const excluded = [];
+    if (selection.kind === 'fixed') {
+        // Fixed selections bypass Auto eligibility entirely; the caller resolves
+        // the deployment directly. Returning an empty guard result keeps this
+        // function honest about what it can decide.
+        return { eligible, excluded };
+    }
+    for (const candidate of candidates) {
+        const reasons = [];
+        if (!candidate.enabled)
+            reasons.push('disabled');
+        if (candidate.unavailableReason)
+            reasons.push(candidate.unavailableReason);
+        if (!inAutoScope(candidate.deployment, selection.scope))
+            reasons.push('outside_scope');
+        if (!inAutoSubset(candidate.deployment, selection.subset))
+            reasons.push('outside_subset');
+        if (candidate.fallbackOnly)
+            reasons.push('fallback_only');
+        if (candidate.preview && !policy.allowPreview)
+            reasons.push('preview_disallowed');
+        if (request.estimatedInputTokens + request.expectedOutputTokens > Math.max(0, candidate.maxContextTokens || 0)) {
+            reasons.push('context_too_small');
+        }
+        if (policy.privacy !== 'default' && !candidate.privacy.includes(policy.privacy))
+            reasons.push(`privacy:${policy.privacy}`);
+        if (policy.dataRegion) {
+            const requiredRegion = policy.dataRegion.toLowerCase();
+            const regions = new Set((candidate.dataRegions || []).map(item => String(item).toLowerCase()));
+            if (!regions.has(requiredRegion))
+                reasons.push(`data_region:${policy.dataRegion}`);
+        }
+        const supportedParameters = new Set((candidate.supportedProtocolParameters || []).map(item => String(item).toLowerCase()));
+        for (const parameter of policy.requiredProtocolParameters || []) {
+            const requiredParameter = String(parameter).toLowerCase();
+            if (requiredParameter && !supportedParameters.has(requiredParameter))
+                reasons.push(`protocol_parameter:${requiredParameter}`);
+        }
+        const expectedCost = expectedRequestCost(candidate, request);
+        if (policy.maxExpectedCostUsd !== undefined && (expectedCost === undefined || expectedCost > policy.maxExpectedCostUsd)) {
+            reasons.push(expectedCost === undefined ? 'unknown_cost' : 'budget_exceeded');
+        }
+        if (reasons.length)
+            excluded.push({ deployment: { ...candidate.deployment }, reasons: [...new Set(reasons)] });
+        else
+            eligible.push(candidate);
+    }
+    return { eligible, excluded };
+}
+/**
+ * A candidate excluded by the Guard may still be used by provider-local
+ * recovery when *only* the fallback-only marker removed it. This mirrors the
+ * pre-existing behaviour: fallback-only deployments are never primary
+ * candidates but may serve as an explicit recovery pool.
+ */
+function excludedOnlyForFallbackPool(exclusion) {
+    return !!exclusion
+        && exclusion.reasons.length > 0
+        && exclusion.reasons.every(reason => reason === 'fallback_only');
+}
+//# sourceMappingURL=routeEligibility.js.map

package/dist/core/runtimeMemoryBudget.d.ts

@@ -0,0 +1,6 @@
+/** Physical RAM policy; never evicts an active run or changes model context. */
+export declare function runtimeMemoryBudget(totalBytes?: number): {
+    maxResidentRuntimes: number;
+    idleTtlMs: number;
+};
+//# sourceMappingURL=runtimeMemoryBudget.d.ts.map

package/dist/core/runtimeMemoryBudget.js

@@ -0,0 +1,12 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runtimeMemoryBudget = runtimeMemoryBudget;
+const node_os_1 = require("node:os");
+/** Physical RAM policy; never evicts an active run or changes model context. */
+function runtimeMemoryBudget(totalBytes = (0, node_os_1.totalmem)()) {
+    const constrained = !Number.isFinite(totalBytes) || totalBytes <= 8 * 1024 ** 3;
+    return constrained
+        ? { maxResidentRuntimes: 2, idleTtlMs: 30_000 }
+        : { maxResidentRuntimes: 8, idleTtlMs: 300_000 };
+}
+//# sourceMappingURL=runtimeMemoryBudget.js.map

package/dist/core/toolPolicy.d.ts

@@ -12,7 +12,7 @@ export interface ToolPolicyDecision {
     settingsVisible: boolean;
     reason?: string;
 }
-export declare const PLAN_COMPUTER_USE_ACTIONS: readonly ["observe", "app_list", "app_observe"];
+export declare const PLAN_COMPUTER_USE_ACTIONS: readonly ["observe", "app_list", "app_observe", "wait_for"];
 export declare const PLAN_BROWSER_USE_ACTIONS: readonly ["observe", "navigate", "wait", "extract"];
 /** 判断一个工具是否可参与并行调度。缺省 false（独占）。
  *  优先看 toolchain registry 推断的 riskLevel（'read' 工具天然并发安全，

package/dist/core/toolPolicy.js

@@ -78,7 +78,7 @@ const PLAN_READ_ONLY_TOOLS = new Set([
     'branch_read',
     'question',
 ]);
-exports.PLAN_COMPUTER_USE_ACTIONS = ['observe', 'app_list', 'app_observe'];
+exports.PLAN_COMPUTER_USE_ACTIONS = ['observe', 'app_list', 'app_observe', 'wait_for'];
 exports.PLAN_BROWSER_USE_ACTIONS = ['observe', 'navigate', 'wait', 'extract'];
 const PLAN_COMPUTER_USE_ACTION_SET = new Set(exports.PLAN_COMPUTER_USE_ACTIONS);
 const PLAN_BROWSER_USE_ACTION_SET = new Set(exports.PLAN_BROWSER_USE_ACTIONS);

package/dist/core/utilityAgentProtocol.d.ts

@@ -3,7 +3,7 @@ import { BrowserUseRequest } from './browserUse';
 import { AgentPromptMessage, ConversationContextCompressOptions, ConversationKernelRunOptions, ConversationKernelRunResult, ConversationQueueAction, ConversationQueueActionInput, ConversationQueueMode, ConversationRuntimeState, ConversationStopResult } from './conversationKernel';
 import { ConversationRuntimeTarget, NormalizedConversationTarget } from './conversationTarget';
 import { AgentMode, AgentWorkEvent, ConversationInputEnvelope, GuideReceipt } from './types';
-import type { AutoRouteRatingResult, ConversationSnapshot } from './agent';
+import type { ConversationSnapshot } from './agent';
 export interface UtilityPromptRequest {
     message: string | AgentPromptMessage;
     target: ConversationRuntimeTarget;
@@ -78,9 +78,16 @@ export type UtilityAgentRequest = {
     method: 'snapshot';
     params: {
         target: ConversationRuntimeTarget;
+        /**
+         * dev-0.6.6: `transcript: 'force'` always returns the full transcript;
+         * `transcriptRevision` lets a caller that already holds that exact
+         * revision receive a slim snapshot instead of a full re-transfer.
+         */
         options?: {
             window?: number;
             before?: number;
+            transcript?: 'auto' | 'force';
+            transcriptRevision?: string;
         };
     };
 } | {
@@ -125,14 +132,6 @@ export type UtilityAgentRequest = {
         target: ConversationRuntimeTarget;
         options?: ConversationContextCompressOptions;
     };
-} | {
-    id: string;
-    method: 'rate_auto_route';
-    params: {
-        target: ConversationRuntimeTarget;
-        score: number;
-        routeId?: string;
-    };
 } | {
     id: string;
     method: 'set_work_run_expanded';
@@ -240,7 +239,6 @@ export interface UtilityAgentSnapshotResult {
     [key: string]: unknown;
 }
 export type UtilityGuideResult = GuideReceipt;
-export type UtilityAutoRouteRatingResult = AutoRouteRatingResult;
 export type UtilityConversationRewindResult = ConversationSnapshot;
 export {};
 //# sourceMappingURL=utilityAgentProtocol.d.ts.map

package/dist/core/utilityHostToolRouter.js

@@ -175,6 +175,8 @@ function createUtilityHostToolHandler(options) {
                 dryRun: args.dry_run === true || args.dryRun === true,
                 captureMaxWidth: Number(args.capture_max_width || args.captureMaxWidth),
                 captureMaxHeight: Number(args.capture_max_height || args.captureMaxHeight),
+                sparseWaitMs: Number(args.sparse_wait_ms ?? args.sparseWaitMs),
+                signal,
                 gradientColors: Array.isArray(args.gradient_colors) ? args.gradient_colors : undefined,
                 gradientSpeed: Number(args.gradient_speed || 0) || undefined,
                 gradientWidth: Number(args.gradient_width || 0) || undefined,

package/dist/core/visualDownscale.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Returns a data URL within `maxBytes`, or `null` when the input is not a
+ * decodable image (callers keep their existing path-based fallback then).
+ */
+export declare function downscaleDataUrlToBytes(dataUrl: string, maxBytes: number): string | null;
+//# sourceMappingURL=visualDownscale.d.ts.map

package/dist/core/visualDownscale.js

@@ -0,0 +1,137 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.downscaleDataUrlToBytes = downscaleDataUrlToBytes;
+const pngjs_1 = require("pngjs");
+const jpeg = __importStar(require("jpeg-js"));
+const conversationVisualBudget_1 = require("./conversationVisualBudget");
+const MAX_SOURCE_PIXELS = 12 * 1024 * 1024;
+const MIN_SCALE = 0.08;
+function decodeDataUrl(dataUrl) {
+    const match = /^data:(image\/(?:png|jpe?g));base64,([A-Za-z0-9+/=\r\n]+)$/i.exec(String(dataUrl || ''));
+    if (!match)
+        return null;
+    const mimeType = /^image\/png$/i.test(match[1]) ? 'image/png' : 'image/jpeg';
+    let bytes;
+    try {
+        bytes = Buffer.from(match[2].replace(/\s/g, ''), 'base64');
+    }
+    catch {
+        return null;
+    }
+    try {
+        if (mimeType === 'image/png') {
+            const decoded = pngjs_1.PNG.sync.read(bytes);
+            if (!decoded?.width || !decoded?.height)
+                return null;
+            if (decoded.width * decoded.height > MAX_SOURCE_PIXELS)
+                return null;
+            return { width: decoded.width, height: decoded.height, data: decoded.data, mimeType };
+        }
+        const decoded = jpeg.decode(bytes, { useTArray: true, formatAsRGBA: true, maxResolutionInMP: 24, maxMemoryUsageInMB: 192 });
+        if (!decoded?.width || !decoded?.height)
+            return null;
+        if (decoded.width * decoded.height > MAX_SOURCE_PIXELS)
+            return null;
+        return { width: decoded.width, height: decoded.height, data: decoded.data, mimeType };
+    }
+    catch {
+        return null;
+    }
+}
+function resample(source, scale) {
+    const width = Math.max(1, Math.round(source.width * scale));
+    const height = Math.max(1, Math.round(source.height * scale));
+    const output = Buffer.alloc(width * height * 4);
+    const sourceData = Buffer.isBuffer(source.data) ? source.data : Buffer.from(source.data);
+    const xRatio = source.width / width;
+    const yRatio = source.height / height;
+    for (let y = 0; y < height; y += 1) {
+        const sourceY = Math.min(source.height - 1, Math.floor(y * yRatio));
+        for (let x = 0; x < width; x += 1) {
+            const sourceX = Math.min(source.width - 1, Math.floor(x * xRatio));
+            const from = (sourceY * source.width + sourceX) * 4;
+            const to = (y * width + x) * 4;
+            output[to] = sourceData[from];
+            output[to + 1] = sourceData[from + 1];
+            output[to + 2] = sourceData[from + 2];
+            output[to + 3] = sourceData[from + 3];
+        }
+    }
+    return { width, height, data: output };
+}
+function encodePng(frame) {
+    const png = new pngjs_1.PNG({ width: frame.width, height: frame.height });
+    frame.data.copy(png.data);
+    return `data:image/png;base64,${pngjs_1.PNG.sync.write(png, { deflateLevel: 6, colorType: 6 }).toString('base64')}`;
+}
+function encodeJpeg(frame, quality) {
+    const encoded = jpeg.encode({ data: frame.data, width: frame.width, height: frame.height }, quality);
+    return `data:image/jpeg;base64,${Buffer.from(encoded.data).toString('base64')}`;
+}
+/**
+ * Returns a data URL within `maxBytes`, or `null` when the input is not a
+ * decodable image (callers keep their existing path-based fallback then).
+ */
+function downscaleDataUrlToBytes(dataUrl, maxBytes) {
+    // No artificial floor: a severe budget may legitimately ask for a very small
+    // image, and the caller decides what is usable.
+    const limit = Math.max(1024, Math.floor(Number(maxBytes) || 0));
+    if (!limit)
+        return null;
+    if ((0, conversationVisualBudget_1.visualDataUrlBytes)(dataUrl) <= limit)
+        return dataUrl;
+    const source = decodeDataUrl(dataUrl);
+    if (!source)
+        return null;
+    // Density scales with the allowed pixel area for this budget, then the result
+    // is verified by re-encoding (encoder overhead differs between formats).
+    let scale = Math.min(1, Math.sqrt(limit / Math.max(1, (0, conversationVisualBudget_1.visualDataUrlBytes)(dataUrl))));
+    for (let attempt = 0; attempt < 4 && scale >= MIN_SCALE; attempt += 1) {
+        const frame = resample(source, scale);
+        const asPng = encodePng(frame);
+        if ((0, conversationVisualBudget_1.visualDataUrlBytes)(asPng) <= limit)
+            return asPng;
+        const asJpeg = encodeJpeg(frame, attempt === 0 ? 72 : 60);
+        if ((0, conversationVisualBudget_1.visualDataUrlBytes)(asJpeg) <= limit)
+            return asJpeg;
+        scale *= 0.6;
+    }
+    // Last resort: a very small JPEG still gives the model a usable overview.
+    const tiny = resample(source, MIN_SCALE);
+    const encoded = encodeJpeg(tiny, 45);
+    return (0, conversationVisualBudget_1.visualDataUrlBytes)(encoded) <= limit ? encoded : null;
+}
+//# sourceMappingURL=visualDownscale.js.map