@skrr-ai/cli 0.1.109 → 0.1.111

package/dist/lib/agentic-stream.js

@@ -242,16 +242,25 @@ function describePermission(event) {
  * word.SECOND" as its answer, and `run.result.text` kept it, because the
  * stream then held the final result as a suffix and the longer text won.
  */
-function envelopesText(event) {
+function envelopesText(event, joiner = (0, data_provider_1.createAssistantTextJoiner)(), accumulated = '') {
     const envelopes = event.envelopes;
     if (!Array.isArray(envelopes))
         return '';
     let out = '';
     for (const envelope of envelopes) {
+        // A tool call ends the agent's text block: the run that resumes after it starts on
+        // its own paragraph, exactly as the stored message has it (OSK-16934). The rule is
+        // the shared one (`assistantTextJoin`, `@skrr-ai/data-provider`); this fold used to
+        // append the runs with nothing between them, so `run.result.text` read
+        // `...in sequence.**Command 1**` and a widget block that opened right after a tool
+        // call read `Ready::::skrr-ui{...`, an opener mid-line that the grammar (and so
+        // `widgetsAsText`) does not recognise, printing the whole raw block.
+        joiner.note(envelope);
         const ev = envelope
             ?.ev;
         if (ev && ev.t === 'text' && ev.thinking !== true && typeof ev.text === 'string') {
-            out += ev.text;
+            // Only the last character of the text so far is read.
+            out += joiner.join(ev.text, out ? out.slice(-1) : accumulated.slice(-1));
         }
     }
     return out;
@@ -713,6 +722,12 @@ function describeRunPermission(event) {
         : '';
     return `${mode} (from ${from})${coerced}`;
 }
+/** `tail` is the end of `whole`, whitespace aside. */
+function endsWithIgnoringWhitespace(whole, tail) {
+    const solid = (value) => value.replace(/\s+/g, '');
+    const wanted = solid(tail);
+    return wanted.length > 0 && solid(whole).endsWith(wanted);
+}
 class AgenticStreamClient {
     options;
     socket = null;
@@ -721,6 +736,8 @@ class AgenticStreamClient {
     settled = false;
     closed = false;
     accumulated = '';
+    /** Where a tool call fell in the envelopes folded into `accumulated` (OSK-16934). */
+    textJoiner = (0, data_provider_1.createAssistantTextJoiner)();
     /** Highest envelope `__seq` folded into `accumulated`, for gap detection. */
     highestSeq = 0;
     pendingEnvelopes = new Map();
@@ -1448,7 +1465,7 @@ class AgenticStreamClient {
                 fresh.some((env) => env?.ev?.t === 'turn-end')) {
                 this.requestHandoverRead();
             }
-            const envelopeText = envelopesText(scoped);
+            const envelopeText = envelopesText(scoped, this.textJoiner, this.accumulated);
             if (envelopeText) {
                 this.accumulated += envelopeText;
                 this.emit({ ...scoped, type: 'text.delta', text: this.answerText() });
@@ -1557,6 +1574,7 @@ class AgenticStreamClient {
             if (!match(event))
                 return;
             this.accumulated = '';
+            this.textJoiner.reset();
             this.renderedText = '';
             // Seqs restart with the stream, so a fresh low seq is not a gap.
             this.highestSeq = 0;
@@ -2140,9 +2158,16 @@ class AgenticStreamClient {
         // the two when one contains the other is right for both defects: the
         // truncated-stream case (result longer) and the last-block case
         // (accumulation longer).
+        //
+        // Compared without whitespace: the join across a tool call puts a paragraph break
+        // INSIDE a run that begins with its own whitespace (`' ::::skrr-ui{'` arrives as
+        // `' \n\n::::skrr-ui{'`), so the harness's last block is not a byte-for-byte suffix of the
+        // accumulation even though it is its tail, and taking it as the answer would drop
+        // everything the agent said before the tool call (OSK-16934).
         const accumulationIsSuperset = finalText.length > 0 &&
             this.accumulated.length > finalText.length &&
-            this.accumulated.endsWith(finalText);
+            (this.accumulated.endsWith(finalText) ||
+                endsWithIgnoringWhitespace(this.accumulated, finalText));
         if (finalText && finalText !== this.accumulated && !accumulationIsSuperset) {
             this.accumulated = finalText;
         }

package/dist/lib/appData.d.ts

@@ -0,0 +1,75 @@
+import type { AppPersonDataRefusal, AppStoreConflict, AppStoreDocView, AppStoreQueryResult } from '@skrr-ai/data-provider';
+/** Why the input could not be used; never carries what was in it. */
+export declare class AppDataInputError extends Error {
+    readonly code: 'APP_DATA_SOURCE' | 'APP_DATA_NOT_JSON' | 'APP_DATA_NOT_OBJECT' | 'APP_DATA_WHERE';
+    constructor(code: 'APP_DATA_SOURCE' | 'APP_DATA_NOT_JSON' | 'APP_DATA_NOT_OBJECT' | 'APP_DATA_WHERE', message: string);
+}
+/**
+ * The document the person gave, from exactly one of `--doc`, `--from-file` and `--stdin`. A file is read the way the
+ * authoring commands read one (a symbolic link is refused, never followed). The error names the problem and never
+ * quotes the input, which may be anything.
+ */
+export declare function readDocumentInput(input: {
+    doc?: string;
+    fromFile?: string;
+    stdin?: boolean;
+}): Promise<Record<string, unknown>>;
+/** The `--where` of a read: a JSON object. What it may hold is the server's parser's to say, once, for every client. */
+export declare function readWhereInput(text: string): Record<string, string | number | boolean | null>;
+export type PersonDataFailure = {
+    kind: 'refusal';
+    code: AppPersonDataRefusal;
+    status?: number;
+    message?: string;
+    retryAfterMs?: number;
+} | {
+    kind: 'conflict';
+    conflict: AppStoreConflict;
+    status?: number;
+    currentRev?: number;
+};
+/**
+ * What the person channel answered, read out of an API error: a refusal (`{ error, code, message }`, the code from
+ * the contract's closed set) or a conflict (`409 { error: "conflict", conflict, currentRev? }`). `null` for anything
+ * else (a network failure, an HTML error page, another route's refusal), which the base command says.
+ */
+export declare function readPersonDataFailure(error: unknown): PersonDataFailure | null;
+/** The machine code each refusal exits under; a `Record` over the contract's list, so a new member needs one. */
+export declare const PERSON_DATA_REFUSAL_CODES: Record<AppPersonDataRefusal, string>;
+/** The machine code of a conflict. `not_found` here is "there is no such DOCUMENT", not "no such installation". */
+export declare const PERSON_DATA_CONFLICT_CODES: Record<AppStoreConflict, string>;
+/** A refusal that says "that is not there for you" exits as an unknown app does; the rest exit 1. */
+export declare function personDataFailureExit(failure: PersonDataFailure): number;
+/** Can the same call work a moment later? A busy server and a rate limit can; the rest need something changed. */
+export declare function personDataFailureRetryable(failure: PersonDataFailure): boolean;
+/** The words for a refusal. The server's own sentence, when it sent one, is added after ours and never replaces it. */
+export declare function describePersonDataRefusal(failure: Extract<PersonDataFailure, {
+    kind: 'refusal';
+}>, bin: string): string;
+/**
+ * What a conflict means and what to do. A conflict is an ANSWER: someone (the app's window, an Agent, another person)
+ * wrote the document first, so read it again, merge, and retry with the revision it is at now. Nothing was written.
+ */
+export declare function describePersonDataConflict(failure: Extract<PersonDataFailure, {
+    kind: 'conflict';
+}>, target: {
+    installation: string;
+    collection: string;
+    id: string;
+}, bin: string): string;
+/**
+ * Text that came from an app's data, safe to print: a control character, a C1 control, a line or paragraph separator,
+ * a bidirectional override and a character that draws nothing (a zero-width character, a variation selector, a Unicode tag character:
+ * text a person cannot see) are written as a visible `\uXXXX` and everything else is left alone. `JSON.stringify`
+ * already escapes everything below U+0020, but not these.
+ */
+export declare function safeForTerminal(text: string): string;
+/** One document as two lines: where it stands, and its content as compact JSON (cut where it would flood a terminal). */
+export declare function formatDocument(doc: AppStoreDocView): string[];
+/** A page of documents, in lines; an empty page says so, and a page that ends early says how to ask for the rest. */
+export declare function formatQueryResult(result: AppStoreQueryResult, target: {
+    installation: string;
+    collection: string;
+}, bin: string): string[];
+/** The limit the reference and this help text share, so a number is never typed twice. */
+export declare const PERSON_DATA_QUERY_LIMIT_MAX: 200;

package/dist/lib/appData.js

@@ -0,0 +1,274 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PERSON_DATA_QUERY_LIMIT_MAX = exports.PERSON_DATA_CONFLICT_CODES = exports.PERSON_DATA_REFUSAL_CODES = exports.AppDataInputError = void 0;
+exports.readDocumentInput = readDocumentInput;
+exports.readWhereInput = readWhereInput;
+exports.readPersonDataFailure = readPersonDataFailure;
+exports.personDataFailureExit = personDataFailureExit;
+exports.personDataFailureRetryable = personDataFailureRetryable;
+exports.describePersonDataRefusal = describePersonDataRefusal;
+exports.describePersonDataConflict = describePersonDataConflict;
+exports.safeForTerminal = safeForTerminal;
+exports.formatDocument = formatDocument;
+exports.formatQueryResult = formatQueryResult;
+/**
+ * `skrr apps data put | query`: what the commands that write and read an installed app's OWN documents, as the
+ * signed-in person, share. The domain lib of the person channel; the authoring loop's is `lib/apps.ts` and the
+ * installation commands' `lib/appInstallations.ts`.
+ *
+ * It builds no URL. Every call is a `dataService` function (`@skrr-ai/data-provider`: `putAppInstallationData`,
+ * `queryAppInstallationData`), which is what keeps this CLI and any other client on one route (and what
+ * `domain-api-parity.spec.ts` checks). What lives here is what a terminal needs around it:
+ *
+ *  - where a document comes from (`--doc`, `--from-file`, `--stdin`: exactly one) and that it is a JSON OBJECT, said
+ *    before anything is sent;
+ *  - the `where` of a read, a JSON object of equalities on top-level fields (the store's own rule, refused by the
+ *    server's parser if it is more);
+ *  - what a refusal means in words, keyed by the contract's whole vocabulary (`APP_PERSON_DATA_REFUSALS`), and what a
+ *    conflict (someone wrote first) means and the revision to retry from: an answer, never an error;
+ *  - a document drawn for a terminal: its content is whatever the app's window, a webhook, an Agent or a person
+ *    wrote, so it is DATA, and nothing a terminal would act on is printed raw (control characters, escapes and
+ *    bidirectional overrides are written out as `\uXXXX`).
+ *
+ * NEVER PRINTED: who wrote a row. The server returns the KIND of writer (`app`, `agent`, `person`) and never an id.
+ */
+const data_provider_1 = require("@skrr-ai/data-provider");
+const appsFs_1 = require("./appsFs");
+// ── what a document is, and where it comes from ─────────────────────────────
+/** Why the input could not be used; never carries what was in it. */
+class AppDataInputError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = 'AppDataInputError';
+    }
+}
+exports.AppDataInputError = AppDataInputError;
+/** `{ ... }` and not a list, a string, a number or null: the store holds objects. */
+function asPlainObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value)
+        ? value
+        : null;
+}
+/**
+ * The document the person gave, from exactly one of `--doc`, `--from-file` and `--stdin`. A file is read the way the
+ * authoring commands read one (a symbolic link is refused, never followed). The error names the problem and never
+ * quotes the input, which may be anything.
+ */
+async function readDocumentInput(input) {
+    const given = [input.doc !== undefined, input.fromFile !== undefined, input.stdin === true];
+    if (given.filter(Boolean).length !== 1) {
+        throw new AppDataInputError('APP_DATA_SOURCE', 'Give the document with exactly one of --doc, --from-file or --stdin.');
+    }
+    let text;
+    if (input.doc !== undefined) {
+        text = input.doc;
+    }
+    else if (input.fromFile !== undefined) {
+        text = (0, appsFs_1.readRegularTextFile)(input.fromFile, input.fromFile);
+    }
+    else {
+        text = await (0, appsFs_1.readStdinText)();
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        throw new AppDataInputError('APP_DATA_NOT_JSON', 'The document is not JSON.');
+    }
+    const object = asPlainObject(parsed);
+    if (!object) {
+        throw new AppDataInputError('APP_DATA_NOT_OBJECT', 'The document must be a JSON object ({ ... }), not a list, a text, a number or null.');
+    }
+    return object;
+}
+/** The `--where` of a read: a JSON object. What it may hold is the server's parser's to say, once, for every client. */
+function readWhereInput(text) {
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        throw new AppDataInputError('APP_DATA_WHERE', '--where must be a JSON object of equalities on top-level fields, for example \'{"status":"open"}\'.');
+    }
+    const object = asPlainObject(parsed);
+    if (!object) {
+        throw new AppDataInputError('APP_DATA_WHERE', '--where must be a JSON object of equalities on top-level fields, for example \'{"status":"open"}\'.');
+    }
+    return object;
+}
+/**
+ * What the person channel answered, read out of an API error: a refusal (`{ error, code, message }`, the code from
+ * the contract's closed set) or a conflict (`409 { error: "conflict", conflict, currentRev? }`). `null` for anything
+ * else (a network failure, an HTML error page, another route's refusal), which the base command says.
+ */
+function readPersonDataFailure(error) {
+    const e = error;
+    if (!e || typeof e.body !== 'string') {
+        return null;
+    }
+    let body;
+    try {
+        const parsed = JSON.parse(e.body);
+        const object = asPlainObject(parsed);
+        if (!object) {
+            return null;
+        }
+        body = object;
+    }
+    catch {
+        return null;
+    }
+    const status = typeof e.status === 'number' ? { status: e.status } : {};
+    if (body.code === 'conflict') {
+        const conflict = data_provider_1.APP_STORE_CONFLICTS.includes(body.conflict)
+            ? body.conflict
+            : null;
+        return conflict === null
+            ? null
+            : {
+                kind: 'conflict',
+                conflict,
+                ...status,
+                ...(typeof body.currentRev === 'number' ? { currentRev: body.currentRev } : {}),
+            };
+    }
+    const code = data_provider_1.APP_PERSON_DATA_REFUSALS.includes(body.code)
+        ? body.code
+        : null;
+    if (code === null) {
+        return null;
+    }
+    return {
+        kind: 'refusal',
+        code,
+        ...status,
+        ...(typeof body.message === 'string' ? { message: body.message } : {}),
+        ...(typeof body.retryAfterMs === 'number' ? { retryAfterMs: body.retryAfterMs } : {}),
+    };
+}
+/** The machine code each refusal exits under; a `Record` over the contract's list, so a new member needs one. */
+exports.PERSON_DATA_REFUSAL_CODES = {
+    human_only: 'APP_DATA_HUMAN_ONLY',
+    not_found: 'APP_DATA_NOT_FOUND',
+    not_granted: 'APP_DATA_NOT_GRANTED',
+    forbidden_by_viewer: 'APP_DATA_FORBIDDEN',
+    grant_stale: 'APP_DATA_GRANT_STALE',
+    schema: 'APP_DATA_INVALID',
+    quota: 'APP_DATA_QUOTA',
+    rate: 'APP_DATA_RATE',
+    unavailable: 'APP_DATA_UNAVAILABLE',
+};
+/** The machine code of a conflict. `not_found` here is "there is no such DOCUMENT", not "no such installation". */
+exports.PERSON_DATA_CONFLICT_CODES = {
+    rev_mismatch: 'APP_DATA_REV_MISMATCH',
+    exists: 'APP_DATA_EXISTS',
+    not_found: 'APP_DATA_DOC_NOT_FOUND',
+};
+/** A refusal that says "that is not there for you" exits as an unknown app does; the rest exit 1. */
+function personDataFailureExit(failure) {
+    return failure.kind === 'refusal' && failure.code === 'not_found' ? 4 : 1;
+}
+/** Can the same call work a moment later? A busy server and a rate limit can; the rest need something changed. */
+function personDataFailureRetryable(failure) {
+    return failure.kind === 'refusal' && (failure.code === 'rate' || failure.code === 'unavailable');
+}
+const REFUSAL_WORDS = {
+    human_only: (bin) => `Only a signed-in person can write an app's data this way. This credential is not one (an agent's, a workload's or an access token). Sign in as yourself with \`${bin} login\`.`,
+    not_found: () => 'There is no such installation that you can see.',
+    not_granted: () => 'A person may not write this collection here. The running version must list it in capabilities.store and name "person" in its write list, and the person who installed the app must have approved that. Nothing was written.',
+    forbidden_by_viewer: () => 'You do not have permission to do this on the agent this app is installed on (writing needs edit access, reading needs view access). Nothing was written.',
+    grant_stale: (bin) => `This app changed since it was approved. Approve it again with \`${bin} apps reconsent <installation>\` and try again.`,
+    schema: () => 'The request does not fit this operation (the collection name, the document id, the document, or a query parameter). Nothing was written.',
+    quota: () => `That would go over a limit (a document is at most ${data_provider_1.APP_STORE_LIMITS.docMaxChars} characters of JSON, a collection holds at most ${data_provider_1.APP_STORE_LIMITS.docsPerCollectionMax} documents, an installation at most ${data_provider_1.APP_STORE_LIMITS.installationMaxBytes} bytes). Nothing was written; nothing is ever trimmed to fit.`,
+    rate: () => 'Too many writes in a short time. Wait a moment and try again.',
+    unavailable: () => 'This is not available right now: the installation may be paused, or the server is busy. Check `apps installations show <installation>`, then try again.',
+};
+/** The words for a refusal. The server's own sentence, when it sent one, is added after ours and never replaces it. */
+function describePersonDataRefusal(failure, bin) {
+    const lines = [REFUSAL_WORDS[failure.code](bin)];
+    if (failure.code === 'rate' && failure.retryAfterMs !== undefined) {
+        lines.push(`→ Try again in ${Math.max(1, Math.ceil(failure.retryAfterMs / 1000))} s.`);
+    }
+    return lines.join('\n');
+}
+/**
+ * What a conflict means and what to do. A conflict is an ANSWER: someone (the app's window, an Agent, another person)
+ * wrote the document first, so read it again, merge, and retry with the revision it is at now. Nothing was written.
+ */
+function describePersonDataConflict(failure, target, bin) {
+    const read = `${bin} apps data query ${target.installation} ${target.collection} --id ${target.id}`;
+    switch (failure.conflict) {
+        case 'rev_mismatch':
+            return [
+                `Not written: ${target.collection}/${target.id} is at revision ${failure.currentRev ?? '(unknown)'}, not the one you named.`,
+                `→ Read it again (\`${read}\`), merge, and retry with --expected-rev ${failure.currentRev ?? '<its revision>'}.`,
+            ].join('\n');
+        case 'exists':
+            return [
+                `Not written: ${target.collection}/${target.id} already exists${failure.currentRev === undefined ? '' : ` (revision ${failure.currentRev})`}, and --expected-rev 0 only creates.`,
+                `→ Read it (\`${read}\`) and replace it with --expected-rev ${failure.currentRev ?? '<its revision>'}, or leave --expected-rev out to overwrite whatever is there.`,
+            ].join('\n');
+        case 'not_found':
+            return [
+                `Not written: there is no document ${target.collection}/${target.id} to replace.`,
+                `→ Create it with --expected-rev 0, or leave --expected-rev out.`,
+            ].join('\n');
+        default: {
+            const never = failure.conflict;
+            return String(never);
+        }
+    }
+}
+// ── a document, drawn for a terminal ────────────────────────────────────────
+/**
+ * Text that came from an app's data, safe to print: a control character, a C1 control, a line or paragraph separator,
+ * a bidirectional override and a character that draws nothing (a zero-width character, a variation selector, a Unicode tag character:
+ * text a person cannot see) are written as a visible `\uXXXX` and everything else is left alone. `JSON.stringify`
+ * already escapes everything below U+0020, but not these.
+ */
+function safeForTerminal(text) {
+    return text.replace(
+    // eslint-disable-next-line no-control-regex, no-misleading-character-class -- the point of the pattern is to match control, combining and invisible characters
+    /[\u0000-\u001f\u007f-\u009f\u00ad\u034f\u061c\u115f\u1160\u17b4\u17b5\u180b-\u180e\u200b-\u200f\u2028-\u202e\u2060-\u206f\u2800\u3164\ufe00-\ufe0f\ufeff\uffa0\ufff9-\ufffb\u{1d173}-\u{1d17a}\u{e0000}-\u{e03ff}]/gu, (c) => {
+        const code = c.codePointAt(0) ?? 0;
+        return code > 0xffff
+            ? `\\u{${code.toString(16)}}`
+            : `\\u${code.toString(16).padStart(4, '0')}`;
+    });
+}
+const DATA_LINE_MAX = 400;
+/** One document as two lines: where it stands, and its content as compact JSON (cut where it would flood a terminal). */
+function formatDocument(doc) {
+    const head = `${doc.id}  rev ${doc.rev}  by ${doc.writtenBy.kind}${doc.writtenBy.via ? ` (${doc.writtenBy.via})` : ''}  ${doc.updatedAt}`;
+    if (doc.unreadable) {
+        return [
+            head,
+            '    (this document cannot be shown: it is stored in a form the store cannot hand over)',
+        ];
+    }
+    const json = safeForTerminal(JSON.stringify(doc.data));
+    const shown = json.length > DATA_LINE_MAX
+        ? `${json.slice(0, DATA_LINE_MAX)}... (${json.length - DATA_LINE_MAX} more characters; --json prints it whole)`
+        : json;
+    return [head, `    ${shown}`];
+}
+/** A page of documents, in lines; an empty page says so, and a page that ends early says how to ask for the rest. */
+function formatQueryResult(result, target, bin) {
+    const lines = [];
+    const total = result.total === undefined ? '' : ` of ${result.total}`;
+    lines.push(result.docs.length === 0
+        ? `No documents in ${target.collection}.`
+        : `${result.docs.length} document${result.docs.length === 1 ? '' : 's'}${total} in ${target.collection}:`);
+    for (const doc of result.docs) {
+        lines.push(...formatDocument(doc));
+    }
+    if (result.nextCursor) {
+        lines.push(`→ More: \`${bin} apps data query ${target.installation} ${target.collection} --cursor ${result.nextCursor}\` (same filters).`);
+    }
+    return lines;
+}
+/** The limit the reference and this help text share, so a number is never typed twice. */
+exports.PERSON_DATA_QUERY_LIMIT_MAX = data_provider_1.APP_STORE_LIMITS.queryLimitMax;

package/dist/lib/appInstallations.d.ts

@@ -0,0 +1,117 @@
+import type { AppDisclosureCheck, AppDisclosureFacts, AppHostUnsuitable, AppInstallationJobState, AppInstallationListItem, AppOperatorUnmet } from '@skrr-ai/data-provider';
+import type { AppsRefusal } from './apps';
+/**
+ * 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.
+ */
+export declare function describeAvailability(availability: unknown): string;
+export declare function describeTrust(trust: unknown): string;
+export declare function describeTrustShort(trust: unknown): string;
+/**
+ * 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).
+ */
+export declare function formatInstallationRow(item: AppInstallationListItem): string;
+/**
+ * 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.
+ */
+export declare function describeJobScheduling(jobState: {
+    state?: unknown;
+    reason?: unknown;
+} | null | undefined): {
+    state: string;
+    what: string;
+    next: string | null;
+} | null;
+/** 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. */
+export declare function formatJobStates(jobStates: readonly AppInstallationJobState[] | undefined, installationId: string): string[];
+/** The words for each reason a grant stopped covering a version; a kind it does not know is said as it came. */
+export declare function describeGrantReasons(kinds: readonly string[]): string[];
+/**
+ * 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".
+ */
+export declare function formatDisclosure(raw: unknown, facts?: AppDisclosureFacts): string[];
+export declare function describeHostUnsuitable(reason: AppHostUnsuitable): string;
+export declare function describeOperatorUnmet(unmet: AppOperatorUnmet): string;
+/**
+ * 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".
+ */
+export declare function formatBindings(raw: unknown): string[];
+/**
+ * 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.
+ */
+export declare function formatHosting(raw: unknown): string[];
+/** The words for a `binding_required` refusal: what was missing, and why what was given would not do. */
+export declare function describeBindingRefusal(refusal: AppsRefusal): string;
+/**
+ * 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".
+ */
+export declare function describeDisclosureCheck(check: AppDisclosureCheck | undefined): string[];
+export interface InstallTarget {
+    appId: string;
+    versionId: string;
+    bundleHash: string;
+    version: number;
+}
+export declare class InstallTargetError extends Error {
+    readonly code: 'no_versions' | 'version_not_found' | 'wrong_app';
+    constructor(code: 'no_versions' | 'version_not_found' | 'wrong_app', message: string);
+}
+/**
+ * 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.
+ */
+export declare function resolveInstallTarget(input: {
+    appId: string;
+    versionId?: string;
+}): Promise<InstallTarget>;
+/** The sentence for a refusal the server made on an installation call, or null for one that is not. */
+export declare function describeInstallationConflict(refusal: AppsRefusal, bin: string): string | null;
+/** The machine code of every installation refusal: `APP_<REASON>`. */
+export declare const ALL_INSTALLATION_REFUSAL_CODES: Record<string, string>;
+export declare const INSTALLATION_REFUSAL_CODES: Record<string, string>;
+/** The lines the disclosure preview adds when the app cannot be installed on the principal asked about. Empty for none. */
+export declare function formatScopeIssues(raw: unknown): string[];
+/**
+ * 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.
+ */
+export declare function resolveInstallPrincipal(input: {
+    agent?: string;
+    me?: boolean;
+}): Promise<{
+    kind: 'agent' | 'user';
+    id: string;
+}>;
+/** A layout read, in lines: the revision to name when writing, then the top-level order and each folder. */
+export declare function formatUserLayout(raw: unknown): string[];
+/** What the layout route refused with: the contract's word, the revision to retry from, and where the body did not fit. */
+export interface LayoutRefusal {
+    status?: number;
+    error: string;
+    currentRev?: number;
+    issue?: string;
+}
+/** Read a layout refusal out of an API error, or null when the error is not one the layout route made. */
+export declare function readLayoutRefusal(error: unknown): LayoutRefusal | null;
+/** The machine code of a report refusal that is the report's alone: `APP_REPORT_<REASON>`. */
+export declare const REPORT_REFUSAL_CODES: Record<string, string>;
+/** The sentence for a refusal the server made on a report, or null for one that is not the report's alone. */
+export declare function describeReportRefusal(refusal: AppsRefusal, bin: string): string | null;
+/** The exit of a refusal that says "that is not there for you": the same one an unknown app gets. */
+export declare function installationRefusalExit(conflict: string): number;