@north-light/api 0.3.580 → 0.3.588

package/dist/core/human/tickets.d.ts

@@ -0,0 +1,68 @@
+import type { TicketResult } from './types.js';
+import type { PreparedPage } from './page-authoring.js';
+import { type PageManifest, type PageResponses } from './page-schema.js';
+/** Strict decoder for the canonical SQL terminal result. A corrupt result throws
+ *  rather than being treated as absent, because that would hide data loss from
+ *  the caller that owns the failure boundary. */
+export declare function readTicketResult(dir: string): Promise<TicketResult | null>;
+/** Publish an immutable revision, then atomically select it with its matching specification. */
+export declare function publishPage(dir: string, prepared: PreparedPage): Promise<{
+    id: string;
+    dir: string;
+    kind: 'page';
+    manifest: PageManifest;
+}>;
+/** Resolve a stable request directory to the SQL-selected immutable page revision. */
+export declare function selectedPageDir(dir: string): Promise<string>;
+/** Validate a final page response against its ticket's reply contract. */
+export declare function validateFinalPageResponses(manifest: PageManifest, responses: unknown): PageResponses;
+/** Validate a page resolution against its SQL-selected immutable revision. */
+export declare function validatePageTicketResponses(dir: string, responses: unknown): Promise<PageResponses>;
+/** Page state is derived from the SQL request row. */
+export declare function pageTicketState(dir: string): Promise<'pending' | 'resolved' | 'canceled' | 'passive'>;
+/** Autosave partial page work. Every supplied response is validated; omitted components are permitted. */
+export declare function writePageProgress(dir: string, responses: unknown): Promise<PageResponses>;
+/** Saved partial work from the request row, or null when none exists. */
+export declare function readPageProgress(dir: string): Promise<PageResponses | null>;
+export interface PageTicket {
+    dir: string;
+    id: string;
+    manifest: PageManifest;
+    /** The authored TSX source document, verbatim. */
+    document: string;
+    /** The compiled module the Gateway evaluates, for JSX pages. */
+    module?: string;
+    state: 'pending' | 'resolved' | 'canceled' | 'passive';
+    progress: PageResponses | null;
+}
+/** Read one addressable page ticket — pending, resolved or canceled alike. */
+export declare function readPageTicket(dir: string): Promise<PageTicket>;
+export interface CompletePageOptions {
+    completedAt?: string;
+    actor?: string;
+}
+/** Page settlement must go through daemon/human/finish, which records its SQL result and direct obligations together. */
+export declare function completePage(_dir: string, _responses: unknown, _claimToken: string, _opts?: CompletePageOptions): {
+    won: boolean;
+    result: TicketResult;
+};
+/** Page settlement must go through daemon/human/finish, which records its SQL result and direct obligations together. */
+export declare function takeoverAndCompletePage(_dir: string, _responses: unknown, _owner: {
+    host: string;
+    pid: number;
+}, _opts?: CompletePageOptions): {
+    won: boolean;
+    result: TicketResult;
+};
+export interface CancelTicketOptions {
+    reason?: string;
+    actor?: string;
+    disposition?: 'canceled' | 'dismissed';
+}
+/** Page settlement must go through daemon/human/finish, which records its SQL result and direct obligations together. */
+export declare function cancelTicket(_dir: string, _opts?: CancelTicketOptions): {
+    status: 'canceled' | 'already_resolved';
+    result: TicketResult;
+};
+/** Review projection is performed by daemon/review/finish after its SQL terminal transition. */
+export declare function projectReviewOutput(_dir: string): 'projected' | 'not_a_review' | 'no_result';

package/dist/core/human/tickets.js

