@wiro-ai/wiro-mcp 1.4.1 → 1.5.1

package/dist/utils/agent-config.js

@@ -1,6 +1,7 @@
 import crypto from 'node:crypto';
-import { ApiResultError, asString, hasErrorCode, isPlainObject, requireApiSuccess, toNumber, truncate, unixToIso, } from './api.js';
-import { planEndsWithPeriod } from './user-agent.js';
+import { AGENT_NOT_FOUND_TEXT, ApiResultError, asString, hasErrorCode, isAgentNotFound, isPlainObject, requireApiSuccess, toNumber, truncate, unixToIso, } from './api.js';
+import { oneLine, quotedSpan } from './quoted-text.js';
+import { credentialKeysSetupWaitsFor, isWalletNotRead, nameList, planEndsWithPeriod, skillLabel, STARTER_TASK_KEY, toSkillGroups, WALLET_NOT_READ_NOTE, WIRO_PROJECT_CREDENTIAL, wordsFromKey, } from './user-agent.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.
@@ -61,11 +62,59 @@ export function restartNote(status, what = 'change') {
             return `The ${what} takes effect the next time the agent starts.`;
     }
 }
+export function keyList(keys) {
+    return keys.length > 1 ? `${keys.slice(0, -1).join(', ')} and ${keys[keys.length - 1]}` : keys.join('');
+}
+function afterWriteNote(status) {
+    switch (status) {
+        case 1:
+            return 'The agent restarts to load the new values, which takes about a minute.';
+        case 2:
+        case 3:
+            return 'The agent is starting and loads the new values.';
+        case 4:
+            // A save that changes a value sets a running agent stopping before Wiro answers.
+            return 'The agent kept running: a save that matches what is stored does not restart it. If it should load new values now, control_agent with action restart does it.';
+        case 6:
+            return 'The agent still needs setup before it can start; get_my_agent shows what is missing.';
+        case 5:
+            return 'The agent stopped with an error; the values are used when it starts.';
+        case null:
+            return 'Check the agent with get_my_agent.';
+        default:
+            return `The agent is ${agentStatusLabel(status)}; the values are used when it starts.`;
+    }
+}
+/** What the setup still waits for and the tool that gives each one: a Wiro project, a sign-in or saved fields. */
+export function setupStillMissingNote(missing) {
+    if (missing.length === 0)
+        return null;
+    const titles = (items) => items.map(item => item.title);
+    const isProject = (item) => item.key === WIRO_PROJECT_CREDENTIAL;
+    const steps = [
+        { verb: 'Set', names: titles(missing.filter(item => !item.oauth && !isProject(item))), tool: 'set_agent_credentials' },
+        { verb: 'Connect', names: titles(missing.filter(item => item.oauth && !isProject(item))), tool: 'connect_agent_oauth' },
+        { verb: 'Connect', names: titles(missing.filter(isProject)), tool: 'bind_agent_project' },
+    ].filter(step => step.names.length > 0);
+    const first = steps[0];
+    const how = steps.length === 1 && first
+        ? `${first.verb} ${first.names.length > 1 ? 'them' : 'it'} with ${first.tool}`
+        : steps.map((step, index) => `${index === 0 ? step.verb : step.verb.toLowerCase()} ${keyList(step.names)} with ${step.tool}`).join(', ');
+    return `Setup is not finished: still missing ${keyList(titles(missing))}. ${how}, then check with get_my_agent.`;
+}
+/** When the agent loads the values, and the credentials its setup still waits for, at any status. */
+export function afterWriteNotes(status, missing) {
+    const setup = setupStillMissingNote(missing);
+    if (!setup)
+        return [afterWriteNote(status)];
+    // At status 6 the general note says the same without the names.
+    return status === 6 ? [setup] : [afterWriteNote(status), setup];
+}
 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.`);
+        throw new Error(AGENT_NOT_FOUND_TEXT);
     return row;
 }
 export function agentStatusOf(row) {
@@ -138,9 +187,34 @@ export function parseSkillRegistry(body) {
     }
     return { skills, channels };
 }
+/** The catalog title of every skill the registry lists that has one, for skillLabel. */
+export function registryTitles(registry) {
+    return new Map([...registry.skills.values()].filter(skill => skill.title !== skill.name).map(skill => [skill.name, skill.title]));
+}
 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.')));
 }
+/**
+ * The catalog titles of these skills, so a text names them as people see them. The catalog is read only when
+ * there is a name; the map is empty when there is none or the catalog cannot be read.
+ */
+export async function skillTitles(client, names, signal) {
+    const titles = new Map();
+    const wanted = new Set(names);
+    if (wanted.size === 0)
+        return titles;
+    const registry = await loadSkillRegistry(client, signal).catch(() => null);
+    for (const name of wanted) {
+        const title = registry?.skills.get(name)?.title;
+        if (title && title !== name)
+            titles.set(name, title);
+    }
+    return titles;
+}
+/** The catalog titles of the skills these scheduled tasks are paused for (skillTitles). */
+export async function pausedSkillTitles(client, tasks, signal) {
+    return skillTitles(client, tasks.filter(task => task.skillOff).flatMap(task => (task.offSkills ?? []).flat()), signal);
+}
 function suggestSkills(name, registry) {
     const tokens = new Set(name.toLowerCase().split(/[^a-z0-9]+/).filter(token => token.length > 2));
     return [...registry.skills.keys()]
@@ -162,6 +236,8 @@ function suggestSkills(name, registry) {
 export function planSkillChanges(input, registry, addDependencies) {
     const errors = new Set();
     const requested = {};
+    const titles = registryTitles(registry);
+    const label = (name) => skillLabel(name, titles);
     for (const [rawName, enabled] of Object.entries(input)) {
         const name = rawName.trim();
         if (!name) {
@@ -180,11 +256,11 @@ export function planSkillChanges(input, registry, addDependencies) {
         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.`);
