@skrr-ai/cli 0.1.110 → 0.1.113

package/dist/lib/appInstallations.js

@@ -0,0 +1,960 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.REPORT_REFUSAL_CODES = exports.INSTALLATION_REFUSAL_CODES = exports.ALL_INSTALLATION_REFUSAL_CODES = exports.InstallTargetError = void 0;
+exports.describeAvailability = describeAvailability;
+exports.describeTrust = describeTrust;
+exports.describeTrustShort = describeTrustShort;
+exports.formatInstallationRow = formatInstallationRow;
+exports.describeJobScheduling = describeJobScheduling;
+exports.formatJobStates = formatJobStates;
+exports.describeGrantReasons = describeGrantReasons;
+exports.formatDisclosure = formatDisclosure;
+exports.describeHostUnsuitable = describeHostUnsuitable;
+exports.describeOperatorUnmet = describeOperatorUnmet;
+exports.formatBindings = formatBindings;
+exports.formatHosting = formatHosting;
+exports.describeBindingRefusal = describeBindingRefusal;
+exports.describeDisclosureCheck = describeDisclosureCheck;
+exports.resolveInstallTarget = resolveInstallTarget;
+exports.describeInstallationConflict = describeInstallationConflict;
+exports.formatScopeIssues = formatScopeIssues;
+exports.resolveInstallPrincipal = resolveInstallPrincipal;
+exports.formatUserLayout = formatUserLayout;
+exports.readLayoutRefusal = readLayoutRefusal;
+exports.describeReportRefusal = describeReportRefusal;
+exports.installationRefusalExit = installationRefusalExit;
+/**
+ * `skrr apps install | installations | reconsent | upgrade | suspend | resume | uninstall | disclosure`: what
+ * the installation commands share. The second half of the domain lib of the Agent App commands; the first,
+ * `lib/apps.ts`, is the authoring loop's.
+ *
+ * It builds no URL. Every call to the API is a `dataService` function (`@skrr-ai/data-provider`), which is
+ * what keeps this CLI, the web install dialog and the host window on one set of routes (and what
+ * `domain-api-parity.spec.ts` checks). What lives here is what a terminal needs around them:
+ *
+ *  - saying a DISCLOSURE in words. It is the same data the web dialog draws (`parseAppDisclosure`), written as
+ *    what the app CAN DO and never as a permission key, with the unattended jobs said in the same sentence
+ *    that says whose authority they run under (owner decision D35 accepted that risk on the condition that
+ *    the install screen says so, and a terminal is an install screen);
+ *  - choosing what an `install` points at (an app, a version, the bundle the person was shown);
+ *  - saying why an installation call was refused, in the contract's closed vocabulary of reasons, with the
+ *    next step.
+ */
+const data_provider_1 = require("@skrr-ai/data-provider");
+// ── what an installation is, in a line ──────────────────────────────────────
+const AVAILABILITY_WORDS = {
+    ready: 'ready',
+    suspended: 'paused',
+    needs_reconsent: 'needs your approval again',
+    unavailable: 'cannot be read now',
+};
+/**
+ * The words for an availability the contract names. One this CLI does not know (a server newer than the CLI) is said
+ * as it came and as NOT recognised, never as "ready" and never as nothing.
+ */
+function describeAvailability(availability) {
+    if (typeof availability !== 'string') {
+        return 'unknown';
+    }
+    return (AVAILABILITY_WORDS[availability] ??
+        `${(0, data_provider_1.plainAppLabel)(availability, 40)} (not recognised: update the CLI)`);
+}
+/**
+ * How far an app is trusted, in a sentence. `reviewed` names no person: there is no human review, and an automatic
+ * check is not a statement that an app is safe. `workspace` says what is recorded (published to a workspace and
+ * marked approved), not who approved it: nothing here knows.
+ */
+const TRUST_WORDS = {
+    platform: 'built in',
+    reviewed: 'public; only automatic checks have looked at it (no person has reviewed it, and the checks do not show it is safe)',
+    workspace: 'published to a workspace and marked approved (who approved it is not recorded here)',
+    self: 'private: nobody but its maker has looked at it',
+};
+function describeTrust(trust) {
+    return typeof trust === 'string' ? (TRUST_WORDS[trust] ?? trust) : 'unknown';
+}
+/** The same four tiers in a few words, for a table: never the raw tier word, which reads as a verdict. */
+const TRUST_SHORT = {
+    platform: 'built in',
+    reviewed: 'automatic checks only',
+    workspace: 'workspace',
+    self: 'private',
+};
+function describeTrustShort(trust) {
+    return typeof trust === 'string' ? (TRUST_SHORT[trust] ?? trust) : 'unknown';
+}
+/**
+ * A table row of the apps installed on a principal. When the platform did not schedule some of the app's jobs (refused, or
+ * chose not to run) the row says how many at its end, and when it has not confirmed some (nothing is recorded for the
+ * version the app runs now) it says that, as its own count: "the platform said no" and "nobody has said anything" are
+ * different facts, and a row that counted only the first read an app whose every job is unconfirmed the same as a healthy
+ * one. Neither count is a verdict on the others, and neither says anything reassuring; `show` says which jobs and why. A row
+ * with nothing to say is the row it was (a job the person deleted the schedule of is their own choice, and adds nothing).
+ */
+function formatInstallationRow(item) {
+    const { notScheduled, notConfirmed } = (0, data_provider_1.summarizeAppJobStates)(item.jobState);
+    const jobs = (count) => `${count} ${count === 1 ? 'job' : 'jobs'}`;
+    return [
+        item.id,
+        (item.name ?? item.slug ?? item.appId).padEnd(24),
+        `v${item.version ?? '?'}`.padEnd(5),
+        describeAvailability(item.availability).padEnd(26),
+        describeTrustShort(item.trust),
+        ...(notScheduled > 0 ? [`${jobs(notScheduled)} not scheduled`] : []),
+        ...(notConfirmed > 0 ? [`${jobs(notConfirmed)} not confirmed`] : []),
+    ].join('  ');
+}
+// ── the disclosure, in words ────────────────────────────────────────────────
+const CONSENT_MARK = {
+    new: ' [new: you have not approved this]',
+    granted: '',
+    stale: ' [approved for different code: approve again]',
+    changed: ' [changed since you approved it]',
+};
+function mark(consent) {
+    return CONSENT_MARK[consent] ?? '';
+}
+const ISOLATION_WORDS = {
+    none: 'no isolation beyond the machine it runs on',
+    gvisor: 'inside a gVisor sandbox',
+    microvm: 'inside its own microVM',
+};
+/**
+ * Who can change a collection, as the words in the brackets. "The app's own code can change it" and "only your
+ * agent can change it" are different promises, so they are different sentences.
+ */
+const STORE_WRITER_WORDS = {
+    app_and_agent: "the app's own code can read and change it, including what your agent writes there",
+    app: "the app's own code can read and change it",
+    person_and_agent: "only people and your agent can change it; the app's own code can only read it",
+    agent: "only your agent can change it; the app's own code can only read it",
+    person: "only people can change it; the app's own code can only read it",
+};
+/** A job's schedule in words, beside the text the author wrote (which is always still shown). */
+function describeSchedule(schedule) {
+    const reading = (0, data_provider_1.readAppJobSchedule)(schedule);
+    switch (reading.kind) {
+        case 'daily':
+            return `every day at ${reading.times.join(' and ')}`;
+        case 'every':
+            return `every ${reading.count === 1 ? reading.unit.replace(/s$/, '') : `${reading.count} ${reading.unit}`}`;
+        case 'configured':
+            return "on a schedule set in the app's settings";
+        default:
+            return 'a schedule this CLI cannot read';
+    }
+}
+const DISABLE_REASON_WORDS = {
+    installation_suspended: 'the app is paused',
+    needs_reconsent: 'the app needs your approval again',
+    job_not_authorized: "you haven't approved this job as it is now",
+    schedule_invalid: "its schedule can't run",
+    guide_unavailable: "its guide can't be read",
+    circuit_open: 'turned off after repeated failures',
+};
+const PAUSE_AND_RESUME = 'then `skrr apps suspend <installation>` and `skrr apps resume <installation>`';
+/**
+ * Why the platform could NOT make an installed job's trigger (the jobs reconciler's refusal, recorded on the installation),
+ * one clause and one next step for each member of the contract's closed list. A `Record` over the list does not compile
+ * without words for a new reason. The reconciler used to say these only in a server log: an app that was installed and
+ * approved could have a job that never ran with nothing here to say why.
+ */
+const SCHEDULING_REFUSAL_WORDS = {
+    trigger_quota: {
+        what: "you've reached your limit on scheduled triggers",
+        next: `Turn off or delete a trigger you no longer need (\`skrr triggers list\`), ${PAUSE_AND_RESUME} to try again.`,
+    },
+    installer_cannot_manage_agent: {
+        what: "you can't manage the agent this app is installed on",
+        next: `Scheduling a job needs the same access as creating a trigger on that agent. Ask the agent's owner for that access, ${PAUSE_AND_RESUME}.`,
+    },
+    agent_missing: {
+        what: "the agent this app is installed on can't be found",
+        next: 'It may have been deleted. Install the app on another agent.',
+    },
+    schedule_refused: {
+        what: 'its schedule was refused',
+        next: "The scheduler didn't accept this job's schedule or your time zone. Check your time zone; if it is right, the app's author has to change the schedule in the manifest.",
+    },
+    prompt_too_long: {
+        what: 'its guide is too long for a trigger',
+        next: "The app's author has to shorten the guide this job follows and publish a new version.",
+    },
+    prompt_refused: {
+        what: 'its guide was refused',
+        next: "The scheduler didn't accept the text of the guide this job follows. The app's author has to change the guide and publish a new version.",
+    },
+    consent_refused: {
+        what: "your approval for this job couldn't be recorded",
+        next: 'Approve the app again with `skrr apps reconsent <installation> --yes`. If it keeps happening, tell whoever made the app.',
+    },
+    input_refused: {
+        what: "the scheduler didn't accept this job",
+        next: "Something in the job isn't something a trigger can hold, and you can't fix it from here. The app's author has to change the job in the manifest.",
+    },
+    error: {
+        what: "the platform couldn't set it up",
+        next: `The reason is not one this CLI has words for. Try again (${PAUSE_AND_RESUME}) and tell whoever made the app if it keeps happening.`,
+    },
+};
+/** Why the platform chose NOT to schedule a job. The same reasons as `DISABLE_REASON_WORDS`, each with its next step. */
+const NOT_SCHEDULED_WORDS = {
+    installation_suspended: {
+        what: 'the app is paused',
+        next: "Resume it with `skrr apps resume <installation>`. A pause the platform set can't be lifted by you.",
+    },
+    needs_reconsent: {
+        what: 'the app needs your approval again',
+        next: 'Review what changed with `skrr apps disclosure`, then approve with `skrr apps reconsent <installation> --yes`.',
+    },
+    job_not_authorized: {
+        what: "this job isn't approved to run",
+        next: "Approve the app again with `skrr apps reconsent <installation> --yes`. If that doesn't help, the agent or the person who approved it may have been removed: install the app again.",
+    },
+    schedule_invalid: {
+        what: "its schedule can't run",
+        next: "If the schedule uses a setting of the app, check that setting. Otherwise the app's author has to fix the schedule in the manifest.",
+    },
+    guide_unavailable: {
+        what: "its guide can't be used",
+        next: "The guide this job follows is missing, unreadable or too long. The app's author has to fix it and publish a new version.",
+    },
+    circuit_open: {
+        what: 'it was turned off after repeated failures',
+        next: "Look at the job's last runs (`skrr triggers list`), then turn it back on once you've decided it should run.",
+    },
+};
+const UNKNOWN_NOT_SCHEDULED_WORDS = {
+    what: 'the platform gave a reason this CLI does not know',
+    next: 'Update the CLI (`skrr update`) and look again.',
+};
+const NOT_RECORDED_WORDS = {
+    what: "the platform hasn't recorded whether this job is scheduled",
+    next: 'Pausing the app and resuming it checks again (`skrr apps suspend <installation>`, then `skrr apps resume <installation>`).',
+};
+/**
+ * A job's scheduling state, in words: `null` when it is scheduled (nothing to say). A state with something to say returns
+ * the clause and the next step; `unknown` is NEVER null, because "nobody recorded it" reads as "fine" when it is silent.
+ */
+function describeJobScheduling(jobState) {
+    if (!jobState || typeof jobState !== 'object') {
+        return null;
+    }
+    switch (jobState.state) {
+        case 'scheduled':
+            return null;
+        case 'refused': {
+            const words = (0, data_provider_1.isAppJobRefusalReason)(jobState.reason)
+                ? SCHEDULING_REFUSAL_WORDS[jobState.reason]
+                : SCHEDULING_REFUSAL_WORDS.error;
+            return { state: 'refused', ...words };
+        }
+        case 'not_runnable': {
+            const words = (0, data_provider_1.isAppJobDisableReason)(jobState.reason)
+                ? NOT_SCHEDULED_WORDS[jobState.reason]
+                : UNKNOWN_NOT_SCHEDULED_WORDS;
+            return { state: 'not_runnable', ...words };
+        }
+        case 'removed_by_person':
+            return {
+                state: 'removed_by_person',
+                what: 'you deleted its schedule; it stays deleted for this version',
+                next: null,
+            };
+        default:
+            return { state: 'unknown', ...NOT_RECORDED_WORDS };
+    }
+}
+/** The lines `skrr apps installations show` prints for the jobs' states: one per job, the reason and the next step under a job that is not scheduled. */
+function formatJobStates(jobStates, installationId) {
+    if (!Array.isArray(jobStates)) {
+        // a server that predates the record: say so, since silence would read as "all scheduled"
+        return ['  (this server does not say whether the jobs are scheduled)'];
+    }
+    const lines = [];
+    for (const job of jobStates) {
+        const words = describeJobScheduling(job);
+        if (!words) {
+            lines.push(`  job ${(0, data_provider_1.plainAppLabel)(job.id, 64)}: scheduled`);
+            continue;
+        }
+        lines.push(`  job ${(0, data_provider_1.plainAppLabel)(job.id, 64)}: NOT SCHEDULED: ${words.what}`);
+        if (words.next) {
+            lines.push(`    next: ${words.next.replace(/<installation>/g, installationId)}`);
+        }
+    }
+    return lines;
+}
+/**
+ * What became of a job's trigger, when the server says (an installed app). `managed` is the ordinary case and says
+ * nothing; every other state is said, because a job that does not run and a job that does must not read alike.
+ */
+function describeJobState(job) {
+    const scheduling = describeJobScheduling(job.jobState);
+    // The platform tried to schedule it and was REFUSED: the most useful thing to read, even when an older trigger is
+    // still there (it runs the text from before the refusal).
+    if (scheduling?.state === 'refused') {
+        return ` [NOT SCHEDULED: ${scheduling.what}]`;
+    }
+    const trigger = job.trigger;
+    if (trigger) {
+        switch (trigger.state) {
+            case 'paused_by_person':
+                return ' [you turned this job off]';
+            case 'paused_by_platform': {
+                const reason = trigger.platformDisabled?.reason;
+                const words = reason ? (DISABLE_REASON_WORDS[reason] ?? reason) : 'no reason recorded';
+                return ` [turned off by the platform: ${words}]`;
+            }
+            case 'removed_by_person':
+                return ' [you deleted its schedule; it stays deleted for this version]';
+            default:
+                break;
+        }
+    }
+    // no trigger to speak for the job: what the platform recorded about it, or that it recorded nothing
+    if (scheduling && scheduling.state !== 'unknown') {
+        return ` [not scheduled: ${scheduling.what}]`;
+    }
+    if (trigger?.state === 'missing') {
+        return scheduling
+            ? ` [not scheduled right now; ${scheduling.what}]`
+            : ' [not scheduled right now]';
+    }
+    if (scheduling && !trigger) {
+        return ` [${scheduling.what}]`;
+    }
+    return '';
+}
+/** The next step for a job whose state has one, as the line under it. */
+function jobNextLine(job) {
+    const scheduling = describeJobScheduling(job.jobState);
+    const stateReason = scheduling && scheduling.state !== 'removed_by_person' ? scheduling : null;
+    if (!stateReason?.next) {
+        return [];
+    }
+    // a live trigger vouches for a job nothing is recorded for
+    const live = job.trigger?.state === 'managed' || job.trigger?.state === 'detached';
+    if (stateReason.state === 'unknown' && live) {
+        return [];
+    }
+    return [`        next: ${stateReason.next.replace(/<installation>/g, '<installation id>')}`];
+}
+function itemLines(item) {
+    switch (item.kind) {
+        case 'store':
+            return item.collections.map((collection) => {
+                // a server that predates `writers` is drawn from `access` alone
+                const summary = collection.writers
+                    ? (0, data_provider_1.appStoreWriterSummary)(collection.writers.map((writer) => writer.kind))
+                    : null;
+                let words = collection.access === 'read_write' ? 'it can read and change it' : 'it can only read it';
+                if (summary) {
+                    words = STORE_WRITER_WORDS[summary];
+                }
+                return `keep its own data in "${collection.name}" (${words})${mark(collection.consent)}`;
+            });
+        case 'query':
+            return item.contracts.map((contract) => `read "${contract.name}" from the platform, as whoever is looking (each person sees only what they may see)${mark(contract.consent)}`);
+        case 'tools':
+            return item.tools.map((tool) => `call the tool "${tool.name}"${tool.connector ? ` (your ${tool.connector} connection)` : ''}${mark(tool.consent)}`);
+        case 'http':
+            return item.origins.map((origin) => `have ${data_provider_1.BRAND.displayName} contact ${origin.origin} for it (the app's page has no network of its own); this stops working if the app's code changes, until you approve again${mark(origin.consent)}`);
+        case 'act':
+            return item.effects.map((effect) => `ask to "${effect.effect}"; it only asks, and a person releases each one under their own name${mark(effect.consent)}`);
+        case 'webhooks':
+            return item.hooks.map((hook) => `let an outside system that holds a secret address add entries to "${hook.collection}" (the hook "${hook.name}"${hook.title ? `, "${hook.title}"` : ''}); entries are only stored there, nothing runs because one arrived${mark(hook.consent)}`);
+        case 'service': {
+            const declaration = item.declaration;
+            const lines = [
+                `run a background program (${declaration.protocol}, ${declaration.liveness.replace(/_/g, ' ')}), ${ISOLATION_WORDS[declaration.isolation] ?? declaration.isolation}; this stops working if the app's code changes, until you approve again${mark(item.consent)}`,
+                `    command: ${declaration.command.join(' ')}`,
+            ];
+            if (declaration.secretNames.length > 0) {
+                lines.push(`    uses secrets named: ${declaration.secretNames.join(', ')} (names only)`);
+            }
+            // the disclosure has no field for either, and a silence here would read as "none": say it is not told
+            lines.push("    what it can reach on the network, and which machine it runs on, are not part of this disclosure (the app's page having no network of its own says nothing about this program)");
+            return lines;
+        }
+        case 'jobs':
+            return [
+                `run these jobs on a schedule, unattended. ${item.statement} That is accepted when you install it, and each job is listed so you can weigh it:`,
+                ...item.jobs.flatMap((job) => [
+                    `    - ${(0, data_provider_1.plainAppLabel)(job.title)} (${job.schedule}): ${describeSchedule(job.schedule)}${job.guide ? `, following ${job.guide}` : ''}${mark(job.consent)}${describeJobState(job)}`,
+                    ...jobNextLine(job),
+                ]),
+                ...(item.notices?.some((notice) => notice.kind === 'trigger_detached')
+                    ? [
+                        '    (a job someone edited in Triggers no longer follows this app: an upgrade will not change it)',
+                    ]
+                    : []),
+            ];
+        default:
+            return [];
+    }
+}
+const REASON_WORDS = {
+    no_grant: 'nothing has been approved yet',
+    capability_added: 'this version asks for something the earlier one did not',
+    capability_expanded: 'this version asks for more than was approved',
+    egress_code_changed: `the app changed, and what it may send out of ${data_provider_1.BRAND.displayName} is approved only for the code you saw`,
+    jobs_changed: 'a job was added or changed',
+    store_writers_expanded: "this version lets something new change the data the app keeps, such as the app's own code",
+};
+/** The words for each reason a grant stopped covering a version; a kind it does not know is said as it came. */
+function describeGrantReasons(kinds) {
+    const words = REASON_WORDS;
+    return kinds.map((kind) => words[kind] ?? kind);
+}
+/**
+ * A disclosure as the lines a person reads before they approve. `null` (a disclosure this CLI cannot read) is
+ * said plainly: "cannot show what you would be approving" is never "nothing to approve".
+ */
+function formatDisclosure(raw, facts) {
+    const disclosure = (0, data_provider_1.parseAppDisclosure)(raw);
+    if (!disclosure) {
+        return [
+            'This disclosure is not in a form this version of the CLI understands, so it cannot show what you would be approving.',
+            'Update the CLI (`skrr update`) and try again.',
+        ];
+    }
+    const lines = [];
+    lines.push(`${disclosure.app.name}${disclosure.bundleHash ? `  (bundle ${disclosure.bundleHash.slice(0, 12)})` : ''}`);
+    if (facts) {
+        // who is asking to be trusted, beside what it asks
+        lines.push(`Version ${facts.version}, published by ${facts.publisher.name ?? 'someone the platform cannot name'}; ${describeTrust(facts.trust)}.`);
+    }
+    if (disclosure.app.description) {
+        lines.push(disclosure.app.description);
+    }
+    if (disclosure.scope) {
+        // WHERE it is installed, and no claim about how far it reaches: the list below says what it can do, and a
+        // sentence that said "nothing else" over a list with jobs, tools and outbound requests would contradict it
+        if (disclosure.scope.principal.kind === 'user') {
+            // an app on a PERSON: say whose it is and what that means in words, and what does not happen for it yet
+            lines.push('Installed on you. It is private to your account: what it keeps is not visible to any other person through it (your own sign-ins, and tools you give your account to, can see it as you can), and what it reads from the platform it reads as you.');
+        }
+        else {
+            lines.push(`Installed on ${disclosure.scope.principal.kind} ${disclosure.scope.principal.id}.`);
+        }
+    }
+    if (disclosure.can.length === 0) {
+        lines.push('It asks for nothing: it can only draw itself.');
+    }
+    else {
+        lines.push('It can:');
+        for (const item of disclosure.can) {
+            const [first, ...rest] = itemLines(item);
+            if (first !== undefined) {
+                lines.push(`  - ${first}`);
+                lines.push(...rest.map((line) => `    ${line.replace(/^ {4}/, '')}`.replace(/^ {4}(?=- )/, '  ')));
+            }
+        }
+    }
+    if (disclosure.consent.status === 'needs_reconsent') {
+        lines.push('Why it needs approving again:');
+        for (const reason of describeGrantReasons(disclosure.consent.reasons.map((r) => r.kind))) {
+            lines.push(`  - ${reason}`);
+        }
+    }
+    else if (disclosure.consent.status === 'valid') {
+        lines.push('What you approved still covers this version.');
+    }
+    lines.push(...describeDisclosureCheck(disclosure.check));
+    return lines;
+}
+// ── where it runs, and what that costs (p2-11, p2-06) ───────────────────────
+/** US dollars, whole when they are whole. Every figure it is given is the server's arithmetic over a rate. */
+function usd(cents) {
+    const dollars = cents / 100;
+    return new Intl.NumberFormat('en-US', {
+        style: 'currency',
+        currency: 'USD',
+        minimumFractionDigits: Number.isInteger(dollars) ? 0 : 2,
+        maximumFractionDigits: 2,
+    }).format(dollars);
+}
+/** Why a computer that said what it can run still cannot run this: what it has, against what the app asks for. */
+const HOST_CAPABILITY_WORDS = {
+    os_unsupported: (required, offered) => `it runs ${offered}; the app needs ${required}`,
+    arch_unsupported: (required, offered) => `it is a ${offered} computer; the app needs ${required}`,
+    runtime_missing: (required, offered) => `the app needs ${required} installed; it has ${offered}`,
+    isolation_insufficient: (required, offered) => `the app asks to be isolated at "${required}"; it offers "${offered}"`,
+    availability_insufficient: (required, offered) => `the app needs a computer that is ${required}; this one is ${offered}`,
+    persistent_fs_missing: () => 'the app keeps files, and it has no storage that survives a restart',
+    ingress_relay_missing: () => 'the app gateway cannot reach it yet; it may need an update',
+    supervision_missing: () => 'it has no way to keep a program running',
+};
+function describeHostUnsuitable(reason) {
+    switch (reason.kind) {
+        case 'not_announced':
+            return 'it has not said what it can run, so the app cannot be placed on it yet';
+        case 'gone':
+            return 'it is being removed, or it is gone';
+        default:
+            return HOST_CAPABILITY_WORDS[reason.code]((0, data_provider_1.plainAppLabel)(reason.required, 80), (0, data_provider_1.plainAppLabel)(reason.offered, 80));
+    }
+}
+/** What an app asked of its Agent, as a phrase. The name is the author's word, reduced to printable text. */
+function describeRequirement(requirement) {
+    const colon = requirement.indexOf(':');
+    const kind = colon === -1 ? '' : requirement.slice(0, colon);
+    const name = (0, data_provider_1.plainAppLabel)(colon === -1 ? requirement : requirement.slice(colon + 1), 80);
+    const nouns = {
+        skill: 'the skill',
+        connector: 'the connection',
+        tool: 'the tool',
+        lineage: 'the Agent line',
+    };
+    return nouns[kind] ? `${nouns[kind]} "${name}"` : name;
+}
+function describeOperatorUnmet(unmet) {
+    const what = describeRequirement(unmet.requirement);
+    return unmet.verdict === 'missing'
+        ? `it does not have ${what}`
+        : `we cannot tell whether it has ${what}`;
+}
+/** What an install was MISSING. The first is the design's sentence: install it on an Agent, or choose one to run it. */
+const BINDING_ISSUE_WORDS = {
+    operator_required: 'This app needs an Agent to run it. Install it on one of your Agents instead, or choose an Agent to run it.',
+    host_machine_required: 'This app needs a computer to run on. Choose one of yours with --host-machine.',
+};
+/**
+ * The choices an install has to settle, as lines. `undefined` is "this app needs no choice" and says nothing; a block this
+ * CLI cannot read is said so, and is never "nothing to choose".
+ */
+function formatBindings(raw) {
+    if (raw === undefined) {
+        return [];
+    }
+    const bindings = (0, data_provider_1.parseAppBindings)(raw);
+    if (!bindings) {
+        return [
+            'This server sent the choices this app needs in a form this version of the CLI does not understand, so it cannot show them. Update the CLI and try again.',
+        ];
+    }
+    const lines = [];
+    if (bindings.needs.operator === 'choose') {
+        lines.push(bindings.role
+            ? `Choose which of your Agents plays "${(0, data_provider_1.plainAppLabel)(bindings.role, 60)}" for this app:`
+            : 'Choose which of your Agents runs this app:');
+        const usable = bindings.operators.filter((entry) => entry.verdict.ok);
+        if (usable.length === 0) {
+            lines.push('  You have no Agent you can use here. Install it on one of your Agents instead.');
+        }
+        for (const entry of usable) {
+            lines.push(`  - ${entry.id}  ${(0, data_provider_1.plainAppLabel)(entry.name, 120)}`);
+        }
+        for (const entry of bindings.operators) {
+            if (!entry.verdict.ok) {
+                lines.push(`  x ${entry.id}  ${(0, data_provider_1.plainAppLabel)(entry.name, 120)}: ${entry.verdict.unmet
+                    .map(describeOperatorUnmet)
+                    .join('; ')}`);
+            }
+        }
+    }
+    if (bindings.needs.hostMachine === 'choose') {
+        lines.push('This app has a background program. Choose which of your computers runs it (--host-machine):');
+        const usable = bindings.machines.filter((entry) => entry.verdict.ok);
+        if (bindings.machines.length === 0) {
+            lines.push('  You do not have a computer to run it on yet. Get one first.');
+        }
+        else if (usable.length === 0) {
+            lines.push('  None of your computers can run this yet.');
+        }
+        for (const entry of usable) {
+            lines.push(`  - ${entry.id}  ${(0, data_provider_1.plainAppLabel)(entry.name, 120) || 'Unnamed computer'}`);
+        }
+        for (const entry of bindings.machines) {
+            if (!entry.verdict.ok) {
+                lines.push(`  x ${entry.id}  ${(0, data_provider_1.plainAppLabel)(entry.name, 120) || 'Unnamed computer'}: ${entry.verdict.reasons
+                    .map(describeHostUnsuitable)
+                    .join('; ')}`);
+            }
+        }
+    }
+    if (bindings.truncated) {
+        lines.push('  (This list may be incomplete.)');
+    }
+    return lines;
+}
+const COST_ADDED_WORDS = {
+    nothing: ({ machine }) => `${machine} is set to stay on, so it already runs all month. This app adds no compute charge.`,
+    keeps_on: ({ monthlyCents }) => `This app needs the computer on all the time, so it keeps it running: about ${usd(monthlyCents ?? 0)} a month.`,
+    usage_example: ({ monthlyCents, usageHoursPerDay, idleTailMinutes }) => `For example, if you use it about ${usageHoursPerDay} hours a day and the computer stays on ${idleTailMinutes} minutes after you stop, that comes to about ${usd(monthlyCents ?? 0)} a month.`,
+    by_the_hour: () => 'How much it adds depends on how often and for how long the computer runs for it, so no monthly figure is given.',
+};
+/**
+ * What the app's service would cost, as lines. Every figure is the server's arithmetic over the computer's rate; nothing
+ * here is an amount written in advance, and a state without a number says why and is never zero. `undefined` is "this app
+ * has no service" and says nothing.
+ */
+function formatHosting(raw) {
+    if (raw === undefined) {
+        return [];
+    }
+    const cost = (0, data_provider_1.parseAppServiceCost)(raw);
+    if (!cost) {
+        return ['What running it costs: this CLI could not read the estimate, so it shows none.'];
+    }
+    switch (cost.state) {
+        case 'needs_machine':
+            return [
+                'What running it costs: this app runs a program on a computer, and you do not have one that can run apps yet. What it costs depends on that computer, so no figure is given.',
+            ];
+        case 'select_machine':
+            return [
+                'What running it costs: choose the computer it will run on (--host-machine) to see what it would bill.',
+            ];
+        case 'unpriced':
+            return [
+                `What running it costs: ${(0, data_provider_1.plainAppLabel)(cost.machine.name, 120) || 'that computer'} has no price on record, so what this would cost is not known. Nothing is assumed.`,
+            ];
+        case 'unknown':
+            return [
+                'What running it costs: we could not work out what this would cost. The computer bills by the hour it is running.',
+            ];
+        default: {
+            const machine = (0, data_provider_1.plainAppLabel)(cost.machine.name, 120) || 'The computer';
+            const added = cost.added;
+            return [
+                'What running it costs:',
+                `  ${machine} bills ${usd(cost.rateCentsPerHour)} for each hour it is running.`,
+                ...(cost.rateSource === 'admitted'
+                    ? [
+                        `  That is the rate it was started at; the current price list does not name one for it.`,
+                    ]
+                    : []),
+                `  If it never stopped, that would come to about ${usd(cost.ceilingMonthlyCents)} in a ${cost.hoursPerMonth}-hour month.`,
+                `  ${COST_ADDED_WORDS[added.basis]({
+                    machine,
+                    ...('monthlyCents' in added ? { monthlyCents: added.monthlyCents } : {}),
+                    ...('usageHoursPerDay' in added
+                        ? { usageHoursPerDay: added.usageHoursPerDay, idleTailMinutes: added.idleTailMinutes }
+                        : {}),
+                })}`,
+                cost.payer
+                    ? `  These hours are billed to ${cost.payer.kind === 'workspace' ? 'your workspace' : 'you'}, apart from the app's own price.`
+                    : '  Who these hours are billed to could not be read.',
+                "  These figures come from today's prices and your computer's settings. They are estimates, not a promise.",
+            ];
+        }
+    }
+}
+/** The words for a `binding_required` refusal: what was missing, and why what was given would not do. */
+function describeBindingRefusal(refusal) {
+    const lines = [];
+    const issues = Array.isArray(refusal.issues) ? refusal.issues : [];
+    const words = BINDING_ISSUE_WORDS;
+    for (const issue of issues) {
+        if (typeof issue === 'string' && words[issue]) {
+            lines.push(words[issue]);
+        }
+    }
+    const unsuitable = (0, data_provider_1.parseAppBindingUnsuitable)(refusal.unsuitable);
+    if (unsuitable?.operator === 'not_found') {
+        lines.push('That Agent could not be used: it was not found, or you cannot edit it.');
+    }
+    else if (unsuitable?.operator) {
+        lines.push(`That Agent will not do: ${unsuitable.operator.map(describeOperatorUnmet).join('; ')}.`);
+    }
+    if (unsuitable?.hostMachine === 'not_found') {
+        lines.push('That computer could not be used: it was not found, or it is not yours.');
+    }
+    else if (unsuitable?.hostMachine) {
+        lines.push(`That computer will not do: ${unsuitable.hostMachine.map(describeHostUnsuitable).join('; ')}.`);
+    }
+    return lines.length > 0
+        ? lines.join('\n')
+        : 'This app needs something the installation did not bind (an operator agent or a host machine).';
+}
+const CHECK_OUTCOME_WORDS = {
+    blocked_for_store: 'found something that keeps this version out of the store',
+    cannot_analyze: 'could not read part of it, so it could not check that part',
+    findings: 'found things to look at',
+    nothing_found: 'found nothing it looks for',
+};
+const LIMITS_REMINDER = 'That is not a statement that the app is safe, and no person reviews an app.';
+/**
+ * What the automatic check recorded for this version, in lines. It is never a verdict of "safe", and the three states
+ * a surface must keep apart are kept apart: a result, no result on record (the version predates the check), and a
+ * result stored in a form this CLI cannot read. A server that did not send the section at all is a fourth, said as such.
+ * None of the last three is ever drawn as "nothing found".
+ */
+function describeDisclosureCheck(check) {
+    if (check === undefined) {
+        return ['Automatic check: this server did not say what it found. That is not a clean result.'];
+    }
+    if (!check.recorded) {
+        return check.reason === 'unreadable'
+            ? [
+                'Automatic check: a result is stored for this version but this CLI cannot read it. That is not a clean result.',
+            ]
+            : [
+                'Automatic check: none is on record for this version (it was cut before the check was recorded). That is not a clean result.',
+            ];
+    }
+    const { summary } = check;
+    const { counts } = summary;
+    const lines = [
+        `Automatic check: ${CHECK_OUTCOME_WORDS[summary.outcome] ?? summary.outcome}. ${LIMITS_REMINDER}`,
+    ];
+    if (counts.block + counts.warn + counts.info + counts.unanalyzable > 0) {
+        lines.push(`  ${counts.block} would keep it out of the store, ${counts.warn} to read, ${counts.info} low-key, ${counts.unanalyzable} could not be read`);
+    }
+    for (const found of summary.findings.slice(0, 5)) {
+        const title = summary.rules[found.rule]?.title ?? found.rule;
+        const place = found.path ? ` (${found.line ? `${found.path}:${found.line}` : found.path})` : '';
+        lines.push(`  - ${(0, data_provider_1.plainAppLabel)(title, 160)}${place}`);
+    }
+    const more = summary.findings.length - 5 + summary.omitted;
+    if (more > 0) {
+        lines.push(`  - and ${more} more (run \`apps check\` on the app for all of them)`);
+    }
+    lines.push(`  ${summary.limitations.headline}`);
+    return lines;
+}
+class InstallTargetError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = 'InstallTargetError';
+        this.code = code;
+    }
+}
+exports.InstallTargetError = InstallTargetError;
+/**
+ * The version an install points at, and the bundle the person is about to be shown. With `--version` that
+ * version (and it must belong to the app); without it the app's newest. The server decides whether it is
+ * installable (a rejected or delisted version, a beta for a channel that does not see them): this does not
+ * guess at that vocabulary, it lets the refusal say it.
+ */
+async function resolveInstallTarget(input) {
+    if (input.versionId) {
+        let detail;
+        try {
+            detail = await data_provider_1.dataService.getAppVersion(input.versionId);
+        }
+        catch (error) {
+            if (error?.status === 404) {
+                throw new InstallTargetError('version_not_found', `There is no version ${input.versionId} that you can use.`);
+            }
+            throw error;
+        }
+        if (detail.version.appId !== input.appId) {
+            throw new InstallTargetError('wrong_app', `${input.versionId} is a version of another app (${detail.version.appId}), not ${input.appId}.`);
+        }
+        return {
+            appId: input.appId,
+            versionId: detail.version.id,
+            bundleHash: detail.version.bundleHash,
+            version: detail.version.version,
+        };
+    }
+    const { versions } = await data_provider_1.dataService.listAppVersions({ appId: input.appId });
+    const newest = [...versions].sort((a, b) => b.version - a.version)[0];
+    if (!newest) {
+        throw new InstallTargetError('no_versions', `${input.appId} has no version yet. Cut one with \`apps version create\`.`);
+    }
+    return {
+        appId: input.appId,
+        versionId: newest.id,
+        bundleHash: newest.bundleHash,
+        version: newest.version,
+    };
+}
+// ── a refusal, in words ─────────────────────────────────────────────────────
+const FORBIDDEN_REASON_WORDS = {
+    missing_permission: 'You need edit access to that agent to do this.',
+    human_only: 'Only a person can do this, not an agent.',
+    not_decided: 'This is not something an agent may do (the platform has not decided to allow it), and it is not something this command can do for you.',
+    app_is_not_a_principal: 'An app cannot do this to itself.',
+    unknown_actor: 'The platform could not tell who is asking.',
+    // the installation was suspended by the platform, not by the person: resuming it is not theirs to do
+    suspended_by_moderation: 'The platform suspended this app, not you, and only the platform can lift that. There is nothing to resume from here.',
+};
+/**
+ * Every reason an installation call is refused, with the sentence and the next step. A `Record` over the
+ * contract's list, so a reason added there does not compile here until it has words.
+ */
+const CONFLICT_WORDS = {
+    invalid_input: () => 'The request was not understood. Check the ids and try again.',
+    principal_kind_not_enabled: () => 'Apps can be installed on an agent or on yourself today; installing on a space is not available yet.',
+    principal_not_found: () => 'There is no such agent that you can see (and an app on a person can be put there only by that person). Check the id (and that you have access to it).',
+    forbidden: (refusal) => FORBIDDEN_REASON_WORDS[refusal.reason ?? ''] ?? 'You may not do this.',
+    app_not_found: () => 'There is no such app that you can use. Check the id, or ask its owner to share it.',
+    version_not_found: () => 'There is no such version of that app that you can use.',
+    version_not_installable: (_refusal, bin) => `That version cannot be installed (it was withdrawn, replaced, or is a beta your update channel does not see). Name another with --version, or list them with \`${bin} apps versions\`.`,
+    manifest_invalid: () => "That version's manifest is not one this platform will run, so it was not installed.",
+    consent_mismatch: (_refusal, bin) => `The bundle you were shown is not the one on record for that version. Nothing was installed. Run \`${bin} apps disclosure\` again and approve what it shows.`,
+    version_changed: (refusal, bin) => `The installation moved to another version while you were deciding${refusal.current ? ` (now ${refusal.current.versionId})` : ''}. Nothing was changed. Read \`${bin} apps disclosure\` again and approve what it shows.`,
+    invalid_update_policy: () => 'That update policy is not one of manual, auto_minor or beta.',
+    binding_required: (refusal) => describeBindingRefusal(refusal),
+    already_installed: (refusal, bin) => `That app is already installed on this agent${refusal.installationId ? ` (${refusal.installationId})` : ''}. Move it to a newer version with \`${bin} apps upgrade\`.`,
+    not_found: () => 'There is no such installation that you can see.',
+    changed: (_refusal, bin) => `The installation changed while this was running. Nothing was written. Read it again with \`${bin} apps installations show\` and retry.`,
+    not_auto_updatable: () => 'That installation does not update on its own.',
+    data_deletion_not_confirmed: (refusal) => `Removing this app also deletes its data (${refusal.docCount ?? 'some'} document${refusal.docCount === 1 ? '' : 's'}), which is yours to confirm. Nothing was removed. Say it, with --delete-data, if you mean it.`,
+    installation_incomplete: () => 'This installation points at a version that can no longer be read. It can be removed, not run.',
+    principal_scope_unserved: (refusal) => `This app asks for ${describeScopeIssues(refusal.unserved)}, which cannot work for the place it would be installed (an app installed on a person reaches that person's own data, never an agent's or a space's, and has no agent to run it yet).${needsOperator(refusal.unserved)
+        ? ' An app that needs an agent to run it can, for now, only be installed on one of your agents.'
+        : ''} Nothing was installed.`,
+    job_schedule_invalid: (refusal, bin) => {
+        const issues = Array.isArray(refusal.issues)
+            ? refusal.issues.length
+            : 0;
+        return `${issues > 0 ? `${issues} of this app's scheduled jobs have` : 'A scheduled job has'} a schedule that runs more often than allowed (at most once a minute) or cannot be read. Nothing was installed. Check it with \`${bin} apps check\`.`;
+    },
+};
+/** The sentence for a refusal the server made on an installation call, or null for one that is not. */
+function describeInstallationConflict(refusal, bin) {
+    if (!(0, data_provider_1.isAppInstallationConflict)(refusal.error)) {
+        return null;
+    }
+    return CONFLICT_WORDS[refusal.error](refusal, bin);
+}
+/** The machine code of every installation refusal: `APP_<REASON>`. */
+exports.ALL_INSTALLATION_REFUSAL_CODES = Object.fromEntries(Object.keys(CONFLICT_WORDS).map((conflict) => [conflict, `APP_${conflict.toUpperCase()}`]));
+/**
+ * `not_found` and `forbidden` are ALSO what the authoring loop says (`APP_AUTHORING_REFUSALS`), about an app
+ * and not an installation, and the generic handler words them for every other command. So the authoring
+ * commands' map gets only the reasons that are an installation's alone, and the installation commands read the
+ * whole of {@link ALL_INSTALLATION_REFUSAL_CODES} themselves (`AppsCommand.failInstallation`).
+ */
+const SHARED_WITH_AUTHORING = ['not_found', 'forbidden'];
+exports.INSTALLATION_REFUSAL_CODES = Object.fromEntries(Object.entries(exports.ALL_INSTALLATION_REFUSAL_CODES).filter(([conflict]) => SHARED_WITH_AUTHORING.indexOf(conflict) === -1));
+// ── an app on a person (p2-10) ──────────────────────────────────────────────
+/** What an item a principal cannot serve is called in a sentence, by kind (a `Record`: a new kind does not compile without words). */
+const SCOPE_ISSUE_PHRASE = {
+    query: (name) => `the read "${name}"`,
+    tools: (name) => `the tool "${name}"`,
+    operator: () => 'an agent to run it',
+};
+/** The same, as a line of the disclosure preview. */
+const SCOPE_ISSUE_LINE = {
+    query: (name) => `reads ${name}`,
+    tools: (name) => `tool ${name}`,
+    operator: () => 'needs an agent to run it: for now install it on one of your agents instead',
+};
+/** Does the refusal name the Agent that runs the app (`requires.agent`) among what a person's install cannot serve? */
+function needsOperator(raw) {
+    return ((0, data_provider_1.parseAppPrincipalScopeIssues)(raw) ?? []).some((issue) => issue.capability === 'operator');
+}
+/** The items an app declares that its principal cannot serve, as one phrase; "something it declares" when unreadable. */
+function describeScopeIssues(raw) {
+    const issues = (0, data_provider_1.parseAppPrincipalScopeIssues)(raw);
+    if (issues === null || issues.length === 0) {
+        return 'something it declares';
+    }
+    return issues.map((issue) => SCOPE_ISSUE_PHRASE[issue.capability](issue.name)).join(', ');
+}
+/** The lines the disclosure preview adds when the app cannot be installed on the principal asked about. Empty for none. */
+function formatScopeIssues(raw) {
+    if (raw === undefined) {
+        return [];
+    }
+    const issues = (0, data_provider_1.parseAppPrincipalScopeIssues)(raw);
+    if (issues === null) {
+        return [
+            'This app declares something that cannot work for the place it would be installed, and this version of the CLI cannot say what. It would be refused.',
+        ];
+    }
+    return [
+        'It cannot be installed there, because it declares what an app installed on a person cannot use:',
+        ...issues.map((issue) => `  - ${SCOPE_ISSUE_LINE[issue.capability](issue.name)}`),
+    ];
+}
+/**
+ * Where an install points: one of the person's agents, or the person themself. `me` is the signed-in person's own id,
+ * which the server compares with the request's user (a stranger's id is refused as not found), so naming it here is
+ * not a claim the server takes on trust.
+ */
+async function resolveInstallPrincipal(input) {
+    if (input.me) {
+        const user = await data_provider_1.dataService.getUser();
+        return { kind: 'user', id: String(user.id) };
+    }
+    return { kind: 'agent', id: String(input.agent) };
+}
+/** A layout read, in lines: the revision to name when writing, then the top-level order and each folder. */
+function formatUserLayout(raw) {
+    const read = (0, data_provider_1.parseAppUserLayoutRead)(raw);
+    if (read === null) {
+        return [
+            'This layout is not in a form this version of the CLI understands, so it is not shown (and will not be written over).',
+        ];
+    }
+    const lines = [
+        read.rev === 0
+            ? 'Nothing arranged yet (revision 0): your apps are shown in the order they were installed.'
+            : `Revision ${read.rev}.`,
+    ];
+    lines.push(read.layout.order.length === 0 ? 'Order: (none)' : `Order: ${read.layout.order.join(', ')}`);
+    for (const folder of read.layout.folders) {
+        lines.push(`Folder ${folder.id} "${(0, data_provider_1.plainAppLabel)(folder.name)}": ${folder.items.join(', ') || '(empty)'}`);
+    }
+    return lines;
+}
+/** Read a layout refusal out of an API error, or null when the error is not one the layout route made. */
+function readLayoutRefusal(error) {
+    const e = error;
+    if (!e || typeof e.body !== 'string') {
+        return null;
+    }
+    try {
+        const body = JSON.parse(e.body);
+        if (!body || typeof body !== 'object' || typeof body.error !== 'string') {
+            return null;
+        }
+        return {
+            ...(typeof e.status === 'number' ? { status: e.status } : {}),
+            error: body.error,
+            ...(typeof body.currentRev === 'number' ? { currentRev: body.currentRev } : {}),
+            ...(typeof body.issue === 'string' ? { issue: body.issue } : {}),
+        };
+    }
+    catch {
+        return null;
+    }
+}
+// ── a report that was not taken, in words (p3-04) ───────────────────────────
+/**
+ * Every reason a report on an installed app is refused, with the sentence and the next step. A `Record` over
+ * the contract's list, so a reason added there does not compile here until it has words. `invalid_input`,
+ * `forbidden` and `not_found` are ALSO installation refusals and read the same words there.
+ */
+const REPORT_REFUSAL_WORDS = {
+    invalid_input: () => 'The request was not understood. Check the installation id and the flags.',
+    invalid_reason: () => `That reason is not one the Store takes. Use one of: ${data_provider_1.STORE_REPORT_REASONS.map((entry) => entry.value).join(', ')}.`,
+    description_required: () => 'A security report needs --description, so that whoever reads it can reproduce the problem. Nothing was sent.',
+    forbidden: (refusal) => FORBIDDEN_REASON_WORDS[refusal.reason ?? ''] ?? 'You may not report this app.',
+    not_found: () => 'There is no such installation that you can see.',
+    version_not_installed: () => 'You can only report the version this installation runs. Leave --version out, or name that one.',
+    already_reported: (_refusal, bin) => `You have already reported this version of the app. A second report on the same version is not taken. Follow the first with \`${bin} store reports\`.`,
+    security_report_open: (_refusal, bin) => `You already have a security report open for this app, and it has not been looked at yet. Follow it with \`${bin} store reports\`.`,
+};
+/** The reasons a report is refused that no installation call is refused for. */
+const REPORT_ONLY_REFUSALS = [
+    'invalid_reason',
+    'description_required',
+    'version_not_installed',
+    'already_reported',
+    'security_report_open',
+];
+/** The machine code of a report refusal that is the report's alone: `APP_REPORT_<REASON>`. */
+exports.REPORT_REFUSAL_CODES = Object.fromEntries(data_provider_1.APP_REPORT_REFUSALS.filter((reason) => REPORT_ONLY_REFUSALS.indexOf(reason) !== -1).map((reason) => [reason, `APP_REPORT_${reason.toUpperCase()}`]));
+/** The sentence for a refusal the server made on a report, or null for one that is not the report's alone. */
+function describeReportRefusal(refusal, bin) {
+    const code = refusal.error ?? '';
+    if (REPORT_ONLY_REFUSALS.indexOf(code) === -1) {
+        return null;
+    }
+    return REPORT_REFUSAL_WORDS[code](refusal, bin);
+}
+/** The exit of a refusal that says "that is not there for you": the same one an unknown app gets. */
+function installationRefusalExit(conflict) {
+    return ['not_found', 'principal_not_found', 'app_not_found', 'version_not_found'].indexOf(conflict) === -1
+        ? 1
+        : 4;
+}