@wiro-ai/wiro-mcp 1.3.4 → 1.4.1

package/dist/utils/user-agent.js

@@ -0,0 +1,897 @@
+import { z } from 'zod';
+import { WiroApiError } from '../client.js';
+import { ApiResultError, asString, isPlainObject, requireApiSuccess, toNumber, truncate, unixToIso, } from './api.js';
+import { pollUntil, reportProgress } from './poll.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)}`;
+}
+// ---------------------------------------------------------------------------
+// Status
+// ---------------------------------------------------------------------------
+const STATUS_LABELS = [
+    'stopped',
+    'stopping',
+    'queued',
+    'starting',
+    'running',
+    'error',
+    'setup_required',
+    'unknown',
+];
+export const agentStatusLabelSchema = z.enum(STATUS_LABELS);
+const STATUS_TEXT = {
+    stopped: 'Stopped',
+    stopping: 'Stopping',
+    queued: 'Queued',
+    starting: 'Starting',
+    running: 'Running',
+    error: 'Error',
+    setup_required: 'Setup required',
+    unknown: 'Unknown',
+};
+const STATUS_HINT = {
+    stopped: 'It is not running. control_agent with action start starts it.',
+    stopping: 'It is shutting down. If a restart was requested it is queued again on its own.',
+    queued: 'It is waiting to start. This can take a while.',
+    starting: 'It is starting up. If it does not come up within about two minutes it moves to error.',
+    running: 'It is live and accepts messages.',
+    error: 'The start failed or the agent stopped unexpectedly. control_agent with action start retries, and get_agent_activity with kind logs may show why.',
+    setup_required: 'It has no paid plan yet, or required credentials are missing. It does not leave this state on its own.',
+    unknown: 'The status could not be read.',
+};
+export function readAgentStatus(row) {
+    const status = toNumber(row.status);
+    return status === null ? null : Math.trunc(status);
+}
+export function agentStatusLabel(status) {
+    if (status === null || status === undefined || !Number.isInteger(status))
+        return 'unknown';
+    return status >= 0 && status <= 6 ? STATUS_LABELS[status] : 'unknown';
+}
+/** "Running (4)" */
+export function describeAgentStatus(status) {
+    const label = agentStatusLabel(status);
+    return status === null || status === undefined
+        ? STATUS_TEXT[label]
+        : `${STATUS_TEXT[label]} (${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) {
+    return status === 1 || status === 2 || status === 3;
+}
+// ---------------------------------------------------------------------------
+// Prices, plans and credits
+// ---------------------------------------------------------------------------
+export const AGENT_TIERS = ['starter', 'pro'];
+export const tierPriceSchema = z.object({
+    priceUsd: z.number(),
+    monthlyCredits: z.number(),
+});
+export const tierPricingSchema = z.object({
+    starter: tierPriceSchema,
+    pro: tierPriceSchema,
+});
+function toTierPrice(value) {
+    if (!isPlainObject(value))
+        return null;
+    const priceUsd = toNumber(value.priceUsd);
+    const credits = toNumber(value.credits);
+    if (priceUsd === null || credits === null)
+        return null;
+    return { priceUsd, monthlyCredits: credits };
+}
+/** Starter and Pro prices, or null when Wiro could not price the agent. */
+export function toTierPricing(value) {
+    if (!isPlainObject(value))
+        return null;
+    const starter = toTierPrice(value.starter);
+    const pro = toTierPrice(value.pro);
+    return starter && pro ? { starter, pro } : null;
+}
+export function asTier(value) {
+    return value === 'starter' || value === 'pro' ? value : undefined;
+}
+export function formatUsd(value) {
+    if (value === null || value === undefined || !Number.isFinite(value))
+        return 'unknown';
+    return `$${value.toFixed(2)}`;
+}
+export function formatCredits(value) {
+    if (value === null || value === undefined || !Number.isFinite(value))
+        return 'unknown';
+    return Math.round(value).toLocaleString('en-US');
+}
+export function roundUsd(value) {
+    return Math.round(value * 100) / 100;
+}
+// A confirmed charge goes ahead only when a fresh quote still matches the
+// amount the user approved; anything else is quoted again.
+export const AMOUNT_TOLERANCE_USD = 0.005;
+export function sameAmount(quoted, approved) {
+    return Math.abs(quoted - approved) <= AMOUNT_TOLERANCE_USD;
+}
+export const subscriptionSchema = z.object({
+    status: z.string(),
+    billing: z.enum(['wallet', 'card']),
+    switchingToWallet: z.boolean(),
+    amountUsd: z.number().nullable(),
+    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.'),
+});
+/**
+ * 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. Any other card
+ * plan is known only when the row carries its card state (cardEnds).
+ */
+export function planEndsWithPeriod(subscription, cardEnds) {
+    if (subscription.pendingdowngrade === 'cancel' || cardEnds === true)
+        return true;
+    if (subscription.provider === 'prepaid' || subscription.nextprovider === 'prepaid' || cardEnds === false)
+        return false;
+    return 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,
+        billing: provider === 'prepaid' ? 'wallet' : 'card',
+        switchingToWallet: provider !== 'prepaid' && value.nextprovider === 'prepaid',
+        amountUsd: toNumber(value.amount),
+        ...(periodEndsAt ? { periodEndsAt } : {}),
+        daysRemaining: toNumber(value.daysremaining),
+        // 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. */
+export function chargeRoute(subscription) {
+    if (!isPlainObject(subscription))
+        return null;
+    if (subscription.nextprovider === 'prepaid' || subscription.provider === 'prepaid')
+        return 'wallet';
+    return 'card';
+}
+export const creditsSchema = z.object({
+    monthly: z.number(),
+    extra: z.number(),
+    used: z.number(),
+    remaining: z.number(),
+    period: z.string().optional(),
+});
+export function toCredits(row) {
+    const period = asString(row.creditperiod);
+    return {
+        monthly: toNumber(row.monthlycredits) ?? 0,
+        extra: toNumber(row.extracredits) ?? 0,
+        used: toNumber(row.usedcredits) ?? 0,
+        remaining: toNumber(row.remainingcredits) ?? 0,
+        ...(period ? { period } : {}),
+    };
+}
+// ---------------------------------------------------------------------------
+// Text helpers
+// ---------------------------------------------------------------------------
+const ENTITIES = {
+    '&nbsp;': ' ',
+    '&lt;': '<',
+    '&gt;': '>',
+    '&quot;': '"',
+    '&#39;': '\'',
+    '&amp;': '&',
+};
+/** Plain text from catalog HTML. Links keep their target so setup steps stay usable. */
+export function htmlToText(value, maxLength) {
+    const html = asString(value);
+    if (!html)
+        return '';
+    const text = html
+        .replace(/<a\b[^>]*?href\s*=\s*"([^"]*)"[^>]*>([\s\S]*?)<\/a>/gi, (_match, href, inner) => {
+        const label = inner.replace(/<[^>]*>/g, '').trim();
+        if (!/^https?:\/\//i.test(href) || label.includes(href))
+            return label;
+        return label ? `${label} (${href})` : href;
+    })
+        .replace(/<\s*br\s*\/?\s*>/gi, '\n')
+        .replace(/<li\b[^>]*>/gi, '\n- ')
+        .replace(/<\/(p|li|div|ol|ul|h[1-6])\s*>/gi, '\n')
+        .replace(/<[^>]*>/g, '')
+        .replace(/&nbsp;|&lt;|&gt;|&quot;|&#39;|&amp;/g, entity => ENTITIES[entity] ?? entity)
+        .split('\n')
+        .map(line => line.replace(/[ \t]+/g, ' ').trim())
+        .filter(Boolean)
+        .join('\n');
+    return maxLength ? truncate(text, maxLength) : text;
+}
+export function toStringArray(value) {
+    let list = value;
+    if (typeof value === 'string') {
+        try {
+            list = JSON.parse(value);
+        }
+        catch {
+            return value.split(',').map(item => item.trim()).filter(Boolean);
+        }
+    }
+    if (!Array.isArray(list))
+        return [];
+    return list
+        .map((item) => (isPlainObject(item) ? asString(item.name) : asString(item)))
+        .filter((item) => typeof item === 'string' && item.length > 0);
+}
+// ---------------------------------------------------------------------------
+// Credentials, channels and tasks of a deployed agent
+// ---------------------------------------------------------------------------
+export const credentialStatusSchema = z.object({
+    key: z.string(),
+    title: z.string(),
+    optional: z.boolean(),
+    oauth: z.boolean(),
+    connected: z.boolean(),
+    filled: z.boolean(),
+    requiredMissing: z.boolean(),
+});
+/** The state of each credential: whether it is filled, connected or missing. */
+export function summarizeCredentials(credentials, skipKeys = new Set()) {
+    if (!isPlainObject(credentials))
+        return [];
+    const statuses = [];
+    for (const [key, group] of Object.entries(credentials)) {
+        if (key.startsWith('_') || skipKeys.has(key) || !isPlainObject(group))
+            continue;
+        const schema = isPlainObject(group._schema) ? group._schema : {};
+        statuses.push({
+            key,
+            title: asString(schema.title) ?? key,
+            optional: group.optional === true,
+            oauth: isPlainObject(schema.oauth_provider),
+            connected: group._connected === true,
+            filled: group._filled === true,
+            requiredMissing: group._required_missing === true,
+        });
+    }
+    return statuses;
+}
+export const channelStatusSchema = z.object({
+    id: z.string(),
+    title: z.string(),
+    credentialKey: z.string(),
+    enabled: z.boolean(),
+    configured: z.boolean(),
+    missingFields: z.array(z.string()),
+});
+export function summarizeChannels(value) {
+    if (!Array.isArray(value))
+        return [];
+    return value.filter(isPlainObject).map(channel => {
+        const id = asString(channel.id) ?? '';
+        return {
+            id,
+            title: asString(channel.title) ?? id,
+            credentialKey: asString(channel.credentialkey) ?? id,
+            enabled: channel.enabled === true,
+            configured: channel.configured === true,
+            missingFields: toStringArray(channel.missingfields),
+        };
+    });
+}
+export const agentTaskSchema = z.object({
+    key: z.string(),
+    description: z.string().optional(),
+    enabled: z.boolean(),
+    interval: z.string().nullable().optional(),
+    source: z.enum(['template', 'skill', 'user']).optional(),
+    instructions: z.string().optional(),
+    instructionsTruncated: z.boolean().optional(),
+});
+const TASK_SOURCES = {
+    'preset-strategy': 'template',
+    'skill-bundle': 'skill',
+    'user-created': 'user',
+};
+/** Custom instructions and scheduled tasks, with the instruction text cut short. */
+export function summarizeTasks(value, maxInstructionLength = 300) {
+    if (!Array.isArray(value))
+        return [];
+    return value.filter(isPlainObject).map(task => {
+        const description = asString(task.description);
+        const interval = asString(task.interval) ?? asString(task.intervalexpr);
+        const instructions = asString(task.value) ?? '';
+        const shortened = truncate(instructions, maxInstructionLength);
+        const source = TASK_SOURCES[asString(task._source) ?? ''];
+        return {
+            key: asString(task.key) ?? '',
+            ...(description ? { description } : {}),
+            enabled: task.enabled !== false,
+            ...(interval !== undefined ? { interval: interval || null } : {}),
+            ...(source ? { source } : {}),
+            ...(shortened ? { instructions: shortened } : {}),
+            ...(instructions.length > maxInstructionLength ? { instructionsTruncated: true } : {}),
+        };
+    });
+}
+// ---------------------------------------------------------------------------
+// Deployed agent views
+// ---------------------------------------------------------------------------
+const agentTemplateRefSchema = z.object({
+    custom: z.boolean(),
+    guid: z.string().optional(),
+    slug: z.string().optional(),
+    title: z.string().optional(),
+});
+const modelSettingsSchema = z.object({
+    chat: z.string().nullable(),
+    cron: z.string().nullable(),
+    voicePrep: z.string().nullable(),
+    voicePostcall: z.string().nullable(),
+});
+const selectableModelSchema = z.object({
+    slug: z.string(),
+    label: z.string().optional(),
+    inputCreditsPer1M: z.number().optional(),
+    outputCreditsPer1M: z.number().optional(),
+});
+export const extraCreditPackSchema = z.object({
+    pack: z.string(),
+    credits: z.number(),
+    priceUsd: z.number(),
+});
+export const agentSummarySchema = z.object({
+    guid: z.string(),
+    title: z.string(),
+    status: z.number().int().nullable(),
+    statusLabel: agentStatusLabelSchema,
+    setupRequired: z.boolean(),
+    workspace: z.enum(['personal', 'team']),
+    template: agentTemplateRefSchema,
+    tier: z.string().optional(),
+    monthlyPriceUsd: z.number().nullable(),
+    credits: creditsSchema,
+    subscription: subscriptionSchema.nullable(),
+    timezone: z.string().nullable().optional(),
+    teamSessionMode: z.string().optional(),
+    skills: z.array(z.string()),
+    createdAt: z.string().optional(),
+    updatedAt: z.string().optional(),
+});
+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),
+    models: modelSettingsSchema.optional(),
+    selectableModels: z.array(selectableModelSchema).optional(),
+    enabledCommands: z.array(z.string()).nullable(),
+    credentials: z.array(credentialStatusSchema),
+    missingCredentials: z.array(z.object({ key: z.string(), title: z.string(), oauth: z.boolean() })),
+    channels: z.array(channelStatusSchema),
+    scheduledTasks: z.array(agentTaskSchema),
+    customInstructions: z.array(agentTaskSchema),
+    queuedAt: z.string().optional(),
+    startedAt: z.string().optional(),
+    runningAt: z.string().optional(),
+    stoppedAt: z.string().optional(),
+    erroredAt: z.string().optional(),
+    dashboardUrl: z.string(),
+});
+/** The part of a new agent that matters right after deploying it. */
+export const deployedAgentSchema = agentSummarySchema.extend({
+    missingCredentials: agentDetailSchema.shape.missingCredentials,
+    channels: agentDetailSchema.shape.channels,
+    dashboardUrl: z.string(),
+});
+export function toDeployedAgent(agent) {
+    // Object schemas drop the keys they do not declare.
+    return deployedAgentSchema.parse(agent);
+}
+function templateRef(row) {
+    const agent = isPlainObject(row.agent) ? row.agent : {};
+    const guid = asString(agent.guid) ?? asString(row.agentguid);
+    if (agent.custom === true || !guid)
+        return { custom: true };
+    const slug = asString(agent.slug);
+    const title = asString(agent.title);
+    return {
+        custom: false,
+        guid,
+        ...(slug ? { slug } : {}),
+        ...(title ? { title } : {}),
+    };
+}
+function timestamps(row, map) {
+    const out = {};
+    for (const [key, column] of Object.entries(map)) {
+        const iso = unixToIso(row[column]);
+        if (iso)
+            out[key] = iso;
+    }
+    return out;
+}
+/** The compact row used by list_my_agents. */
+export function toAgentSummary(row) {
+    const status = readAgentStatus(row);
+    const tier = asString(row.tier);
+    const timezone = row.timezone === null ? null : asString(row.timezone);
+    const sessionMode = asString(row.teamsessionmode);
+    return {
+        guid: asString(row.guid) ?? '',
+        title: asString(row.title) ?? '',
+        status,
+        statusLabel: agentStatusLabel(status),
+        setupRequired: row.setuprequired === true || status === 6,
+        workspace: row.teamguid ? 'team' : 'personal',
+        template: templateRef(row),
+        ...(tier ? { tier } : {}),
+        monthlyPriceUsd: toNumber(row.monthlypriceusd),
+        credits: toCredits(row),
+        subscription: toSubscription(row.subscription, row.stripecancelatperiodend),
+        ...(timezone !== undefined ? { timezone } : {}),
+        ...(sessionMode ? { teamSessionMode: sessionMode } : {}),
+        skills: toStringArray(row.skills ?? row.enabledSkills),
+        ...timestamps(row, { createdAt: 'createdat', updatedAt: 'updatedat' }),
+    };
+}
+/** The models an agent can switch to, with their credits per 1M input and output tokens when Wiro lists them. */
+function selectableModels(tokenRates) {
+    if (!isPlainObject(tokenRates) || !isPlainObject(tokenRates.models))
+        return [];
+    return Object.entries(tokenRates.models)
+        .filter(([, meta]) => isPlainObject(meta) && meta.selectable === true)
+        .map(([slug, meta]) => {
+        const rates = meta;
+        const label = asString(rates.label);
+        const input = toNumber(rates.input_per_1m);
+        const output = toNumber(rates.output_per_1m);
+        return {
+            slug,
+            ...(label ? { label } : {}),
+            ...(input !== null ? { inputCreditsPer1M: input } : {}),
+            ...(output !== null ? { outputCreditsPer1M: output } : {}),
+        };
+    });
+}
+/** Slugs a deployed agent may switch its chat, cron or voice model to. */
+export function selectableModelSlugs(row) {
+    return new Set(selectableModels(row.tokenRates).map(model => model.slug));
+}
+/**
+ * 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);
+    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)
+        ? agent.extracreditpacks.filter(isPlainObject).filter(pack => pack.enabled !== false)
+        : [];
+    return {
+        ...summary,
+        ...(description ? { description: truncate(description, 2_000) } : {}),
+        ...(cover ? { cover } : {}),
+        categories: toStringArray(row.categories),
+        pricing: toTierPricing(agent.tiers),
+        extraCreditPacks: packs.flatMap(pack => {
+            const name = asString(pack.packkey);
+            const credits = toNumber(pack.credits);
+            const priceUsd = toNumber(pack.priceusd);
+            return name && credits !== null && priceUsd !== null ? [{ pack: name, credits, priceUsd }] : [];
+        }),
+        ...(agentModel
+            ? {
+                models: {
+                    chat: asString(agentModel.chatModel) ?? null,
+                    cron: asString(agentModel.cronModel) ?? null,
+                    voicePrep: asString(agentModel.voicePrepModel) ?? null,
+                    voicePostcall: asString(agentModel.voicePostcallModel) ?? null,
+                },
+            }
+            : {}),
+        ...(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))
+            .map(({ key, title, oauth }) => ({ key, title, oauth })),
+        channels,
+        scheduledTasks: summarizeTasks(row.scheduledskills),
+        customInstructions: summarizeTasks(row.customskills),
+        ...timestamps(row, {
+            queuedAt: 'queuedat',
+            startedAt: 'startedat',
+            runningAt: 'runningat',
+            stoppedAt: 'stopdat',
+            erroredAt: 'errordat',
+        }),
+        dashboardUrl: agentDashboardUrl(summary.guid),
+    };
+}
+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.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 {
+            // 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(', ');
+}
+/** 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.');
+}
+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)}. ${hint}`,
+        `**Plan:** ${agent.tier ?? 'no tier'}; ${formatSubscriptionLine(agent.subscription, plainMember)}`,
+        `**Credits:** ${formatCredits(agent.credits.remaining)} left (monthly ${formatCredits(agent.credits.monthly)}, extra ${formatCredits(agent.credits.extra)}, used ${formatCredits(agent.credits.used)})`,
+    ];
+}
+/** 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.interval ? `, ${task.interval}` : ''}${task.description ? `: ${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 ? `: ${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 ?? [];
+    const nameOf = (slug) => (slug ? choices.find(model => model.slug === slug)?.label ?? slug : 'the default model');
+    const parts = [];
+    if (agent.models)
+        parts.push(`chat ${nameOf(agent.models.chat)}, scheduled tasks ${nameOf(agent.models.cron)}.`);
+    if (choices.length > 0) {
+        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, plainMember = false) {
+    const lines = formatAgentSummaryLines(agent, plainMember);
+    if (agent.pricing) {
+        // 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, and a skill change moves the plan to today's prices for all its skills.`);
+    }
+    const models = formatModelsLine(agent);
+    if (models)
+        lines.push(models);
+    if (agent.timezone !== undefined) {
+        lines.push(`**Time zone:** ${agent.timezone?.trim() ? agent.timezone : 'UTC, the default'}. Scheduled tasks run in it.`);
+    }
+    if (agent.setupRequired) {
+        lines.push(agent.missingCredentials.length > 0
+            ? `**Setup required:** missing ${agent.missingCredentials.map(item => item.title).join(', ')}`
+            : '**Setup required:** yes');
+    }
+    if (agent.skills.length > 0)
+        lines.push(`**Skills:** ${agent.skills.join(', ')}`);
+    if (agent.channels.length > 0) {
+        lines.push(`**Channels:** ${agent.channels.map(channel => `${channel.title} ${channel.enabled ? 'on' : channel.configured ? 'configured' : 'off'}`).join(', ')}`);
+    }
+    if (agent.credentials.length > 0) {
+        lines.push('', '### Credentials', '');
+        for (const credential of agent.credentials) {
+            const state = credential.connected
+                ? 'connected'
+                : credential.filled
+                    ? 'filled'
+                    : credential.requiredMissing
+                        ? 'missing (required)'
+                        : '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(formatScheduledTaskLine(task, shortenedNote(task.key)));
+    }
+    if (agent.customInstructions.length > 0) {
+        lines.push('', '### Custom instructions', '');
+        for (const task of agent.customInstructions)
+            lines.push(formatCustomInstructionLine(task, shortenedNote(task.key)));
+    }
+    lines.push('', `Dashboard: ${agent.dashboardUrl}`);
+    return lines.join('\n');
+}
+// Custom skill keys get the same canonical shape the server gives them, so a
+// key can be compared with the template's own entries before deploying.
+export function normalizeCustomSkillKey(input, interval) {
+    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 {
+        const scheduled = typeof interval === 'string'
+            && !['', 'manual', 'false'].includes(interval.trim().toLowerCase());
+        prefix = scheduled ? 'cs-cron-' : 'cs-';
+        body = trimmed;
+    }
+    if (body.length === 0 || body.length > 60)
+        return null;
+    return /^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(body) ? prefix + body : null;
+}
+const GUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+export function isGuid(value) {
+    return GUID_PATTERN.test(value.trim());
+}
+/** 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}".`);
+    return rows[0];
+}
+// Every Detail read prices the agent, so polling stays slower than for tasks.
+export function agentPollInterval(elapsedMs) {
+    return elapsedMs < 60_000 ? 5_000 : 10_000;
+}
+/** Reads the agent until its status is no longer stopping, queued or starting. */
+export async function waitForAgentToSettle(client, guid, waitSeconds, extra, fallbackRow) {
+    const result = await pollUntil({
+        read: signal => readAgentDetail(client, guid, signal),
+        isDone: row => !isTransitionalStatus(readAgentStatus(row)),
+        timeoutMs: waitSeconds * 1000,
+        signal: extra?.signal,
+        interval: agentPollInterval,
+        onPoll: (row, elapsedMs) => reportProgress(extra, elapsedMs, `Agent status: ${describeAgentStatus(readAgentStatus(row))}`),
+    });
+    return {
+        row: result.value ?? fallbackRow,
+        fresh: result.value !== undefined,
+        settled: result.done,
+        elapsedMs: result.elapsedMs,
+    };
+}
+/** 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(', ');
+    return missing.oauth
+        ? {
+            tool: 'connect_agent_oauth',
+            arguments: { action: 'connect', agent_guid: agent.guid, credential: missing.key },
+            reason: `Provide the missing credentials (${keys}). This starts with ${missing.title}, which the user connects by signing in.`,
+        }
+        : {
+            tool: 'set_agent_credentials',
+            arguments: { agent_guid: agent.guid, credential: missing.key },
+            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. 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',
+            arguments: { agent_guid: agent.guid, action: 'subscribe' },
+            reason: 'The agent has no paid plan. This returns the price; nothing is charged without confirm: true.',
+        };
+    }
+    const missing = agent.missingCredentials[0];
+    if (missing)
+        return missingCredentialStep(agent);
+    if (wait)
+        return wait;
+    if ((agent.status === 0 || agent.status === 5) && startNeedsPlan(agent)) {
+        return {
+            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) {
+        return {
+            tool: 'control_agent',
+            arguments: { agent_guid: agent.guid, action: 'start' },
+            reason: agent.status === 5 ? 'Retry the failed start.' : 'Start the agent.',
+        };
+    }
+    return undefined;
+}
+// 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 PRE_CHARGE_REFUSALS = [
+    /insufficient wallet balance/i,
+    /could not retrieve wallet balance/i,
+    /wallet deduction failed/i,
+    /subscription (is )?already active/i,
+    /already on (the )?(pro|starter) tier/i,
+    /no active subscription|active subscription required|no expired subscription found/i,
+    /stripe subscriptions must be/i,
+    /extra credit pack|pack key required|purchase request id/i,
+    /could not (initialize|resume) prepaid credit purchase|prepaid credit purchase cannot be resumed/i,
+    /downgrading to starter is not supported|targettier must be|tier must be 'starter' or 'pro'/i,
+    /failed to compute (target-tier )?pricing|must be greater than \$0|failed to apply pricing snapshot/i,
+    /failed to create subscription record|subscription record returned invalid id/i,
+    /payment for this agent is already being processed|checkout for this agent is already being opened/i,
+    /confirm this agent's previous checkout|card checkouts for a team agent|payment system not configured/i,
+    /agent not found|team admin|don't have access|access denied|must own this/i,
+    /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,
+    /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 of the refusals known to leave the wallet untouched. */
+export function isPreChargeRefusal(error) {
+    if (!(error instanceof ApiResultError))
+        return false;
+    if (error.codes.some(code => PRE_CHARGE_CODES.has(Number(code))))
+        return true;
+    return PRE_CHARGE_REFUSALS.some(pattern => pattern.test(error.message.trim()));
+}
+/**
+ * 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.
+ */
+export function outcomeUnknown(error) {
+    if (error instanceof ApiResultError)
+        return !isPreChargeRefusal(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. 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.';
+        case 5:
+            return 'The agent failed to start. get_agent_activity with kind logs may show why, and control_agent with action start retries.';
+        case 0:
+            return 'The agent is stopped. Right after a start this means it has no active plan and no credits left, or someone stopped it.';
+        case 6:
+            return 'The agent needs setup: it has no paid plan, or required credentials are missing.';
+        default:
+            return agentStatusHint(status, plainMember);
+    }
+}
+//# sourceMappingURL=user-agent.js.map