primitive-admin 1.0.61 → 1.0.62

package/dist/src/lib/log-inspection.d.ts

@@ -0,0 +1,568 @@
+/**
+ * Shared inspection-output library for the CLI's log/event commands
+ * (issue #1967, Phase A1).
+ *
+ * The platform keeps "what happened in my app" in four disconnected stores —
+ * integration invocations, workflow runs, workflow step runs, webhook events,
+ * and activity events. Each has its own CLI command with its own ad-hoc output
+ * shape. This module gives all of them one consistent, platform-vocabulary
+ * inspection model:
+ *
+ *   1. A **source-keyed discriminated union** (`LogEntry`) with a common
+ *      envelope `{ source, timestamp, outcome, nativeStatus, correlation }`
+ *      plus a typed, per-source `detail`. Workflow runs and workflow steps are
+ *      **separate variants** (`workflow-run` / `workflow-step`) — there is no
+ *      `kind` sub-discriminator.
+ *   2. An **outcome normalizer** that maps each source's native status onto a
+ *      small platform vocabulary (`ok` / `error` / `pending` / `neutral`) via a
+ *      documented policy, while preserving the raw value verbatim in
+ *      `nativeStatus`.
+ *   3. CLI-owned **per-source adapters** (`toIntegrationInspectionRow`, …) that
+ *      project each source record into its `LogEntry` variant. `detail` is a
+ *      deliberate **allowlist** projection — never the whole native record — so
+ *      stack-bearing error details, large-payload storage keys, step config/IO,
+ *      and infrastructure-internal activity fields never leak into `--json` by
+ *      default.
+ *   4. `--json` **envelope builders** per source, so every log view emits the
+ *      normalized item shape inside its endpoint's own pagination envelope —
+ *      never a bare array. This normalization is `--json`-only: the human
+ *      tables stay per-source, because each carries columns the generic shape
+ *      has no room for (a run's queue delay, a step's inter-step gap and token
+ *      counts, a webhook event's id). All four already share one definition of
+ *      time/duration/status formatting — `cli/src/lib/output.ts` — so there is
+ *      no second copy to reconcile, and no server-side projection
+ *      (`BlockRunSummary`, `IntegrationProxy.LogEntry`) is moved or imported
+ *      here.
+ *   5. A small **unsupported-flag rejection helper** so a filter a command
+ *      cannot serve fails with a clear message instead of being silently
+ *      ignored.
+ *
+ * Nothing here reaches the network; adapters are pure functions over records
+ * the caller already fetched (one upstream call per command invocation).
+ */
+/** The log store an entry came from. Workflow runs and steps are distinct. */
+export type LogSource = "integration" | "workflow-run" | "workflow-step" | "webhook" | "activity";
+/**
+ * Normalized outcome vocabulary (platform terms only):
+ * - `ok`      — completed / accepted successfully
+ * - `error`   — failed / rejected
+ * - `pending` — still in flight (queued, running, apply-pending, …)
+ * - `neutral` — no meaningful success/failure signal (skipped steps, activity
+ *               events, or an absent status). Never fabricated as `ok`.
+ */
+export type Outcome = "ok" | "error" | "pending" | "neutral";
+/**
+ * Cross-source pivot keys an operator follows between stores. Every field is
+ * optional — each source populates only the keys it actually carries.
+ */
+export interface Correlation {
+    runId?: string;
+    stepId?: string;
+    /** The step run's own row id — the key for a follow-up lookup. */
+    stepRunId?: string;
+    /** The webhook event's own row id — the key for a follow-up lookup. */
+    eventId?: string;
+    traceId?: string;
+    workflowId?: string;
+    workflowKey?: string;
+    integrationKey?: string;
+    webhookId?: string;
+    workflowRunId?: string;
+    /** The acting user, where the source records one (workflow, activity). */
+    userId?: string;
+}
+/** Common envelope shared by every variant. */
+interface BaseLogEntry {
+    source: LogSource;
+    /** ISO timestamp of the source event, or null when the record has none. */
+    timestamp: string | null;
+    outcome: Outcome;
+    /** The source's raw status value, preserved verbatim (never remapped). */
+    nativeStatus: string | number | null;
+    correlation: Correlation;
+    /** Duration in ms where the source records one, else null/absent. */
+    durationMs?: number | null;
+}
+export interface IntegrationDetail {
+    method?: string;
+    path?: string;
+    /** The call source: user | admin | test | workflow. */
+    callSource?: string;
+    requestBytes?: number;
+    responseBytes?: number;
+    errorCode?: string;
+    actorType?: string;
+    actorEmail?: string;
+}
+export interface WorkflowRunDetail {
+    workflowKey?: string;
+    isPreview?: boolean;
+    queueDelayMs?: number;
+    createCallDurationMs?: number;
+    executionStartedAt?: string;
+    endedAt?: string;
+    initiatorKind?: string;
+    errorMessage?: string;
+    /**
+     * #2074 — the run's failure summary. `errorTitle` is the normalized form of
+     * `errorMessage` and matches the `normalized_title` of the corresponding
+     * `analytics errors-groups` row, so the two commands compose. The failed-step
+     * fields are the run's own denormalized attribution — the step's `id`/`kind`
+     * and the normalized title of its error, never the stack-bearing
+     * `errorDetails` (which stays behind `runs error`).
+     */
+    errorTitle?: string;
+    failedStepId?: string;
+    failedStepKind?: string;
+    failedStepErrorTitle?: string;
+}
+export interface WorkflowStepDetail {
+    stepId?: string;
+    stepIndex?: number;
+    stepKind?: string;
+    inputTokens?: number;
+    outputTokens?: number;
+    totalTokens?: number;
+    /** The error *message* only — never the stack-bearing `errorDetails`. */
+    error?: string;
+}
+export interface WebhookDetail {
+    externalEventId?: string;
+    /**
+     * The signature-derived replay-suppression key. Present on `accepted`
+     * deliveries only; the `duplicate` row a later replay produces carries none,
+     * so this key identifies the accepted delivery a duplicate collapsed into.
+     *
+     * It always begins with a reserved tag naming which domain it came from:
+     * `sha256:` a digest the platform computed over the signed payload, `id:` an
+     * identifier the delivery itself carried, `cap:` the rehash of a key too long
+     * for the index. The tags keep the domains from overlapping, so a carried id
+     * can never name a platform digest.
+     */
+    dedupKey?: string;
+    httpStatus?: number;
+    rejectionReason?: string;
+    workflowRunId?: string;
+    payloadSummary?: string;
+    processingDurationMs?: number;
+}
+export interface ActivityDetail {
+    action?: string;
+    feature?: string;
+    route?: string;
+    country?: string;
+    /**
+     * The caller-supplied event context. Genuinely open (an app writes whatever
+     * it logs), so it rides as `unknown` rather than being flattened or typed.
+     */
+    context?: unknown;
+    inputTokens?: number;
+    outputTokens?: number;
+    totalTokens?: number;
+}
+export interface IntegrationLogEntry extends BaseLogEntry {
+    source: "integration";
+    /** HTTP status code from the upstream call. */
+    nativeStatus: number | null;
+    detail: IntegrationDetail;
+}
+export interface WorkflowRunLogEntry extends BaseLogEntry {
+    source: "workflow-run";
+    nativeStatus: string | null;
+    detail: WorkflowRunDetail;
+}
+export interface WorkflowStepLogEntry extends BaseLogEntry {
+    source: "workflow-step";
+    nativeStatus: string | null;
+    detail: WorkflowStepDetail;
+}
+export interface WebhookLogEntry extends BaseLogEntry {
+    source: "webhook";
+    nativeStatus: string | null;
+    detail: WebhookDetail;
+}
+export interface ActivityLogEntry extends BaseLogEntry {
+    source: "activity";
+    /** Activity events carry no success/failure status. */
+    nativeStatus: null;
+    detail: ActivityDetail;
+}
+export type LogEntry = IntegrationLogEntry | WorkflowRunLogEntry | WorkflowStepLogEntry | WebhookLogEntry | ActivityLogEntry;
+export interface RawIntegrationLog {
+    timestamp?: string;
+    status?: number;
+    method?: string;
+    path?: string;
+    durationMs?: number;
+    source?: string;
+    requestBytes?: number;
+    responseBytes?: number;
+    errorCode?: string;
+    actorType?: string;
+    actorId?: string;
+    actorEmail?: string;
+    traceId?: string;
+    integrationKey?: string;
+    workflowKey?: string;
+    runId?: string;
+    stepId?: string;
+}
+export interface RawWorkflowRun {
+    runId?: string;
+    status?: string;
+    startedAt?: string;
+    executionStartedAt?: string | null;
+    endedAt?: string | null;
+    queueDelayMs?: number | null;
+    createCallDurationMs?: number | null;
+    isPreview?: boolean;
+    workflowId?: string;
+    workflowKey?: string;
+    startedByUserId?: string | null;
+    initiatorKind?: string | null;
+    errorMessage?: string | null;
+    errorCode?: string | null;
+    skipReason?: string | null;
+    errorTitle?: string | null;
+    failedStepId?: string | null;
+    failedStepKind?: string | null;
+    failedStepErrorTitle?: string | null;
+}
+export interface RawWorkflowStepRun {
+    stepRunId?: string;
+    runId?: string;
+    stepId?: string;
+    stepIndex?: number;
+    stepKind?: string;
+    status?: string;
+    startedAt?: string;
+    endedAt?: string;
+    durationMs?: number;
+    inputTokens?: number;
+    outputTokens?: number;
+    totalTokens?: number;
+    error?: string;
+}
+export interface RawWebhookEvent {
+    eventId?: string;
+    webhookId?: string;
+    externalEventId?: string;
+    dedupKey?: string | null;
+    status?: string;
+    httpStatus?: number;
+    rejectionReason?: string;
+    workflowRunId?: string;
+    payloadSummary?: string;
+    processingDurationMs?: number;
+    createdAt?: string;
+}
+export interface RawActivityRow {
+    timestamp?: string;
+    user_ulid?: string;
+    action?: string;
+    feature?: string;
+    route?: string;
+    country?: string;
+    context_json?: unknown;
+    duration_ms?: number;
+    input_tokens?: number;
+    output_tokens?: number;
+    total_tokens?: number;
+    [key: string]: unknown;
+}
+/** HTTP status → outcome: `<400` ok, `>=400` error, absent neutral. */
+export declare function integrationOutcome(httpStatus: number | null | undefined): Outcome;
+/**
+ * Workflow *run* status → outcome:
+ *   completed → ok; failed/terminated → error;
+ *   queued/running/apply_pending/apply_claimed → pending;
+ *   missing → neutral; else neutral.
+ *
+ * The cases cover the full canonical run-status vocabulary (`lib/run-status.ts`,
+ * #2348) — since that change the server reconciles every status surface onto
+ * those eight values, so nothing else should reach the default. `missing` (no
+ * live instance to report on) stays neutral rather than error: it says the
+ * platform lost sight of the run, not that the run failed. That matches the
+ * outcome table published in
+ * `primitive-docs/guides/latest/AGENT_GUIDE_TO_PRIMITIVE_INSPECTION.template.md`.
+ */
+export declare function workflowRunOutcome(status: string | null | undefined): Outcome;
+/**
+ * Workflow *step* status → outcome:
+ *   completed → ok; failed/error_captured → error; skipped → neutral.
+ */
+export declare function workflowStepOutcome(status: string | null | undefined): Outcome;
+/**
+ * Webhook event status → outcome. Documented policy table:
+ *   accepted / duplicate / handshake / workflow_inactive → ok
+ *   rejected / error → error
+ *   (anything else) → neutral
+ *
+ * `workflow_inactive` maps to `ok` on purpose: the event was accepted, it
+ * just wasn't dispatched to a live workflow. Treating it as an error would
+ * mislead a debugging session into reading a non-dispatch as a failure.
+ */
+export declare function webhookOutcome(status: string | null | undefined): Outcome;
+export declare function toIntegrationInspectionRow(raw: RawIntegrationLog): IntegrationLogEntry;
+export declare function toWorkflowRunInspectionRow(raw: RawWorkflowRun): WorkflowRunLogEntry;
+/**
+ * The CLI's single answer to "which step failed this run" (#2074).
+ *
+ * The server denormalizes the failed step onto the run row using one selector
+ * (`src/workflows/failed-step.ts`: lowest `stepIndex` with `status: "failed"`).
+ * When that attribution is present, this returns exactly that row, so the STEP
+ * column in `runs failures` and the drill-down in `runs error` can never name
+ * different steps for the same run. Runs written before that change (or by a
+ * launch-time failure that held no step results) carry no `failedStepId`; the
+ * fallback applies the same rule locally — lowest `stepIndex` first — instead
+ * of trusting whatever order the step-run query returned.
+ */
+export declare function selectFailedStepRow<T extends {
+    stepId?: string;
+    status?: string;
+    stepIndex?: number;
+}>(steps: readonly T[] | null | undefined, failedStepId?: string | null): T | null;
+/** Longest ERROR cell the `runs failures` table prints before truncating. */
+export declare const FAILURE_ERROR_CELL_MAX_LENGTH = 50;
+/**
+ * The STEP cell of `workflows runs failures` (#2074). `-` is a routine
+ * outcome, not a bug: every launch-time failure (a run that aborted before any
+ * step ran, a reclaimed run, an output-schema violation after all steps
+ * completed) legitimately has no failed step to name, as do runs written before
+ * the attribution shipped.
+ */
+export declare function formatFailureStepCell(failedStepId?: string | null): string;
+/**
+ * The CODE cell of `workflows runs failures` / `runs error` (#2636). `-` is the
+ * routine case: the platform classifies only the failures it owns (a lost
+ * declarative-lock race, an exhausted lock wait), so every other failure — and
+ * every run written before the codes — reads `-`.
+ */
+export declare function formatFailureCodeCell(errorCode?: string | null): string;
+/**
+ * The ERROR cell of `workflows runs failures` (#2074). The full untruncated
+ * message stays available in `--json` and in `runs error <runId>`; the table
+ * truncates so the row still fits a terminal.
+ */
+export declare function formatFailureErrorCell(errorMessage?: string | null): string;
+export declare function toWorkflowStepInspectionRow(raw: RawWorkflowStepRun): WorkflowStepLogEntry;
+export declare function toWebhookInspectionRow(raw: RawWebhookEvent): WebhookLogEntry;
+/**
+ * Activity events have no success/failure status, so `outcome` is `neutral`
+ * (never a fabricated `ok`) and `nativeStatus` is null. `detail` is a strict
+ * allowlist of the operator-facing fields (what happened, plus the app's own
+ * `context_json` and the recorded token counts) — every infrastructure-shaped
+ * field present on the wire (`colo`, `connection_id`, `region_code`,
+ * `entity_key`, …) is dropped by construction, not enumerated as a denylist.
+ */
+export declare function toActivityInspectionRow(raw: RawActivityRow): ActivityLogEntry;
+/** Build the "flag not supported for this source" message (behavior 12). */
+export declare function unsupportedFlagMessage(flag: string, source: string, supported: string[]): string;
+/**
+ * Reject any provided flag that the source cannot serve, with a clear message
+ * listing the supported flags — never a silent no-op. `provided` maps flag
+ * names to their (possibly undefined) values; only flags with a defined value
+ * are checked. Throws on the first unsupported flag.
+ */
+export declare function assertSupportedFlags(source: string, provided: Record<string, unknown>, supported: string[]): void;
+/** Unpaginated envelope: a source whose endpoint returns a bounded item list. */
+export interface UnpaginatedEnvelope<T extends LogEntry> {
+    items: T[];
+}
+/**
+ * Paginated envelope (#1316): workflow runs and webhook events. `cursor` is a
+ * deprecated dual-emit alias of `nextCursor`, passed through verbatim so a
+ * caller reading either key keeps working.
+ */
+export interface PaginatedEnvelope<T extends LogEntry> {
+    items: T[];
+    nextCursor: string | null;
+    hasMore: boolean;
+    /** @deprecated #1316 alias of `nextCursor`. */
+    cursor: string | null;
+    /**
+     * Index rows the server examined (#2237). Present only for filtered reads
+     * that walk the index, and only against a server new enough to report it.
+     * On a multi-request sweep this is the sum across every resumed page.
+     */
+    scanned?: number;
+}
+/** Activity envelope: WAE is offset-paged, not cursor-paged. */
+export interface ActivityEnvelope {
+    items: ActivityLogEntry[];
+    page: number;
+    pageSize: number;
+    totalRows: number;
+}
+/** The raw #1316 pagination fields a list endpoint returns (all optional). */
+export interface RawPage {
+    nextCursor?: string | null;
+    hasMore?: boolean;
+    /** @deprecated alias of `nextCursor`. */
+    cursor?: string | null;
+    /** Index rows examined by this request (#2237); filtered reads only. */
+    scanned?: number;
+}
+/**
+ * The raw `analytics/events` response shape (offset-paged, snake_case). `rows`
+ * is `unknown[]` because the WAE row is dynamic per source and carries
+ * infrastructure-shaped fields the adapter deliberately drops — each row is
+ * narrowed to `RawActivityRow` inside the builder before the allowlist runs.
+ */
+export interface RawActivityResponse {
+    rows?: unknown[];
+    page?: number;
+    page_size?: number;
+    total_rows?: number;
+}
+export declare function buildIntegrationEnvelope(raw: RawIntegrationLog[]): UnpaginatedEnvelope<IntegrationLogEntry>;
+export declare function buildWorkflowRunEnvelope(raw: RawWorkflowRun[], page?: RawPage): PaginatedEnvelope<WorkflowRunLogEntry>;
+export declare function buildWorkflowStepEnvelope(raw: RawWorkflowStepRun[]): UnpaginatedEnvelope<WorkflowStepLogEntry>;
+export declare function buildWebhookEnvelope(raw: RawWebhookEvent[], page?: RawPage): PaginatedEnvelope<WebhookLogEntry>;
+/**
+ * Normalize the `analytics/events` response into the activity envelope:
+ * `{page_size, rows}` → `{pageSize, items}`, `total_rows` → `totalRows`, and
+ * every row projected through the activity allowlist so infrastructure-shaped
+ * fields (`colo`, `connection_id`, …) are dropped by construction (behavior 9).
+ */
+export declare function buildActivityEnvelope(resp: RawActivityResponse): ActivityEnvelope;
+/** Server cap on `limit` for the run-list routes. */
+export declare const RUN_LIST_MAX_LIMIT = 200;
+/**
+ * Default ceiling on index rows a single `runs failures` sweep will examine.
+ *
+ * The ceiling is checked between requests, against the `scanned` the server
+ * reports — the server has no public per-request scan-budget parameter, so the
+ * CLI cannot bound a request before issuing it. A sweep therefore stops at the
+ * first request boundary at or past `--max-scan`, which means it can examine up
+ * to one server request's worth of extra rows (the filtered read is bounded at
+ * {@link SERVER_SCAN_ROWS_PER_REQUEST}). `--max-scan 100` really examines that
+ * many rows, not 100 — so the bound is documented as "to the nearest request"
+ * in the help text, the docs page and the agent guide rather than left to
+ * surprise the caller (#2237 review; #2280 tracks a real per-request budget
+ * parameter). The count the command *reports* is always the true `scanned`, so
+ * nothing it prints is wrong — only the flag's granularity is coarse.
+ */
+export declare const DEFAULT_FAILURE_SWEEP_MAX_SCAN = 5000;
+/**
+ * Rows a single filtered server request examines at most
+ * (`BOUNDED_SCAN_MAX_SCANNED` in `src/app-api/helpers/bounded-index-scan.ts`).
+ * Documented here because it is the granularity of `--max-scan`.
+ */
+export declare const SERVER_SCAN_ROWS_PER_REQUEST = 1000;
+/**
+ * Hard ceiling on requests per sweep. `--max-scan` is the user-facing bound,
+ * but it is enforced from the server's `scanned` field — an older server that
+ * does not report it would otherwise let the loop run until the index ended.
+ *
+ * It is independent of `--max-scan`, so a sweep that stops here reports its own
+ * stop reason (`"request-ceiling"`): telling a user who already passed
+ * `--max-scan 0` to raise `--max-scan` is advice they cannot act on (#2237
+ * review).
+ */
+export declare const FAILURE_SWEEP_MAX_REQUESTS = 200;
+/** Why a sweep stopped. Determines which of the honest messages is printed. */
+export type FailureSweepStop = 
+/** Collected the requested number of failures. */
+"collected"
+/** Reached the true end of history — the answer is complete. */
+ | "exhausted"
+/** Hit `--max-scan` with history left. */
+ | "max-scan"
+/**
+ * Hit `FAILURE_SWEEP_MAX_REQUESTS` with history left. Only `--cursor` can
+ * continue from here — raising `--max-scan` does not move this ceiling.
+ */
+ | "request-ceiling"
+/** Ctrl-C. Partial result, still honest about it. */
+ | "interrupted";
+export interface FailureSweepPage extends RawPage {
+    items?: RawWorkflowRun[];
+}
+export interface FailureSweepRequest {
+    cursor?: string;
+    limit: number;
+}
+export interface FailureSweepOptions {
+    /** How many FAILURES to collect (not how many runs to look at). */
+    limit: number;
+    /** Ceiling on index rows examined across the whole sweep; `0` = uncapped. */
+    maxScan?: number;
+    /** Resume position from `--cursor`. */
+    startCursor?: string;
+    /** Called after each request with the running row count, for a TTY line. */
+    onProgress?: (scanned: number, collected: number) => void;
+    /** Cooperative cancellation (Ctrl-C): checked between requests. */
+    shouldStop?: () => boolean;
+    /** Test hook; defaults to `FAILURE_SWEEP_MAX_REQUESTS`. */
+    maxRequests?: number;
+}
+export interface FailureSweepResult {
+    items: RawWorkflowRun[];
+    /** Summed `scanned` across every request in the sweep. */
+    scanned: number;
+    /**
+     * False when the server never reported `scanned` (an older server). The
+     * caller must then omit row counts from its messaging rather than print `0`
+     * or `NaN` runs searched.
+     */
+    scannedKnown: boolean;
+    /** Resume position, or `null` when history is exhausted. */
+    nextCursor: string | null;
+    /** Requests issued. */
+    requests: number;
+    /**
+     * True when the sweep started from a caller-supplied `--cursor`. `scanned`
+     * then counts rows from THAT position, not from the head of the index, so
+     * the messaging must not call them "the most recent runs" (#2237 review).
+     */
+    resumed: boolean;
+    stoppedBecause: FailureSweepStop;
+}
+/**
+ * Walk the bounded server-side scan until `limit` FAILURES are collected,
+ * history is exhausted, or `maxScan` index rows have been examined (#2237).
+ *
+ * `--limit N` has always been documented as "Number of failures to show", but
+ * it was passed straight through as the server's `limit` — and the server's
+ * filtered read is bounded, so a workflow with a long success streak answered
+ * with an empty page plus a cursor and the CLI printed "No failures found."
+ * The bound has to live somewhere: keeping it in the server would either make
+ * every filtered request expensive or still lie one streak deeper, so it lives
+ * here, where it is explicit (`--max-scan`), tunable and interruptible.
+ *
+ * Extracted from the command so the loop is unit-testable without a server:
+ * the aggregation of `scanned` across resumed pages is exactly the thing a
+ * future caller would get wrong, and the repeated-cursor guard (borrowed from
+ * `paginateAll`) is what keeps a non-advancing server cursor from hanging the
+ * command.
+ */
+export declare function collectWorkflowFailures(fetchPage: (req: FailureSweepRequest) => Promise<FailureSweepPage>, options: FailureSweepOptions): Promise<FailureSweepResult>;
+/**
+ * The empty-state line for a run-list PAGE (`runs list`) (#2237).
+ *
+ * `runs list` stays a pager — its `--limit` is a page size and it does not
+ * auto-resume (that would make one flag mean two different things depending on
+ * whether `--status` was passed). But a filtered page comes from the same
+ * bounded index walk, so "No runs found." asserts the same absence it cannot
+ * back up. This says how far the read got and how to continue instead.
+ *
+ * `resumed` is true when the caller passed `--cursor`: the rows this page
+ * examined then start at that position rather than at the head of the index, so
+ * calling them "the most recent runs" would be false (#2237 review).
+ */
+export declare function describeEmptyRunPage(page: RawPage, resumed?: boolean): string;
+/**
+ * The line `runs failures` prints under (or instead of) its table (#2237).
+ *
+ * The unconditional "No failures found." was the defect the issue named as
+ * "the worst possible failure mode for a triage command": a bounded search
+ * that stopped early asserted the absence of failures it had never reached.
+ * Every form below either states the search was complete or says how far it
+ * got and how to continue — and none of them claims absence it cannot back up.
+ *
+ * Returns `null` when the result speaks for itself (a full set of failures
+ * from a completed search).
+ */
+export declare function describeFailureSweep(result: FailureSweepResult, limit: number): string | null;
+export {};