@@ -0,0 +1,175 @@
+import { mkdirSync, realpathSync } from 'node:fs';
+import { basename, isAbsolute, resolve } from 'node:path';
+import { z } from 'zod';
+import { pageModulePath, pagePath } from './convention.js';
+import { readPageManifest } from './page.js';
+import { isBlobRequestPath, readRequestText } from './request-files.js';
+import { validatePageResponses, validatePartialPageResponses } from './page-schema.js';
+import { signalInboxActivity } from './root.js';
+import { createPageRequest, getRequestByDirectory, presentationDir, publishPageRevisionTo, revisePageRequest, writeProgress as writeRequestProgress } from './requests.js';
+const feedbackCommentSchema = z.object({ id: z.string().min(1), line: z.number().int().positive(), endLine: z.number().int().positive(), quote: z.string().optional(), colStart: z.number().int().nonnegative().optional(), colEnd: z.number().int().nonnegative().optional(), lineText: z.string(), comment: z.string().min(1), createdAt: z.string().min(1) }).strict();
+const iso = z.string().datetime({ offset: true });
+const feedbackSchema = z.object({ file: z.string().min(1).refine(isAbsolute, 'file must be absolute').refine((file) => resolve(file) === file, 'file must be canonical'), submitted: z.literal(true), approved: z.boolean(), comments: z.array(feedbackCommentSchema), submittedAt: iso, savedAt: iso, reviewId: z.string().optional(), changed: z.boolean().optional(), baselineSha256: z.string().optional(), approvedSha256: z.string().optional(), companionNodeId: z.string().optional(), commentsTotal: z.number().int().nonnegative().optional(), commentsUnresolved: z.number().int().nonnegative().optional() }).strict().superRefine((result, ctx) => {
+    result.comments.forEach((comment, index) => {
+        if (comment.endLine < comment.line)
+            ctx.addIssue({ code: 'custom', message: 'endLine must be >= line', path: ['comments', index, 'endLine'] });
+        if ((comment.colStart === undefined) !== (comment.colEnd === undefined))
+            ctx.addIssue({ code: 'custom', message: 'columns must be supplied together', path: ['comments', index] });
+        if (comment.line === comment.endLine && comment.colStart !== undefined && comment.colEnd !== undefined && comment.colEnd <= comment.colStart)
+            ctx.addIssue({ code: 'custom', message: 'colEnd must exceed colStart', path: ['comments', index, 'colEnd'] });
+    });
+});
+const slotResponseSchema = z.record(z.string(), z.unknown());
+const pageResultSchema = z.object({ schema: z.literal('crtr.page-response/v1'), kind: z.literal('page'), responses: z.record(z.string(), slotResponseSchema), summary: z.string(), completedAt: iso, actor: z.string().optional() }).strict();
+const pageProgressSchema = z.object({ kind: z.literal('page'), responses: z.record(z.string(), slotResponseSchema), savedAt: iso }).strict();
+const reviewResultSchema = z.object({ schema: z.literal('humanloop.review-response/v1'), kind: z.literal('review'), result: feedbackSchema, completedAt: iso }).strict();
+const canceledResultSchema = z.object({ schema: z.literal('humanloop.cancel/v1'), kind: z.literal('canceled'), canceledAt: iso, reason: z.string().optional(), actor: z.string().optional(), disposition: z.enum(['canceled', 'dismissed']).optional() }).strict();
+/** Strict decoder for the canonical SQL terminal result. A corrupt result throws
+ *  rather than being treated as absent, because that would hide data loss from
+ *  the caller that owns the failure boundary. */
+export async function readTicketResult(dir) {
+    const request = await getRequestByDirectory(dir);
+    if (request === null)
+        throw new Error(`unknown human request directory: ${dir}`);
+    if (request.state !== 'settled' || request.result_json === null)
+        return null;
+    let raw;
+    try {
+        raw = JSON.parse(request.result_json);
+    }
+    catch (error) {
+        throw new Error(`corrupt human request result: ${request.request_id}`, { cause: error });
+    }
+    const page = pageResultSchema.safeParse(raw);
+    if (page.success)
+        return page.data;
+    const review = reviewResultSchema.safeParse(raw);
+    if (review.success)
+        return review.data;
+    const canceled = canceledResultSchema.safeParse(raw);
+    if (canceled.success)
+        return canceled.data;
+    throw new Error(`human request has an invalid terminal result: ${request.request_id}`);
+}
+/** Publish an immutable revision, then atomically select it with its matching specification. */
+export async function publishPage(dir, prepared) {
+    let ticket = dir;
+    if (!isBlobRequestPath(dir)) {
+        mkdirSync(dir, { recursive: true, mode: 0o700 });
+        ticket = realpathSync(dir);
+    }
+    const request = await getRequestByDirectory(ticket);
+    if (request === null) {
+        const created = await createPageRequest({ request_id: basename(ticket), prepared });
+        signalInboxActivity();
+        return { id: created.request_id, dir: created.request_dir, kind: 'page', manifest: prepared.manifest };
+    }
+    const revision = await publishPageRevisionTo(ticket, prepared);
+    if (!await revisePageRequest(request.request_id, {
+        presentation_dir: revision,
+        specification_json: JSON.stringify(prepared.manifest),
+        title: prepared.manifest.title,
+        subtitle: prepared.manifest.subtitle ?? null,
+        inbox_listed: prepared.manifest.delivery.inbox,
+        settleable: prepared.manifest.delivery.inbox || prepared.manifest.delivery.reply,
+    }))
+        throw new Error(`page request is not open: ${request.request_id}`);
+    signalInboxActivity();
+    return { id: request.request_id, dir: ticket, kind: 'page', manifest: prepared.manifest };
+}
+async function pageRequest(dir) {
+    const request = await getRequestByDirectory(dir);
+    if (request === null || request.kind !== 'page')
+        throw new Error(`unknown page request directory: ${dir}`);
+    return request;
+}
+/** Resolve a stable request directory to the SQL-selected immutable page revision. */
+export async function selectedPageDir(dir) { return presentationDir(await pageRequest(dir)); }
+async function requirePage(dir) {
+    return await readPageManifest(await selectedPageDir(dir));
+}
+async function requireSettleablePage(dir) {
+    const manifest = await requirePage(dir);
+    if (!manifest.delivery.inbox && !manifest.delivery.reply)
+        throw new Error('page_has_no_response_lifecycle');
+    return manifest;
+}
+function isEmptyResponseMap(responses) {
+    return typeof responses === 'object' && responses !== null && !Array.isArray(responses) && Object.keys(responses).length === 0;
+}
+/** Validate a final page response against its ticket's reply contract. */
+export function validateFinalPageResponses(manifest, responses) {
+    if (!manifest.delivery.reply && isEmptyResponseMap(responses))
+        return validatePartialPageResponses(manifest, responses);
+    return validatePageResponses(manifest, responses);
+}
+async function validateFinalPageTicketResponses(dir, responses) {
+    return validateFinalPageResponses(await requireSettleablePage(dir), responses);
+}
+/** Validate a page resolution against its SQL-selected immutable revision. */
+export async function validatePageTicketResponses(dir, responses) {
+    return await validateFinalPageTicketResponses(dir, responses);
+}
+/** Page state is derived from the SQL request row. */
+export async function pageTicketState(dir) {
+    const request = await pageRequest(dir);
+    if (!request.settleable)
+        return 'passive';
+    if (request.state !== 'settled')
+        return 'pending';
+    return request.outcome === 'canceled' || request.outcome === 'dismissed' ? 'canceled' : 'resolved';
+}
+/** Autosave partial page work. Every supplied response is validated; omitted components are permitted. */
+export async function writePageProgress(dir, responses) {
+    const request = await pageRequest(dir);
+    const validated = validatePartialPageResponses(await requireSettleablePage(dir), responses);
+    if (!await writeRequestProgress(request.inbox_ticket_id, validated))
+        throw new Error(`page request is not open and settleable: ${request.request_id}`);
+    return validated;
+}
+/** Saved partial work from the request row, or null when none exists. */
+export async function readPageProgress(dir) {
+    const request = await pageRequest(dir);
+    if (request.progress_json === null)
+        return null;
+    try {
+        const progress = JSON.parse(request.progress_json);
+        if (progress.kind !== 'page')
+            throw new Error('wrong kind');
+        return progress.responses;
+    }
+    catch (error) {
+        throw new Error(`page progress is malformed for ${request.request_id}`, { cause: error });
+    }
+}
+/** Read one addressable page ticket — pending, resolved or canceled alike. */
+export async function readPageTicket(dir) {
+    const request = await pageRequest(dir);
+    const presentation = presentationDir(request);
+    const manifest = await readPageManifest(presentation);
+    return {
+        dir: request.request_dir,
+        id: request.request_id,
+        manifest,
+        document: await readRequestText(pagePath(presentation, manifest.dialect)),
+        ...(manifest.dialect === 'jsx' ? { module: await readRequestText(pageModulePath(presentation)) } : { module: undefined }),
+        state: await pageTicketState(request.request_dir),
+        progress: manifest.delivery.inbox || manifest.delivery.reply ? await readPageProgress(request.request_dir) : null,
+    };
+}
+/** Page settlement must go through daemon/human/finish, which records its SQL result and direct obligations together. */
+export function completePage(_dir, _responses, _claimToken, _opts = {}) {
+    throw new Error('page completion must use settleHumanRequest');
+}
+/** Page settlement must go through daemon/human/finish, which records its SQL result and direct obligations together. */
+export function takeoverAndCompletePage(_dir, _responses, _owner, _opts = {}) {
+    throw new Error('page completion must use settleHumanRequest');
+}
+/** Page settlement must go through daemon/human/finish, which records its SQL result and direct obligations together. */
+export function cancelTicket(_dir, _opts = {}) {
+    throw new Error('page cancellation must use settleHumanRequest');
+}
+/** Review projection is performed by daemon/review/finish after its SQL terminal transition. */
+export function projectReviewOutput(_dir) {
+    throw new Error('review projection must use projectReviewResult');
+}

