const failureMessages = RUN_OUTCOME_OPERATIONS[operation]

if (!failureMessages) return null

if (!payload || typeof payload !== 'object' || Array.isArray(payload)) return null

const { status, error } = payload as { status?: unknown; error?: unknown }

if (typeof status !== 'string') return null

const fallback = failureMessages[status]

if (!fallback) return null

const reported = (error as { message?: unknown } | null | undefined)?.message

return safeOneLine(typeof reported === 'string' && reported ? reported : fallback)

const failed = lengthOf(payload.failed)

if (failed === 0 && payload.success !== false) return null

return `${failed > 0 ? `Invitation batch failed for ${failed} ${failed === 1 ? 'recipient' : 'recipients'}.` : 'Invitation batch failed.'} Successful results remain committed; inspect failed recipients before retrying.`

if (countOf((payload.deletedItems as { files?: unknown } | undefined)?.files) > 0) return null

const requested = lengthOf(body?.fileIds)

if (requested === 0) return null

return `Deleted nothing: none of the ${requested} requested ${requested === 1 ? 'file was' : 'files were'} deleted.`

const items = payload.deletedItems as { files?: unknown; folders?: unknown } | undefined

if (countOf(items?.files) + countOf(items?.folders) > 0) return null

const requested = lengthOf(body?.fileIds) + lengthOf(body?.folderIds)

if (requested === 0) return null

return `Archived nothing: none of the ${requested} requested ${requested === 1 ? 'item was' : 'items were'} archived.`

if (lengthOf(payload.added) > 0) return null

const failed = lengthOf(payload.failed)

if (failed === 0) return null

return `Indexed nothing: none of the ${failed} requested ${failed === 1 ? 'file was' : 'files were'} added.`

const items = payload.deletedItems as { tables?: unknown; folders?: unknown } | undefined

const deleted = countOf(items?.tables) + countOf(items?.folders)

if (deleted > 0) return null

const missed = lengthOf(payload.notFound) + lengthOf(payload.failed)

if (missed === 0) return null

return `Deleted nothing: ${missed} of ${missed} ${missed === 1 ? 'item was' : 'items were'} not found or could not be deleted.`

if (countOf(payload.processed) > 0) return null

const requested = lengthOf(body?.chunkIds)

if (requested === 0) return null

const reported = (payload.errors as unknown[] | undefined)?.[0]

return typeof reported === 'string' && reported

? safeOneLine(reported)

: `Updated nothing: none of the ${requested} requested ${requested === 1 ? 'chunk' : 'chunks'} matched.`

if (countOf(payload.deletedCount) > 0) return null

const requested = countOf(payload.requestedCount)

if (requested === 0) return null

return `Deleted nothing: none of the ${requested} requested ${requested === 1 ? 'row was' : 'rows were'} deleted.`

if (lengthOf(payload.moved) > 0) return null

const missed = lengthOf(payload.notFound) + lengthOf(payload.failed)

if (missed === 0) return null

return `Moved nothing: ${missed} of ${missed} ${missed === 1 ? 'item was' : 'items were'} not found or could not be moved.`

if (lengthOf(payload.moved) > 0) return null

const failed = lengthOf(payload.failed)

if (failed === 0) return null

return `Moved nothing: ${failed} of ${failed} ${failed === 1 ? 'workflow' : 'workflows'} could not be moved.`

const authType = payload.authType ?? body?.authType ?? 'public'

return authType === 'public'

? 'note: auth type is public — anyone with the link can chat; pass --auth-type password|email to restrict it.'

: null

operation: V2OperationName,

payload: unknown,

