@wiro-ai/wiro-mcp 1.4.0 → 1.5.0

package/dist/utils/user-agent.js

@@ -1,11 +1,10 @@
 import { z } from 'zod';
 import { WiroApiError } from '../client.js';
-import { ApiResultError, asString, isPlainObject, requireApiSuccess, toNumber, truncate, unixToIso, } from './api.js';
+import { AGENT_NOT_FOUND_TEXT, ApiResultError, asString, isPlainObject, requireApiSuccess, toNumber, truncate, unixToIso, } from './api.js';
 import { pollUntil, reportProgress } from './poll.js';
-// Deployed agents and the agent catalog. Agent rows come back with the
-// owner's stored credential values, billing links and account ids, none of
-// which an assistant should pass on, so every row is rebuilt here from an
-// allowlist instead of being passed through.
+import { quotedSpan } from './quoted-text.js';
+// Deployed agents and the agent catalog. Results are rebuilt from an
+// allowlist: only states, labels, prices and settings are returned.
 export const AGENT_DASHBOARD_URL = 'https://wiro.ai/panel/agents';
 export function agentDashboardUrl(guid) {
     return `${AGENT_DASHBOARD_URL}/${encodeURIComponent(guid)}`;
@@ -60,8 +59,24 @@ export function describeAgentStatus(status) {
         ? STATUS_TEXT[label]
         : `${STATUS_TEXT[label]} (${status})`;
 }
-export function agentStatusHint(status) {
-    return STATUS_HINT[agentStatusLabel(status)];
+// On a team agent a team admin or the person who deployed it starts, changes
+// and pays for it (the organization's owner can also pay for it). Other members
+// can read it and message it, so their hints say who can act instead of naming
+// a call they cannot make.
+const TEAM_AGENT_MANAGERS = 'a team admin or the person who deployed it';
+// Connected accounts are the exception: Wiro lets only the person who
+// deployed the agent connect them (connect_agent_oauth).
+export const MEMBER_SETUP_HELP = `On this team agent, ${TEAM_AGENT_MANAGERS} saves credentials and pays for the plan. `
+    + 'Only the person who deployed it can connect accounts, such as Instagram or Google Ads.';
+const MEMBER_STATUS_HINT = {
+    stopped: `It is not running. On this team agent, ${TEAM_AGENT_MANAGERS} can start it.`,
+    error: `The start failed or the agent stopped unexpectedly. On this team agent, ${TEAM_AGENT_MANAGERS} can start it again and read its logs.`,
+    setup_required: `${STATUS_HINT.setup_required} ${MEMBER_SETUP_HELP}`,
+};
+/** plainMember: the connection acts as a member of the agent's team without admin rights. */
+export function agentStatusHint(status, plainMember = false) {
+    const label = agentStatusLabel(status);
+    return (plainMember ? MEMBER_STATUS_HINT[label] : undefined) ?? STATUS_HINT[label];
 }
 /** Stopping, queued and starting move on by themselves; every other status stays until someone acts. */
 export function isTransitionalStatus(status) {
@@ -122,24 +137,47 @@ export const subscriptionSchema = z.object({
     status: z.string(),
     billing: z.enum(['wallet', 'card']),
     switchingToWallet: z.boolean(),
-    amountUsd: z.number().nullable(),
+    amountUsd: z.number().nullable()
+        .describe('What the plan costs every 30 days. For a plan that has ended, the agent\'s monthly price, which is what a renew charges.'),
     periodEndsAt: z.string().optional(),
     daysRemaining: z.number().nullable(),
     cancelAtPeriodEnd: z.boolean(),
+    atPeriodEnd: z.enum(['renews', 'ends', 'unknown']).optional()
+        .describe('For an active plan, what happens at periodEndsAt: it renews, it ends, or unknown for a card plan whose renewal is managed in the Wiro dashboard.'),
 });
-export function toSubscription(value, cancelAtPeriodEnd) {
+/**
+ * Whether a plan ends with its current period: true when it ends, false when
+ * it renews, null when that is not known. A wallet plan says so itself, and a
+ * card plan moving to wallet billing renews from the wallet, even though its
+ * card subscription is set to end with the period. Any other card plan is
+ * known only when the row carries its card state (cardEnds).
+ */
+export function planEndsWithPeriod(subscription, cardEnds) {
+    if (subscription.pendingdowngrade === 'cancel')
+        return true;
+    if (subscription.provider === 'prepaid' || subscription.nextprovider === 'prepaid')
+        return false;
+    if (cardEnds === true)
+        return true;
+    return cardEnds === false ? false : null;
+}
+export function toSubscription(value, cardEnds) {
     if (!isPlainObject(value))
         return null;
     const provider = asString(value.provider) ?? 'stripe';
     const periodEndsAt = unixToIso(value.currentperiodend);
+    const status = asString(value.status) ?? 'expired';
+    const ends = planEndsWithPeriod(value, cardEnds);
     return {
-        status: asString(value.status) ?? 'expired',
+        status,
         billing: provider === 'prepaid' ? 'wallet' : 'card',
         switchingToWallet: provider !== 'prepaid' && value.nextprovider === 'prepaid',
         amountUsd: toNumber(value.amount),
         ...(periodEndsAt ? { periodEndsAt } : {}),
         daysRemaining: toNumber(value.daysremaining),
-        cancelAtPeriodEnd: value.pendingdowngrade === 'cancel' || cancelAtPeriodEnd === true,
+        // True only when the plan is known to end; atPeriodEnd also tells a plan that renews from an unknown one.
+        cancelAtPeriodEnd: ends === true,
+        ...(status === 'active' ? { atPeriodEnd: ends === true ? 'ends' : ends === false ? 'renews' : 'unknown' } : {}),
     };
 }
 /** How a new charge for this plan is paid right now. */
@@ -151,7 +189,10 @@ export function chargeRoute(subscription) {
     return 'card';
 }
 export const creditsSchema = z.object({
-    monthly: z.number(),
+    monthly: z.number()
+        .describe('The monthly credits this period grants. A plan change inside a period moves it for the time left, so it can differ from renewal.'),
+    renewal: z.number().optional()
+        .describe('The monthly credits each renewal grants.'),
     extra: z.number(),
     used: z.number(),
     remaining: z.number(),
@@ -159,14 +200,22 @@ export const creditsSchema = z.object({
 });
 export function toCredits(row) {
     const period = asString(row.creditperiod);
+    const renewal = toNumber(row.renewalcredits);
     return {
         monthly: toNumber(row.monthlycredits) ?? 0,
+        ...(renewal !== null ? { renewal } : {}),
         extra: toNumber(row.extracredits) ?? 0,
         used: toNumber(row.usedcredits) ?? 0,
         remaining: toNumber(row.remainingcredits) ?? 0,
         ...(period ? { period } : {}),
     };
 }
+/** The monthly credits as said in a line: those of this period, and those of each renewal when they differ. */
+export function monthlyCreditsText(credits) {
+    return credits.renewal !== undefined && credits.renewal !== credits.monthly
+        ? `${formatCredits(credits.monthly)} credits this period, ${formatCredits(credits.renewal)} from each renewal`
+        : `monthly ${formatCredits(credits.monthly)}`;
+}
 // ---------------------------------------------------------------------------
 // Text helpers
 // ---------------------------------------------------------------------------
@@ -229,7 +278,7 @@ export const credentialStatusSchema = z.object({
     filled: z.boolean(),
     requiredMissing: z.boolean(),
 });
-/** Per-credential state only. Field values never leave this function. */
+/** The state of each credential: whether it is filled, connected or missing. */
 export function summarizeCredentials(credentials, skipKeys = new Set()) {
     if (!isPlainObject(credentials))
         return [];
@@ -273,10 +322,14 @@ export function summarizeChannels(value) {
         };
     });
 }
+/** The scheduled task a custom build starts with. It runs only once its text has been written. */
+export const STARTER_TASK_KEY = 'cs-cron-my-scheduled-task';
 export const agentTaskSchema = z.object({
     key: z.string(),
     description: z.string().optional(),
     enabled: z.boolean(),
+    notWritten: z.boolean().optional()
+        .describe('The starter task whose text was never written. It does not run, even when it shows on, until its text is saved with manage_agent_custom_skill.'),
     interval: z.string().nullable().optional(),
     source: z.enum(['template', 'skill', 'user']).optional(),
     instructions: z.string().optional(),
@@ -301,6 +354,7 @@ export function summarizeTasks(value, maxInstructionLength = 300) {
             key: asString(task.key) ?? '',
             ...(description ? { description } : {}),
             enabled: task.enabled !== false,
+            ...(asString(task.key) === STARTER_TASK_KEY && task._edited === false ? { notWritten: true } : {}),
             ...(interval !== undefined ? { interval: interval || null } : {}),
             ...(source ? { source } : {}),
             ...(shortened ? { instructions: shortened } : {}),
@@ -339,7 +393,8 @@ export const agentSummarySchema = z.object({
     title: z.string(),
     status: z.number().int().nullable(),
     statusLabel: agentStatusLabelSchema,
-    setupRequired: z.boolean(),
+    setupRequired: z.boolean()
+        .describe('Whether the agent waits for setup. list_my_agents goes by the status (6). get_my_agent also checks each required credential and names what is missing.'),
     workspace: z.enum(['personal', 'team']),
     template: agentTemplateRefSchema,
     tier: z.string().optional(),
@@ -351,13 +406,16 @@ export const agentSummarySchema = z.object({
     skills: z.array(z.string()),
     createdAt: z.string().optional(),
     updatedAt: z.string().optional(),
+    lastActivityAt: z.string().optional()
+        .describe('When the agent\'s newest message was written, on any channel, scheduled runs included. Left out when it has none.'),
 });
 export const agentDetailSchema = agentSummarySchema.extend({
     description: z.string().optional(),
     cover: z.string().optional(),
     categories: z.array(z.string()),
     pricing: tierPricingSchema.nullable(),
-    extraCreditPacks: z.array(extraCreditPackSchema),
+    extraCreditPacks: z.array(extraCreditPackSchema)
+        .describe('The extra credit packs this plan can buy. Only an active Pro plan can buy them, so any other plan lists none.'),
     models: modelSettingsSchema.optional(),
     selectableModels: z.array(selectableModelSchema).optional(),
     enabledCommands: z.array(z.string()).nullable(),
@@ -406,6 +464,15 @@ function timestamps(row, map) {
     }
     return out;
 }
+/**
+ * The plan as it is shown. A plan that has ended renews at the agent's monthly
+ * price, not at the amount of its last period, so that is its one price.
+ */
+function planOf(row) {
+    const plan = toSubscription(row.subscription, row.stripecancelatperiodend);
+    const price = toNumber(row.monthlypriceusd);
+    return plan && plan.status !== 'active' && price !== null && price > 0 ? { ...plan, amountUsd: price } : plan;
+}
 /** The compact row used by list_my_agents. */
 export function toAgentSummary(row) {
     const status = readAgentStatus(row);
@@ -423,11 +490,11 @@ export function toAgentSummary(row) {
         ...(tier ? { tier } : {}),
         monthlyPriceUsd: toNumber(row.monthlypriceusd),
         credits: toCredits(row),
-        subscription: toSubscription(row.subscription, row.stripecancelatperiodend),
+        subscription: planOf(row),
         ...(timezone !== undefined ? { timezone } : {}),
         ...(sessionMode ? { teamSessionMode: sessionMode } : {}),
         skills: toStringArray(row.skills ?? row.enabledSkills),
-        ...timestamps(row, { createdAt: 'createdat', updatedAt: 'updatedat' }),
+        ...timestamps(row, { createdAt: 'createdat', updatedAt: 'updatedat', lastActivityAt: 'lastactivityat' }),
     };
 }
 /** The models an agent can switch to, with their credits per 1M input and output tokens when Wiro lists them. */
@@ -454,29 +521,54 @@ export function selectableModelSlugs(row) {
     return new Set(selectableModels(row.tokenRates).map(model => model.slug));
 }
 /**
- * The full sanitized view of one deployed agent (Detail, Deploy and Update
- * rows). Credential values, billing session links, account ids and the
- * team id are dropped; only states, labels and settings remain.
+ * The keys of the credentials an agent's setup waits for: a credential with a
+ * required field empty, a required credential that holds no value yet, or a
+ * required sign-in that is not connected. A custom build's setup waits only for
+ * the main credential of each active skill, which skillsmeta lists. Its chat
+ * channels are never among them.
+ */
+export function credentialKeysSetupWaitsFor(row) {
+    const channelKeys = new Set(summarizeChannels(row.communicationChannels).map(channel => channel.credentialKey));
+    const activeKeys = templateRef(row).custom && isPlainObject(row.skillsmeta)
+        ? new Set(Object.values(row.skillsmeta).filter(isPlainObject)
+            .filter(meta => meta.requires_credentials === true)
+            .map(meta => asString(meta.credential_key))
+            .filter((key) => Boolean(key)))
+        : null;
+    return new Set(summarizeCredentials(row.credentials, channelKeys)
+        // A required credential whose fields are all optional has no empty required
+        // field to show, and the setup still waits until it holds a value.
+        .filter(credential => credential.requiredMissing
+        || (!credential.optional && !credential.connected && (credential.oauth || (row.setuprequired === true && !credential.filled))))
+        .filter(credential => !activeKeys || activeKeys.has(credential.key))
+        // A group with no optional flag has no template row and no skill behind it, only saved values left over.
+        .filter((credential) => {
+        const group = isPlainObject(row.credentials) ? row.credentials[credential.key] : undefined;
+        return isPlainObject(group) && typeof group.optional === 'boolean';
+    })
+        .map(credential => credential.key));
+}
+/**
+ * The full view of one deployed agent (Detail, Deploy and Update rows): its
+ * status, plan, prices, credits and settings, and the state of each
+ * credential and channel.
  */
 export function toAgentDetail(row) {
     const summary = toAgentSummary(row);
     const agent = isPlainObject(row.agent) ? row.agent : {};
     const channels = summarizeChannels(row.communicationChannels);
     const channelKeys = new Set(channels.map(channel => channel.credentialKey));
-    const credentials = summarizeCredentials(row.credentials, channelKeys);
+    // A credential is required and missing exactly when the setup waits for it, so its row and the setup line agree.
+    const setupWaitsFor = credentialKeysSetupWaitsFor(row);
+    const credentials = summarizeCredentials(row.credentials, channelKeys)
+        .map(credential => ({ ...credential, requiredMissing: setupWaitsFor.has(credential.key) }));
     const description = asString(row.description);
     const cover = asString(row.cover) || asString(agent.cover);
     const agentModel = isPlainObject(row.agentModel) ? row.agentModel : undefined;
     const models = selectableModels(row.tokenRates);
-    // A custom build's setup waits only for the main credential of each active
-    // skill, which skillsmeta lists, so only those count as missing.
-    const activeKeys = summary.template.custom && isPlainObject(row.skillsmeta)
-        ? new Set(Object.values(row.skillsmeta).filter(isPlainObject)
-            .filter(meta => meta.requires_credentials === true)
-            .map(meta => asString(meta.credential_key))
-            .filter((key) => Boolean(key)))
-        : null;
-    const packs = Array.isArray(agent.extracreditpacks)
+    // Packs are bought only on an active Pro plan, so only that plan lists them.
+    const canBuyPacks = summary.tier === 'pro' && summary.subscription?.status === 'active';
+    const packs = canBuyPacks && Array.isArray(agent.extracreditpacks)
         ? agent.extracreditpacks.filter(isPlainObject).filter(pack => pack.enabled !== false)
         : [];
     return {
@@ -504,11 +596,8 @@ export function toAgentDetail(row) {
         ...(models.length > 0 ? { selectableModels: models } : {}),
         enabledCommands: Array.isArray(row.enabledCommands) ? toStringArray(row.enabledCommands) : null,
         credentials,
-        // A required sign-in that is not connected also holds back the setup, so it
-        // is listed as missing too.
         missingCredentials: credentials
-            .filter(credential => credential.requiredMissing || (credential.oauth && !credential.optional && !credential.connected))
-            .filter(credential => !activeKeys || activeKeys.has(credential.key))
+            .filter(credential => credential.requiredMissing)
             .map(({ key, title, oauth }) => ({ key, title, oauth })),
         channels,
         scheduledTasks: summarizeTasks(row.scheduledskills),
@@ -523,41 +612,94 @@ export function toAgentDetail(row) {
         dashboardUrl: agentDashboardUrl(summary.guid),
     };
 }
-export function formatSubscriptionLine(subscription) {
-    if (!subscription)
-        return 'No plan. manage_agent_billing with action subscribe starts one.';
+export function formatSubscriptionLine(subscription, plainMember = false) {
+    if (!subscription) {
+        return plainMember
+            ? 'No plan. On this team agent, a team admin, the organization\'s owner or the person who deployed it can start one.'
+            : 'No plan. manage_agent_billing with action subscribe starts one.';
+    }
     const parts = [`${subscription.status}, billed ${subscription.billing === 'wallet' ? 'from the wallet' : 'by card'}`];
-    if (subscription.amountUsd !== null)
-        parts.push(`${formatUsd(subscription.amountUsd)} per 30 days`);
+    if (subscription.amountUsd !== null) {
+        parts.push(subscription.status === 'expired' && subscription.billing === 'wallet'
+            ? `a renew charges ${formatUsd(subscription.amountUsd)} per 30 days`
+            : `${formatUsd(subscription.amountUsd)} per 30 days`);
+    }
     if (subscription.periodEndsAt) {
+        const atPeriodEnd = subscription.atPeriodEnd ?? (subscription.cancelAtPeriodEnd ? 'ends' : 'renews');
         if (subscription.status !== 'active') {
             parts.push(`period ended ${subscription.periodEndsAt}`);
         }
+        else if (atPeriodEnd === 'ends') {
+            parts.push(`cancelled, ends after ${subscription.periodEndsAt}`);
+        }
+        else if (atPeriodEnd === 'renews') {
+            parts.push(`renews after ${subscription.periodEndsAt}`);
+        }
         else {
-            parts.push(subscription.cancelAtPeriodEnd
-                ? `cancelled, ends after ${subscription.periodEndsAt}`
-                : `renews after ${subscription.periodEndsAt}`);
+            // Whether this card plan renews is not known here.
+            parts.push(`paid through ${subscription.periodEndsAt}`);
         }
     }
     if (subscription.switchingToWallet)
         parts.push('switching to wallet billing at period end');
     return parts.join(', ');
 }
-export function formatAgentSummaryLines(agent) {
+/** Without an active plan, an agent starts only on the extra credits it has left. */
+export function startNeedsPlan(agent) {
+    return agent.subscription?.status !== 'active' && agent.credits.extra <= 0;
+}
+/** renew brings back an expired wallet plan; any other agent without an active plan takes a new one. */
+function planActionForStart(agent) {
+    return agent.subscription?.status === 'expired' && agent.subscription.billing === 'wallet' ? 'renew' : 'subscribe';
+}
+function noPlanStartHint(agent) {
+    return 'It has no active plan and no extra credits left, so it cannot start. '
+        + (planActionForStart(agent) === 'renew'
+            ? 'Its wallet plan has expired; manage_agent_billing with action renew restarts it.'
+            : 'manage_agent_billing with action subscribe pays for a plan and starts the agent.');
+}
+/** An agent's title inside a line of this server's own text: on one line, in a code span it cannot close. */
+export function agentTitleSpan(title) {
+    return title.trim() ? quotedSpan(title) : 'Untitled agent';
+}
+export function formatAgentSummaryLines(agent, plainMember = false) {
     const template = agent.template.custom
         ? 'custom build'
         : `template ${agent.template.title ?? agent.template.slug ?? agent.template.guid}`;
+    const hint = !plainMember && (agent.status === 0 || agent.status === 5) && startNeedsPlan(agent)
+        ? `${agent.status === 5 ? 'The start failed or the agent stopped unexpectedly.' : 'It is not running.'} ${noPlanStartHint(agent)}`
+        : agentStatusHint(agent.status, plainMember);
     return [
-        `**Agent:** ${agent.title} (\`${agent.guid}\`), ${template}, ${agent.workspace} workspace`,
-        `**Status:** ${describeAgentStatus(agent.status)}. ${agentStatusHint(agent.status)}`,
-        `**Plan:** ${agent.tier ?? 'no tier'}; ${formatSubscriptionLine(agent.subscription)}`,
-        `**Credits:** ${formatCredits(agent.credits.remaining)} left (monthly ${formatCredits(agent.credits.monthly)}, extra ${formatCredits(agent.credits.extra)}, used ${formatCredits(agent.credits.used)})`,
+        `**Agent:** ${agentTitleSpan(agent.title)} (\`${agent.guid}\`), ${template}, ${agent.workspace} workspace`,
+        `**Status:** ${describeAgentStatus(agent.status)}. ${hint}`,
+        `**Plan:** ${agent.tier ?? 'no tier'}; ${formatSubscriptionLine(agent.subscription, plainMember)}`,
+        `**Credits:** ${formatCredits(agent.credits.remaining)} left (${monthlyCreditsText(agent.credits)}, extra ${formatCredits(agent.credits.extra)}, used ${formatCredits(agent.credits.used)})`,
     ];
 }
-const SHORTENED_NOTE = ' (its text is long; manage_agent_custom_skill history shows it in full)';
+/** Where an entry the list shortens is read in full. */
+function shortenedNote(key) {
+    return ` (its text is long; get_my_agent with entry "${key}" shows it in full)`;
+}
+/** A scheduled task as a list line: key, on or off, schedule and description, then shortenedNote if its text was cut. */
+export function formatScheduledTaskLine(task, shortenedNote = '') {
+    return `- \`${task.key}\` ${task.enabled ? 'on' : 'off'}${task.notWritten ? ' (its text is not written yet, so it does not run)' : ''}${task.interval ? `, ${task.interval}` : ''}${task.description ? `: ${quotedSpan(task.description)}` : ''}${task.instructionsTruncated ? shortenedNote : ''}`;
+}
+/** A custom instruction as a list line: key, on or off and description, then shortenedNote if its text was cut. */
+export function formatCustomInstructionLine(task, shortenedNote = '') {
+    return `- \`${task.key}\` ${task.enabled ? 'on' : 'off'}${task.description ? `: ${quotedSpan(task.description)}` : ''}${task.instructionsTruncated ? shortenedNote : ''}`;
+}
 function formatRate(credits) {
     return credits.toLocaleString('en-US', { maximumFractionDigits: 3 });
 }
+/** Each model with its credits per 1M input and output tokens, separated by semicolons. */
+export function formatModelRates(models) {
+    return models.map(model => {
+        const name = model.label ? `${model.label} (${model.slug})` : model.slug;
+        return model.inputCreditsPer1M !== undefined && model.outputCreditsPer1M !== undefined
+            ? `${name} ${formatRate(model.inputCreditsPer1M)} and ${formatRate(model.outputCreditsPer1M)}`
+            : `${name} rate unknown`;
+    }).join('; ');
+}
 /** The chat and scheduled-task models, then every model the agent can switch to with its rates. */
 function formatModelsLine(agent) {
     const choices = agent.selectableModels ?? [];
@@ -566,22 +708,19 @@ function formatModelsLine(agent) {
     if (agent.models)
         parts.push(`chat ${nameOf(agent.models.chat)}, scheduled tasks ${nameOf(agent.models.cron)}.`);
     if (choices.length > 0) {
-        const rates = choices.map(model => {
-            const name = model.label ? `${model.label} (${model.slug})` : model.slug;
-            return model.inputCreditsPer1M !== undefined && model.outputCreditsPer1M !== undefined
-                ? `${name} ${formatRate(model.inputCreditsPer1M)} and ${formatRate(model.outputCreditsPer1M)}`
-                : `${name} rate unknown`;
-        });
-        parts.push(`Models you can switch to, in credits per 1M input and output tokens: ${rates.join('; ')}.`);
+        parts.push(`Models you can switch to, in credits per 1M input and output tokens: ${formatModelRates(choices)}.`);
     }
     return parts.length > 0 ? `**Models:** ${parts.join(' ')}` : null;
 }
-export function formatAgentDetail(agent) {
-    const lines = formatAgentSummaryLines(agent);
+export function formatAgentDetail(agent, plainMember = false) {
+    const lines = formatAgentSummaryLines(agent, plainMember);
+    if (agent.lastActivityAt)
+        lines.push(`**Last activity:** ${agent.lastActivityAt}`);
     if (agent.pricing) {
-        // This agent's own Starter and Pro prices, which can differ from its template's.
+        // Today's Starter and Pro prices for this agent's own skills, which can
+        // differ from its template's and from the price its plan pays.
         const { starter, pro } = agent.pricing;
-        lines.push(`**Prices now:** Starter ${formatUsd(starter.priceUsd)} per 30 days with ${formatCredits(starter.monthlyCredits)} credits per month; Pro ${formatUsd(pro.priceUsd)} per 30 days with ${formatCredits(pro.monthlyCredits)} credits per month. A new plan or an upgrade uses these.`);
+        lines.push(`**Prices now:** Starter ${formatUsd(starter.priceUsd)} per 30 days with ${formatCredits(starter.monthlyCredits)} credits per month; Pro ${formatUsd(pro.priceUsd)} per 30 days with ${formatCredits(pro.monthlyCredits)} credits per month. A new plan or an upgrade uses these, and a skill change moves the plan to today's prices for all its skills.`);
     }
     const models = formatModelsLine(agent);
     if (models)
@@ -604,25 +743,23 @@ export function formatAgentDetail(agent) {
         for (const credential of agent.credentials) {
             const state = credential.connected
                 ? 'connected'
-                : credential.filled
-                    ? 'filled'
-                    : credential.requiredMissing
-                        ? 'missing (required)'
+                : credential.requiredMissing
+                    ? (credential.oauth ? 'not connected (required)' : 'missing (required)')
+                    : credential.filled
+                        ? 'filled'
                         : 'not set';
             lines.push(`- ${credential.title} (\`${credential.key}\`): ${state}${credential.optional ? ', optional' : ''}`);
         }
     }
     if (agent.scheduledTasks.length > 0) {
         lines.push('', '### Scheduled tasks', '');
-        for (const task of agent.scheduledTasks) {
-            lines.push(`- \`${task.key}\` ${task.enabled ? 'on' : 'off'}${task.interval ? `, ${task.interval}` : ''}${task.description ? `: ${task.description}` : ''}${task.instructionsTruncated ? SHORTENED_NOTE : ''}`);
-        }
+        for (const task of agent.scheduledTasks)
+            lines.push(formatScheduledTaskLine(task, shortenedNote(task.key)));
     }
     if (agent.customInstructions.length > 0) {
         lines.push('', '### Custom instructions', '');
-        for (const task of agent.customInstructions) {
-            lines.push(`- \`${task.key}\`${task.description ? `: ${task.description}` : ''}${task.instructionsTruncated ? SHORTENED_NOTE : ''}`);
-        }
+        for (const task of agent.customInstructions)
+            lines.push(formatCustomInstructionLine(task, shortenedNote(task.key)));
     }
     lines.push('', `Dashboard: ${agent.dashboardUrl}`);
     return lines.join('\n');
@@ -661,12 +798,12 @@ const GUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{
 export function isGuid(value) {
     return GUID_PATTERN.test(value.trim());
 }
-/** The raw Detail row. Callers must pass it through toAgentDetail before returning anything. */
+/** Reads one agent's Detail row; tool results are built from it with toAgentDetail or toAgentSummary. */
 export async function readAgentDetail(client, guid, signal) {
     const body = requireApiSuccess(await client.post('/UserAgent/Detail', { guid }, signal), 'The agent could not be read.');
     const rows = Array.isArray(body.useragents) ? body.useragents.filter(isPlainObject) : [];
     if (!rows[0])
-        throw new Error(`No agent was found for agent_guid "${guid}".`);
+        throw new Error(AGENT_NOT_FOUND_TEXT);
     return rows[0];
 }
 // Every Detail read prices the agent, so polling stays slower than for tasks.
@@ -685,16 +822,30 @@ export async function waitForAgentToSettle(client, guid, waitSeconds, extra, fal
     });
     return {
         row: result.value ?? fallbackRow,
+        fresh: result.value !== undefined,
         settled: result.done,
         elapsedMs: result.elapsedMs,
     };
 }
+/** The credential that holds the Wiro project an agent runs models with. */
+export const WIRO_PROJECT_CREDENTIAL = 'wiro';
+/** The call that connects a Wiro project to an agent. It shows the project first; lead says why it comes now. */
+export function bindProjectStep(agentGuid, lead) {
+    return {
+        tool: 'bind_agent_project',
+        arguments: { agent_guid: agentGuid },
+        reason: `${lead} This shows the project first and changes nothing without confirm: true, and no key is needed.`,
+    };
+}
 /** The call that starts on the first missing credential, with every argument it needs. */
 export function missingCredentialStep(agent) {
     const missing = agent.missingCredentials[0];
     if (!missing)
         return undefined;
     const keys = agent.missingCredentials.map(item => item.key).join(', ');
+    if (missing.key === WIRO_PROJECT_CREDENTIAL) {
+        return bindProjectStep(agent.guid, `Provide the missing credentials (${keys}), starting with ${missing.title}.`);
+    }
     return missing.oauth
         ? {
             tool: 'connect_agent_oauth',
@@ -707,8 +858,21 @@ export function missingCredentialStep(agent) {
             reason: `Provide the missing credentials (${keys}). This lists the ${missing.title} fields to ask the user for.`,
         };
 }
-/** The most useful next call for an agent in this state, if any. */
-export function nextStepForAgent(agent, waitSeconds) {
+/**
+ * The most useful next call for an agent in this state, if any. For a team
+ * member without admin rights it is only the wait for a status that moves on
+ * by itself.
+ */
+export function nextStepForAgent(agent, waitSeconds, plainMember = false) {
+    const wait = isTransitionalStatus(agent.status)
+        ? {
+            tool: 'get_my_agent',
+            arguments: { agent_guid: agent.guid, wait_seconds: waitSeconds },
+            reason: 'Wait until the agent has settled. Do not repeat the action that started it.',
+        }
+        : undefined;
+    if (plainMember)
+        return wait;
     if (agent.status === 6 && agent.subscription?.status !== 'active') {
         return {
             tool: 'manage_agent_billing',
@@ -719,11 +883,13 @@ export function nextStepForAgent(agent, waitSeconds) {
     const missing = agent.missingCredentials[0];
     if (missing)
         return missingCredentialStep(agent);
-    if (isTransitionalStatus(agent.status)) {
+    if (wait)
+        return wait;
+    if ((agent.status === 0 || agent.status === 5) && startNeedsPlan(agent)) {
         return {
-            tool: 'get_my_agent',
-            arguments: { agent_guid: agent.guid, wait_seconds: waitSeconds },
-            reason: 'Wait until the agent has settled. Do not repeat the action that started it.',
+            tool: 'manage_agent_billing',
+            arguments: { agent_guid: agent.guid, action: planActionForStart(agent) },
+            reason: 'The agent has no active plan and no extra credits left, so it cannot start. This returns the price; nothing is charged without confirm: true.',
         };
     }
     if (agent.status === 0 || agent.status === 5) {
@@ -735,13 +901,18 @@ export function nextStepForAgent(agent, waitSeconds) {
     }
     return undefined;
 }
-// Refusals Wiro sends before it touches the wallet, or after rolling back
-// everything it wrote. Only these are known to come before any charge, so any
-// other result:false answer to a paid call leaves the outcome open.
+// Refusals known to leave the wallet untouched.
 const PRE_CHARGE_CODES = new Set([95, 96, 97, 99, 101, 102, 103, 104, 105, 106, 107, 108, 109]);
+const WALLET_NOT_READ = /could not retrieve wallet balance/i;
+/** Whether a refusal says the wallet could not be read, which says nothing about what it holds. */
+export function isWalletNotRead(error) {
+    return error instanceof ApiResultError && WALLET_NOT_READ.test(error.message);
+}
+/** The words after such a refusal. No funds are asked for: the wallet may hold plenty. */
+export const WALLET_NOT_READ_NOTE = 'Wiro could not read the balance just now. That is not a low balance, and nothing was charged. Try again in a moment; if it keeps saying so, get_account shows the wallet.';
 const PRE_CHARGE_REFUSALS = [
     /insufficient wallet balance/i,
-    /could not retrieve wallet balance/i,
+    WALLET_NOT_READ,
     /wallet deduction failed/i,
     /subscription (is )?already active/i,
     /already on (the )?(pro|starter) tier/i,
@@ -758,11 +929,14 @@ const PRE_CHARGE_REFUSALS = [
     /switch to (the )?(team|personal) context|belongs to a different team/i,
     /^request parameter \[/i,
     /mutually exclusive|agent terms acceptance|customskills must be|skill key may only contain/i,
+    /^unknown skill: /i,
+    /^the tier change could not be saved\./i,
+    /^we couldn't (schedule|undo) the cancellation\./i,
     /enabledchannels is not accepted|credentials must be an object|credential field|is missing required fields/i,
     /chat mode is not accepted|is managed by (wiro|the connection flow)|^agent-[a-z-]+$/i,
     /^failed to deploy agent|failed to save communication channel settings|failed to save custom skill/i,
 ];
-/** Whether a result:false answer is one that Wiro sends before any charge. */
+/** Whether a result:false answer is one of the refusals known to leave the wallet untouched. */
 export function isPreChargeRefusal(error) {
     if (!(error instanceof ApiResultError))
         return false;
@@ -770,22 +944,51 @@ export function isPreChargeRefusal(error) {
         return true;
     return PRE_CHARGE_REFUSALS.some(pattern => pattern.test(error.message.trim()));
 }
+const CHARGED_START = 'The wallet was charged ';
+const CHARGED_END = /, but the (tier change|renewal) did not finish\. Please contact support and do not try again\.$/;
+/**
+ * Whether a result:false answer says what the wallet paid. Its sentence is the
+ * whole outcome: it is shown as it is, and the call is not repeated.
+ */
+export function isKnownPaidOutcome(error) {
+    if (!(error instanceof ApiResultError))
+        return false;
+    const message = error.message.trim();
+    return message.startsWith(CHARGED_START) && CHARGED_END.test(message);
+}
+/**
+ * Whether a result:false answer carries code 110. Its answer is the whole outcome:
+ * the change is reported as failed, what the agent and the wallet show is read by
+ * hand, and the call is not repeated.
+ */
+export function isKnownFailedChange(error) {
+    return error instanceof ApiResultError && error.codes.some(code => Number(code) === 110);
+}
 /**
  * After a paid request was sent, whether it may still have gone through.
- * Only the known refusals and client errors (other than a timeout or rate
- * limit) settle it; any other answer, a network failure or a server error
- * leaves it open.
+ * Only the known refusals, an answer that says what the wallet paid or carries
+ * code 110, and client errors (other than a timeout or rate limit) settle it; any
+ * other answer, a network failure or a server error leaves it open.
  */
 export function outcomeUnknown(error) {
     if (error instanceof ApiResultError)
-        return !isPreChargeRefusal(error);
+        return !isPreChargeRefusal(error) && !isKnownPaidOutcome(error) && !isKnownFailedChange(error);
     if (error instanceof WiroApiError) {
         return error.status >= 500 || error.status === 408 || error.status === 429;
     }
     return true;
 }
-/** Advice for a status reached after a start, renew or deploy. */
-export function settledStatusAdvice(status) {
+/** Advice for a status reached after a start, renew or deploy. With the agent, a failed agent without a plan or extra credits is sent to billing. */
+export function settledStatusAdvice(status, plainMember = false, agent) {
+    if (!plainMember && agent && status === 5 && startNeedsPlan(agent)) {
+        return `The agent failed to start. ${noPlanStartHint(agent)}`;
+    }
+    if (plainMember && status === 5) {
+        return `The agent failed to start. On this team agent, ${TEAM_AGENT_MANAGERS} can start it again and read its logs.`;
+    }
+    if (plainMember && status === 6) {
+        return `The agent needs setup: it has no paid plan, or required credentials are missing. ${MEMBER_SETUP_HELP}`;
+    }
     switch (status) {
         case 4:
             return 'The agent is running. send_agent_message with agent set to its guid talks to it.';
@@ -796,7 +999,17 @@ export function settledStatusAdvice(status) {
         case 6:
             return 'The agent needs setup: it has no paid plan, or required credentials are missing.';
         default:
-            return agentStatusHint(status);
+            return agentStatusHint(status, plainMember);
     }
 }
+/** Advice for a read, which cannot tell whether a start came first: a stopped agent gets what holds now. */
+export function readStatusAdvice(agent, plainMember = false) {
+    if (agent.status !== 0)
+        return settledStatusAdvice(agent.status, plainMember, agent);
+    if (plainMember)
+        return `The agent is stopped. On this team agent, ${TEAM_AGENT_MANAGERS} can start it.`;
+    return startNeedsPlan(agent)
+        ? `The agent is stopped. ${noPlanStartHint(agent)}`
+        : 'The agent is stopped. control_agent with action start starts it.';
+}
 //# sourceMappingURL=user-agent.js.map