agentsw 0.7.1 → 0.8.0

package/dist/metadata.js

@@ -0,0 +1,400 @@
+import { findModelMeta, getCatalogFetchedAt, toModelSpec } from "./modelsdev.js";
+import { loadGatewayCatalog } from "./gateway.js";
+const forbiddenKeys = new Set(["__proto__", "prototype", "constructor"]);
+const canonicalId = /^[^/\s]+\/[^/\s]+(?:\/[^/\s]+)*$/;
+export function getMetadataMode(settings) {
+    if (settings.gatewayMetadata === undefined || settings.gatewayMetadata === "auto")
+        return "auto";
+    if (settings.gatewayMetadata === true)
+        return "on";
+    if (settings.gatewayMetadata === false)
+        return "off";
+    throw new Error("Gateway metadata must be a boolean or auto");
+}
+function validateSettings(settings) {
+    const result = {};
+    if (settings.gatewayMetadata !== undefined) {
+        getMetadataMode(settings);
+        result.gatewayMetadata = settings.gatewayMetadata;
+    }
+    const aliases = settings.gatewayModelAliases;
+    if (aliases !== undefined) {
+        if (!aliases || typeof aliases !== "object" || Array.isArray(aliases)
+            || ![Object.prototype, null].includes(Object.getPrototypeOf(aliases))) {
+            throw new Error("Gateway model mappings must be a plain object of exact IDs to creator/model IDs");
+        }
+        const entries = Object.entries(aliases);
+        for (const [id, target] of entries) {
+            if (!id || /\s/.test(id) || forbiddenKeys.has(id) || typeof target !== "string" || !canonicalId.test(target)) {
+                throw new Error("Gateway model mappings must contain valid exact IDs and creator/model IDs");
+            }
+        }
+        result.gatewayModelAliases = Object.fromEntries(entries);
+    }
+    return result;
+}
+/** Validate before any mutation or fetch; omitted settings preserve the previous values. */
+export function resolveMetadataOptions(opts, previous) {
+    const settings = validateSettings(previous ?? {});
+    if (opts.gatewayMetadata !== undefined) {
+        if (typeof opts.gatewayMetadata !== "boolean")
+            throw new Error("Gateway metadata must be a boolean");
+        settings.gatewayMetadata = opts.gatewayMetadata;
+    }
+    if (opts.metadataMode !== undefined) {
+        if (opts.metadataMode !== "auto" && opts.metadataMode !== "on" && opts.metadataMode !== "off") {
+            throw new Error("Metadata mode must be auto, on, or off");
+        }
+        const mode = opts.metadataMode === "auto" ? "auto" : opts.metadataMode === "on";
+        if (opts.gatewayMetadata !== undefined && opts.gatewayMetadata !== mode) {
+            throw new Error("Metadata mode conflicts with Gateway metadata flag");
+        }
+        settings.gatewayMetadata = mode;
+    }
+    if (opts.gatewayModels !== undefined) {
+        if (typeof opts.gatewayModels !== "string")
+            throw new Error("Gateway model mappings must be a JSON object");
+        let aliases;
+        try {
+            aliases = JSON.parse(opts.gatewayModels);
+        }
+        catch {
+            throw new Error("Gateway model mappings must be a JSON object");
+        }
+        settings.gatewayModelAliases = validateSettings({ gatewayModelAliases: aliases }).gatewayModelAliases;
+    }
+    return settings;
+}
+const fields = [
+    "name", "contextWindow", "maxInput", "maxOutput", "reasoning", "reasoningEfforts", "imageInput",
+    "cost.input", "cost.output", "cost.cacheRead", "cost.cacheWrite",
+];
+const gatewayFields = fields.filter((field) => !field.startsWith("cost."));
+const limits = ["maxInput", "maxOutput"];
+const coreFields = ["contextWindow", "maxOutput", "reasoning", "imageInput"];
+function fieldValue(spec, field) {
+    if (field.startsWith("cost."))
+        return spec.cost?.[field.slice(5)];
+    return spec[field];
+}
+function setField(spec, field, value) {
+    if (field.startsWith("cost.")) {
+        const leaf = field.slice(5);
+        if (value === undefined) {
+            if (spec.cost)
+                delete spec.cost[leaf];
+        }
+        else {
+            spec.cost ??= {};
+            spec.cost[leaf] = value;
+        }
+    }
+    else {
+        const record = spec;
+        if (value === undefined)
+            delete record[field];
+        else
+            record[field] = Array.isArray(value) ? [...value] : value;
+    }
+}
+function equalValue(a, b) {
+    if (Array.isArray(a) && Array.isArray(b))
+        return a.length === b.length && a.every((value, index) => value === b[index]);
+    return a === b;
+}
+function indexCatalog(catalog) {
+    const exact = new Map();
+    const canonical = new Map();
+    for (const provider of Object.values(catalog)) {
+        for (const [key, model] of Object.entries(provider.models)) {
+            const modelId = model.id.includes("/") ? model.id : `${provider.id}/${model.id}`;
+            const entry = { provider: provider.id, modelId, model };
+            for (const id of new Set([key, model.id])) {
+                const matches = exact.get(id);
+                if (matches)
+                    matches.push(entry);
+                else
+                    exact.set(id, [entry]);
+            }
+            const matches = canonical.get(modelId);
+            if (matches)
+                matches.push(entry);
+            else
+                canonical.set(modelId, [entry]);
+        }
+    }
+    return { exact, canonical };
+}
+function indexGatewayBareIds(gateway) {
+    const result = new Map();
+    for (const id of Object.keys(gateway.models)) {
+        const slash = id.indexOf("/");
+        if (slash < 1 || slash !== id.lastIndexOf("/") || !canonicalId.test(id))
+            continue;
+        const bare = id.slice(slash + 1);
+        result.set(bare, result.has(bare) ? null : id);
+    }
+    return result;
+}
+function selectExact(index, id, hint, aliases, gateway, gatewayBareIds) {
+    const alias = aliases && Object.hasOwn(aliases, id) ? aliases[id] : undefined;
+    const bare = !id.includes("/");
+    let gatewayId = alias;
+    if (gatewayId === undefined && gateway) {
+        if (canonicalId.test(id) && Object.hasOwn(gateway.models, id))
+            gatewayId = id;
+        else if (bare) {
+            const candidate = gatewayBareIds?.get(id);
+            const evidence = index?.exact.get(id);
+            const hintedEvidence = hint ? evidence?.filter((entry) => entry.provider === hint) : undefined;
+            const identities = new Set((hintedEvidence?.length ? hintedEvidence : evidence)?.map((entry) => entry.modelId));
+            // A unique exact basename is safe only with absent or agreeing primary evidence.
+            // Explicit provider hints can resolve primary ambiguity, but never Gateway ambiguity.
+            if (candidate && (identities.size === 0 || (identities.size === 1 && identities.has(candidate))))
+                gatewayId = candidate;
+        }
+    }
+    const candidates = gatewayId !== undefined
+        ? index?.canonical.get(gatewayId)
+        : (bare && hint ? index?.canonical.get(`${hint}/${id}`) : undefined)
+            ?? index?.canonical.get(id) ?? index?.exact.get(id);
+    const hinted = candidates?.find((entry) => entry.provider === hint);
+    const identities = new Set(candidates?.map((entry) => entry.modelId));
+    const primary = hinted ?? (identities.size === 1
+        ? candidates?.find((entry) => entry.modelId.startsWith(`${entry.provider}/`)) ?? candidates?.[0]
+        : undefined);
+    return { primary, gatewayId, alias };
+}
+function legacyPrimary(catalog, id, hint) {
+    const hit = findModelMeta(catalog, id, hint);
+    if (!hit)
+        return undefined;
+    const provider = Object.values(catalog).find((candidate) => candidate.id === hit.provider);
+    const base = id.slice(id.lastIndexOf("/") + 1).toLowerCase();
+    const model = provider && (Object.hasOwn(provider.models, id) ? provider.models[id]
+        : Object.entries(provider.models).find(([key]) => key.slice(key.lastIndexOf("/") + 1).toLowerCase() === base)?.[1]);
+    if (!model)
+        return undefined;
+    hit.spec.id = model.id;
+    return { spec: hit.spec, modelId: model.id.includes("/") ? model.id : `${hit.provider}/${model.id}` };
+}
+function clearGatewayIdentity(spec) {
+    const metadata = spec.metadata;
+    if (!metadata)
+        return;
+    for (const field of fields) {
+        const origin = metadata.fields?.[field];
+        if (origin?.source !== "ai-gateway")
+            continue;
+        if (equalValue(fieldValue(spec, field), origin.value))
+            setField(spec, field, undefined);
+        delete metadata.fields[field];
+    }
+    delete metadata.gateway;
+    if (metadata.conflicts)
+        metadata.conflicts = metadata.conflicts.filter((conflict) => conflict.source !== "ai-gateway");
+}
+function clearStaleIdentity(spec, modelId) {
+    const metadata = spec.metadata;
+    if (!metadata)
+        return;
+    for (const field of fields) {
+        const origin = metadata.fields?.[field];
+        if (!origin || origin.modelId === modelId)
+            continue;
+        if (equalValue(fieldValue(spec, field), origin.value))
+            setField(spec, field, undefined);
+        delete metadata.fields[field];
+    }
+    if (metadata.gateway && metadata.gateway.modelId !== modelId)
+        delete metadata.gateway;
+    if (metadata.conflicts)
+        metadata.conflicts = metadata.conflicts.filter((conflict) => conflict.modelId === modelId);
+}
+/** Apply a source as a set of field proposals, checking bounds against retained values first. */
+function mergeSource(spec, incoming, source, modelId, now, fetchedAt, supplementalGateway) {
+    const sourceFields = source === "ai-gateway" ? gatewayFields : fields;
+    const proposals = new Map();
+    const conflicts = [];
+    const conflict = (field, value, keptValue, blockedBy) => {
+        conflicts.push({ field, source, modelId, value: Array.isArray(value) ? [...value] : value,
+            keptValue: Array.isArray(keptValue) ? [...keptValue] : keptValue, ...(blockedBy ? { blockedBy } : {}) });
+    };
+    for (const field of sourceFields) {
+        const value = fieldValue(incoming, field);
+        if (value === undefined)
+            continue;
+        if (field === "name" && (value === incoming.id || value === modelId))
+            continue;
+        const current = fieldValue(spec, field);
+        const origin = spec.metadata?.fields?.[field];
+        if (current === undefined || (origin && (source === "models.dev" || origin.source === source))) {
+            proposals.set(field, value);
+        }
+        else if (!equalValue(current, value)) {
+            conflict(field, value, current);
+        }
+    }
+    // A proposed context may shrink only when every retained limit still fits.
+    let context = proposals.get("contextWindow") ?? spec.contextWindow;
+    if (typeof context === "number" && proposals.has("contextWindow")) {
+        for (const field of limits) {
+            const proposed = proposals.get(field);
+            const primaryFits = typeof proposed === "number" && proposed <= context;
+            let retained = primaryFits ? proposed : fieldValue(spec, field);
+            // The supplement runs next: account for a still-owned limit that it can
+            // lower in this same refresh, rather than requiring a second refresh.
+            const next = supplementalGateway && spec.metadata?.fields?.[field]?.source === "ai-gateway"
+                ? supplementalGateway[field] : undefined;
+            if (!primaryFits && typeof next === "number" && next <= context)
+                retained = next;
+            if (typeof retained === "number" && retained > context) {
+                conflict("contextWindow", context, retained, field);
+                proposals.delete("contextWindow");
+                context = spec.contextWindow;
+                break;
+            }
+        }
+    }
+    for (const field of limits) {
+        const value = proposals.get(field);
+        if (typeof value === "number" && typeof context === "number" && value > context) {
+            conflict(field, value, context, "contextWindow");
+            proposals.delete(field);
+        }
+    }
+    const reasoning = proposals.get("reasoning") ?? spec.reasoning;
+    if (reasoning === false) {
+        const efforts = proposals.get("reasoningEfforts");
+        const emptyEfforts = Array.isArray(efforts) && efforts.length === 0;
+        if (efforts !== undefined && !emptyEfforts) {
+            conflict("reasoningEfforts", efforts, false, "reasoning");
+            proposals.delete("reasoningEfforts");
+        }
+        // Do not introduce a contradictory false flag over retained effort settings.
+        if (proposals.has("reasoning") && spec.reasoning !== false && !emptyEfforts && spec.reasoningEfforts?.length) {
+            conflict("reasoning", false, spec.reasoningEfforts, "reasoningEfforts");
+            proposals.delete("reasoning");
+        }
+    }
+    const metadata = spec.metadata ??= {};
+    if (metadata.conflicts)
+        metadata.conflicts = metadata.conflicts.filter((entry) => entry.source !== source);
+    if (conflicts.length)
+        metadata.conflicts = [...(metadata.conflicts ?? []), ...conflicts];
+    for (const [field, value] of proposals) {
+        const previous = metadata.fields?.[field];
+        const unchanged = previous?.source === source && previous.modelId === modelId && equalValue(previous.value, value);
+        const origin = {
+            source, modelId, value: Array.isArray(value) ? [...value] : value,
+            updatedAt: unchanged ? previous.updatedAt : now,
+        };
+        const timestamp = fetchedAt ?? (unchanged ? previous.fetchedAt : undefined);
+        if (timestamp !== undefined)
+            origin.fetchedAt = timestamp;
+        (metadata.fields ??= {})[field] = origin;
+        setField(spec, field, value);
+    }
+}
+/** Supplement metadata only; IDs, routes, protocol and provider-effective pricing remain untouched. */
+export async function enrichProviderModels(catalog, ids, settings, options = {}) {
+    const validated = validateSettings(settings);
+    const mode = getMetadataMode(validated);
+    if (ids.length === 0)
+        return [];
+    const enabled = mode !== "off";
+    const index = enabled && catalog ? indexCatalog(catalog) : undefined;
+    const existing = new Map(settings.models?.map((model) => [model.id, model]));
+    const fetchedAt = catalog ? getCatalogFetchedAt(catalog) : undefined;
+    const now = new Date().toISOString();
+    const enrich = (gateway) => {
+        const gatewayBareIds = gateway ? indexGatewayBareIds(gateway) : undefined;
+        return ids.map((id) => {
+            const previous = existing.get(id);
+            const spec = previous ? structuredClone(previous) : { id };
+            for (const field of fields) {
+                const origin = spec.metadata?.fields?.[field];
+                if (origin && !equalValue(fieldValue(spec, field), origin.value))
+                    delete spec.metadata.fields[field];
+            }
+            let primary;
+            let supplement;
+            let match;
+            if (enabled) {
+                match = selectExact(index, id, settings.modelsDevId, validated.gatewayModelAliases, gateway, gatewayBareIds);
+                const oldGateway = spec.metadata?.gateway;
+                if (oldGateway && (oldGateway.alias !== match.alias
+                    || (match.gatewayId !== undefined && oldGateway.modelId !== match.gatewayId))) {
+                    clearGatewayIdentity(spec);
+                }
+                if (match.primary)
+                    primary = { spec: toModelSpec(match.primary.model.id, match.primary.model), modelId: match.primary.modelId };
+                if (gateway && match.gatewayId !== undefined && Object.hasOwn(gateway.models, match.gatewayId)) {
+                    supplement = gateway.models[match.gatewayId];
+                }
+                // An explicit mapping establishes identity even offline. An outage without
+                // a mapping or exact catalog evidence does not justify deleting metadata.
+                const confirmedId = match.alias ?? match.primary?.modelId ?? supplement?.id;
+                if (confirmedId !== undefined)
+                    clearStaleIdentity(spec, confirmedId);
+            }
+            else if (catalog) {
+                primary = legacyPrimary(catalog, id, settings.modelsDevId);
+            }
+            if (primary)
+                mergeSource(spec, primary.spec, "models.dev", primary.modelId, now, fetchedAt, supplement?.spec);
+            if (supplement && gateway && match) {
+                mergeSource(spec, supplement.spec, "ai-gateway", supplement.id, now, gateway.fetchedAt);
+                const audit = { modelId: supplement.id, fetchedAt: gateway.fetchedAt };
+                if (match.alias !== undefined)
+                    audit.alias = match.alias;
+                if (supplement.referenceCost !== undefined)
+                    audit.referenceCost = structuredClone(supplement.referenceCost);
+                if (supplement.pricingIsVariable !== undefined)
+                    audit.pricingIsVariable = supplement.pricingIsVariable;
+                (spec.metadata ??= {}).gateway = audit;
+            }
+            if (spec.metadata?.fields && Object.keys(spec.metadata.fields).length === 0)
+                delete spec.metadata.fields;
+            if (spec.metadata?.conflicts?.length === 0)
+                delete spec.metadata.conflicts;
+            if (spec.metadata && Object.keys(spec.metadata).length === 0)
+                delete spec.metadata;
+            return spec;
+        });
+    };
+    if (!enabled)
+        return enrich();
+    if (options.gateway !== undefined)
+        return enrich(options.gateway ?? undefined);
+    const primaryOnly = mode === "auto" ? enrich() : undefined;
+    if (primaryOnly && !primaryOnly.some((spec) => {
+        if (coreFields.some((field) => spec[field] === undefined)
+            || gatewayFields.some((field) => spec.metadata?.fields?.[field]?.source === "ai-gateway"))
+            return true;
+        // Complete legacy basename metadata still needs an exact identity check,
+        // unless an explicit mapping or current primary match already confirms it.
+        if (!canonicalId.test(spec.id) || !fields.some((field) => {
+            const origin = spec.metadata?.fields?.[field];
+            return origin && origin.modelId !== spec.id;
+        }))
+            return false;
+        const match = selectExact(index, spec.id, settings.modelsDevId, validated.gatewayModelAliases, undefined);
+        const confirmedId = match.alias ?? match.primary?.modelId ?? spec.id;
+        return fields.some((field) => {
+            const origin = spec.metadata?.fields?.[field];
+            return origin && origin.modelId !== confirmedId;
+        });
+    }))
+        return primaryOnly;
+    let gateway;
+    try {
+        gateway = await (options.gatewayLoader ?? loadGatewayCatalog)() ?? null;
+    }
+    catch {
+        gateway = null;
+    }
+    // Never feed the primary pre-pass back into merging: identity and coordinated
+    // bounds must be resolved with the supplement against the original values.
+    return gateway ? enrich(gateway) : primaryOnly ?? enrich();
+}