body: Record<string, unknown> | undefined

): void {

const note = RESULT_NOTES[operation]

if (!note) return

const record =

payload && typeof payload === 'object' && !Array.isArray(payload)

? (payload as Record<string, unknown>)

: {}

const message = note(record, body)

if (message) writeStderr(styles().dim(`${message}\n`))

operation: V2OperationName,

payload: unknown,

body: Record<string, unknown> | undefined

): string | null {

const check = BULK_OUTCOME_CHECKS[operation]

if (!check) return null

if (!payload || typeof payload !== 'object' || Array.isArray(payload)) return null

return check(payload as Record<string, unknown>, body)

const text = String(raw ?? defaultListLimit(operation)).trim()

const value = text === '' ? Number.NaN : Number(text)

if (!Number.isInteger(value) || value < 0) {

throw new SimApiError('--limit must be a whole number of 0 or more (0 for everything)', 0)

}

return value

const exclusive = EXCLUSIVE_CAP_FIELDS[operation]

if (!exclusive) return

const cap = flagNameFor(operation, exclusive.cap)

const ids = flagNameFor(operation, exclusive.ids)

if (flags[camel(cap)] === undefined || flags[camel(ids)] === undefined) return

throw new SimApiError(

`--${cap} caps a --filter match and does nothing to an explicit --${ids} list; pass one, not both`,

0

)

const selector = REQUIRED_SELECTORS[operation]

if (!selector) return

const [first, second] = selector.fields.map((field) => flagNameFor(operation, field))

const given = [first, second].filter((name) => flags[camel(name)] !== undefined)

if (given.length === 1) return

throw new SimApiError(

given.length === 0

? `--${first} or --${second} is required to choose the ${selector.noun}`

: `--${first} and --${second} choose the ${selector.noun} two different ways; pass one, not both`,

0

)

operation: V2OperationName,

commandSpec: CommandSpec,

flags: Record<string, unknown>

): void {

for (const [field, flag] of Object.entries(commandSpec.flags ?? {})) {

const current = flagNameFor(operation, field)

for (const { name, renamed } of otherSpellings(flag)) {

const supplied = flags[camel(name)]

if (supplied === undefined) continue

if (flags[camel(current)] !== undefined) {

throw new SimApiError(

`--${name} is ${renamed ? 'the former name' : 'another spelling'} of --${current}; pass one, not both`,

0

)

}

if (renamed) warnRenamedFlag(name, current)

flags[camel(current)] = supplied

}

}

operation: V2OperationName,

commandSpec: CommandSpec,

operationSpec: OperationSpec,

invocation: unknown[]

): Promise<void> {

const host = invocation[invocation.length - 1] as Command

const inheritedFlags = host.optsWithGlobals() as Record<string, unknown>

const flags: Record<string, unknown> = {

...(inheritedFlags.workspace === undefined ? {} : { workspace: inheritedFlags.workspace }),

...(inheritedFlags.allWorkspaces === undefined

? {}

: { allWorkspaces: inheritedFlags.allWorkspaces }),

...(invocation[invocation.length - 2] as Record<string, unknown>),

}

const pathPositionalCount = operationSpec.pathParams.filter(

(param) => !commandSpec.pathFlags?.[param] && !isProfileWorkspacePath(commandSpec, param)

).length

const positional = invocation.slice(0, pathPositionalCount) as string[]

const requestFlags: Record<string, unknown> = { ...flags }

for (const [index, field] of (commandSpec.positionals ?? []).entries()) {

requestFlags[camel(flagNameFor(operation, field))] = invocation[pathPositionalCount + index]

}

const trailing = trailingListField(commandSpec)

const trailingValues = trailing

? invocation[pathPositionalCount + (commandSpec.positionals?.length ?? 0)]

: undefined

if (trailing && Array.isArray(trailingValues) && trailingValues.length > 0) {

const name = flagNameFor(operation, trailing)

if (requestFlags[camel(name)] !== undefined) {

throw new SimApiError(`Pass the ${name} as arguments or with --${name}, not both`, 0)

}

requestFlags[camel(name)] = trailingValues

}

foldOtherSpellings(operation, commandSpec, requestFlags)

assertCapIsUsable(operation, requestFlags)

assertSelectorIsUsable(operation, requestFlags)

/**

if (commandSpec.confirm && !requestFlags.yes && requestFlags.dryRun !== true) {

throw new SimApiError(`${commandSpec.confirm} Re-run with --yes to confirm.`, 0)

}

if (commandSpec.allWorkspaces && requestFlags.allWorkspaces && requestFlags.workspace) {

throw new SimApiError('--all-workspaces cannot be combined with --workspace', 0)

}

const { client, profile } = connect(host)

const hasWorkspaceField = Boolean(

(operationSpec.query && PROFILE_INJECTED_FIELD in operationSpec.query) ||

(operationSpec.body && PROFILE_INJECTED_FIELD in operationSpec.body)

)

const omitsWorkspace = commandSpec.allWorkspaces && requestFlags.allWorkspaces === true

/**

const needsWorkspace =

(hasWorkspaceField || commandSpec.profileWorkspacePath === true) && !omitsWorkspace

const paging = cursorSlot(operationSpec)

/**

const pagedLimit = paging ? readPagedLimit(requestFlags.limit, operation) : 0

const requestWorkspaceId = needsWorkspace ? client.requireWorkspace() : profile.workspaceId

const request = await buildRequest(operation, positional, requestFlags, requestWorkspaceId)

if (commandSpec.workspaceOperation) {

if (!WORKSPACE_OPERATION_KINDS[operation])

throw new SimApiError('This command has no workspace operation identity configured', 0)

workspaceWaitTimeout(requestFlags.waitTimeout)

if (requestFlags.waitTimeout !== undefined && requestFlags.wait !== true)

throw new SimApiError('--wait-timeout requires --wait', 0)

if (

requestFlags.wait === true &&

(!request.body?.requestId || !request.body?.previewFingerprint)

)

throw new SimApiError(

'--wait requires --request-id and --preview-fingerprint from the reviewed preview',

0

)

if (operationSpec.body?.confirm && requestFlags.yes === true && request.body)

request.body.confirm = true

}

if (paging) {

const initialCursor = request[paging]?.cursor

if (

initialCursor !== undefined &&

(typeof initialCursor !== 'string' || initialCursor.trim() === '')

) {

throw new SimApiError('--cursor must be a non-empty string', 0)

}

const limit = pagedLimit === 0 ? Number.POSITIVE_INFINITY : pagedLimit

const rows: unknown[] = []

const seenCursors = new Set<string>(initialCursor ? [initialCursor] : [])

const progress = pageProgress()

let cursor: string | null = initialCursor ?? null

/** The first page's envelope: where a fact about the whole query is stated. */

let envelope: unknown

// `finally`, for the same reason as `requestAllPages`: a page that throws

// would otherwise leave the progress text on the line the error prints onto.

try {

do {

const pageSize = Math.min(DEFAULT_PAGE_SIZE, limit - rows.length)

const pageLimit = 'limit' in (operationSpec[paging] ?? {}) ? { limit: pageSize } : {}

const page: V2Page<unknown> = await client.request(operation, {

params: request.params,

headers: request.headers,

query: paging === 'query' ? { ...request.query, ...pageLimit, cursor } : request.query,

body:

paging === 'body'

? { ...(request.body ?? {}), ...pageLimit, ...(cursor ? { cursor } : {}) }

: request.body,

})

if (page.data.length > pageSize) {

throw new SimApiError(

`The API returned ${page.data.length} items for a page limit of ${pageSize}; nextCursor would skip unreturned items.`,

0

)

}

assertCursorAdvances(page.nextCursor, seenCursors)

envelope = foldPageEnvelope(envelope, page)

rows.push(...page.data)

cursor = page.nextCursor

if (cursor && rows.length < limit) progress.advance(rows.length)

} while (cursor && rows.length < limit)

} finally {

progress.finish()

}

renderPage(profile.output, { data: rows, nextCursor: cursor }, commandSpec, envelope)

return

}

