@skrr-ai/cli 0.1.108 → 0.1.110

package/dist/lib/tasks.d.ts

@@ -241,6 +241,45 @@ export declare function findTaskByExternalKey({ externalKey, spaceId, goalId, pa
     task: TaskRecord | null;
     duplicates: TaskRecord[];
 }>;
+export type ExternalKeyLookup = {
+    externalKey: string;
+    spaceId?: unknown;
+    goalId?: unknown;
+};
+export type ExternalKeyHit = {
+    task: TaskRecord | null;
+    duplicates: TaskRecord[];
+    /** Set when the lookup itself failed: "could not look" is not "nothing there". */
+    error?: Error;
+};
+/** The identity of one lookup: a key means a task only within its scope. */
+export declare function externalKeyLookupId(lookup: ExternalKeyLookup): string;
+/**
+ * Which of these tasks already exist? Answers for many keys at once.
+ *
+ * `create-tree`, `--resume` and `--verify` all start by asking that of every node
+ * of a tree, and asked it once per node, one after another: 94 round trips
+ * before the first write (OSK-S-440 #3). Two things bring that down without
+ * changing a single answer:
+ *
+ *   - Keys that share a prefix (`aap/c1`, `aap/c2`, ... — a tree is written
+ *     under one) are answered by ONE paged read of the prefix, per scope. The
+ *     read can return rows that are not this tree's; they are ignored, since a
+ *     key is matched whole. If the prefix is broad enough that the read hits its
+ *     page cap, whatever it did not find is looked up directly, because absence
+ *     from a truncated read proves nothing.
+ *   - Whatever is left is looked up by exact key, a few at a time rather than
+ *     one at a time.
+ *
+ * A server that predates `externalKeyPrefix` ignores it and returns the scope's
+ * tasks: still correct (matched whole), merely a wider read, and bounded by the
+ * same cap.
+ */
+export declare function findTasksByExternalKeys(lookups: readonly ExternalKeyLookup[], opts?: {
+    concurrency?: number;
+    minKeysForPrefix?: number;
+    maxPages?: number;
+}): Promise<Map<string, ExternalKeyHit>>;
 /**
  * What the CLI reports under `defaultAgent` in `--json` output.
  *

package/dist/lib/tasks.js

@@ -21,6 +21,8 @@ exports.applyProspectiveTaskExecutionMode = applyProspectiveTaskExecutionMode;
 exports.validateTaskCreateReferences = validateTaskCreateReferences;
 exports.resolveTaskCreateScope = resolveTaskCreateScope;
 exports.findTaskByExternalKey = findTaskByExternalKey;
+exports.externalKeyLookupId = externalKeyLookupId;
+exports.findTasksByExternalKeys = findTasksByExternalKeys;
 exports.droppedDefaultAssignees = droppedDefaultAssignees;
 exports.applyTaskAssigneeDefaults = applyTaskAssigneeDefaults;
 exports.hasExplicitTaskAssignee = hasExplicitTaskAssignee;
@@ -622,6 +624,136 @@ async function findTaskByExternalKey({ externalKey, spaceId, goalId, parentId, }
     }
     return { task: items[0] ?? null, duplicates: [] };
 }
+/** The identity of one lookup: a key means a task only within its scope. */
+function externalKeyLookupId(lookup) {
+    const scope = (value) => (typeof value === 'string' ? value : '');
+    return `${scope(lookup.spaceId)}|${scope(lookup.goalId)}|${lookup.externalKey}`;
+}
+function longestCommonPrefix(values) {
+    if (values.length === 0)
+        return '';
+    let prefix = values[0];
+    for (const value of values) {
+        let i = 0;
+        while (i < prefix.length && i < value.length && prefix[i] === value[i])
+            i += 1;
+        prefix = prefix.slice(0, i);
+        if (!prefix)
+            break;
+    }
+    return prefix;
+}
+async function mapWithConcurrency(items, limit, fn) {
+    const results = new Array(items.length);
+    let next = 0;
+    const worker = async () => {
+        while (next < items.length) {
+            const index = next;
+            next += 1;
+            results[index] = await fn(items[index]);
+        }
+    };
+    await Promise.all(Array.from({ length: Math.min(limit, items.length) }, worker));
+    return results;
+}
+/**
+ * Which of these tasks already exist? Answers for many keys at once.
+ *
+ * `create-tree`, `--resume` and `--verify` all start by asking that of every node
+ * of a tree, and asked it once per node, one after another: 94 round trips
+ * before the first write (OSK-S-440 #3). Two things bring that down without
+ * changing a single answer:
+ *
+ *   - Keys that share a prefix (`aap/c1`, `aap/c2`, ... — a tree is written
+ *     under one) are answered by ONE paged read of the prefix, per scope. The
+ *     read can return rows that are not this tree's; they are ignored, since a
+ *     key is matched whole. If the prefix is broad enough that the read hits its
+ *     page cap, whatever it did not find is looked up directly, because absence
+ *     from a truncated read proves nothing.
+ *   - Whatever is left is looked up by exact key, a few at a time rather than
+ *     one at a time.
+ *
+ * A server that predates `externalKeyPrefix` ignores it and returns the scope's
+ * tasks: still correct (matched whole), merely a wider read, and bounded by the
+ * same cap.
+ */
+async function findTasksByExternalKeys(lookups, opts = {}) {
+    const concurrency = opts.concurrency ?? 6;
+    const minKeysForPrefix = opts.minKeysForPrefix ?? 8;
+    const maxPages = opts.maxPages ?? 10;
+    const hits = new Map();
+    const unique = new Map();
+    for (const lookup of lookups)
+        unique.set(externalKeyLookupId(lookup), lookup);
+    const byScope = new Map();
+    for (const lookup of unique.values()) {
+        const scopeId = externalKeyLookupId({ ...lookup, externalKey: '' });
+        byScope.set(scopeId, [...(byScope.get(scopeId) ?? []), lookup]);
+    }
+    const settle = (lookup, rows) => {
+        const matching = rows.filter((row) => row.externalKey === lookup.externalKey);
+        hits.set(externalKeyLookupId(lookup), {
+            task: matching.length === 1 ? matching[0] : null,
+            duplicates: matching.length > 1 ? matching : [],
+        });
+    };
+    for (const group of byScope.values()) {
+        let unresolved = group;
+        const prefix = longestCommonPrefix(group.map((lookup) => lookup.externalKey));
+        if (group.length >= minKeysForPrefix && prefix.length >= 3) {
+            try {
+                const rows = [];
+                let cursor;
+                let complete = false;
+                for (let page = 0; page < maxPages; page += 1) {
+                    const response = (await data_provider_1.dataService.listTasks({
+                        externalKeyPrefix: prefix,
+                        ...(typeof group[0].spaceId === 'string' && group[0].spaceId
+                            ? { spaceId: group[0].spaceId }
+                            : {}),
+                        ...(typeof group[0].goalId === 'string' && group[0].goalId
+                            ? { goalId: group[0].goalId }
+                            : {}),
+                        limit: 200,
+                        ...(cursor ? { cursor } : {}),
+                    }));
+                    rows.push(...listItems(response));
+                    if (!response?.has_more || !response.next_cursor) {
+                        complete = true;
+                        break;
+                    }
+                    cursor = response.next_cursor;
+                }
+                unresolved = [];
+                for (const lookup of group) {
+                    const found = rows.some((row) => row.externalKey === lookup.externalKey);
+                    // Absence is only an answer from a read that reached the end.
+                    if (found || complete)
+                        settle(lookup, rows);
+                    else
+                        unresolved.push(lookup);
+                }
+            }
+            catch {
+                unresolved = group; // the prefix read failing is not an answer; look directly
+            }
+        }
+        await mapWithConcurrency(unresolved, concurrency, async (lookup) => {
+            try {
+                const { task, duplicates } = await findTaskByExternalKey(lookup);
+                hits.set(externalKeyLookupId(lookup), { task, duplicates });
+            }
+            catch (err) {
+                hits.set(externalKeyLookupId(lookup), {
+                    task: null,
+                    duplicates: [],
+                    error: err instanceof Error ? err : new Error(String(err)),
+                });
+            }
+        });
+    }
+    return hits;
+}
 /**
  * Which DEFAULTED assignees the create route will strip because they are not
  * members of the task's space (`ASSIGNEE_NOT_IN_SPACE` degradation). Only a

package/dist/lib/triggers.d.ts

@@ -1,4 +1,4 @@
-import { type EmbeddedActionRef, type TriggerPreflightReport, type TriggerSensorConfig } from '@skrr-ai/data-provider';
+import { type EmbeddedActionRef, type TriggerIntentUnsupportedItem, type TriggerPreflightReport, type TriggerSensorConfig } from '@skrr-ai/data-provider';
 export declare const TRIGGER_KINDS: readonly ["schedule", "once", "event", "stochastic", "self_scheduled", "on_demand", "form", "chat_message"];
 export declare const TRIGGER_SCOPE_KINDS: readonly ["agent", "group_chat_subscriber", "space_oracle", "space_subscriber", "key_result_watcher", "task_watcher", "goal_watcher", "entity_reminder"];
 /**
@@ -160,6 +160,13 @@ export interface TriggerParseIntentResponse {
     message?: string;
     needsClarification?: boolean;
     proposedTrigger?: Record<string, unknown> | null;
+    /** Conditions the person asked for that the proposal does NOT apply (OSK-15402). */
+    unsupported?: TriggerIntentUnsupportedItem[];
+    /** The transcript including this turn; send it back with a reply to answer a question. */
+    history?: Array<{
+        role: 'user' | 'assistant';
+        content: string;
+    }>;
     usage?: Record<string, unknown>;
 }
 export interface TriggerEventCatalogEntry {
@@ -225,6 +232,10 @@ export interface SpaceAssistantResponse {
 export declare const SCOPE_IMPLIED_REF_KEY: Partial<Record<TriggerScopeKind, string>>;
 export declare function parseKeyValueFlags(values: string[] | undefined, flagName: string, scopeKind?: string): Record<string, string>;
 export declare function parseJsonObject(raw: string | undefined, flagName: string): Record<string, unknown> | undefined;
+/**
+ * A JSON-array flag value: inline JSON, `@path` (a file), or a bare path to an existing file. A
+ * path used to reach `JSON.parse` and fail with "Unexpected token '/'" (OSK-15402).
+ */
 export declare function parseJsonArray(raw: string | undefined, flagName: string): unknown[] | undefined;
 export declare function buildBuiltinActionPayload(input: {
     builtinAction?: string;
@@ -288,6 +299,29 @@ export declare const FLAG_OWNER_KINDS: Readonly<Record<string, readonly string[]
 export declare function assertKindFlagsApply(kind: unknown, flags: Record<string, unknown>, options?: {
     kindIsFixed?: boolean;
 }): void;
+/**
+ * The request body path each `triggers create` flag writes, for reading a server refusal back
+ * in the person's own words (`lib/request-field-flags.ts`). The server validates the body and
+ * names `execution.workflowSignal`; the person typed `--workflow-event-key` (OSK-15313). A path
+ * missing here is simply left as the server wrote it.
+ */
+export declare const TRIGGER_CREATE_FIELD_FLAGS: Readonly<Record<string, string>>;
+/**
+ * Flags an execution mode cannot work without, refused before the request is sent. The inverse
+ * case (`--workflow-outcome` without `--workflow-event-key`) was already refused by oclif's
+ * `dependsOn`; the missing key for `--mode workflow_signal` went to the server and came back
+ * naming an internal path (OSK-15313).
+ */
+export declare const TRIGGER_MODE_REQUIRED_FLAGS: Readonly<Record<string, ReadonlyArray<{
+    flag: string;
+    field: string;
+    why: string;
+}>>>;
+/**
+ * Refuse a mode whose required flag is missing, unless the body the person supplied
+ * (`--from-json`) already carries the field the flag would write.
+ */
+export declare function assertModeRequiredFlags(mode: unknown, flags: Record<string, unknown>, execution: Record<string, unknown> | undefined): void;
 /**
  * The sentence for a fire's `scheduledFire` report: what a MANUAL fire skipped that a scheduled
  * one would not. A manual fire is exempt from the enabled gate, the working/quiet-hours overlay and
@@ -302,6 +336,13 @@ export declare function describeScheduledFire(result: Record<string, unknown>):
  * about `in_progress` once). Only these are success for `triggers fire --strict`.
  */
 export declare function fireWasAccepted(result: Record<string, unknown>): boolean;
+/**
+ * Why `triggers fire --strict` failed. A strict failure used to print exactly what the exit-0 run
+ * printed and then exit 1, so nothing said what the flag had judged (OSK-16474). It names the
+ * outcome it refused, the reason, the server's sentence when there is one, and what --strict
+ * accepts.
+ */
+export declare function describeStrictFireRefusal(result: Record<string, unknown>): string;
 /**
  * The lines a fire or replay owes beyond `outcome=… reason=…` (OSK-15494): the sentence the
  * server wrote ("Replayed fire … resolved a step that was not waiting when that fire ran:

package/dist/lib/triggers.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.triggerApi = exports.AgentTriggerScopeError = exports.FLAG_OWNER_KINDS = exports.SCOPE_IMPLIED_REF_KEY = exports.TRIGGER_EVENT_CATALOG = exports.TRIGGER_EVENT_ENTITY_TYPES = exports.TRIGGER_CHAT_AUTH_MODES = exports.TRIGGER_CHAT_RESPONSE_MODES = exports.TRIGGER_CHAT_MODES = exports.TRIGGER_FORM_RESPONSE_MODES = exports.TRIGGER_CONCURRENCY_POLICIES = exports.TRIGGER_EVENT_FILTER_MODES = exports.TRIGGER_EXECUTOR_MODES = exports.TRIGGER_SCOPE_KINDS = exports.TRIGGER_KINDS = void 0;
+exports.triggerApi = exports.AgentTriggerScopeError = exports.TRIGGER_MODE_REQUIRED_FLAGS = exports.TRIGGER_CREATE_FIELD_FLAGS = exports.FLAG_OWNER_KINDS = exports.SCOPE_IMPLIED_REF_KEY = exports.TRIGGER_EVENT_CATALOG = exports.TRIGGER_EVENT_ENTITY_TYPES = exports.TRIGGER_CHAT_AUTH_MODES = exports.TRIGGER_CHAT_RESPONSE_MODES = exports.TRIGGER_CHAT_MODES = exports.TRIGGER_FORM_RESPONSE_MODES = exports.TRIGGER_CONCURRENCY_POLICIES = exports.TRIGGER_EVENT_FILTER_MODES = exports.TRIGGER_EXECUTOR_MODES = exports.TRIGGER_SCOPE_KINDS = exports.TRIGGER_KINDS = void 0;
 exports.validateEventReference = validateEventReference;
 exports.validateEventFilter = validateEventFilter;
 exports.serverEventCatalogIncludes = serverEventCatalogIncludes;
@@ -24,8 +24,10 @@ exports.setDefined = setDefined;
 exports.mergeObjectField = mergeObjectField;
 exports.mergeTriggerKindConfig = mergeTriggerKindConfig;
 exports.assertKindFlagsApply = assertKindFlagsApply;
+exports.assertModeRequiredFlags = assertModeRequiredFlags;
 exports.describeScheduledFire = describeScheduledFire;
 exports.fireWasAccepted = fireWasAccepted;
+exports.describeStrictFireRefusal = describeStrictFireRefusal;
 exports.describeFireDetail = describeFireDetail;
 exports.formatFireInZone = formatFireInZone;
 exports.nextFireLines = nextFireLines;
@@ -49,6 +51,7 @@ exports.renderTriggerSummary = renderTriggerSummary;
 exports.renderLegacyRuns = renderLegacyRuns;
 exports.renderFireAudit = renderFireAudit;
 const data_provider_1 = require("@skrr-ai/data-provider");
+const node_fs_1 = require("node:fs");
 const format_1 = require("./format");
 exports.TRIGGER_KINDS = [
     'schedule',
@@ -389,12 +392,28 @@ function parseJsonObject(raw, flagName) {
     }
     return parsed;
 }
+/**
+ * A JSON-array flag value: inline JSON, `@path` (a file), or a bare path to an existing file. A
+ * path used to reach `JSON.parse` and fail with "Unexpected token '/'" (OSK-15402).
+ */
 function parseJsonArray(raw, flagName) {
     if (raw === undefined)
         return undefined;
+    let text = raw;
+    const trimmed = raw.trim();
+    if (trimmed.startsWith('@') || (!/^[[{]/.test(trimmed) && (0, node_fs_1.existsSync)(trimmed))) {
+        const path = trimmed.startsWith('@') ? trimmed.slice(1) : trimmed;
+        try {
+            text = (0, node_fs_1.readFileSync)(path, 'utf8');
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            throw new Error(`Cannot read ${flagName} file ${path}: ${msg}`);
+        }
+    }
     let parsed;
     try {
-        parsed = JSON.parse(raw);
+        parsed = JSON.parse(text);
     }
     catch (err) {
         const msg = err instanceof Error ? err.message : String(err);
@@ -442,6 +461,13 @@ function buildScheduleConfigFromFlags(flags) {
         endAt: flags['end-at'],
         staleCatchupMs: flags['stale-catchup-ms'],
     });
+    // The range is the server's (`TRIGGER_STALE_CATCHUP_MS_RANGE`), checked here too so the refusal
+    // names the flag the person typed and happens before anything is sent (OSK-16474).
+    if (flags['stale-catchup-ms'] !== undefined) {
+        const refusal = (0, data_provider_1.describeStaleCatchupMsRefusal)(flags['stale-catchup-ms'], '--stale-catchup-ms');
+        if (refusal)
+            throw new Error(refusal);
+    }
     return schedule;
 }
 function assertScheduleTimingShape(schedule, options = {}) {
@@ -746,6 +772,59 @@ function assertKindFlagsApply(kind, flags, options = {}) {
     }
     throw new Error(`${named.join(', ')} ${verb} not apply to ${subject}.${fix}`);
 }
+/**
+ * The request body path each `triggers create` flag writes, for reading a server refusal back
+ * in the person's own words (`lib/request-field-flags.ts`). The server validates the body and
+ * names `execution.workflowSignal`; the person typed `--workflow-event-key` (OSK-15313). A path
+ * missing here is simply left as the server wrote it.
+ */
+exports.TRIGGER_CREATE_FIELD_FLAGS = Object.freeze({
+    'execution.mode': '--mode',
+    'execution.promptTemplate': '--prompt',
+    'execution.conversationId': '--conversation',
+    'execution.builtinAction': '--builtin-action',
+    'execution.effectPolicy': '--effect-contract',
+    'execution.effectPolicy.contract': '--effect-contract',
+    'execution.effectPolicy.writeMode': '--effect-write-mode',
+    'execution.effectPolicy.options': '--effect-options',
+    // The whole block is written by --workflow-event-key: without it the block is not sent.
+    'execution.workflowSignal': '--workflow-event-key',
+    'execution.workflowSignal.eventKey': '--workflow-event-key',
+    'execution.workflowSignal.outcome': '--workflow-outcome',
+    'execution.dispatch': '--dispatch',
+    'execution.references': '--reference',
+    'execution.workingHours': '--working-hours',
+    'execution.quietHours': '--quiet-hours',
+});
+/**
+ * Flags an execution mode cannot work without, refused before the request is sent. The inverse
+ * case (`--workflow-outcome` without `--workflow-event-key`) was already refused by oclif's
+ * `dependsOn`; the missing key for `--mode workflow_signal` went to the server and came back
+ * naming an internal path (OSK-15313).
+ */
+exports.TRIGGER_MODE_REQUIRED_FLAGS = Object.freeze({
+    workflow_signal: [
+        {
+            flag: 'workflow-event-key',
+            field: 'workflowSignal',
+            why: 'the exact event key the parked workflow step waits on',
+        },
+    ],
+});
+/**
+ * Refuse a mode whose required flag is missing, unless the body the person supplied
+ * (`--from-json`) already carries the field the flag would write.
+ */
+function assertModeRequiredFlags(mode, flags, execution) {
+    if (typeof mode !== 'string')
+        return;
+    const missing = (exports.TRIGGER_MODE_REQUIRED_FLAGS[mode] ?? []).filter((requirement) => !flagWasPassed(flags[requirement.flag]) && execution?.[requirement.field] === undefined);
+    if (missing.length === 0)
+        return;
+    throw new Error(missing
+        .map((requirement) => `--mode ${mode} requires --${requirement.flag}: ${requirement.why}.`)
+        .join(' '));
+}
 /**
  * The sentence for a fire's `scheduledFire` report: what a MANUAL fire skipped that a scheduled
  * one would not. A manual fire is exempt from the enabled gate, the working/quiet-hours overlay and
@@ -786,6 +865,23 @@ function fireWasAccepted(result) {
         typeof result.originalOutcome === 'string' &&
         accepted.includes(result.originalOutcome));
 }
+/**
+ * Why `triggers fire --strict` failed. A strict failure used to print exactly what the exit-0 run
+ * printed and then exit 1, so nothing said what the flag had judged (OSK-16474). It names the
+ * outcome it refused, the reason, the server's sentence when there is one, and what --strict
+ * accepts.
+ */
+function describeStrictFireRefusal(result) {
+    const text = (value) => (typeof value === 'string' && value.trim() ? value.trim() : '');
+    const outcome = text(result.outcome) || 'unknown';
+    const original = outcome === 'duplicate' ? text(result.originalOutcome) : '';
+    const reason = text(result.reason);
+    const sentence = text(result.detail) || text(result.errorMessage);
+    return (`--strict: the fire was not accepted (outcome ${outcome}` +
+        `${original ? `, a repeat of ${original}` : ''}${reason ? `, reason ${reason}` : ''})` +
+        `${sentence ? `: ${sentence}` : '.'} ` +
+        `--strict accepts only ${data_provider_1.ACCEPTED_AGENT_TRIGGER_FIRE_OUTCOMES.join(', ')}, or a repeat of one.`);
+}
 /**
  * The lines a fire or replay owes beyond `outcome=… reason=…` (OSK-15494): the sentence the
  * server wrote ("Replayed fire … resolved a step that was not waiting when that fire ran:

package/dist/lib/workflow-issues.d.ts

@@ -0,0 +1,14 @@
+import type { WorkflowIssue } from '@skrr-ai/data-provider';
+/**
+ * Lines that say what in a workflow draft is wrong, and where.
+ *
+ * A draft may be STORED invalid — the canvas saves while you are still building
+ * — so `create` and `update` succeed on a graph `publish` will refuse. They used
+ * to print a bare success, and the author learned at publish (OSK-15328). The
+ * server now returns the shared linter's `issues` on every write and on
+ * validate; this renders them the same way on all three, each naming its node
+ * and field so it can be acted on without reading the graph again.
+ */
+export declare function formatWorkflowIssues(issues: WorkflowIssue[] | undefined): string[];
+/** The heading plus issue lines for a draft write, or nothing when the draft is clean. */
+export declare function describeDraftIssues(issues: WorkflowIssue[] | undefined): string[];

package/dist/lib/workflow-issues.js

@@ -0,0 +1,32 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.formatWorkflowIssues = formatWorkflowIssues;
+exports.describeDraftIssues = describeDraftIssues;
+/**
+ * Lines that say what in a workflow draft is wrong, and where.
+ *
+ * A draft may be STORED invalid — the canvas saves while you are still building
+ * — so `create` and `update` succeed on a graph `publish` will refuse. They used
+ * to print a bare success, and the author learned at publish (OSK-15328). The
+ * server now returns the shared linter's `issues` on every write and on
+ * validate; this renders them the same way on all three, each naming its node
+ * and field so it can be acted on without reading the graph again.
+ */
+function formatWorkflowIssues(issues) {
+    return (issues ?? []).map((issue) => {
+        const where = [issue.nodeKey, issue.path].filter(Boolean).join(' ');
+        const label = issue.severity === 'error' ? 'error' : 'warning';
+        return `  ${label}${where ? ` [${where}]` : ''}: ${issue.message}`;
+    });
+}
+/** The heading plus issue lines for a draft write, or nothing when the draft is clean. */
+function describeDraftIssues(issues) {
+    const list = issues ?? [];
+    if (!list.length)
+        return [];
+    const errors = list.filter((issue) => issue.severity === 'error').length;
+    const heading = errors
+        ? `Saved, but this draft cannot be published yet (${errors} error${errors === 1 ? '' : 's'}):`
+        : `Saved. ${list.length} warning${list.length === 1 ? '' : 's'} (publishing is allowed):`;
+    return [heading, ...formatWorkflowIssues(list)];
+}

package/dist/lib/workflow-run-view.d.ts

@@ -0,0 +1,59 @@
+/**
+ * What the plain-text workflow run view says about each node beyond its status.
+ *
+ * The table showed key/type/status/task, so three facts the server already knew were visible
+ * only under `--json` (OSK-15325): a loop that `succeeded` while one of its items failed, what a
+ * `waiting` node was waiting FOR (an event key, an approval, a child run), and how to resolve a
+ * wait a signal can resolve. Rows were also in node-creation order rather than graph order.
+ * Everything here reads server-derived fields (`depth`, `loopSummary`, `signalable`, `waitKind`)
+ * and recomputes none of them.
+ */
+export interface RunViewNode {
+    nodeKey?: unknown;
+    nodeType?: unknown;
+    status?: unknown;
+    depth?: unknown;
+    lane?: unknown;
+    attentionReason?: unknown;
+    error?: {
+        message?: unknown;
+    } | null;
+    waitKind?: unknown;
+    signalable?: unknown;
+    waitingFor?: unknown;
+    stoppedBecause?: {
+        code?: unknown;
+        message?: unknown;
+    } | null;
+    loopSummary?: {
+        total?: unknown;
+        completed?: unknown;
+        succeeded?: unknown;
+        failed?: unknown;
+        partial?: unknown;
+        settled?: unknown;
+    } | null;
+}
+/** One printable line: control characters (an ESC sequence included) become spaces. */
+export declare function printable(value: string): string;
+/**
+ * Nodes in graph order: the server's topological `depth` first, then the order the server
+ * returned them in (a stable sort), so siblings at one depth keep their relative order.
+ */
+export declare function orderNodesByGraph<T extends RunViewNode>(nodes: readonly T[]): T[];
+/** "2 of 3 items succeeded, 1 failed" for a loop, or '' when the server sent no summary. */
+export declare function describeLoopProgress(node: RunViewNode): string;
+/** The DETAIL cell: what needs eyes, what a wait waits for, and how far a loop got. */
+export declare function describeNodeDetail(node: RunViewNode, attention?: string): string;
+/**
+ * How to resolve each wait a signal can resolve. Only the server's `signalable` decides: a loop
+ * or child-run wait is settled by its work, and offering a command for it would invite a person
+ * to skip that work.
+ */
+export declare function describeSignalHints(spaceId: string, runId: string, nodes: readonly RunViewNode[], bin?: string): string[];
+/**
+ * Lines a run's headline status cannot carry: a node that succeeded although some of its items
+ * failed. A loop under `onItemFailure: continue` with a permissive join succeeds with a failed
+ * item, so "run succeeded" alone hid the failure.
+ */
+export declare function describePartialOutcomes(nodes: readonly RunViewNode[]): string[];

package/dist/lib/workflow-run-view.js

@@ -0,0 +1,110 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.printable = printable;
+exports.orderNodesByGraph = orderNodesByGraph;
+exports.describeLoopProgress = describeLoopProgress;
+exports.describeNodeDetail = describeNodeDetail;
+exports.describeSignalHints = describeSignalHints;
+exports.describePartialOutcomes = describePartialOutcomes;
+const data_provider_1 = require("@skrr-ai/data-provider");
+const format_1 = require("./format");
+/** One printable line: control characters (an ESC sequence included) become spaces. */
+function printable(value) {
+    // eslint-disable-next-line no-control-regex
+    return (0, format_1.collapseWhitespace)(value.replace(/[\u0000-\u001f\u007f-\u009f]/g, ' '));
+}
+/**
+ * Nodes in graph order: the server's topological `depth` first, then the order the server
+ * returned them in (a stable sort), so siblings at one depth keep their relative order.
+ */
+function orderNodesByGraph(nodes) {
+    const depthOf = (node) => typeof node.depth === 'number' && Number.isFinite(node.depth)
+        ? node.depth
+        : Number.MAX_SAFE_INTEGER;
+    return nodes
+        .map((node, index) => ({ node, index }))
+        .sort((a, b) => depthOf(a.node) - depthOf(b.node) || a.index - b.index)
+        .map((entry) => entry.node);
+}
+/** "2 of 3 items succeeded, 1 failed" for a loop, or '' when the server sent no summary. */
+function describeLoopProgress(node) {
+    const summary = node.loopSummary;
+    if (node.nodeType !== 'loop' || !summary)
+        return '';
+    const total = Number(summary.total);
+    const completed = Number(summary.completed);
+    const succeeded = Number(summary.succeeded);
+    const failed = Number(summary.failed);
+    if (![total, completed, succeeded, failed].every(Number.isFinite))
+        return '';
+    const parts = [`${succeeded} of ${total} item${total === 1 ? '' : 's'} succeeded`];
+    if (failed > 0)
+        parts.push(`${failed} failed`);
+    if (summary.settled === true && completed < total)
+        parts.push(`${total - completed} not run`);
+    return parts.join(', ');
+}
+/** The DETAIL cell: what needs eyes, what a wait waits for, and how far a loop got. */
+function describeNodeDetail(node, attention = '') {
+    const parts = [];
+    const wait = (0, data_provider_1.describeWorkflowNodeWait)(node);
+    // "approval; waiting for an approval" says one thing twice: the wait phrase carries it.
+    if (attention && attention !== wait?.kind)
+        parts.push(attention);
+    if (wait)
+        parts.push(wait.text);
+    // A cancelled node says why it stopped (the run's deadline, a person's stop), not the
+    // problem it had been parked on before (OSK-16473).
+    const stopped = node.status === 'cancelled' ? node.stoppedBecause?.message : undefined;
+    if (typeof stopped === 'string' && stopped)
+        parts.push(`stopped: ${stopped}`);
+    const loop = describeLoopProgress(node);
+    if (loop)
+        parts.push(loop);
+    return printable(parts.join('; '));
+}
+/**
+ * How to resolve each wait a signal can resolve. Only the server's `signalable` decides: a loop
+ * or child-run wait is settled by its work, and offering a command for it would invite a person
+ * to skip that work.
+ */
+function describeSignalHints(spaceId, runId, nodes, bin = 'skrr') {
+    const lines = [];
+    for (const node of nodes) {
+        if (node.status !== 'waiting' || node.signalable !== true)
+            continue;
+        const key = printable(String(node.nodeKey ?? ''));
+        if (!key)
+            continue;
+        const wait = (0, data_provider_1.describeWorkflowNodeWait)(node);
+        const what = wait?.kind === 'approval' ? 'approve or reject it' : 'resolve it by hand';
+        lines.push(`To ${what}: ${bin} spaces workflows signal ${spaceId} ${runId} ${key}` +
+            (wait?.kind === 'approval'
+                ? ' [--outcome failure]'
+                : ' [--outcome failure] [--payload <json>]'));
+    }
+    return lines;
+}
+/**
+ * Lines a run's headline status cannot carry: a node that succeeded although some of its items
+ * failed. A loop under `onItemFailure: continue` with a permissive join succeeds with a failed
+ * item, so "run succeeded" alone hid the failure.
+ */
+function describePartialOutcomes(nodes) {
+    const lines = [];
+    for (const node of nodes) {
+        const summary = node.loopSummary;
+        // A failed loop already says so in its STATUS column; only a success can hide one.
+        if (node.nodeType !== 'loop' || node.status !== 'succeeded')
+            continue;
+        if (!summary || summary.partial !== true)
+            continue;
+        const failed = Number(summary.failed);
+        const total = Number(summary.total);
+        if (!Number.isFinite(failed) || failed <= 0)
+            continue;
+        lines.push(`Note: ${printable(String(node.nodeKey ?? 'loop'))} succeeded, but ` +
+            `${failed} of ${Number.isFinite(total) ? total : '?'} item${total === 1 ? '' : 's'} failed.`);
+    }
+    return lines;
+}