package/dist/core/human/types.d.ts

@@ -0,0 +1,118 @@
+import type { PageResponses } from './page-schema.js';
+/** Provenance stamped onto every ticket request — page and review alike. */
+export interface TicketSource {
+    sessionName?: string;
+    askedBy?: string;
+    blockedSince?: string;
+    /** Profile name the originating node runs under. Product consumers use this stable name to resolve the applet or worker identity behind the ticket. */
+    profileName?: string;
+    /** Originating canvas node id (CRTR_NODE_ID) when the ask was raised inside a crouter canvas node. */
+    nodeId?: string;
+}
+export interface FeedbackComment {
+    id: string;
+    line: number;
+    endLine: number;
+    quote?: string;
+    colStart?: number;
+    colEnd?: number;
+    lineText: string;
+    comment: string;
+    createdAt: string;
+}
+export interface FeedbackResult {
+    file: string;
+    submitted: boolean;
+    approved: boolean;
+    comments: FeedbackComment[];
+    submittedAt?: string;
+    savedAt: string;
+}
+export interface ClaimSummary {
+    owner: string;
+    claimedAt: string;
+    heartbeatAt: string;
+}
+interface TicketSummaryBase {
+    dir: string;
+    id: string;
+    /** Stored opaque inbox identity. It may differ from `id` after legacy migration. */
+    inboxTicketId: string;
+    title: string;
+    subtitle: string;
+    blockedSince: string;
+    source: TicketSource;
+    claim?: ClaimSummary;
+}
+export interface ReviewTicketSummary extends TicketSummaryBase {
+    kind: 'review';
+    file: string;
+    output: string;
+}
+/** Page triage fields: a client picks a transcript rendering without a second fetch. */
+export interface PageTicketSummary {
+    dir: string;
+    id: string;
+    /** Stored opaque inbox identity. It may differ from `id` after legacy migration. */
+    inboxTicketId: string;
+    kind: 'page';
+    title: string;
+    subtitle: string;
+    source: import('./page-schema.js').PageSource;
+    emittedAt: string;
+    claim?: ClaimSummary;
+    /** Present on resolved history entries; the stored one-line response digest. */
+    answerDigest?: string;
+    dialect: 'jsx' | 'html';
+    placement: 'inline' | 'panel';
+    inbox: boolean;
+    steps: number;
+    slotKinds: string[];
+    /** This ticket is waiting on the person: it asks something, or an agent bridge is parked on its reply. */
+    awaitsResponse: boolean;
+    /** Every question's recommended option, for a row that says what is suggested without opening the page. */
+    recommendedOptions: import('./page-schema.js').RecommendedOption[];
+    /** Present when this ticket can be settled straight from a list row; absent when only the page can answer it. */
+    fastAction?: import('./page-schema.js').PageFastAction;
+    state: 'pending' | 'resolved' | 'canceled' | 'passive';
+}
+/** The only pending-ticket shape scanners expose. */
+export type TicketSummary = ReviewTicketSummary | PageTicketSummary;
+export interface ReviewDescriptor {
+    schema: 'humanloop.review/v1';
+    file: string;
+    output: string;
+    title: string;
+    subtitle: string;
+    source: TicketSource;
+    blockedSince: string;
+}
+export interface PageTicketResult {
+    schema: 'crtr.page-response/v1';
+    kind: 'page';
+    /** An acknowledgement is the empty map; there is no second shape. */
+    responses: PageResponses;
+    summary: string;
+    completedAt: string;
+    /** Recorded when an authorized programmatic writer answered instead of a person. */
+    actor?: string;
+}
+export interface ReviewTicketResult {
+    schema: 'humanloop.review-response/v1';
+    kind: 'review';
+    result: FeedbackResult;
+    completedAt: string;
+}
+export interface CanceledTicketResult {
+    schema: 'humanloop.cancel/v1';
+    kind: 'canceled';
+    canceledAt: string;
+    reason?: string;
+    actor?: string;
+    /** Who ended it without an answer: the recipient (`dismissed`) or the
+     * requester (`canceled`). Absent on records written before the field. */
+    disposition?: 'canceled' | 'dismissed';
+}
+/** The canonical terminal-result union stored in the human request row. */
+export type TicketResult = PageTicketResult | ReviewTicketResult | CanceledTicketResult;
+export {};