package/dist/modelsdev.js

@@ -5,39 +5,57 @@ import { readJsonIfExists, writeFileAtomic } from "./fsutil.js";
 const API_URL = "https://models.dev/api.json";
 const CACHE_FILE = path.join(configDir, "models-dev.json");
 const CACHE_TTL_MS = 24 * 60 * 60 * 1000;
+const catalogFetchedAt = new WeakMap();
+/** Fetch time is kept outside the provider dictionary and never changes its public shape. */
+export function getCatalogFetchedAt(catalog) {
+    return catalogFetchedAt.get(catalog);
+}
+function readCachedCatalog() {
+    const catalog = readJsonIfExists(CACHE_FILE);
+    if (catalog) {
+        try {
+            catalogFetchedAt.set(catalog, fs.statSync(CACHE_FILE).mtime.toISOString());
+        }
+        catch {
+            // A concurrently removed cache still supplies useful metadata without a fetch time.
+        }
+    }
+    return catalog;
+}
 export async function loadCatalog(opts = {}) {
     if (!opts.refresh) {
         try {
             const stat = fs.statSync(CACHE_FILE);
             const fresh = Date.now() - stat.mtimeMs < CACHE_TTL_MS;
             if (fresh || opts.offline)
-                return readJsonIfExists(CACHE_FILE);
+                return readCachedCatalog();
         }
         catch {
             /* no cache */
         }
     }
     if (opts.offline)
-        return readJsonIfExists(CACHE_FILE);
+        return readCachedCatalog();
     try {
         const res = await fetch(API_URL, { signal: AbortSignal.timeout(15000) });
         if (!res.ok)
             throw new Error(`models.dev responded ${res.status}`);
         const text = await res.text();
-        JSON.parse(text); // validate before caching
+        const catalog = JSON.parse(text); // validate before caching
         writeFileAtomic(CACHE_FILE, text);
-        return JSON.parse(text);
+        catalogFetchedAt.set(catalog, new Date().toISOString());
+        return catalog;
     }
     catch (err) {
         // network failure: fall back to stale cache if present
-        const cached = readJsonIfExists(CACHE_FILE);
+        const cached = readCachedCatalog();
         if (cached)
             return cached;
         process.stderr.write(`warning: could not fetch models.dev catalog: ${err.message}\n`);
         return undefined;
     }
 }