let result: { data?: unknown }

try {

result = await client.request<{ data?: unknown }>(operation, {

params: request.params,

headers: request.headers,

query: request.query,

body: request.body,

})

} catch (error) {

if (

commandSpec.workspaceOperation &&

request.body?.requestId &&

(!(error instanceof SimApiError) ||

error.status === 0 ||

error.status >= 500 ||

(error.status >= 200 && error.status < 300))

) {

const failure =

error instanceof SimApiError

? error

: new SimApiError(getErrorMessage(error, 'Unable to read the mutation response'), 0)

throw new SimApiError(

failure.message,

failure.status,

'MUTATION_OUTCOME_UNKNOWN',

{

cause: failure.details,

requestId: request.body.requestId,

workspaceId: requestWorkspaceId,

applied: 'unknown',

reconciliation:

'Find the operation using this requestId, or retry identical inputs with the same requestId.',

},

failure.exitCode

)

}

throw error

}

let payload = result?.data ?? result

if (

commandSpec.workspaceOperation &&

(Boolean(request.body?.requestId) ||

requestFlags.wait === true ||

(payload && typeof payload === 'object' && 'operationId' in payload))

) {

let report

try {

report = readWorkspaceOperation(payload)

const expectedRequestId =

operation !== 'importWorkflow' && typeof request.body?.requestId === 'string'

? request.body.requestId.trim()

: request.body?.requestId

if (

report.requestId !== expectedRequestId ||

report.workspaceId !== requestWorkspaceId ||

report.kind !== WORKSPACE_OPERATION_KINDS[operation]

)

throw new SimApiError('The operation receipt does not match the submitted mutation', 0)

} catch {

throw new SimApiError(

'The mutation response did not contain a matching operation receipt; reconcile using the same request ID',

0,

'MUTATION_OUTCOME_UNKNOWN',

{ requestId: request.body?.requestId, workspaceId: requestWorkspaceId, applied: 'unknown' }

)

}

let timedOut = false

if (requestFlags.wait === true)

({ report, timedOut } = await waitWorkspaceOperation(

client,

report.workspaceId,

report.operationId,

workspaceWaitTimeout(requestFlags.waitTimeout),

report

))

payload = report

renderResult(operation, profile.output, payload, commandSpec)

assertWorkspaceOperationOutcome(report, timedOut)

return

}

renderResult(

operation,

profile.output,

payload,

commandSpec,

{ expandedTrace: requestFlags.trace === true },

// The envelope, not just the payload: a list that does not paginate states

// its own truncation there, and unwrapping `data` discarded it.

result

)

writeResultNote(operation, payload, request.body)

// Printed first, then failed, for the reason `followRun` gives: the envelope

// carries the block outputs that explain *why* the run failed, and exiting

// before writing it would leave a piped consumer an exit code and nothing to

// read.

const failure =

runFailureMessage(operation, payload) ?? bulkFailureMessage(operation, payload, request.body)

if (failure) throw new SimApiError(failure, 0)