+            errors.add(`Unknown skill "${name}".${suggestions.length ? ` Did you mean ${suggestions.map(label).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` : ''}.`);
+            errors.add(`${label(name)} is retired and cannot be turned on${skill.replacement ? `. Use ${label(skill.replacement)} instead` : ''}.`);
             continue;
         }
         requested[name] = enabled;
@@ -196,7 +272,7 @@ export function planSkillChanges(input, registry, addDependencies) {
             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.`);
+                    errors.add(`${label(name)} needs ${label(dependency)}, which this change turns off. Keep ${label(dependency)} on, or leave ${label(name)} off.`);
                     continue;
                 }
                 if (requested[dependency] === true || !registry.skills.has(dependency))
@@ -255,16 +331,7 @@ export function checkSkillSet(enabledNow, changes, registry) {
 }
 /** 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);
-    };
+    const ready = (key) => (row ? credentialReady(row, key) : false);
     return skills
         .map(skill => ({
         skill,
@@ -274,6 +341,73 @@ export function credentialsNeededFor(skills, registry, row) {
     }))
         .filter(entry => entry.credentials.length > 0);
 }
+/** The credential keys the given skills use, main and additional, by the same rule as credentialsNeededFor. */
+export function credentialsUsedBySkills(skills, registry) {
+    const used = new Set();
+    for (const name of skills) {
+        const skill = registry.skills.get(name);
+        if (!skill?.requiresCredentials)
+            continue;
+        for (const key of skill.credentialKeys)
+            used.add(key);
+    }
+    return used;
+}
+/**
+ * Why connect_agent_oauth connect refuses a service on this agent, or null when
+ * it connects: one of the agent's active skills uses it, or one of its custom
+ * skills or scheduled tasks requires it (a skill's scheduled task only when it
+ * can use that credential now). Wiro keeps such an entry off until the
+ * credential is connected, and connecting turns it on, so the entry counts
+ * whatever its enabled says. A template agent's setup also waits for the
+ * credentials its template requires, whichever skills are on, so those stay
+ * connectable.
+ */
+export function unusedCredential(row, credential, registry) {
+    const used = credentialsUsedBySkills(enabledSkillNames(row), registry);
+    // A skill's scheduled task counts only the credentials it can use now; a task of the user's own, the ones its row lists.
+    for (const entry of customSkillEntries(row)) {
+        for (const key of entry.usableCredentials ?? entry.requiresCredentials)
+            used.add(key);
+    }
+    if (used.has(credential) || (!isCustomBuild(row) && credentialGroup(row, credential)?.optional === false))
+        return null;
+    return {
+        services: [...used].flatMap(key => {
+            const schema = credentialGroup(row, key)?._schema;
+            return isPlainObject(schema) && isPlainObject(schema.oauth_provider)
+                ? [`${asString(schema.title) ?? wordsFromKey(key)} (\`${key}\`)`]
+                : [];
+        }),
+        skills: [...registry.skills.values()]
+            .filter(skill => !skill.deprecated && skill.requiresCredentials && skill.credentialKeys[0] === credential)
+            .map(skill => skillLabel(skill.name, registryTitles(registry))),
+    };
+}
+export function turnOnSkillText(title, credential, skills) {
+    return skills.length > 0
+        ? `To use ${title}, first turn on ${skills.join(' or ')} with apply_agent_skills; list_agent_skills with name "${credential}" shows how it connects.`
+        : '';
+}
+/**
+ * The same rule for the answers that offer connect (status, and describing or
+ * saving a credential), as a note to show instead of that offer. Null when the
+ * service connects, and when the skills cannot be read: connect checks again.
+ */
+export async function unusedCredentialNote(client, row, credential, title, signal) {
+    try {
+        const unused = unusedCredential(row, credential, await loadSkillRegistry(client, signal));
+        if (!unused)
+            return null;
+        return [
+            `${title} is not used by any of this agent's active skills, custom skills or scheduled tasks, so connect_agent_oauth refuses it for now.`,
+            turnOnSkillText(title, credential, unused.skills),
+        ].filter(Boolean).join(' ');
+    }
+    catch {
+        return null;
+    }
+}
 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) {
@@ -286,10 +420,15 @@ export function skillChangeDigest(agentGuid, requested, tier) {
 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) {
+/**
+ * Fingerprint of what a quoted charge rests on: the monthly price before and after
+ * a change and, for a plan paid from the wallet, the period it is charged in. A
+ * renewal keeps the prices and starts a new period, which changes the charge.
+ */
+export function skillPriceTag(currentUsd, newUsd, periodEndUnix = null) {
+    const prices = `${cents(currentUsd)}:${cents(newUsd)}`;
     return crypto.createHash('sha256')
-        .update(`${cents(currentUsd)}:${cents(newUsd)}`)
+        .update(periodEndUnix === null ? prices : `${prices}:${periodEndUnix}`)
         .digest('hex')
         .slice(0, 8);
 }
@@ -314,26 +453,45 @@ 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: 'none', status: null, periodEnd: null, wallet, cancelAtPeriodEnd: false, switchingToWallet: false };
     }
