@wiro-ai/wiro-mcp 1.3.3 → 1.4.0

package/dist/utils/agent-config.js

@@ -0,0 +1,1667 @@
+import crypto from 'node:crypto';
+import { ApiResultError, asString, hasErrorCode, isPlainObject, requireApiSuccess, toNumber, truncate, unixToIso, } from './api.js';
+// Helpers for configuring a deployed agent: its registry skills, credentials,
+// sign-in connections and custom skills. The pure functions mirror the server
+// rules closely so a bad request is caught before anything is written.
+export const DEFAULT_CRON_INTERVAL = '0 10 * * 1';
+export const OAUTH_LINK_TTL_SECONDS = 900;
+const DASHBOARD_AGENT_URL = 'https://wiro.ai/panel/agents/';
+const OAUTH_CALLBACK_BASE = 'https://api.wiro.ai/v1';
+const REGISTRY_TTL_MS = 5 * 60_000;
+function stringList(value) {
+    return Array.isArray(value)
+        ? value.map(item => asString(item)).filter((item) => !!item)
+        : [];
+}
+export function formatUsd(amount) {
+    const sign = amount < 0 ? '-' : '';
+    return `${sign}$${Math.abs(amount).toFixed(2)}`;
+}
+// ---------------------------------------------------------------------------
+// Agent row
+// ---------------------------------------------------------------------------
+export const AGENT_STATUS_LABELS = {
+    0: 'stopped',
+    1: 'stopping',
+    2: 'queued',
+    3: 'starting',
+    4: 'running',
+    5: 'error',
+    6: 'setup required',
+};
+export function agentStatusLabel(status) {
+    return status !== null && AGENT_STATUS_LABELS[status] ? AGENT_STATUS_LABELS[status] : 'unknown';
+}
+/** Configuration writes restart an agent only while it is starting or running. */
+export function isAgentRunning(status) {
+    return status === 3 || status === 4;
+}
+/** The agent's page in the Wiro dashboard, in the form the dashboard itself uses as an OAuth return address. */
+export function dashboardAgentUrl(agentGuid) {
+    const guid = encodeURIComponent(agentGuid);
+    return `${DASHBOARD_AGENT_URL}${guid}?id=${guid}`;
+}
+export function restartNote(status, what = 'change') {
+    switch (status) {
+        case 3:
+        case 4:
+            return `The agent restarts to load the ${what}, which takes about a minute. Follow it with get_my_agent.`;
+        case 1:
+            return `The agent is already stopping or restarting; it loads the ${what} when it starts again.`;
+        case 2:
+            return `The agent is queued to start and loads the ${what} when it does.`;
+        case 6:
+            return `The agent still needs setup; the ${what} takes effect once it starts.`;
+        case 0:
+        case 5:
+            return `The agent is ${agentStatusLabel(status)}, so the ${what} takes effect the next time it starts.`;
+        default:
+            return `The ${what} takes effect the next time the agent starts.`;
+    }
+}
+export async function readUserAgent(client, agentGuid, signal) {
+    const body = requireApiSuccess(await client.post('/UserAgent/Detail', { guid: agentGuid }, signal), 'Could not read the agent.');
+    const row = Array.isArray(body.useragents) ? body.useragents[0] : undefined;
+    if (!isPlainObject(row))
+        throw new Error(`Agent ${agentGuid} was not found.`);
+    return row;
+}
+export function agentStatusOf(row) {
+    return toNumber(row.status);
+}
+/** Names of the registry skills that are on. Detail lists only enabled skills. */
+export function enabledSkillNames(row) {
+    if (!Array.isArray(row.skills))
+        return [];
+    return row.skills
+        .map(skill => (isPlainObject(skill)
+        ? (skill.enabled === false ? undefined : asString(skill.name))
+        : asString(skill)))
+        .filter((name) => !!name);
+}
+export function isCustomBuild(row) {
+    return isPlainObject(row.agent) && row.agent.custom === true;
+}
+// ---------------------------------------------------------------------------
+// Registry reads (anonymous, identical for every caller, so cached briefly)
+// ---------------------------------------------------------------------------
+const registryCache = new WeakMap();
+async function cachedRead(owner, key, load) {
+    let entries = registryCache.get(owner);
+    if (!entries) {
+        entries = new Map();
+        registryCache.set(owner, entries);
+    }
+    const hit = entries.get(key);
+    if (hit && Date.now() - hit.at < REGISTRY_TTL_MS)
+        return hit.value;
+    const value = await load();
+    entries.set(key, { at: Date.now(), value });
+    return value;
+}
+export function parseSkillRegistry(body) {
+    const skills = new Map();
+    for (const raw of Array.isArray(body.skills) ? body.skills : []) {
+        if (!isPlainObject(raw))
+            continue;
+        const name = asString(raw.name);
+        if (!name)
+            continue;
+        const pricing = isPlainObject(raw.pricing) ? raw.pricing : {};
+        const primary = asString(raw.credential_key);
+        skills.set(name, {
+            name,
+            title: asString(raw.title) ?? name,
+            dependsOn: stringList(raw.depends_on),
+            conflictsWith: stringList(raw.conflicts_with),
+            deprecated: raw.deprecated === true,
+            ...(asString(raw.replacement) ? { replacement: asString(raw.replacement) } : {}),
+            requiresCredentials: raw.requires_credentials === true,
+            credentialKeys: [...(primary ? [primary] : []), ...stringList(raw.additional_credential_keys)],
+            monthlyPriceUsd: toNumber(pricing.monthly_price_weight_usd ?? raw.monthly_price_weight_usd),
+        });
+    }
+    const channels = new Map();
+    for (const raw of Array.isArray(body.channels) ? body.channels : []) {
+        if (!isPlainObject(raw))
+            continue;
+        const id = asString(raw.id);
+        if (!id)
+            continue;
+        channels.set(id, {
+            id,
+            title: asString(raw.title) ?? id,
+            credentialKey: asString(raw.credential_key) ?? id,
+        });
+    }
+    return { skills, channels };
+}
+export async function loadSkillRegistry(client, signal) {
+    return cachedRead(client, 'skills', async () => parseSkillRegistry(requireApiSuccess(await client.post('/Skills/List', {}, signal), 'Could not read the skill list.')));
+}
+function suggestSkills(name, registry) {
+    const tokens = new Set(name.toLowerCase().split(/[^a-z0-9]+/).filter(token => token.length > 2));
+    return [...registry.skills.keys()]
+        .map(candidate => ({
+        candidate,
+        score: candidate.split('-').filter(token => tokens.has(token)).length,
+    }))
+        .filter(entry => entry.score > 0)
+        .sort((left, right) => right.score - left.score)
+        .slice(0, 3)
+        .map(entry => entry.candidate);
+}
+/**
+ * Validates the requested names against the registry and, when asked, adds
+ * the skills they depend on. The server refuses a change whose enabled set is
+ * missing a dependency. Names are checked against the registry here, so only
+ * known skills are sent.
+ */
+export function planSkillChanges(input, registry, addDependencies) {
+    const errors = new Set();
+    const requested = {};
+    for (const [rawName, enabled] of Object.entries(input)) {
+        const name = rawName.trim();
+        if (!name) {
+            errors.add('Skill names cannot be empty.');
+            continue;
+        }
+        if (name.startsWith('cs-') || name.startsWith('cron-')) {
+            errors.add(`"${name}" is a custom skill or scheduled task. Use manage_agent_custom_skill for it.`);
+            continue;
+        }
+        const channel = registry.channels.get(name);
+        if (channel) {
+            errors.add(`"${name}" is a channel, not a skill. It turns on when its fields are filled with set_agent_credentials (credential "${channel.credentialKey}").`);
+            continue;
+        }
+        const skill = registry.skills.get(name);
+        if (!skill) {
+            const suggestions = suggestSkills(name, registry);
+            errors.add(`Unknown skill "${name}".${suggestions.length ? ` Did you mean ${suggestions.join(', ')}?` : ''} Use list_agent_skills for the full list.`);
+            continue;
+        }
+        if (enabled && skill.deprecated) {
+            errors.add(`${name} is retired and cannot be turned on${skill.replacement ? `. Use ${skill.replacement} instead` : ''}.`);
+            continue;
+        }
+        requested[name] = enabled;
+    }
+    const added = [];
+    if (addDependencies) {
+        const queue = Object.keys(requested).filter(name => requested[name]);
+        while (queue.length > 0) {
+            const name = queue.shift();
+            for (const dependency of registry.skills.get(name)?.dependsOn ?? []) {
+                if (requested[dependency] === false) {
+                    errors.add(`${name} needs ${dependency}, which this change turns off. Keep ${dependency} on, or leave ${name} off.`);
+                    continue;
+                }
+                if (requested[dependency] === true || !registry.skills.has(dependency))
+                    continue;
+                requested[dependency] = true;
+                added.push(dependency);
+                queue.push(dependency);
+            }
+        }
+    }
+    return { requested, addedDependencies: added, errors: [...errors] };
+}
+/** Only real changes are sent, since a skill change restarts a running agent. */
+export function diffSkills(requested, enabledNow) {
+    const current = new Set(enabledNow);
+    const diff = { changes: {}, enable: [], disable: [], alreadySet: [] };
+    for (const [name, enabled] of Object.entries(requested)) {
+        if (enabled === current.has(name)) {
+            diff.alreadySet.push(name);
+            continue;
+        }
+        diff.changes[name] = enabled;
+        (enabled ? diff.enable : diff.disable).push(name);
+    }
+    return diff;
+}
+/**
+ * The same check the API runs before it writes: every skill that ends up on
+ * needs its dependencies on, and no two conflicting skills may be on.
+ */
+export function checkSkillSet(enabledNow, changes, registry) {
+    const finalSet = new Set(enabledNow);
+    for (const [name, enabled] of Object.entries(changes)) {
+        if (enabled)
+            finalSet.add(name);
+        else
+            finalSet.delete(name);
+    }
+    const deps = [];
+    const conflicts = [];
+    for (const name of finalSet) {
+        const skill = registry.skills.get(name);
+        if (!skill)
+            continue;
+        for (const dependency of skill.dependsOn) {
+            if (!finalSet.has(dependency))
+                deps.push({ skill: name, requires: dependency });
+        }
+        for (const other of skill.conflictsWith) {
+            if (finalSet.has(other) && !conflicts.some(pair => pair.a === other && pair.b === name)) {
+                conflicts.push({ a: name, b: other });
+            }
+        }
+    }
+    return { deps, conflicts };
+}
+/** Credential keys the newly enabled skills read, skipping the ones the agent already has. */
+export function credentialsNeededFor(skills, registry, row) {
+    const groups = row && isPlainObject(row.credentials) ? row.credentials : {};
+    // An OAuth credential is ready only once connected: a saved shop domain or
+    // own-app key alone does not let the agent sign in.
+    const ready = (key) => {
+        const group = groups[key];
+        if (!isPlainObject(group))
+            return false;
+        const oauth = isPlainObject(group._schema) && isPlainObject(group._schema.oauth_provider);
+        return group._connected === true || (!oauth && group._filled === true);
+    };
+    return skills
+        .map(skill => ({
+        skill,
+        credentials: (registry.skills.get(skill)?.requiresCredentials
+            ? registry.skills.get(skill)?.credentialKeys ?? []
+            : []).filter(key => !ready(key)),
+    }))
+        .filter(entry => entry.credentials.length > 0);
+}
+const IDEMPOTENCY_KEY_RE = /^mcp-[0-9a-f]{16}-([0-9a-f]{10})-([0-9a-f]{8})$/;
+/** Fingerprint of one logical skill change, independent of the agent's current state. */
+export function skillChangeDigest(agentGuid, requested, tier) {
+    const entries = Object.keys(requested).sort().map(name => `${name}=${requested[name] ? 1 : 0}`);
+    return crypto.createHash('sha256')
+        .update([agentGuid, tier ?? '', ...entries].join('\n'))
+        .digest('hex')
+        .slice(0, 10);
+}
+function cents(value) {
+    return value === null || !Number.isFinite(value) ? 'none' : String(Math.round(value * 100));
+}
+/** Fingerprint of the monthly price before and after a change, as it was quoted. */
+export function skillPriceTag(currentUsd, newUsd) {
+    return crypto.createHash('sha256')
+        .update(`${cents(currentUsd)}:${cents(newUsd)}`)
+        .digest('hex')
+        .slice(0, 8);
+}
+export function newSkillChangeKey(digest, priceTag) {
+    return `mcp-${crypto.randomBytes(8).toString('hex')}-${digest}-${priceTag}`;
+}
+/** The change and price fingerprints of a key minted by this package, or null for any other key. */
+export function parseSkillChangeKey(key) {
+    const match = IDEMPOTENCY_KEY_RE.exec(key.trim());
+    return match ? { digest: match[1], priceTag: match[2] } : null;
+}
+/**
+ * Keys minted by this package carry the fingerprint of their change. Wiro
+ * answers a reused key with the saved result of the call that first used it,
+ * so a key is only sent with the change it was issued for.
+ */
+export function idempotencyKeyMismatch(key, digest) {
+    const parsed = parseSkillChangeKey(key);
+    return parsed !== null && parsed.digest !== digest;
+}
+export function planBilling(row) {
+    const wallet = asString(row.teamguid) ? 'team' : 'personal';
+    const subscription = isPlainObject(row.subscription) ? row.subscription : null;
+    if (!subscription) {
+        return { plan: 'none', status: null, periodEnd: null, daysRemaining: null, wallet, cancelAtPeriodEnd: false };
+    }
+    return {
+        plan: asString(subscription.provider) === 'prepaid' ? 'prepaid' : 'card',
+        status: asString(subscription.status) ?? null,
+        periodEnd: toNumber(subscription.currentperiodend),
+        daysRemaining: toNumber(subscription.daysremaining),
+        wallet,
+        cancelAtPeriodEnd: subscription.pendingdowngrade === 'cancel' || row.stripecancelatperiodend === true,
+    };
+}
+/**
+ * Wiro charges a prepaid plan the monthly difference for the days left in the
+ * period. The estimate assumes a 30-day period.
+ */
+export function estimateProratedUsd(deltaUsd, periodEndUnix, nowMs = Date.now(), periodDays = 30) {
+    if (periodEndUnix === null || !Number.isFinite(deltaUsd))
+        return null;
+    const remainingDays = Math.max(0, Math.round((periodEndUnix - nowMs / 1000) / 86400));
+    return Math.round((deltaUsd / periodDays) * remainingDays * 100) / 100;
+}
+const SKILL_PAYMENT_FAILED = 'The payment for this change did not go through, so the change was undone and nothing was charged.';
+const DEPOSIT_PAGE = 'https://wiro.ai/panel/wallet/deposit/credit-card (for a team project, select that team in the dashboard first)';
+/**
+ * What to do after a skill change whose payment failed, for the agent's plan
+ * when it is known. A wallet that does not cover the charge is refused before
+ * any payment (code 103), so a wallet plan needs no funds added here.
+ */
+function skillPaymentGuidance(plan) {
+    if (plan === 'prepaid')
+        return `${SKILL_PAYMENT_FAILED} The balance is not the cause, so no funds need to be added. Ask for a new quote and confirm it once the user approves.`;
+    if (plan === 'card')
+        return `${SKILL_PAYMENT_FAILED} Update the card in the Wiro dashboard, then ask for a new quote.`;
+    return `${SKILL_PAYMENT_FAILED} For a plan paid by card, update the card in the Wiro dashboard first. Then ask for a new quote.`;
+}
+/**
+ * Turns a refused SkillsApply into an explanation and the step that fixes it.
+ * With the agent's plan, a payment failure names only the fix for that plan.
+ */
+export function describeSkillsApplyError(error, plan) {
+    const message = error instanceof Error ? error.message : String(error);
+    const body = error instanceof ApiResultError ? error.body : {};
+    const codes = error instanceof ApiResultError ? error.codes.map(code => toNumber(code)) : [];
+    const code = codes.find(candidate => candidate !== null && candidate >= 95 && candidate <= 109) ?? null;
+    const base = { code, message, retrySameKey: false };
+    switch (code) {
+        case 101: {
+            const deps = (Array.isArray(body.deps) ? body.deps : [])
+                .filter(isPlainObject)
+                .map(dep => ({ skill: asString(dep.skill) ?? '', requires: asString(dep.requires) ?? '' }));
+            return {
+                ...base,
+                deps,
+                guidance: `Some skills need others that would be off: ${deps.map(dep => `${dep.skill} needs ${dep.requires}`).join('; ')}. Turn the needed skills on in the same change (add_dependencies does this for skills you turn on), or keep them on when you turn other skills off.`,
+            };
+        }
+        case 102: {
+            const conflicts = (Array.isArray(body.conflicts) ? body.conflicts : [])
+                .filter(isPlainObject)
+                .map(pair => ({ a: asString(pair.a) ?? '', b: asString(pair.b) ?? '' }));
+            return {
+                ...base,
+                conflicts,
+                guidance: `These skills cannot be on together: ${conflicts.map(pair => `${pair.a} and ${pair.b}`).join('; ')}. Keep only one of each pair.`,
+            };
+        }
+        case 103: {
+            const requiredUsd = toNumber(body.requiredUsd);
+            const availableUsd = toNumber(body.availableUsd);
+            return {
+                ...base,
+                requiredUsd,
+                availableUsd,
+                guidance: `The wallet does not cover the charge for the rest of this period${requiredUsd !== null ? `: it needs ${formatUsd(requiredUsd)}` : ''}${availableUsd !== null ? ` and has ${formatUsd(availableUsd)}` : ''}. Nothing was changed. Funds are added at ${DEPOSIT_PAGE}; once the user has added them and says yes, confirm again.`,
+            };
+        }
+        case 104:
+            return {
+                ...base,
+                retrySameKey: true,
+                guidance: 'Another skill change for this agent is still running. Wait a few seconds, then repeat the call with the same idempotency_key.',
+            };
+        case 105:
+            return {
+                ...base,
+                guidance: 'A Pro plan cannot be moved back to Starter here. Cancel the plan with manage_agent_billing and subscribe again at Starter once it ends.',
+            };
+        case 106:
+            return {
+                ...base,
+                guidance: 'The agent\'s subscription is not active, so its skills cannot change. Renew it with manage_agent_billing first.',
+            };
+        case 107:
+            return {
+                ...base,
+                guidance: 'Repeat the call without idempotency_key to start a fresh change.',
+            };
+        case 108:
+            return {
+                ...base,
+                retrySameKey: true,
+                guidance: 'Nothing was changed. Repeat the call with the same idempotency_key.',
+            };
+        case 109:
+            return {
+                ...base,
+                guidance: skillPaymentGuidance(plan),
+            };
+        case 95:
+        case 96:
+        case 97:
+            return {
+                ...base,
+                guidance: 'Only the agent\'s owner or an admin of the team that owns it can change its skills.',
+            };
+        default:
+            break;
+    }
+    if (/pricing snapshot|not found in registry/i.test(message)) {
+        return {
+            ...base,
+            guidance: 'The new price could not be computed, so nothing was changed. Check the skill names with list_agent_skills.',
+        };
+    }
+    return { ...base, guidance: workspaceHint(message) ?? '' };
+}
+/** The API names a dashboard concept ("team context"); here the workspace is the connected project's. */
+export function workspaceHint(message) {
+    return /switch to the (team|personal)|different team|personal workspace/i.test(message)
+        ? 'Connect with a project in the workspace (personal or team) that owns this agent, by its API key or a browser sign-in.'
+        : undefined;
+}
+// A field's setup help is shown whole: its last steps, such as sharing a
+// calendar with the service account, are part of the setup.
+export const FIELD_HELP_MAX = 4_000;
+export function htmlToText(value, maxLength = 400) {
+    const html = asString(value);
+    if (!html)
+        return undefined;
+    const text = html
+        .replace(/<\s*(br|\/p|\/li|\/div)\s*\/?>/gi, ' ')
+        .replace(/<[^>]*>/g, '')
+        .replace(/&nbsp;/g, ' ')
+        .replace(/&lt;/g, '<')
+        .replace(/&gt;/g, '>')
+        .replace(/&quot;/g, '"')
+        .replace(/&#39;/g, '\'')
+        .replace(/&amp;/g, '&')
+        .replace(/\s+/g, ' ')
+        .trim();
+    return text ? truncate(text, maxLength) : undefined;
+}
+function itemSchemaOf(raw) {
+    if (Array.isArray(raw.item_schema))
+        return raw.item_schema.filter(isPlainObject);
+    const config = isPlainObject(raw.custom_component_config) ? raw.custom_component_config : null;
+    if (!config)
+        return [];
+    for (const [key, value] of Object.entries(config)) {
+        if (key.startsWith('per_') && key.endsWith('_schema') && Array.isArray(value)) {
+            return value.filter(isPlainObject);
+        }
+    }
+    return [];
+}
+function parseOptions(value) {
+    if (!Array.isArray(value))
+        return undefined;
+    const options = value
+        .map(option => (isPlainObject(option) ? asString(option.value) ?? '' : asString(option)))
+        .filter((option) => option !== undefined);
+    return options.length > 0 ? options : undefined;
+}
+export function parseCredentialField(raw) {
+    const key = asString(raw.key) ?? '';
+    return {
+        key,
+        label: asString(raw.label) ?? key,
+        type: asString(raw.type) ?? 'text',
+        required: raw.required === true,
+        encrypted: raw.encrypted === true,
+        oauthManaged: raw.oauth_managed === true,
+        autoFilled: raw.auto_filled_by_oauth === true,
+        serverManaged: raw.server_managed === true,
+        platformManaged: raw.platform_managed === true,
+        onlyInModes: Array.isArray(raw.only_in_modes) ? stringList(raw.only_in_modes) : null,
+        ...(asString(raw.pattern) ? { pattern: asString(raw.pattern) } : {}),
+        ...(toNumber(raw.minlength) !== null ? { minLength: toNumber(raw.minlength) } : {}),
+        ...(toNumber(raw.maxlength) !== null ? { maxLength: toNumber(raw.maxlength) } : {}),
+        ...(parseOptions(raw.options) ? { options: parseOptions(raw.options) } : {}),
+        ...(Array.isArray(raw.filetypes) ? { fileTypes: stringList(raw.filetypes) } : {}),
+        ...(toNumber(raw.maxsize) !== null ? { maxSizeKb: toNumber(raw.maxsize) } : {}),
+        ...(asString(raw.item_type) ? { itemType: asString(raw.item_type) } : {}),
+        itemSchema: itemSchemaOf(raw).map(parseCredentialField).filter(field => field.key),
+        ...(htmlToText(raw.help, FIELD_HELP_MAX) ? { help: htmlToText(raw.help, FIELD_HELP_MAX) } : {}),
+        ...(asString(raw.placeholder) ? { placeholder: asString(raw.placeholder) } : {}),
+    };
+}
+function parsePicker(raw) {
+    if (!isPlainObject(raw) || raw.enabled === false)
+        return null;
+    const valueField = asString(raw.item_value_field);
+    if (!valueField)
+        return null;
+    const urlItemFields = {};
+    if (isPlainObject(raw.url_item_fields)) {
+        for (const [saved, source] of Object.entries(raw.url_item_fields)) {
+            if (asString(source))
+                urlItemFields[saved] = asString(source);
+        }
+    }
+    const nextRaw = isPlainObject(raw.next) && raw.next.enabled !== false ? raw.next : null;
+    const next = nextRaw && asString(nextRaw.key) && asString(nextRaw.item_value_field)
+        ? {
+            key: asString(nextRaw.key),
+            label: asString(nextRaw.modal_title)?.replace(/^select\s+/i, '') ?? asString(nextRaw.key),
+            optional: nextRaw.optional === true,
+            parentValueField: asString(nextRaw.parent_value_field) ?? valueField,
+            parentLabelField: asString(nextRaw.parent_label_field) ?? asString(raw.item_label_field) ?? valueField,
+            itemValueField: asString(nextRaw.item_value_field),
+            itemLabelField: asString(nextRaw.item_label_field) ?? asString(nextRaw.item_value_field),
+            persistField: asString(nextRaw.persist_field) ?? '',
+        }
+        : null;
+    return {
+        multiSelect: raw.multi_select === true,
+        valueField,
+        ...(asString(raw.item_label_field) ? { labelField: asString(raw.item_label_field) } : {}),
+        fieldsToSave: stringList(raw.item_fields_to_save).length > 0 ? stringList(raw.item_fields_to_save) : [valueField],
+        urlItemFields,
+        pendingCache: isPlainObject(raw.pending_cache),
+        next,
+    };
+}
+export function parseCredentialMeta(raw) {
+    const key = asString(raw.key) ?? '';
+    const fields = (Array.isArray(raw.credential_schema) ? raw.credential_schema : [])
+        .filter(isPlainObject)
+        .map(parseCredentialField)
+        .filter(field => field.key);
+    const provider = isPlainObject(raw.oauth_provider) ? raw.oauth_provider : null;
+    let oauth = null;
+    if (provider) {
+        const flow = isPlainObject(provider.oauth_flow) ? provider.oauth_flow : {};
+        const probe = isPlainObject(provider.direct_probe) ? provider.direct_probe : null;
+        const tokenField = probe ? asString(probe.token_field) : undefined;
+        oauth = {
+            ...(asString(flow.callback_path) ? { callbackPath: asString(flow.callback_path) } : {}),
+            stateFields: stringList(flow.state_fields),
+            connectRequirements: (Array.isArray(flow.connect_requirements) ? flow.connect_requirements : [])
+                .filter(isPlainObject)
+                .map(requirement => asString(requirement.message) ?? '')
+                .filter(Boolean),
+            directProbe: probe
+                ? {
+                    mode: asString(probe.mode) ?? 'api_key',
+                    ...(asString(probe.mode_label) ? { label: asString(probe.mode_label) } : {}),
+                    requiredFields: stringList(probe.required_fields).length > 0
+                        ? stringList(probe.required_fields)
+                        : (tokenField ? [tokenField] : []),
+                }
+                : null,
+            picker: parsePicker(provider.account_picker),
+        };
+    }
+    const channel = isPlainObject(raw.channel)
+        ? { id: asString(raw.channel.id) ?? key, requiredFields: stringList(raw.channel.required_fields) }
+        : null;
+    return {
+        key,
+        title: asString(raw.title) ?? key,
+        connectionModes: stringList(raw.connection_modes),
+        ...(asString(raw.default_connection_mode) ? { defaultConnectionMode: asString(raw.default_connection_mode) } : {}),
+        wiroPending: raw.wiro_connect_pending === true,
+        fields,
+        channel,
+        oauth,
+        platformOnly: raw.credential_mode === 'rule_only'
+            || (!provider && fields.length > 0 && fields.every(field => field.platformManaged)),
+    };
+}
+/** The modes a connection can use now: wiro is left out while the registry marks it pending. */
+export function usableConnectionModes(meta) {
+    return meta.connectionModes.filter(mode => mode !== 'wiro' || !meta.wiroPending);
+}
+/** Returns null when the registry has no credential with that key. */
+export async function loadCredentialMeta(client, key, signal) {
+    try {
+        return await cachedRead(client, `credential:${key}`, async () => {
+            const body = requireApiSuccess(await client.post('/Credentials/Detail', { key }, signal), `Could not read the credential "${key}".`);
+            if (!isPlainObject(body.credential)) {
+                throw new ApiResultError(`Credential not found: ${key}`, [404], body);
+            }
+            return parseCredentialMeta(body.credential);
+        });
+    }
+    catch (error) {
+        if (hasErrorCode(error, 404))
+            return null;
+        throw error;
+    }
+}
+const OBJECT_LIST_TYPES = new Set([
+    'custom:apps-list-ios',
+    'custom:apps-list-android',
+    'custom:apps-list-adjust',
+    'custom:urls-list',
+    'custom:firebase-accounts-list',
+    'custom:drive-folder-picker',
+]);
+/** Mirrors how the API stores a field: lists of rows, lists of strings, files or one value. */
+export function credentialFieldShape(field) {
+    const type = field.type;
+    if (type === 'object-array' || OBJECT_LIST_TYPES.has(type))
+        return 'object-array';
+    if (type === 'string-array')
+        return 'string-array';
+    if (type === 'array') {
+        if (field.itemType === 'object')
+            return 'object-array';
+        if (field.itemType === 'string')
+            return 'string-array';
+        return field.itemSchema.length > 0 ? 'object-array' : 'string-array';
+    }
+    if (type === 'fileinput')
+        return 'file';
+    if (type === 'fileinput-base64')
+        return 'base64-file';
+    if (type === 'boolean')
+        return 'boolean';
+    if (type === 'number')
+        return 'number';
+    if (type === 'select')
+        return 'select';
+    return 'text';
+}
+/** Fields the connection flow or Wiro fills; customers cannot write them. */
+export function isWritableField(field) {
+    return !field.autoFilled && !field.serverManaged && !field.platformManaged && field.type !== 'computed';
+}
+// Token state the connection flow owns.
+const CONNECTION_STATE_FIELDS = new Set([
+    'accesstoken',
+    'refreshtoken',
+    'connectedat',
+    'tokenexpiresat',
+    'refreshtokenexpiresat',
+]);
+/**
+ * Base64 file fields hold the file's bytes as base64. Callers often have the
+ * file's text instead (a service account JSON, a .p8 key), so anything that is
+ * not already base64 is encoded here.
+ */
+export function normalizeBase64FileValue(value) {
+    const dataUrl = /^data:[^,]*;base64,(.*)$/s.exec(value.trim());
+    if (dataUrl)
+        return (dataUrl[1] ?? '').replace(/\s+/g, '');
+    const compact = value.replace(/\s+/g, '');
+    if (compact && compact.length % 4 === 0 && /^[A-Za-z0-9+/]+={0,2}$/.test(compact))
+        return compact;
+    return Buffer.from(value, 'utf8').toString('base64');
+}
+function isJsonObjectText(text) {
+    try {
+        return isPlainObject(JSON.parse(text));
+    }
+    catch {
+        return false;
+    }
+}
+/** A key file field's value as Wiro stores it, or why it is refused. The value itself is never repeated. */
+function keyFileValue(field, value, label) {
+    if (typeof value !== 'string')
+        return { error: `${label} takes the file's content as text or base64.` };
+    // Key files take the file's text; refuse a link before anything is saved.
+    if (/^\s*https?:\/\//i.test(value)) {
+        return { error: `${label} takes the file's content as text or base64, not a link. The user can paste the file's text or upload the file on the agent's page in the Wiro dashboard.` };
+    }
+    const stored = normalizeBase64FileValue(value);
+    // A JSON key, such as a service account file, must hold a JSON object, so a
+    // path, a share link or an id is refused before anything is saved.
+    if (field.fileTypes?.includes('application/json') && !isJsonObjectText(Buffer.from(stored, 'base64').toString('utf8'))) {
+        return { error: `${label} takes the text of the JSON key file. This value is not JSON. The user can paste the file's text or upload the file on the agent's page in the Wiro dashboard.` };
+    }
+    return { value: stored };
+}
+function isEmptyValue(value) {
+    if (value === null || value === undefined)
+        return true;
+    if (typeof value === 'string')
+        return value.trim() === '';
+    if (Array.isArray(value))
+        return value.length === 0;
+    return false;
+}
+// Short values (select options, flags) are not secrets and would garble messages.
+function collectStrings(value, into) {
+    if (typeof value === 'string') {
+        if (value.trim().length >= 8)
+            into.push(value.trim());
+    }
+    else if (Array.isArray(value)) {
+        for (const item of value)
+            collectStrings(item, into);
+    }
+    else if (isPlainObject(value)) {
+        for (const item of Object.values(value))
+            collectStrings(item, into);
+    }
+}
+function patternError(field, value, label) {
+    if (field.minLength !== undefined && value.length < field.minLength) {
+        return `${label} must be at least ${field.minLength} characters.`;
+    }
+    if (field.maxLength !== undefined && value.length > field.maxLength) {
+        return `${label} must be at most ${field.maxLength} characters.`;
+    }
+    if (field.pattern) {
+        try {
+            if (!new RegExp(field.pattern).test(value))
+                return `${label} has an invalid format (expected pattern ${field.pattern}).`;
+        }
+        catch {
+            return null;
+        }
+    }
+    return null;
+}
+function fieldList(fields) {
+    return fields.filter(isWritableField).map(field => field.key).join(', ');
+}
+function scalarValue(field, value, label) {
+    const shape = credentialFieldShape(field);
+    if (shape === 'boolean') {
+        return typeof value === 'boolean' ? { value } : { error: `${label} takes true or false.` };
+    }
+    if (shape === 'number') {
+        const number = toNumber(value);
+        return number === null ? { error: `${label} takes a number.` } : { value: number };
+    }
+    if (typeof value !== 'string' && typeof value !== 'number') {
+        return { error: `${label} takes a single text value.` };
+    }
+    const text = String(value);
+    if (shape === 'select' && field.options && !field.options.includes(text)) {
+        return { error: `${label} must be one of: ${field.options.map(option => option || '(empty)').join(', ')}.` };
+    }
+    const problem = text.trim() ? patternError(field, text.trim(), label) : null;
+    return problem ? { error: problem } : { value: text };
+}
+/**
+ * A list field's value. Items and rows are named the way Wiro names them,
+ * counting from 1: "Allowed Telegram DM User IDs #2" at the top level, and
+ * itemLabel names the items of a text list inside an entry.
+ */
+function listValue(field, value, label, itemLabel = index => `${label} #${index + 1}`) {
+    const shape = credentialFieldShape(field);
+    if (!Array.isArray(value))
+        return { error: `${label} takes a list (JSON array).` };
+    if (shape === 'string-array') {
+        const items = [];
+        for (const [index, item] of value.entries()) {
+            if (typeof item !== 'string' && typeof item !== 'number') {
+                return { error: `${field.label} takes a list of text values; ${itemLabel(index)} is not one.` };
+            }
+            const text = String(item).trim();
+            if (!text)
+                continue;
+            const problem = patternError(field, text, itemLabel(index));
+            if (problem)
+                return { error: problem };
+            items.push(text);
+        }
+        return { value: items };
+    }
+    return rowsValue(field, value, index => `${label} #${index + 1}`);
+}
+function isListField(field) {
+    const shape = credentialFieldShape(field);
+    return shape === 'object-array' || shape === 'string-array';
+}
+/**
+ * The rows of a list of objects, checked the way Wiro checks them: only the
+ * keys the item schema declares, each value by its own rules, and a list inside
+ * a row (such as the apps of one Firebase account) by its own shape. Errors
+ * name the row the way Wiro does: "App ID in Apps #2 in Firebase Accounts #1".
+ */
+function rowsValue(field, value, rowLabel) {
+    const allowed = new Set(field.itemSchema.map(item => item.key));
+    const rows = [];
+    for (const [index, item] of value.entries()) {
+        const label = rowLabel(index);
+        if (!isPlainObject(item))
+            return { error: `${field.label} takes a list of objects; ${label} is not one.` };
+        if (allowed.size > 0) {
+            const unknown = Object.keys(item).filter(key => !allowed.has(key));
+            if (unknown.length > 0) {
+                return { error: `${label} has unknown keys (${unknown.join(', ')}). Allowed: ${[...allowed].join(', ')}.` };
+            }
+        }
+        const row = { ...item };
+        for (const entry of field.itemSchema) {
+            const checked = isListField(entry)
+                ? nestedListValue(entry, row[entry.key], label)
+                : rowFieldValue(entry, row[entry.key], `${entry.label} in ${label}`);
+            if (checked.error)
+                return { error: checked.error };
+            if (Object.prototype.hasOwnProperty.call(row, entry.key))
+                row[entry.key] = checked.value;
+        }
+        rows.push(row);
+    }
+    return { value: rows };
+}
+/** One value in a list row: required, options, length and pattern, as Wiro checks it. */
+function rowFieldValue(field, value, label) {
+    if (!isFilledValue(value))
+        return field.required ? { error: `${label} is required.` } : { value };
+    const shape = credentialFieldShape(field);
+    // Key files inside a row, such as each Firebase account's service account JSON, are stored like top-level ones.
+    if (shape === 'base64-file')
+        return keyFileValue(field, value, label);
+    if (typeof value === 'object')
+        return { error: `${label} takes a single text value.` };
+    const text = String(value);
+    if (shape === 'select' && field.options && !field.options.includes(text)) {
+        return { error: `${label} must be one of: ${field.options.map(option => option || '(empty)').join(', ')}.` };
+    }
+    const problem = patternError(field, text, label);
+    return problem ? { error: problem } : { value };
+}
+/**
+ * A list inside one entry of a list, such as the apps of one Firebase account,
+ * in a whole write of the outer list or on its own with parent_field: rows
+ * checked against its item schema, or text items.
+ */
+function nestedListValue(field, value, entryLabel) {
+    const label = `${field.label} in ${entryLabel}`;
+    if (!Array.isArray(value)) {
+        if (isFilledValue(value))
+            return { error: `${label} takes a list (JSON array).` };
+        return field.required ? { error: `${label} is required.` } : { value };
+    }
+    const checked = credentialFieldShape(field) === 'object-array'
+        ? rowsValue(field, value, index => `${field.label} #${index + 1} in ${entryLabel}`)
+        : listValue({ ...field, type: 'string-array' }, value, label, index => `${label}, item #${index + 1}`);
+    if (checked.error)
+        return checked;
+    return field.required && Array.isArray(checked.value) && checked.value.length === 0
+        ? { error: `${label} is required.` }
+        : checked;
+}
+/**
+ * Checks every requested field against the credential registry and builds the
+ * API payload. Nothing is written when any field is refused.
+ */
+export function prepareCredentialWrite(inputs, metas) {
+    const prepared = { apiFields: [], files: [], errors: [], secrets: [] };
+    const reportedUnknown = new Set();
+    for (const input of inputs) {
+        collectStrings(input.value, prepared.secrets);
+        const credential = input.credential.trim();
+        const fieldName = input.field.trim();
+        const meta = metas.get(credential) ?? null;
+        if (!meta) {
+            if (!reportedUnknown.has(credential)) {
+                prepared.errors.push(`Unknown credential "${credential}". The credential keys a skill uses are listed by list_agent_skills and get_my_agent.`);
+                reportedUnknown.add(credential);
+            }
+            continue;
+        }
+        if (meta.platformOnly) {
+            prepared.errors.push(`${meta.title} is managed by Wiro and cannot be set.`);
+            continue;
+        }
+        if (!fieldName) {
+            prepared.errors.push(`${meta.title}: the field key is empty.`);
+            continue;
+        }
+        if (fieldName.startsWith('_')) {
+            prepared.errors.push(`${meta.title}: "${fieldName}" is a reserved name.`);
+            continue;
+        }
+        if (CONNECTION_STATE_FIELDS.has(fieldName)) {
+            prepared.errors.push(`${meta.title}: "${fieldName}" is filled by the connection itself. Use connect_agent_oauth.`);
+            continue;
+        }
+        if (fieldName === 'authmethod') {
+            const usable = usableConnectionModes(meta);
+            if (input.parent_field || usable.length === 0) {
+                prepared.errors.push(`${meta.title} has no connection modes, so "authmethod" does not apply.`);
+            }
+            else if (typeof input.value !== 'string' || !usable.includes(input.value)) {
+                prepared.errors.push(`${meta.title}: authmethod must be one of ${usable.join(', ')}.`);
+            }
+            else {
+                prepared.apiFields.push({ credentialkey: credential, fieldname: 'authmethod', fieldvalue: input.value });
+            }
+            continue;
+        }
+        if (input.parent_field) {
+            const root = input.parent_field.split(/[.[\]]/)[0]?.trim() ?? '';
+            const parent = meta.fields.find(field => field.key === root);
+            if (!parent || credentialFieldShape(parent) !== 'object-array') {
+                prepared.errors.push(`${meta.title} has no list field "${root}" for parent_field. List fields: ${meta.fields.filter(field => credentialFieldShape(field) === 'object-array').map(field => field.key).join(', ') || 'none'}.`);
+                continue;
+            }
+            // Wiro checks and stores an entry's field under the list's own key and
+            // the entry's position, so parent_field takes that key alone and the
+            // position goes in ordinal.
+            if (input.parent_field.trim() !== parent.key) {
+                prepared.errors.push(`${parent.label}: parent_field takes the list field's key alone ("${parent.key}"); pass the entry's position, from 0, as ordinal.`);
+                continue;
+            }
+            if (!isWritableField(parent)) {
+                prepared.errors.push(`${parent.label} is filled by the connection or by Wiro and cannot be set.`);
+                continue;
+            }
+            const item = parent.itemSchema.find(candidate => candidate.key === fieldName);
+            if (parent.itemSchema.length > 0 && !item) {
+                prepared.errors.push(`${parent.label} entries have no field "${fieldName}". Entry fields: ${parent.itemSchema.map(candidate => candidate.key).join(', ')}.`);
+                continue;
+            }
+            if (input.ordinal === undefined) {
+                prepared.errors.push(`${parent.label}: ordinal (the entry's position, from 0) is required with parent_field.`);
+                continue;
+            }
+            // The entry is named the way Wiro names it, counting from 1.
+            const entryLabel = `${parent.label} #${input.ordinal + 1}`;
+            let value = input.value;
+            // An entry's field is checked as it is in a whole write of the list,
+            // empty values included, so a required one cannot be cleared.
+            if (item) {
+                const checked = isListField(item)
+                    ? nestedListValue(item, isEmptyValue(value) ? [] : value, entryLabel)
+                    : rowFieldValue(item, value, `${item.label} in ${entryLabel}`);
+                if (checked.error) {
+                    prepared.errors.push(checked.error);
+                    continue;
+                }
+                value = checked.value;
+            }
+            prepared.apiFields.push({
+                credentialkey: credential,
+                fieldname: fieldName,
+                fieldvalue: item && !isFilledValue(value) ? (isListField(item) ? [] : '') : (value ?? ''),
+                parentfield: parent.key,
+                ordinal: input.ordinal,
+            });
+            continue;
+        }
+        const field = meta.fields.find(candidate => candidate.key === fieldName);
+        if (!field) {
+            prepared.errors.push(`${meta.title} has no field "${fieldName}". Fields you can set: ${fieldList(meta.fields) || 'none'}.`);
+            continue;
+        }
+        if (field.platformManaged) {
+            prepared.errors.push(`${field.label} is managed by Wiro and cannot be set.`);
+            continue;
+        }
+        if (!isWritableField(field)) {
+            prepared.errors.push(`${field.label} is filled when the account is connected with connect_agent_oauth and cannot be set directly.`);
+            continue;
+        }
+        const shape = credentialFieldShape(field);
+        // Channel groups are optional as a whole: clearing one activation field turns the channel off.
+        const mayClear = !field.required || meta.channel !== null;
+        if (isEmptyValue(input.value)) {
+            if (!mayClear) {
+                prepared.errors.push(`${field.label} is required and cannot be cleared.`);
+                continue;
+            }
+            const cleared = shape === 'string-array' || shape === 'object-array' ? [] : '';
+            prepared.apiFields.push({ credentialkey: credential, fieldname: fieldName, fieldvalue: cleared });
+            continue;
+        }
+        if (shape === 'file') {
+            const url = typeof input.value === 'string' ? input.value.trim() : '';
+            if (!/^https?:\/\//i.test(url)) {
+                prepared.errors.push(`${field.label} takes the public http(s) URL of the file to upload.`);
+                continue;
+            }
+            prepared.files.push({
+                credential,
+                field: fieldName,
+                label: field.label,
+                url,
+                fileTypes: field.fileTypes ?? [],
+                maxBytes: (field.maxSizeKb ?? 10240) * 1024,
+            });
+            continue;
+        }
+        if (shape === 'base64-file') {
+            const checked = keyFileValue(field, input.value, field.label);
+            if (checked.error) {
+                prepared.errors.push(checked.error);
+                continue;
+            }
+            prepared.apiFields.push({ credentialkey: credential, fieldname: fieldName, fieldvalue: checked.value });
+            continue;
+        }
+        const checked = shape === 'string-array' || shape === 'object-array'
+            ? listValue(field, input.value, field.label)
+            : scalarValue(field, input.value, field.label);
+        if (checked.error) {
+            prepared.errors.push(checked.error);
+            continue;
+        }
+        if ((shape === 'string-array' || shape === 'object-array')
+            && Array.isArray(checked.value) && checked.value.length === 0 && !mayClear) {
+            prepared.errors.push(`${field.label} is required and cannot be empty.`);
+            continue;
+        }
+        prepared.apiFields.push({ credentialkey: credential, fieldname: fieldName, fieldvalue: checked.value });
+    }
+    return prepared;
+}
+/** Removes every value the caller sent from a message before it is shown. */
+export function redactSecrets(text, secrets) {
+    let out = text;
+    for (const secret of [...secrets].sort((left, right) => right.length - left.length)) {
+        if (secret.length >= 8)
+            out = out.split(secret).join('[hidden]');
+    }
+    return out;
+}
+const EXTENSION_BY_TYPE = {
+    'audio/mpeg': 'mp3',
+    'audio/mp3': 'mp3',
+    'audio/wav': 'wav',
+    'audio/x-wav': 'wav',
+    'audio/ogg': 'ogg',
+    'image/png': 'png',
+    'image/jpeg': 'jpg',
+    'image/webp': 'webp',
+    'application/pdf': 'pdf',
+};
+/** The API derives the stored file's extension from its name, so one is always added. */
+export function uploadFileName(url, field, contentType) {
+    let base = '';
+    try {
+        base = decodeURIComponent(new URL(url).pathname.split('/').pop() ?? '');
+    }
+    catch {
+        base = '';
+    }
+    base = base.replace(/[^A-Za-z0-9._-]+/g, '_').slice(-100);
+    if (/\.[A-Za-z0-9]{2,5}$/.test(base))
+        return base;
+    const extension = EXTENSION_BY_TYPE[contentType] ?? 'bin';
+    return `${base || field}.${extension}`;
+}
+// ---------------------------------------------------------------------------
+// Agent credential status (from /UserAgent/Detail, values never read out)
+// ---------------------------------------------------------------------------
+export function isFilledValue(value) {
+    if (value === null || value === undefined)
+        return false;
+    if (typeof value === 'string')
+        return value.trim() !== '';
+    if (Array.isArray(value))
+        return value.some(isFilledValue);
+    if (isPlainObject(value))
+        return Object.values(value).some(isFilledValue);
+    return true;
+}
+export function credentialGroup(row, key) {
+    const groups = isPlainObject(row.credentials) ? row.credentials : null;
+    const group = groups ? groups[key] : undefined;
+    return isPlainObject(group) ? group : null;
+}
+export function credentialStatus(row, key, meta) {
+    const group = credentialGroup(row, key);
+    if (!group)
+        return null;
+    const schema = isPlainObject(group._schema) ? group._schema : {};
+    const connected = group._connected === true;
+    // A sign-in credential's required fields depend on its mode; connected is the signal there.
+    const missingFields = connected || !meta || meta.oauth
+        ? []
+        : meta.fields
+            .filter(field => field.required && isWritableField(field) && !isFilledValue(group[field.key]))
+            .map(field => field.label);
+    return {
+        key,
+        title: asString(schema.title) ?? meta?.title ?? key,
+        connected,
+        filled: group._filled === true,
+        requiredMissing: group._required_missing === true,
+        optional: group.optional === true,
+        missingFields,
+    };
+}
+export function channelStatuses(row) {
+    const channels = Array.isArray(row.communicationChannels) ? row.communicationChannels : [];
+    return channels.filter(isPlainObject).map(channel => {
+        const schema = isPlainObject(channel.schema) ? channel.schema : {};
+        const labels = new Map();
+        for (const field of Array.isArray(schema.fields) ? schema.fields : []) {
+            if (isPlainObject(field) && asString(field.key)) {
+                labels.set(asString(field.key), asString(field.label) ?? asString(field.key));
+            }
+        }
+        const id = asString(channel.id) ?? '';
+        return {
+            id,
+            title: asString(channel.title) ?? id,
+            credential: asString(channel.credentialkey) ?? id,
+            enabled: channel.enabled === true,
+            missingFields: stringList(channel.missingfields).map(field => labels.get(field) ?? field),
+        };
+    });
+}
+// ---------------------------------------------------------------------------
+// Sign-in connections (connect_agent_oauth)
+// ---------------------------------------------------------------------------
+/**
+ * Wiro sends the browser to this address after sign-in with the connected
+ * account names appended, so only the agent's own dashboard page or an
+ * address on the user's own machine is accepted.
+ */
+export function isAllowedRedirectUrl(url, agentGuid) {
+    let parsed;
+    try {
+        parsed = new URL(url.trim());
+    }
+    catch {
+        return false;
+    }
+    if (parsed.username || parsed.password)
+        return false;
+    if (parsed.protocol === 'http:')
+        return parsed.hostname === 'localhost' || parsed.hostname === '127.0.0.1';
+    const dashboard = new URL(dashboardAgentUrl(agentGuid));
+    return parsed.protocol === 'https:'
+        && parsed.host === dashboard.host
+        && parsed.pathname.replace(/\/+$/, '') === dashboard.pathname
+        && (parsed.search === '' || parsed.search === dashboard.search)
+        && parsed.hash === '';
+}
+/** The redirect URI a customer registers in their own OAuth app. */
+export function ownAppRedirectUri(meta) {
+    return meta.oauth?.callbackPath ? `${OAUTH_CALLBACK_BASE}${meta.oauth.callbackPath}` : undefined;
+}
+function fieldsForMode(meta, mode) {
+    if (mode === 'wiro')
+        return [];
+    const byKey = new Map(meta.fields.map(field => [field.key, field]));
+    const keys = [];
+    if (mode === meta.oauth?.directProbe?.mode) {
+        keys.push(...meta.oauth.directProbe.requiredFields);
+    }
+    else {
+        for (const field of meta.fields) {
+            if (isWritableField(field) && field.onlyInModes?.includes(mode))
+                keys.push(field.key);
+        }
+        if (mode === 'own')
+            keys.push(...(meta.oauth?.stateFields ?? []));
+    }
+    return [...new Set(keys)]
+        .map(key => byKey.get(key) ?? { ...parseCredentialField({ key }), required: true })
+        .filter(field => isWritableField(field));
+}
+/** What each connection mode needs, with which of those fields are already saved. */
+export function connectionModeRequirements(meta, group) {
+    const modes = meta.connectionModes.length > 0 ? meta.connectionModes : ['wiro'];
+    return modes.map(mode => {
+        const fields = fieldsForMode(meta, mode).map(field => ({
+            field: field.key,
+            label: field.label,
+            isSet: group !== null && isFilledValue(group[field.key]),
+        }));
+        if (mode === 'wiro') {
+            return {
+                mode,
+                available: !meta.wiroPending,
+                needsBrowser: true,
+                fields,
+                note: meta.wiroPending
+                    ? `Use another mode for ${meta.title}.`
+                    : `Sign in through Wiro's own ${meta.title} app. Nothing to set up first.`,
+            };
+        }
+        if (mode === meta.oauth?.directProbe?.mode) {
+            return {
+                mode,
+                available: true,
+                needsBrowser: false,
+                fields,
+                note: `Save ${meta.oauth.directProbe.label ? `the ${meta.oauth.directProbe.label}` : 'these fields'} with set_agent_credentials, then connect with mode ${mode}. Wiro checks it and lists the accounts it can use. No browser needed.`,
+            };
+        }
+        if (mode === 'api_key') {
+            return {
+                mode,
+                available: true,
+                needsBrowser: false,
+                fields,
+                note: `Save these fields with set_agent_credentials together with authmethod ${mode}. There is no sign-in or connect step for this mode.`,
+            };
+        }
+        if (mode === 'own') {
+            const redirect = ownAppRedirectUri(meta);
+            const requirements = meta.oauth?.connectRequirements ?? [];
+            return {
+                mode,
+                available: true,
+                needsBrowser: true,
+                fields,
+                note: `Use your own ${meta.title} app: save its keys with set_agent_credentials${redirect ? ` and allow ${redirect} as a redirect URI in the app` : ''}, then connect with mode own and sign in.${requirements.length > 0 ? ` ${requirements.join(' ')}` : ''}`,
+            };
+        }
+        return { mode, available: true, needsBrowser: true, fields, note: `Connect with mode ${mode}.` };
+    });
+}
+/**
+ * The mode to use when the caller did not name one: Wiro's own app when it is
+ * available, the only remaining mode, or the first mode whose fields are
+ * already saved (the registry's default first).
+ */
+export function chooseConnectionMode(meta, requirements) {
+    const usable = requirements.filter(requirement => requirement.available);
+    const wiro = usable.find(requirement => requirement.mode === 'wiro');
+    if (wiro)
+        return 'wiro';
+    if (usable.length === 1)
+        return usable[0]?.mode ?? null;
+    const ordered = [...usable].sort((left, right) => {
+        const preferred = meta.defaultConnectionMode;
+        return Number(right.mode === preferred) - Number(left.mode === preferred);
+    });
+    return ordered.find(requirement => requirement.fields.every(field => field.isSet))?.mode ?? null;
+}
+/** Candidate or saved accounts in one shape, whatever the provider calls the fields. */
+export function toAccountRefs(list, picker) {
+    if (!Array.isArray(list))
+        return [];
+    return list.filter(isPlainObject).map(item => {
+        const id = asString(item.id) ?? (picker ? asString(item[picker.valueField]) : undefined) ?? '';
+        const name = asString(item.name)
+            ?? asString(item.title)
+            ?? asString(item.displayName)
+            ?? (picker?.labelField ? asString(item[picker.labelField]) : undefined)
+            ?? '';
+        return { id, name };
+    }).filter(account => account.id);
+}
+/** Maps {id, name} selections onto the fields the picker saves. */
+export function buildPickerAccounts(picker, accounts) {
+    if (accounts.length === 0)
+        return { error: 'Pass at least one account.' };
+    if (!picker.multiSelect && accounts.length !== 1)
+        return { error: 'This connection uses exactly one account.' };
+    const seen = new Set();
+    const out = [];
+    for (const account of accounts) {
+        const id = asString(account.id) ?? asString(account[picker.valueField]) ?? '';
+        const name = asString(account.name)
+            ?? (picker.labelField ? asString(account[picker.labelField]) : undefined)
+            ?? asString(account.title)
+            ?? asString(account.displayName)
+            ?? '';
+        if (!id.trim())
+            return { error: 'Every account needs an id.' };
+        if (seen.has(id.trim()))
+            return { error: `Account ${id} is listed twice.` };
+        seen.add(id.trim());
+        const mapped = {};
+        for (const field of picker.fieldsToSave) {
+            if (field === picker.valueField)
+                mapped[field] = id.trim();
+            else if (field === picker.labelField)
+                mapped[field] = name;
+            else if (asString(account[field]) !== undefined)
+                mapped[field] = asString(account[field]);
+            else
+                mapped[field] = picker.urlItemFields[field] === 'id' ? id.trim() : name;
+        }
+        out.push(mapped);
+    }
+    return { accounts: out };
+}
+export function parseDiscoveredGroups(next, groups) {
+    if (!Array.isArray(groups))
+        return [];
+    return groups.filter(isPlainObject).map(group => {
+        const parent = isPlainObject(group.parent) ? group.parent : {};
+        const items = Array.isArray(group.items) ? group.items.filter(isPlainObject) : [];
+        return {
+            parent: {
+                id: asString(parent[next.parentValueField]) ?? '',
+                name: asString(parent[next.parentLabelField]) ?? '',
+            },
+            items: items
+                .map(item => ({
+                id: asString(item[next.itemValueField]) ?? '',
+                name: asString(item[next.itemLabelField]) ?? '',
+            }))
+                .filter(item => item.id),
+            ...(asString(group.errorcode) ? { errorCode: asString(group.errorcode) } : {}),
+        };
+    });
+}
+function sameId(left, right) {
+    if (left.trim() === right.trim())
+        return true;
+    const digits = (value) => value.replace(/\D+/g, '');
+    return digits(left) !== '' && digits(left) === digits(right);
+}
+/**
+ * Builds the chained-step payload from a fresh discovery. The API wants every
+ * readable parent exactly once and each item with its discovered label, so
+ * parents the caller left out are sent with no items.
+ */
+export function buildChainedSelections(next, groups, selections) {
+    const chosen = new Map();
+    for (const selection of selections) {
+        const group = groups.find(candidate => sameId(candidate.parent.id, selection.parent));
+        if (!group) {
+            return {
+                skippedParents: [],
+                error: `Account "${selection.parent}" is not among the connected accounts (${groups.map(candidate => candidate.parent.id).join(', ') || 'none'}).`,
+            };
+        }
+        if (group.errorCode) {
+            return {
+                skippedParents: [],
+                error: `${group.parent.name || group.parent.id} could not be read (${group.errorCode}), so nothing can be chosen for it. Leave it out.`,
+            };
+        }
+        const ids = chosen.get(group.parent.id) ?? [];
+        for (const itemId of selection.items) {
+            const item = group.items.find(candidate => sameId(candidate.id, itemId));
+            if (!item) {
+                return {
+                    skippedParents: [],
+                    error: `"${itemId}" is not available under ${group.parent.name || group.parent.id}. Available: ${group.items.map(candidate => `${candidate.id} (${candidate.name})`).join(', ') || 'none'}.`,
+                };
+            }
+            if (!ids.includes(item.id))
+                ids.push(item.id);
+        }
+        chosen.set(group.parent.id, ids);
+    }
+    const skippedParents = [];
+    const payload = groups.filter(group => !group.errorCode).map(group => {
+        const ids = chosen.get(group.parent.id);
+        if (!ids)
+            skippedParents.push(group.parent);
+        return {
+            parentvalue: group.parent.id,
+            items: group.items
+                .filter(item => ids?.includes(item.id))
+                .map(item => ({ [next.itemValueField]: item.id, [next.itemLabelField]: item.name })),
+        };
+    });
+    return { selections: payload, skippedParents };
+}
+export function parseOAuthStatus(body, picker) {
+    let childStep = null;
+    const next = picker?.next;
+    const steps = isPlainObject(body.pickersteps) ? body.pickersteps : null;
+    const step = next && steps && isPlainObject(steps[next.key]) ? steps[next.key] : null;
+    if (next && step) {
+        childStep = {
+            picker: next.key,
+            optional: step.optional === true,
+            configured: step.configured === true,
+            groups: parseDiscoveredGroups(next, step.groups).map(group => ({ parent: group.parent, items: group.items })),
+        };
+    }
+    return {
+        connected: body.connected === true,
+        accounts: toAccountRefs(body.accounts, picker),
+        connectedAt: asString(body.connectedat) ?? '',
+        tokenExpiresAt: asString(body.tokenexpiresat) ?? '',
+        childStep,
+    };
+}
+export async function readOAuthStatus(client, agentGuid, credential, picker, signal) {
+    const body = requireApiSuccess(await client.post('/UserAgentOAuth/OAuthStatus', {
+        useragentguid: agentGuid,
+        credentialkey: credential,
+    }, signal), 'Could not read the connection status.');
+    return parseOAuthStatus(body, picker);
+}
+/**
+ * Wiro reports a picker credential as not connected until an account is
+ * saved, so a fresh connectedat with no accounts means "signed in, accounts
+ * still to choose". since is the connectedat seen before the sign-in started.
+ */
+export function connectionState(status, options) {
+    if (options.since !== undefined && status.connectedAt === options.since)
+        return 'waiting_for_user';
+    if (status.connected) {
+        return status.childStep && !status.childStep.optional && !status.childStep.configured
+            ? 'pick_child_items'
+            : 'connected';
+    }
+    const expiresAt = Date.parse(status.tokenExpiresAt);
+    if (Number.isFinite(expiresAt) && expiresAt <= (options.nowMs ?? Date.now())
+        && (status.accounts.length > 0 || status.connectedAt)) {
+        return 'token_expired';
+    }
+    if (options.hasPicker && status.connectedAt && status.accounts.length === 0)
+        return 'pick_accounts';
+    return 'not_connected';
+}
+const SLUG_RE = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+/**
+ * Same rules as the API's key normalisation: cs-cron-x and cs-x stay, cron-x
+ * becomes cs-cron-x, and a bare slug gets cs-cron- when scheduled (or given a
+ * non-empty interval) and cs- otherwise. The slug is 1-60 characters of
+ * lowercase letters, digits and single dashes. Returns null when invalid.
+ */
+export function normalizeCustomSkillKey(input, options = {}) {
+    if (typeof input !== 'string')
+        return null;
+    const trimmed = input.trim();
+    if (!trimmed)
+        return null;
+    let prefix;
+    let body;
+    if (trimmed.startsWith('cs-cron-')) {
+        prefix = 'cs-cron-';
+        body = trimmed.slice('cs-cron-'.length);
+    }
+    else if (trimmed.startsWith('cs-')) {
+        prefix = 'cs-';
+        body = trimmed.slice('cs-'.length);
+    }
+    else if (trimmed.startsWith('cron-')) {
+        prefix = 'cs-';
+        body = trimmed;
+    }
+    else {
+        let scheduled = options.scheduled === true;
+        if (!scheduled && options.hasInterval !== undefined && options.hasInterval !== null && options.hasInterval !== false) {
+            const interval = String(options.hasInterval).trim().toLowerCase();
+            scheduled = interval !== '' && interval !== 'manual' && interval !== 'false';
+        }
+        prefix = scheduled ? 'cs-cron-' : 'cs-';
+        body = trimmed;
+    }
+    if (body.length === 0 || body.length > 60 || !SLUG_RE.test(body))
+        return null;
+    return prefix + body;
+}
+export function customSkillKindOf(key) {
+    return key.startsWith('cs-cron-') ? 'scheduled_task' : 'skill';
+}
+const INVALID_KEY_MESSAGE = 'Use lowercase letters, digits and single dashes, for example lead-strategy (at most 60 characters after the cs- or cs-cron- prefix).';
+function isBareCustomSkillKey(key) {
+    return !key.startsWith('cs-') && !key.startsWith('cron-');
+}
+/**
+ * The key an upsert writes, computed with the API's own rules. With the
+ * agent's entries, a bare key with no kind and no interval names the existing
+ * entry of that name, as rename, delete, history and revert do; the API would
+ * otherwise create a new cs- entry.
+ */
+export function upsertCustomSkillKey(input, kind, interval, existingKeys) {
+    const trimmed = input.trim();
+    const scheduledPrefix = trimmed.startsWith('cs-cron-') || trimmed.startsWith('cron-');
+    if (kind === 'skill' && scheduledPrefix) {
+        return { error: `"${input}" is a scheduled task key. Use kind scheduled_task, or a key without cron-.` };
+    }
+    if (kind === 'scheduled_task' && trimmed.startsWith('cs-') && !scheduledPrefix) {
+        return { error: `"${input}" is a custom skill key. Scheduled task keys start with cs-cron-.` };
+    }
+    if (existingKeys && !kind && interval === undefined && isBareCustomSkillKey(trimmed)) {
+        const asSkill = normalizeCustomSkillKey(trimmed, { scheduled: false });
+        const asTask = normalizeCustomSkillKey(trimmed, { scheduled: true });
+        if (asSkill && asTask && existingKeys.has(asTask)) {
+            return existingKeys.has(asSkill)
+                ? { error: `Both ${asSkill} and ${asTask} exist on this agent. Pass the full key.` }
+                : { key: asTask };
+        }
+    }
+    const key = normalizeCustomSkillKey(trimmed, {
+        scheduled: kind === 'scheduled_task',
+        hasInterval: kind === 'skill' ? undefined : interval,
+    });
+    if (!key)
+        return { error: `Invalid key "${input}". ${INVALID_KEY_MESSAGE}` };
+    if (interval !== undefined && customSkillKindOf(key) === 'skill') {
+        return { error: 'interval only applies to scheduled tasks (keys starting with cs-cron-). Use kind scheduled_task.' };
+    }
+    return { key };
+}
+/** The exact key of an existing entry; the API matches rename, delete, history and revert keys literally. */
+export function resolveExistingCustomSkillKey(input, existingKeys, kind) {
+    const trimmed = input.trim();
+    if (trimmed.startsWith('cs-') || trimmed.startsWith('cron-')) {
+        const key = normalizeCustomSkillKey(trimmed);
+        return key ? { key } : { error: `Invalid key "${input}". ${INVALID_KEY_MESSAGE}` };
+    }
+    const asSkill = normalizeCustomSkillKey(trimmed, { scheduled: false });
+    const asTask = normalizeCustomSkillKey(trimmed, { scheduled: true });
+    if (!asSkill || !asTask)
+        return { error: `Invalid key "${input}". ${INVALID_KEY_MESSAGE}` };
+    if (kind)
+        return { key: kind === 'scheduled_task' ? asTask : asSkill };
+    const matches = [asSkill, asTask].filter(key => existingKeys.has(key));
+    if (matches.length === 1)
+        return { key: matches[0] };
+    if (matches.length > 1)
+        return { error: `Both ${asSkill} and ${asTask} exist. Pass the full key.` };
+    return { error: `This agent has no custom skill or scheduled task named "${input}". Pass the full key (cs-... or cs-cron-...) or check get_my_agent.` };
+}
+/** A light shape check; the API validates the expression fully. */
+export function looksLikeCron(expression) {
+    const parts = expression.trim().split(/\s+/);
+    if (parts.length !== 5 && parts.length !== 6)
+        return false;
+    return parts.every(part => /^[0-9A-Za-z*,/?#-]+$/.test(part));
+}
+/** The runtime always runs a template's scheduled task with the template's own prompt. */
+export function templateTaskTextError(key) {
+    return `The text of ${key} comes from the agent's template and cannot be changed; only its schedule (interval) and on/off state (enabled) can. To change what it does, edit the related custom skill (a cs- key without cron), or create your own scheduled task.`;
+}
+/**
+ * Checks deploy_agent's custom_skills the way manage_agent_custom_skill
+ * would, before the deploy is paid for. A bare key names the template's own
+ * entry of that name when it has one. Without the template's entries only the
+ * checks that need no template run.
+ */
+export function resolveDeployCustomSkills(entries, template) {
+    const skills = [];
+    const errors = [];
+    const seen = new Set();
+    const known = new Map((template ?? []).map(task => [task.key, task]));
+    for (const entry of entries) {
+        const raw = entry.key.trim();
+        const interval = entry.interval?.trim();
+        let key;
+        if (isBareCustomSkillKey(raw) && entry.interval === undefined) {
+            const asSkill = normalizeCustomSkillKey(raw, { scheduled: false });
+            const asTask = normalizeCustomSkillKey(raw, { scheduled: true });
+            if (asSkill && asTask && known.has(asSkill) && known.has(asTask)) {
+                errors.push(`The template has both ${asSkill} and ${asTask}. Pass the full key instead of "${raw}".`);
+                continue;
+            }
+            key = asTask && known.has(asTask) ? asTask : asSkill;
+        }
+        else {
+            key = normalizeCustomSkillKey(raw, { hasInterval: entry.interval });
+        }
+        if (!key) {
+            errors.push(`The custom skill key "${entry.key}" is not valid. ${INVALID_KEY_MESSAGE}`);
+            continue;
+        }
+        if (template && seen.has(key)) {
+            errors.push(`${key} is listed twice in custom_skills.`);
+            continue;
+        }
+        seen.add(key);
+        const kind = customSkillKindOf(key);
+        if (entry.interval !== undefined && (!interval || !looksLikeCron(interval))) {
+            errors.push(`${key}: interval must be a cron expression with five fields: minute hour day-of-month month day-of-week, for example "0 9 * * 1-5" for weekdays at 09:00.`);
+            continue;
+        }
+        if (entry.interval !== undefined && kind !== 'scheduled_task') {
+            errors.push(`${key}: interval only applies to scheduled tasks (keys starting with cs-cron-).`);
+            continue;
+        }
+        const fromTemplate = known.has(key);
+        const templateTask = fromTemplate && kind === 'scheduled_task';
+        if (entry.value !== undefined && !entry.value.trim()) {
+            errors.push(`${key}: value cannot be empty.${fromTemplate ? ' Leave it out to keep the template\'s text.' : ''}`);
+            continue;
+        }
+        if (templateTask && entry.value !== undefined) {
+            errors.push(templateTaskTextError(key));
+            continue;
+        }
+        if (template && !fromTemplate && entry.value === undefined) {
+            errors.push(`${key} is a new ${kind === 'scheduled_task' ? 'scheduled task, so it needs value: the prompt the agent runs on schedule' : 'custom skill, so it needs value: the instructions the agent follows'}.`);
+            continue;
+        }
+        // A scheduled task sent without a schedule is saved on the weekly
+        // default, so a template's own task is sent with its own schedule.
+        const schedule = interval ?? (templateTask ? known.get(key)?.interval || undefined : undefined);
+        skills.push({
+            key,
+            kind,
+            fromTemplate,
+            ...(entry.value !== undefined ? { value: entry.value } : {}),
+            ...(entry.description !== undefined ? { description: entry.description } : {}),
+            ...(schedule !== undefined ? { interval: schedule } : {}),
+            ...(entry.enabled !== undefined ? { enabled: entry.enabled } : {}),
+        });
+    }
+    return { skills, errors };
+}
+export function humanizeCustomSkillKey(key) {
+    let body = key.trim();
+    if (body.startsWith('cs-cron-'))
+        body = body.slice('cs-cron-'.length);
+    else if (body.startsWith('cs-'))
+        body = body.slice('cs-'.length);
+    body = body.replace(/[-_]+/g, ' ').replace(/\s+/g, ' ').trim();
+    return body ? body.charAt(0).toUpperCase() + body.slice(1) : '';
+}
+export function customSkillEntries(row) {
+    const rows = [
+        ...(Array.isArray(row.customskills) ? row.customskills : []),
+        ...(Array.isArray(row.scheduledskills) ? row.scheduledskills : []),
+    ];
+    return rows.filter(isPlainObject).map(entry => {
+        const key = asString(entry.key) ?? '';
+        const source = asString(entry._source) ?? '';
+        return {
+            key,
+            kind: customSkillKindOf(key),
+            description: asString(entry.description) ?? '',
+            value: asString(entry.value) ?? '',
+            interval: asString(entry.interval) ?? null,
+            enabled: entry.enabled !== false,
+            source,
+            userCreated: source === 'user-created' || entry._user_created === true,
+            requiresCredentials: stringList(entry.requires_credentials),
+        };
+    }).filter(entry => entry.key);
+}
+/** Readable text for the API's custom skill error codes. */
+export function customSkillErrorMessage(message) {
+    if (/invalid-cron-expression|invalid cron/i.test(message)) {
+        return 'The schedule is not a valid cron expression. Use five fields: minute hour day-of-month month day-of-week, for example "0 9 * * 1-5".';
+    }
+    if (/customskill-preset-description-not-editable/.test(message)) {
+        return 'This entry comes with the agent, so its description cannot be changed. Its text and on/off state can.';
+    }
+    if (/customskill-(registry|preset)-not-deletable/.test(message)) {
+        return 'This entry comes with the agent and cannot be deleted. Turn it off with action upsert and enabled: false instead.';
+    }
+    if (/useragent-customskill-version-not-found/.test(message)) {
+        return 'That version was not found. List the versions with action history.';
+    }
+    if (/useragent-customskill-not-found|agent-customskill-not-found/.test(message)) {
+        return 'This agent has no custom skill or scheduled task with that key.';
+    }
+    return message;
+}
+export function toIsoTime(value) {
+    const iso = unixToIso(value);
+    if (iso)
+        return iso;
+    const text = asString(value);
+    return text && !/^\d+$/.test(text) ? text : undefined;
+}
+//# sourceMappingURL=agent-config.js.map