-function toModelSpec(id, m) {
+export function toModelSpec(id, m) {
     const efforts = m.reasoning_options?.find((o) => o.type === "effort")?.values;
     return {
         id,
@@ -46,8 +64,10 @@ function toModelSpec(id, m) {
         maxInput: m.limit?.input,
         maxOutput: m.limit?.output,
         reasoning: m.reasoning,
-        reasoningEfforts: efforts?.length ? efforts : undefined,
-        imageInput: m.attachment || m.modalities?.input?.includes("image") || undefined,
+        reasoningEfforts: efforts,
+        imageInput: m.attachment !== undefined || m.modalities?.input !== undefined
+            ? m.attachment === true || m.modalities?.input?.includes("image") === true
+            : undefined,
         cost: m.cost
             ? { input: m.cost.input, output: m.cost.output, cacheRead: m.cost.cache_read, cacheWrite: m.cost.cache_write }
             : undefined,
@@ -75,9 +95,13 @@ export function findModelMeta(catalog, modelId, providerHint) {
         if (m)
             return { spec: toModelSpec(modelId, m), provider: hinted.id };
     }
-    for (const p of Object.values(catalog)) {
-        if (p === hinted)
-            continue;
+    const providers = Object.values(catalog).filter((p) => p !== hinted);
+    for (const p of providers) {
+        const m = p.models[modelId];
+        if (m)
+            return { spec: toModelSpec(modelId, m), provider: p.id };
+    }
+    for (const p of providers) {
         const m = scan(p);
         if (m)
             return { spec: toModelSpec(modelId, m), provider: p.id };

package/dist/provider-identity.js

@@ -0,0 +1,25 @@
+import { createHash } from "node:crypto";
+/** Previous releases used this lossy encoding; recognize it, never generate it. */
+export function legacyManagedCredentialRef(id) {
+    return `AGENTSW_${id.toUpperCase().replace(/[^A-Z0-9]/g, "_")}_API_KEY`;
+}
+/** Human-readable prefix plus an exact, case-sensitive provider identity digest. */
+export function managedCredentialRef(id) {
+    const prefix = id.toUpperCase().replace(/[^A-Z0-9]/g, "_").slice(0, 48) || "PROVIDER";
+    const digest = createHash("sha256").update(id).digest("hex").slice(0, 24).toUpperCase();
+    return `AGENTSW_${prefix}_${digest}_API_KEY`;
+}
+export function isManagedCredentialRef(ref, id) {
+    return ref === managedCredentialRef(id) || ref === legacyManagedCredentialRef(id);
+}
+/** Account-qualified app-local selector; never embeds endpoints or credentials. */
+export function localProviderId(candidate) {
+    const identity = JSON.stringify([
+        candidate.id,
+        candidate.protocol,
+        candidate.baseUrl,
+        candidate.apiKey ?? null,
+        candidate.keyEnv ?? null,
+    ]);
+    return `local-${createHash("sha256").update(identity).digest("hex").slice(0, 32)}`;
+}