+    const plan = asString(subscription.provider) === 'prepaid' ? 'prepaid' : 'card';
     return {
-        plan: asString(subscription.provider) === 'prepaid' ? 'prepaid' : 'card',
+        plan,
         status: asString(subscription.status) ?? null,
         periodEnd: toNumber(subscription.currentperiodend),
-        daysRemaining: toNumber(subscription.daysremaining),
         wallet,
         cancelAtPeriodEnd: planEndsWithPeriod(subscription, row.stripecancelatperiodend),
+        switchingToWallet: plan === 'card' && subscription.nextprovider === 'prepaid',
     };
 }
-/**
- * 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))
+const DAY_SECONDS = 86400;
+/** The plan change of a pricing answer, or null when the agent has no active plan or Wiro sent none. */
+export function readPlanChange(value) {
+    if (!isPlainObject(value))
         return null;
-    const remainingDays = Math.max(0, Math.round((periodEndUnix - nowMs / 1000) / 86400));
-    return Math.round((deltaUsd / periodDays) * remainingDays * 100) / 100;
+    return {
+        wallet: asString(value.provider) === 'prepaid',
+        periodEnd: toNumber(value.periodEnd),
+        secondsLeft: toNumber(value.secondsLeft),
+        creditsNow: toNumber(value.creditsNow),
+        creditsThisPeriod: toNumber(value.creditsThisPeriod),
+        creditsFromRenewal: toNumber(value.creditsFromRenewal),
+        chargeNowUsd: toNumber(value.chargeNowUsd),
+        creditNowUsd: toNumber(value.creditNowUsd),
+        usedCreditsUsd: toNumber(value.usedCreditsUsd),
+    };
+}
+/** Whether a rise now pays the one-day minimum: under a day is left of the period. */
+export function underOneDayLeft(secondsLeft) {
+    return secondsLeft !== null && secondsLeft < DAY_SECONDS;
+}
+/** The time left of a period in whole days, at least 1, for a sentence such as "(27 days)". */
+export function daysLeftText(secondsLeft) {
+    if (secondsLeft === null || secondsLeft < 0)
+        return null;
+    const days = Math.max(1, Math.round(secondsLeft / DAY_SECONDS));
+    return `${days} ${days === 1 ? 'day' : 'days'}`;
 }
 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)';