package/dist/core/human/types.js

@@ -0,0 +1 @@
+export {};

package/dist/core/human/visible-paths.d.ts

@@ -0,0 +1,16 @@
+/** Extract existing file paths from surface text, preserving occurrence order. */
+export declare function extractFilePaths(texts: readonly string[], cwd: string): string[];
+/** Check whether a local file fits the review surface's limits. */
+export declare function checkReviewableFile(abs: string): {
+    ok: true;
+} | {
+    ok: false;
+    reason: string;
+};
+/** The same limits as {@link checkReviewableFile}, for bytes already read (a file, or a request file from the blob store). */
+export declare function checkReviewableBytes(bytes: Buffer): {
+    ok: true;
+} | {
+    ok: false;
+    reason: string;
+};

package/dist/core/human/visible-paths.js

@@ -0,0 +1,74 @@
+import { existsSync, readFileSync, statSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { isAbsolute, resolve } from 'node:path';
+import { documentLines } from '../document-lines.js';
+const MAX_CANDIDATES = 50;
+const MAX_FILE_BYTES = 2 * 1024 * 1024;
+const MAX_FILE_LINES = 5000;
+const PATH_TOKEN = /[A-Za-z0-9._~@\-/]+(?::\d+(?::\d+)?)?/g;
+const EXTENSION_END = /\.[A-Za-z][A-Za-z0-9]{0,15}$/;
+function normalizeCandidate(raw) {
+    let candidate = raw
+        .replace(/^[`'"(]+/, '')
+        .replace(/[`'".,;:)\]}]+$/, '');
+    candidate = candidate.replace(/:\d+(?::\d+)?$/, '');
+    return candidate.replace(/[`'".,;:)\]}]+$/, '');
+}
+function candidatePath(raw, cwd) {
+    let candidate = normalizeCandidate(raw);
+    if (!candidate || (!candidate.includes('/') && !EXTENSION_END.test(candidate)))
+        return null;
+    if (candidate.startsWith('~/'))
+        candidate = resolve(homedir(), candidate.slice(2));
+    return resolve(isAbsolute(candidate) ? candidate : resolve(cwd, candidate));
+}
+/** Extract existing file paths from surface text, preserving occurrence order. */
+export function extractFilePaths(texts, cwd) {
+    const found = [];
+    const seen = new Set();
+    for (const text of texts) {
+        for (const match of text.matchAll(PATH_TOKEN)) {
+            const abs = candidatePath(match[0], cwd);
+            if (abs === null || seen.has(abs))
+                continue;
+            try {
+                if (!existsSync(abs) || !statSync(abs).isFile())
+                    continue;
+            }
+            catch {
+                continue;
+            }
+            seen.add(abs);
+            found.push(abs);
+            if (found.length === MAX_CANDIDATES)
+                return found;
+        }
+    }
+    return found;
+}
+/** Check whether a local file fits the review surface's limits. */
+export function checkReviewableFile(abs) {
+    let bytes;
+    try {
+        if (!statSync(abs).isFile())
+            return { ok: false, reason: 'not a file' };
+        bytes = readFileSync(abs);
+    }
+    catch {
+        return { ok: false, reason: 'not a file' };
+    }
+    return checkReviewableBytes(bytes);
+}
+/** The same limits as {@link checkReviewableFile}, for bytes already read (a file, or a request file from the blob store). */
+export function checkReviewableBytes(bytes) {
+    if (bytes.length > MAX_FILE_BYTES)
+        return { ok: false, reason: 'file is too large to review (2 MB limit)' };
+    const content = bytes.toString('utf8');
+    if (content.includes('\uFFFD') || content.includes('\0')) {
+        return { ok: false, reason: 'file is not UTF-8 text' };
+    }
+    if (documentLines(content).length > MAX_FILE_LINES) {
+        return { ok: false, reason: 'file is too long to review (5,000 line limit)' };
+    }
+    return { ok: true };
+}

package/dist/core/human-actions.d.ts

@@ -0,0 +1,25 @@
+export interface ResolvedHumanAction {
+    name: string;
+    /** Absolute path of the config file that won resolution. */
+    configOrigin: string;
+    /** Fully resolved argv; argv[0] is an absolute executable path. */
+    argv: string[];
+    /** Fully resolved absolute working directory. */
+    cwd: string;
+}
+export type HumanActionIssue = {
+    kind: 'unknown_action';
+    name: string;
+} | {
+    kind: 'invalid_action';
+    name: string;
+    configOrigin: string;
+    reason: string;
+    block?: true;
+};
+/** Resolve one declared action from a creator's absolute cwd: nearest project
+ * ancestor first, then farther project ancestors, then user scope. Never
+ * consults plugin or profile config. Read-only; never executes anything. */
+export declare function resolveHumanAction(name: string, creatorCwd: string): ResolvedHumanAction | HumanActionIssue;
+/** Every declared action reachable from a cwd, with its issues, for doctor. */
+export declare function inspectHumanActions(creatorCwd: string): Array<ResolvedHumanAction | HumanActionIssue>;

package/dist/core/human-actions.js

@@ -0,0 +1,101 @@
+import { statSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { CONFIG_FILE } from '../types.js';
+import { humanActionDeclarationIssues, readRawConfigAtRoot } from './config.js';
+import { findProjectScopeRoots, scopeRoot } from './scope.js';
+function actionContributors(creatorCwd) {
+    const contributors = [];
+    for (const scopeRootPath of findProjectScopeRoots(creatorCwd, null)) {
+        const raw = readRawConfigAtRoot(scopeRootPath)?.humanActions;
+        if (raw !== undefined) {
+            contributors.push({
+                configOrigin: join(scopeRootPath, CONFIG_FILE),
+                authoringRoot: dirname(scopeRootPath),
+                raw,
+            });
+        }
+    }
+    const userRoot = scopeRoot('user');
+    if (userRoot !== null) {
+        const raw = readRawConfigAtRoot(userRoot)?.humanActions;
+        if (raw !== undefined) {
+            contributors.push({ configOrigin: join(userRoot, CONFIG_FILE), authoringRoot: userRoot, raw });
+        }
+    }
+    return contributors;
+}
+function declarationIssue(name, raw) {
+    return humanActionDeclarationIssues({ [name]: raw }).find((issue) => issue.name === name)?.reason;
+}
+function resolveDeclaredAction(name, declaration, contributor) {
+    const cwd = resolve(contributor.authoringRoot, declaration.cwd);
+    try {
+        if (!statSync(cwd).isDirectory()) {
+            return { kind: 'invalid_action', name, configOrigin: contributor.configOrigin, reason: `cwd is not a directory: ${cwd}` };
+        }
+    }
+    catch {
+        return { kind: 'invalid_action', name, configOrigin: contributor.configOrigin, reason: `cwd does not exist: ${cwd}` };
+    }
+    const executable = resolve(contributor.authoringRoot, declaration.argv[0]);
+    try {
+        const stat = statSync(executable);
+        if (!stat.isFile()) {
+            return { kind: 'invalid_action', name, configOrigin: contributor.configOrigin, reason: `argv[0] is not a regular file: ${executable}` };
+        }
+        if ((stat.mode & 0o111) === 0) {
+            return { kind: 'invalid_action', name, configOrigin: contributor.configOrigin, reason: `argv[0] lacks the POSIX exec bit: ${executable}` };
+        }
+    }
+    catch {
+        return { kind: 'invalid_action', name, configOrigin: contributor.configOrigin, reason: `argv[0] does not exist: ${executable}` };
+    }
+    return {
+        name,
+        configOrigin: contributor.configOrigin,
+        argv: [executable, ...declaration.argv.slice(1)],
+        cwd,
+    };
+}
+/** Resolve one declared action from a creator's absolute cwd: nearest project
+ * ancestor first, then farther project ancestors, then user scope. Never
+ * consults plugin or profile config. Read-only; never executes anything. */
+export function resolveHumanAction(name, creatorCwd) {
+    for (const contributor of actionContributors(creatorCwd)) {
+        if (contributor.raw === null || typeof contributor.raw !== 'object' || Array.isArray(contributor.raw))
+            continue;
+        const declarations = contributor.raw;
+        if (!Object.hasOwn(declarations, name))
+            continue;
+        const raw = declarations[name];
+        const issue = declarationIssue(name, raw);
+        if (issue !== undefined) {
+            return { kind: 'invalid_action', name, configOrigin: contributor.configOrigin, reason: issue };
+        }
+        return resolveDeclaredAction(name, raw, contributor);
+    }
+    return { kind: 'unknown_action', name };
+}
+/** Every declared action reachable from a cwd, with its issues, for doctor. */
+export function inspectHumanActions(creatorCwd) {
+    const results = [];
+    for (const contributor of actionContributors(creatorCwd)) {
+        const issues = humanActionDeclarationIssues(contributor.raw);
+        const invalid = new Map(issues.map((issue) => [issue.name, issue.reason]));
+        if (contributor.raw === null || typeof contributor.raw !== 'object' || Array.isArray(contributor.raw)) {
+            for (const issue of issues) {
+                results.push({ kind: 'invalid_action', name: issue.name, configOrigin: contributor.configOrigin, reason: issue.reason, ...(issue.block === true ? { block: true } : {}) });
+            }
+            continue;
+        }
+        for (const [name, raw] of Object.entries(contributor.raw)) {
+            const issue = invalid.get(name);
+            if (issue !== undefined) {
+                results.push({ kind: 'invalid_action', name, configOrigin: contributor.configOrigin, reason: issue });
+                continue;
+            }
+            results.push(resolveDeclaredAction(name, raw, contributor));
+        }
+    }
+    return results;
+}

package/dist/core/import/bundle/blob-keys.d.ts

@@ -0,0 +1,10 @@
+export declare const runBlobPrefix: (run: string) => string;
+export declare const runBlobKey: (run: string, key: string) => string;
+/** `node`: the owner is a node id of the bundle; `request`: a human request id of the bundle. */
+export interface ParsedBlobKey {
+    kind: 'conversation' | 'attachment' | 'job' | 'event' | 'request';
+    ownerTable: 'nodes' | 'human_requests';
+    owner: string;
+}
+/** The key's kind and owner, or null when it is none of the keys cycle 5 reads (or has an empty, `.` or `..` segment). */
+export declare function parseBlobKey(key: string): ParsedBlobKey | null;

package/dist/core/import/bundle/blob-keys.js

@@ -0,0 +1,23 @@
+// Blob keys an import moves. The exporter uploads every source blob to `imports/<run>/blobs/<key>` (the only place the upload route signs for a run);
+// the lane moves each one to `<key>` after the staged rows are bound to the run's person. `parseBlobKey` is the one definition of which keys the lane
+// moves and which row the key's owner must be in the bundle.
+export const runBlobPrefix = (run) => `imports/${run}/blobs/`;
+export const runBlobKey = (run, key) => `${runBlobPrefix(run)}${key}`;
+const SHAPES = [
+    ['conversation', /^conversations\/([^/]+)\/[^/]+\/[^/]+$/],
+    ['attachment', /^attachments\/([^/]+)\/[0-9a-f]{64}$/],
+    ['job', /^jobs\/([^/]+)\/[^/]+\/output(?:\/\d{8})?$/],
+    ['event', /^events\/([^/]+)\/\d{16}-\d{16}-[0-9a-f]{32}\.jsonl\.zst$/],
+    ['request', /^requests\/([^/]+)\/.+$/],
+];
+/** The key's kind and owner, or null when it is none of the keys cycle 5 reads (or has an empty, `.` or `..` segment). */
+export function parseBlobKey(key) {
+    if (key.split('/').some((s) => s === '' || s === '.' || s === '..'))
+        return null;
+    for (const [kind, shape] of SHAPES) {
+        const match = shape.exec(key);
+        if (match !== null)
+            return { kind, ownerTable: kind === 'request' ? 'human_requests' : 'nodes', owner: match[1] };
+    }
+    return null;
+}