@@ -353,11 +511,11 @@ function skillPaymentGuidance(plan) {
  * 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) {
+export function describeSkillsApplyError(error, plan, titles) {
     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 code = codes.find(candidate => candidate !== null && candidate >= 95 && candidate <= 110) ?? null;
     const base = { code, message, retrySameKey: false };
     switch (code) {
         case 101: {
@@ -367,7 +525,7 @@ export function describeSkillsApplyError(error, plan) {
             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.`,
+                guidance: `Some skills need others that would be off: ${deps.map(dep => `${skillLabel(dep.skill, titles)} needs ${skillLabel(dep.requires, titles)}`).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: {
@@ -377,7 +535,7 @@ export function describeSkillsApplyError(error, plan) {
             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.`,
+                guidance: `These skills cannot be on together: ${conflicts.map(pair => `${skillLabel(pair.a, titles)} and ${skillLabel(pair.b, titles)}`).join('; ')}. Keep only one of each pair.`,
             };
         }
         case 103: {
@@ -391,10 +549,14 @@ export function describeSkillsApplyError(error, plan) {
             };
         }
         case 104:
+            // Two refusals share the code: another change to the agent's plan, or another payment from its wallet.
+            // Skill changes, an upgrade to Pro and a wallet plan's renewal take turns on an agent.
             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.',
+                guidance: /wallet/i.test(message)
+                    ? 'Another payment from the same wallet was going through, so this change was not made and nothing was charged. It is not a low balance, and no funds need to be added. Offer to try again in a minute: repeat the call with the same idempotency_key.'
+                    : 'Another change to this agent\'s skills or plan, such as an upgrade or a renewal, is still going through, and one runs at a time. Nothing was changed or charged by this call. Wait a few seconds, then repeat the call with the same idempotency_key. If it keeps saying so, it clears within 15 minutes.',
             };
         case 105:
             return {
@@ -409,19 +571,26 @@ export function describeSkillsApplyError(error, plan) {
         case 107:
             return {
                 ...base,
-                guidance: 'Repeat the call without idempotency_key to start a fresh change.',
+                guidance: 'This idempotency_key cannot be used for this call, and nothing was changed or charged by it. Get a new quote: repeat the call without idempotency_key, show the quote to the user, and confirm with the key it gives.',
             };
         case 108:
             return {
                 ...base,
                 retrySameKey: true,
-                guidance: 'Nothing was changed. Repeat the call with the same idempotency_key.',
+                guidance: 'Wiro could not read or save what this change needs just now, and the wallet balance can be part of that. It is not a low balance, so no funds need to be added. Nothing was changed or charged. Try again: repeat the call with the same idempotency_key.',
             };
         case 109:
+            // Wiro's sentence covers cards and wallets alike. The guidance names the fix for this plan.
             return {
                 ...base,
+                message: 'Payment processing failed for this skill change.',
                 guidance: skillPaymentGuidance(plan),
             };
+        case 110:
+            return {
+                ...base,
+                guidance: 'Do not repeat this change. Check the agent\'s skills and monthly price with get_my_agent and the wallet with get_account (recent_transactions) before changing anything, and contact Wiro support if they are not what you expect.',
+            };
         case 95:
         case 96:
         case 97:
@@ -438,17 +607,54 @@ export function describeSkillsApplyError(error, plan) {
             guidance: 'The new price could not be computed, so nothing was changed. Check the skill names with list_agent_skills.',
         };
     }
+    if (/^unknown skill: /i.test(message)) {
+        return {
+            ...base,
+            guidance: 'Nothing was changed or charged. Use names from list_agent_skills.',
+        };
+    }
+    if (isWalletNotRead(error))
+        return { ...base, guidance: WALLET_NOT_READ_NOTE };
     return { ...base, guidance: workspaceHint(message) ?? '' };
 }
+/**
+ * One refusal covers an agent that does not exist and an agent this project may
+ * not connect, and the fix for each is different. The agent's own read tells
+ * them apart.
+ */
+export async function connectionRefusalText(client, agentGuid, message, done, signal) {
+    const rule = `can only be ${done} with a project created by the person who deployed the agent: `
+        + 'connect this server with such a project, by its API key or a browser sign-in.';
+    try {
+        await readUserAgent(client, agentGuid, signal);
+    }
+    catch (error) {
+        if (isAgentNotFound(error))
+            return AGENT_NOT_FOUND_TEXT;
+        return `${message}\n\nCheck the guid with list_my_agents. If the agent is listed, integrations ${rule}`;
+    }
+    return `${message}\n\nIntegrations ${rule}`;
+}
+/** Wiro's answer when it could not clear a saved connection. Nothing says the connection is gone, and a repeat is safe. */
+export const CONNECTION_NOT_CLEARED = 'The saved connection could not be cleared. Please try again.';
+export const WORKSPACE_HINT = 'Connect with a project in the workspace (personal or team) that owns this agent, by its API key or a browser sign-in.';
 /** 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;
+    return /switch to the (team|personal)|different team|personal workspace/i.test(message) ? WORKSPACE_HINT : 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;
+// The Wiro project field. On the dashboard it is a project picker, and the help
+// it comes with describes that picker, so this line is shown instead.
+export const WIRO_PROJECT_NOTE = 'Connect a Wiro project with bind_agent_project: it takes the project of this connection or '
+    + 'one from list_projects, and no key passes through this chat. The user can also pick the project on the agent\'s page in '
+    + 'the Wiro dashboard. Saving a project API key with set_agent_credentials stays possible when the user gives one for this, '
+    + 'and Wiro adds the project\'s secret by itself. Model runs the agent starts are billed to the wallet of the workspace '
+    + 'that owns the project.';
+export function isWiroProjectField(raw) {
+    return /^(custom:)?wiro-project-picker$/.test(asString(raw.type) ?? '');
+}
 export function htmlToText(value, maxLength = 400) {
     const html = asString(value);
     if (!html)
@@ -508,7 +714,7 @@ export function parseCredentialField(raw) {
         ...(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) } : {}),
+        ...(!isWiroProjectField(raw) && htmlToText(raw.help, FIELD_HELP_MAX) ? { help: htmlToText(raw.help, FIELD_HELP_MAX) } : {}),
         ...(asString(raw.placeholder) ? { placeholder: asString(raw.placeholder) } : {}),
     };
 }
@@ -983,7 +1189,8 @@ export function prepareCredentialWrite(inputs, metas) {
         const mayClear = !field.required || meta.channel !== null;
         if (isEmptyValue(input.value)) {
             if (!mayClear) {
-                prepared.errors.push(`${field.label} is required and cannot be cleared.`);
+                prepared.errors.push(`${field.label} is required and cannot be cleared. To replace the saved value, send the new one. `
+                    + 'To end the agent\'s access, revoke it with the service it belongs to.');
                 continue;
             }
             const cleared = shape === 'string-array' || shape === 'object-array' ? [] : '';
@@ -1080,29 +1287,73 @@ export function isFilledValue(value) {
         return Object.values(value).some(isFilledValue);
     return true;
 }
+/**
+ * Whether a field of a saved credential holds what someone entered, counted the
+ * way Wiro counts it for a card's filled state: a list of options counts only an
+ * option that is selected, and a row of a list does not count for its selects
+ * and switches, which come with a default.
+ */
+export function isCredentialFieldFilled(field, value) {
+    if (field.itemSchema.length === 0 || !Array.isArray(value))
+        return isCredentialValueFilled(value);
+    return value.some(row => {
+        if (!isPlainObject(row))
+            return isCredentialValueFilled(row);
+        return Object.entries(row).some(([key, item]) => {
+            const inner = field.itemSchema.find(entry => entry.key === key);
+            if (!inner)
+                return isCredentialValueFilled(item);
+            if (inner.type === 'select' || inner.type === 'boolean')
+                return false;
+            return isCredentialFieldFilled(inner, item);
+        });
+    });
+}
+function isCredentialValueFilled(value) {
+    if (Array.isArray(value) && value.length > 0 && value.every(option => isPlainObject(option) && 'selected' in option)) {
+        return value.some(option => isPlainObject(option) && option.selected === true);
+    }
+    if (Array.isArray(value))
+        return value.some(isCredentialValueFilled);
+    if (isPlainObject(value))
+        return Object.values(value).some(isCredentialValueFilled);
+    return isFilledValue(value);
+}
 export function credentialGroup(row, key) {
     const groups = isPlainObject(row.credentials) ? row.credentials : null;
     const group = groups ? groups[key] : undefined;
     return isPlainObject(group) ? group : null;
 }
+/**
+ * Whether the agent can use a credential now. An OAuth credential is ready only once connected: a saved shop
+ * domain or own-app key alone does not let the agent sign in.
+ */
+export function credentialReady(row, key) {
+    const group = credentialGroup(row, key);
+    if (!group)
+        return false;
+    const oauth = isPlainObject(group._schema) && isPlainObject(group._schema.oauth_provider);
+    return group._connected === true || (!oauth && group._filled === true);
+}
 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
+    // A sign-in credential's required fields depend on its mode; connected is the signal there. Filled says every
+    // required field holds a value, a template's own value that is not shown included.
+    const missingFields = connected || !meta || meta.oauth || group._filled === true
         ? []
         : meta.fields
-            .filter(field => field.required && isWritableField(field) && !isFilledValue(group[field.key]))
+            .filter(field => field.required && isWritableField(field) && !isCredentialFieldFilled(field, 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,
+        requiredMissing: credentialKeysSetupWaitsFor(row).has(key),
         optional: group.optional === true,
         missingFields,
     };
@@ -1158,6 +1409,17 @@ export function isAllowedRedirectUrl(url, agentGuid) {
 export function ownAppRedirectUri(meta) {
     return meta.oauth?.callbackPath ? `${OAUTH_CALLBACK_BASE}${meta.oauth.callbackPath}` : undefined;
 }
+/** Goes with a list of missing fields that holds app keys, which may be saved already. */
+export function writeOnlyNote(mode) {
+    return `App keys are not shown once saved. If they are saved already, connect with mode ${mode}.`;
+}
+/** The same note before a mode is chosen: it names each usable mode that takes app keys. */
+export function writeOnlyModesNote(requirements) {
+    const modes = requirements
+        .filter(requirement => requirement.available && requirement.fields.some(field => field.writeOnly))
+        .map(requirement => requirement.mode);
+    return modes.length > 0 ? writeOnlyNote(modes.join(' or ')) : null;
+}
 function fieldsForMode(meta, mode) {
     if (mode === 'wiro')
         return [];
@@ -1182,11 +1444,15 @@ function fieldsForMode(meta, mode) {
 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]),
-        }));
+        const fields = fieldsForMode(meta, mode).map(field => {
+            const isSet = group !== null && isFilledValue(group[field.key]);
+            return {
+                field: field.key,
+                label: field.label,
+                isSet,
+                ...(field.oauthManaged && !isSet ? { writeOnly: true } : {}),
+            };
+        });
         if (mode === 'wiro') {
             return {
                 mode,
@@ -1248,6 +1514,16 @@ export function chooseConnectionMode(meta, requirements) {
     });
     return ordered.find(requirement => requirement.fields.every(field => field.isSet))?.mode ?? null;
 }
+/**
+ * An account in a line of this server's text. The outside service sets its name,
+ * and a service without an account choice gives that name as the id too, so both
+ * are quoted and a repeat is left out.
+ */
+export function accountLabel(account) {
+    const name = oneLine(account.name);
+    const id = quotedSpan(account.id);
+    return name && name !== oneLine(account.id) ? `${quotedSpan(name)} (${id})` : id;
+}
 /** Candidate or saved accounts in one shape, whatever the provider calls the fields. */
 export function toAccountRefs(list, picker) {
     if (!Array.isArray(list))
@@ -1342,7 +1618,7 @@ export function buildChainedSelections(next, groups, selections) {
         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.`,
+                error: `${accountLabel(group.parent)} could not be read (${group.errorCode}), so nothing can be chosen for it. Leave it out.`,
             };
         }
         const ids = chosen.get(group.parent.id) ?? [];
@@ -1351,7 +1627,7 @@ export function buildChainedSelections(next, groups, selections) {
             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'}.`,
+                    error: `"${itemId}" is not available under ${accountLabel(group.parent)}. Available: ${group.items.map(accountLabel).join(', ') || 'none'}.`,
                 };
             }
             if (!ids.includes(item.id))
@@ -1423,6 +1699,8 @@ export function connectionState(status, options) {
         return 'pick_accounts';
     return 'not_connected';
 }
+/** The entry that holds what an agent posts, sends or changes by itself until the user says yes. */
+export const APPROVAL_POLICY_KEY = 'cs-approval-policy';
 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
@@ -1523,7 +1801,7 @@ export function resolveExistingCustomSkillKey(input, existingKeys, kind) {
         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.` };
+    return { error: `This agent has no custom skill or scheduled task named "${input}". Pass the full key (cs-... or cs-cron-...). get_my_agent without entry lists its keys.` };
 }
 /** A light shape check; the API validates the expression fully. */
 export function looksLikeCron(expression) {
@@ -1619,12 +1897,9 @@ export function humanizeCustomSkillKey(key) {
     body = body.replace(/[-_]+/g, ' ').replace(/\s+/g, ' ').trim();
     return body ? body.charAt(0).toUpperCase() + body.slice(1) : '';
 }
-/** Text in a fence longer than any run of backticks inside it, so it shows as is. */
-export function textBlock(value) {
-    let fence = '```';
-    while (value.includes(fence))
-        fence += '`';
-    return [`${fence}text`, value, fence];
+/** Wiro's _if_connected: each credential key with the lists of skills a task would still wait for. */
+function skillGroupsByKey(value) {
+    return Object.fromEntries(Object.entries(value).filter(([, groups]) => Array.isArray(groups)).map(([key, groups]) => [key, toSkillGroups(groups)]));
 }
 export function customSkillEntries(row) {
     const rows = [
@@ -1644,9 +1919,90 @@ export function customSkillEntries(row) {
             source,
             userCreated: source === 'user-created' || entry._user_created === true,
             requiresCredentials: stringList(entry.requires_credentials),
+            notWritten: key === STARTER_TASK_KEY && entry._edited === false,
+            ownerSkills: stringList(entry._owner_skills),
+            skillOff: entry._skill_off === true,
+            offSkills: toSkillGroups(entry._off_skills),
+            ...(Array.isArray(entry._usable_credentials) ? { usableCredentials: stringList(entry._usable_credentials) } : {}),
+            ...(isPlainObject(entry._if_connected) ? { ifConnected: skillGroupsByKey(entry._if_connected) } : {}),
         };
     }).filter(entry => entry.key);
 }
+/**
+ * What connecting a credential does to the entries that need it. Saving it turns on an entry that is off only
+ * when the entry's own list names it. For a skill's scheduled task Wiro says what it would still wait for once
+ * that credential is connected: such a task turns on and runs (on), or turns on and stays paused while those
+ * skills are off (paused). A scheduled task that is on already starts running when only this connection held
+ * it back (starts), or stays paused while those skills are off (waiting).
+ */
+export function entriesTurnedOnBy(row, credential) {
+    const on = [];
+    const paused = [];
+    const starts = [];
+    const waiting = [];
+    for (const entry of customSkillEntries(row)) {
+        const groups = entry.ifConnected?.[credential];
+        if (entry.enabled) {
+            if (groups && groups.length > 0)
+                waiting.push({ key: entry.key, groups });
+            else if (startsOnConnect(row, entry, credential))
+                starts.push(entry);
+            continue;
+        }
+        if (!entry.requiresCredentials.includes(credential))
+            continue;
+        if (!entry.ifConnected || (groups !== undefined && groups.length === 0))
+            on.push(entry);
+        else if (groups !== undefined)
+            paused.push({ key: entry.key, groups });
+    }
+    return { on, paused, starts, waiting };
+}
+/**
+ * Whether a scheduled task that is on runs once this credential is connected, and not before. A skill's task
+ * runs then when Wiro says it needs nothing more ([]), and does not run now while it is paused for skills or
+ * none of the connections it can use is ready. A task with no skill gate runs while any credential its list
+ * names is ready. The starter task does not run until its text is written.
+ */
+function startsOnConnect(row, entry, credential) {
+    if (entry.kind !== 'scheduled_task' || entry.notWritten)
+        return false;
+    if (entry.ifConnected) {
+        const usable = entry.usableCredentials ?? [];
+        return entry.ifConnected[credential]?.length === 0
+            && (entry.skillOff === true || (usable.length > 0 && !usable.some(key => credentialReady(row, key))));
+    }
+    return entry.requiresCredentials.includes(credential) && !entry.requiresCredentials.some(key => credentialReady(row, key));
+}
+/**
+ * The connection a scheduled task needs, as a sentence: the credentials it can use (a skill's task) or the
+ * ones its row lists (a task of the user's own), by title where the agent's credential cards have one.
+ */
+export function connectionNeededText(row, entry) {
+    const keys = entry.usableCredentials ?? entry.requiresCredentials;
+    if (keys.length === 0)
+        return '';
+    const labels = keys.map(key => credentialLabel(row, key));
+    return `It only runs while ${labels.length > 1 ? 'one of ' : ''}${nameList(labels, 'or')} is connected.`;
+}
+/**
+ * A credential as people see it, with its key: Google Ads (`google-ads`). Its title comes from the agent's card
+ * for it, or from titles (the credential catalog), or is made from the key.
+ */
+export function credentialLabel(row, key, titles) {
+    const schema = credentialGroup(row, key)?._schema;
+    const title = isPlainObject(schema) ? asString(schema.title) : undefined;
+    return `${title ?? titles?.get(key) ?? wordsFromKey(key)} (\`${key}\`)`;
+}
+/** The catalog titles of these credentials, read through the cached credential details; a key it cannot read is left out. */
+export async function credentialTitles(client, keys, signal) {
+    const unique = [...new Set(keys)];
+    const metas = await Promise.all(unique.map(key => loadCredentialMeta(client, key, signal).catch(() => null)));
+    return new Map(unique.flatMap((key, index) => {
+        const title = metas[index]?.title;
+        return title && title !== key ? [[key, title]] : [];
+    }));
+}
 /** Readable text for the API's custom skill error codes. */
 export function customSkillErrorMessage(message) {
     if (/invalid-cron-expression|invalid cron/i.test(message)) {