@north-light/crouter 0.3.221 → 0.3.222

package/dist/core/canvas/human-deliveries.js

@@ -0,0 +1,75 @@
+// Durable action-completion delivery state. The terminal ticket is composed
+// before this row exists; this module schedules its already-complete document.
+import { openDb, withCanvasWrite } from './db.js';
+function actionDeliveryFrom(row) {
+    return {
+        requestId: row.request_id,
+        state: row.state,
+        attempt: row.attempt,
+        argv: JSON.parse(row.argv_json),
+        cwd: row.cwd,
+        completion: JSON.parse(row.completion_json),
+        nextAttemptAt: row.next_attempt_at,
+        claimedAt: row.claimed_at,
+        claimOwner: row.claim_owner,
+        acceptedAt: row.accepted_at,
+        permanentFailedAt: row.permanent_failed_at,
+        lastFailure: row.last_failure_json === null ? null : JSON.parse(row.last_failure_json),
+        createdAt: row.created_at,
+        updatedAt: row.updated_at,
+    };
+}
+/** Insert the one delivery row for a settled action-bound request. Idempotent
+ *  on requestId: a replayed settlement must not create a second row. */
+export function enqueueActionDelivery(row) {
+    const now = Date.now();
+    withCanvasWrite((db) => {
+        db.prepare(`INSERT INTO human_action_deliveries
+        (request_id, state, attempt, argv_json, cwd, completion_json, next_attempt_at, created_at, updated_at)
+       VALUES (?, 'pending', 0, ?, ?, ?, ?, ?, ?)
+       ON CONFLICT(request_id) DO NOTHING`).run(row.requestId, JSON.stringify(row.argv), row.cwd, JSON.stringify(row.completion), now, now, now);
+    });
+}
+/** Delivery state for `GET /v1/human/requests/:id`; null when no row exists. */
+export function readActionDelivery(requestId) {
+    const row = openDb()
+        .prepare('SELECT * FROM human_action_deliveries WHERE request_id = ?')
+        .get(requestId);
+    return row === undefined ? null : actionDeliveryFrom(row);
+}
+/** Due pending records in deterministic order for the daemon's serial tick. */
+export function dueActionDeliveries(now) {
+    return openDb()
+        .prepare(`SELECT * FROM human_action_deliveries
+         WHERE state = 'pending' AND next_attempt_at <= ?
+         ORDER BY next_attempt_at, created_at, request_id`)
+        .all(now).map(actionDeliveryFrom);
+}
+/** Atomically start one due delivery attempt. A null result lost the claim. */
+export function claimActionDelivery(requestId, now, claimOwner) {
+    return withCanvasWrite((db) => {
+        const claimed = db.prepare(`UPDATE human_action_deliveries
+       SET state = 'running', attempt = attempt + 1, claimed_at = ?, claim_owner = ?, updated_at = ?
+       WHERE request_id = ? AND state = 'pending' AND next_attempt_at <= ?`).run(now, claimOwner, now, requestId, now);
+        if (Number(claimed.changes) === 0)
+            return null;
+        const row = db.prepare('SELECT * FROM human_action_deliveries WHERE request_id = ?').get(requestId);
+        return actionDeliveryFrom(row);
+    });
+}
+/** Settle only the still-owned running attempt, so a stale process cannot overwrite a newer claim. */
+export function settleActionDelivery(requestId, attempt, claimOwner, settlement, now) {
+    const failure = settlement.state === 'accepted' ? null : JSON.stringify(settlement.failure);
+    const result = withCanvasWrite((db) => db.prepare(`UPDATE human_action_deliveries
+     SET state = ?, next_attempt_at = ?, claimed_at = NULL, claim_owner = NULL,
+         accepted_at = ?, permanent_failed_at = ?, last_failure_json = ?, updated_at = ?
+     WHERE request_id = ? AND state = 'running' AND attempt = ? AND claim_owner = ?`).run(settlement.state, settlement.state === 'pending' ? settlement.nextAttemptAt : now, settlement.state === 'accepted' ? now : null, settlement.state === 'permanent_failed' ? now : null, failure, now, requestId, attempt, claimOwner));
+    return Number(result.changes) === 1;
+}
+/** A new daemon deliberately redelivers interrupted completions at least once. */
+export function recoverRunningActionDeliveries(now) {
+    const result = withCanvasWrite((db) => db.prepare(`UPDATE human_action_deliveries
+     SET state = 'pending', next_attempt_at = ?, claimed_at = NULL, claim_owner = NULL, updated_at = ?
+     WHERE state = 'running'`).run(now, now));
+    return Number(result.changes);
+}

package/dist/core/config.d.ts

@@ -1,4 +1,4 @@
-import type { PageComponentRegistration, Scope, ScopeConfig, ScopeState, KindConfig, ModelLaddersConfig, ModelProvider, ModelStrength, ModelRouteConfig, ModelRoutingConfig } from '../types.js';
+import type { PageComponentRegistration, Scope, ScopeConfig, ScopeState, HumanActionConfig, KindConfig, ModelLaddersConfig, ModelProvider, ModelStrength, ModelRouteConfig, ModelRoutingConfig } from '../types.js';
 import { type BindingId } from './keybindings/catalog.js';
 export declare function configPath(scope: Scope): string | null;
 export declare function statePath(scope: Scope): string | null;
@@ -40,6 +40,18 @@ export declare function binDeclarationIssues(raw: unknown): BinDeclarationIssue[
  *  manifest's) to name → root-relative path. Invalid entries never become
  *  commands; `binDeclarationIssues` keeps them visible to Doctor. */
 export declare function normalizeBin(raw: unknown): Record<string, string>;
+export interface HumanActionDeclarationIssue {
+    name: string;
+    reason: string;
+    block?: true;
+}
+/** Validate `humanActions` declaration shape without touching the filesystem.
+ * Filesystem checks happen only when resolving an action or running Doctor. */
+export declare function humanActionDeclarationIssues(raw: unknown): HumanActionDeclarationIssue[];
+/** Normalize valid action declarations for scope-local config inspection.
+ * Invalid entries remain available through raw reads so resolution and Doctor
+ * can report them rather than silently treating them as absent. */
+export declare function normalizeHumanActions(raw: unknown): Record<string, HumanActionConfig>;
 /** STRICT install-time validation for a plugin-declared `bin` block. Target
  *  filesystem state is checked later by Doctor because it can change after
  *  install. */

package/dist/core/config.js

@@ -320,6 +320,55 @@ export function normalizeBin(raw) {
     }
     return out;
 }
+const HUMAN_ACTION_NAME_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
+/** Validate `humanActions` declaration shape without touching the filesystem.
+ * Filesystem checks happen only when resolving an action or running Doctor. */
+export function humanActionDeclarationIssues(raw) {
+    if (raw === null || typeof raw !== 'object' || Array.isArray(raw)) {
+        return [{ name: 'humanActions', reason: 'humanActions must be a JSON object mapping action names to {argv, cwd}', block: true }];
+    }
+    const issues = [];
+    for (const [name, value] of Object.entries(raw)) {
+        const reasons = [];
+        if (!HUMAN_ACTION_NAME_PATTERN.test(name)) {
+            reasons.push(`action name must match ${HUMAN_ACTION_NAME_PATTERN.source}`);
+        }
+        if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+            reasons.push('action must be an object with argv and cwd');
+        }
+        else {
+            const action = value;
+            const extras = Object.keys(action).filter((key) => key !== 'argv' && key !== 'cwd');
+            if (extras.length > 0)
+                reasons.push(`action has unsupported field${extras.length === 1 ? '' : 's'}: ${extras.join(', ')}`);
+            if (!Array.isArray(action.argv) || action.argv.length === 0 || !action.argv.every((arg) => typeof arg === 'string' && arg.length > 0)) {
+                reasons.push('argv must be a non-empty array of non-empty strings');
+            }
+            if (typeof action.cwd !== 'string' || action.cwd.length === 0) {
+                reasons.push('cwd is required and must be a non-empty string');
+            }
+        }
+        if (reasons.length > 0)
+            issues.push({ name, reason: reasons.join('; ') });
+    }
+    return issues;
+}
+/** Normalize valid action declarations for scope-local config inspection.
+ * Invalid entries remain available through raw reads so resolution and Doctor
+ * can report them rather than silently treating them as absent. */
+export function normalizeHumanActions(raw) {
+    if (raw === null || typeof raw !== 'object' || Array.isArray(raw))
+        return {};
+    const invalid = new Set(humanActionDeclarationIssues(raw).map((issue) => issue.name));
+    const out = {};
+    for (const [name, value] of Object.entries(raw)) {
+        if (invalid.has(name))
+            continue;
+        const action = value;
+        out[name] = { argv: [...action.argv], cwd: action.cwd };
+    }
+    return out;
+}
 /** STRICT install-time validation for a plugin-declared `bin` block. Target
  *  filesystem state is checked later by Doctor because it can change after
  *  install. */
@@ -635,7 +684,8 @@ function mergeConfig(partial) {
     const remoteCanvas = mergeRemoteCanvas(partial.remoteCanvas);
     const spawnEnv = mergeSpawnEnv(partial.spawnEnv, defaults.spawnEnv?.allow);
     const bin = normalizeBin(partial.bin);
-    return { bin, schema_version, marketplaces, plugins, auto_update, max_panes_per_window, auto_open_child_viewers, brokerThresholds, completion_bell, working_gerunds, whip_mode, page_components, page_surface, whip_messages, whip_message_mode, mouse_mode_default, live_cycles, condensed_history, bash_tool_purpose, fold_finished_tools, summarize_tool_calls, detailed_tool_recaps, keybindings, tmux_passthrough, modelLadders, ...(Object.keys(modelRoutes).length > 0 ? { modelRoutes } : {}), ...(modelRouting !== undefined ? { modelRouting } : {}), kinds, remoteCanvas, spawnEnv };
+    const humanActions = normalizeHumanActions(partial.humanActions);
+    return { bin, humanActions, schema_version, marketplaces, plugins, auto_update, max_panes_per_window, auto_open_child_viewers, brokerThresholds, completion_bell, working_gerunds, whip_mode, page_components, page_surface, whip_messages, whip_message_mode, mouse_mode_default, live_cycles, condensed_history, bash_tool_purpose, fold_finished_tools, summarize_tool_calls, detailed_tool_recaps, keybindings, tmux_passthrough, modelLadders, ...(Object.keys(modelRoutes).length > 0 ? { modelRoutes } : {}), ...(modelRouting !== undefined ? { modelRouting } : {}), kinds, remoteCanvas, spawnEnv };
 }
 /** Raw (un-defaulted) partial config for one scope, or null if the scope has
  *  no root or no config.json. Used by `readMergedLaunchConfig` to layer

package/dist/core/feed/inbox.d.ts

@@ -66,6 +66,12 @@ export declare function readCanceledEntryIds(nodeId: string): Set<InboxEntryId>;
  *  the interrupt's abort lands right behind, and covered handoffs are never
  *  re-delivered anyway. Returns the newly canceled entry ids. */
 export declare function cancelPendingHumanMessages(nodeId: string): InboxEntryId[];
+/** Cancel every not-yet-settled entry the predicate selects. Retraction, not
+ *  deletion: the append-only inbox is untouched and the sidecar grows. Safe to
+ *  call late — an entry already past the cursor is not pending, and the watcher
+ *  re-reads the set at plan time so a cancel racing a buffered entry still
+ *  lands. */
+export declare function cancelPendingEntries(nodeId: string, select: (entry: InboxEntry) => boolean): InboxEntryId[];
 /** Read and validate the persisted exact cursor identity. */
 export declare function readCursor(nodeId: string): InboxEntryId | undefined;
 /** Persist one validated exact cursor identity (atomic tmp+rename). */

package/dist/core/feed/inbox.js

@@ -245,11 +245,19 @@ export function readCanceledEntryIds(nodeId) {
  *  the interrupt's abort lands right behind, and covered handoffs are never
  *  re-delivered anyway. Returns the newly canceled entry ids. */
 export function cancelPendingHumanMessages(nodeId) {
+    return cancelPendingEntries(nodeId, (e) => e.from === 'human' && e.kind === 'message');
+}
+/** Cancel every not-yet-settled entry the predicate selects. Retraction, not
+ *  deletion: the append-only inbox is untouched and the sidecar grows. Safe to
+ *  call late — an entry already past the cursor is not pending, and the watcher
+ *  re-reads the set at plan time so a cancel racing a buffered entry still
+ *  lands. */
+export function cancelPendingEntries(nodeId, select) {
     const cursor = readCursor(nodeId);
     const pending = readInboxSince(nodeId, cursor);
     const already = readCanceledEntryIds(nodeId);
     const targets = pending
-        .filter((e) => e.from === 'human' && e.kind === 'message' && !already.has(e.entry_id))
+        .filter((e) => !already.has(e.entry_id) && select(e))
         .map((e) => e.entry_id);
     if (targets.length === 0)
         return [];

package/dist/core/human/action-binding.d.ts

@@ -0,0 +1,21 @@
+export declare const HUMAN_ACTION_NAME_PATTERN: RegExp;
+export interface TicketActionBinding {
+    schema: 'crtr.human-action-binding/v1';
+    /** Declared action name, matching HUMAN_ACTION_NAME_PATTERN. */
+    name: string;
+    /** Frozen creation payload; opaque JSON, never inspected. */
+    payload: unknown;
+    /** The creator's absolute cwd, captured verbatim. */
+    creatorCwd: 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;
+}
+/** Publish the binding before the page exists, so a visible request is never
+ * unbound. A second write is a caller bug, not a race to tolerate. */
+export declare function publishTicketActionBinding(dir: string, binding: TicketActionBinding): void;
+/** The frozen binding, or null for a request with no completion action. */
+export declare function readTicketActionBinding(dir: string): TicketActionBinding | null;

package/dist/core/human/action-binding.js

@@ -0,0 +1,40 @@
+// The optional completion-action binding of a durable human request. Written
+// once at creation and never again: `replace` revises the page, so the approved
+// effect must not be reachable from any later write.
+import { readFileSync } from 'node:fs';
+import { z } from 'zod';
+import { actionBindingPath, publishJsonExclusive } from './convention.js';
+export const HUMAN_ACTION_NAME_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
+const bindingSchema = z.object({
+    schema: z.literal('crtr.human-action-binding/v1'),
+    name: z.string().regex(HUMAN_ACTION_NAME_PATTERN),
+    payload: z.unknown(),
+    creatorCwd: z.string().min(1),
+    configOrigin: z.string().min(1),
+    argv: z.array(z.string().min(1)).min(1),
+    cwd: z.string().min(1),
+}).strict();
+/** Publish the binding before the page exists, so a visible request is never
+ * unbound. A second write is a caller bug, not a race to tolerate. */
+export function publishTicketActionBinding(dir, binding) {
+    if (!publishJsonExclusive(actionBindingPath(dir), binding)) {
+        throw new Error(`action binding already exists: ${actionBindingPath(dir)}`);
+    }
+}
+/** The frozen binding, or null for a request with no completion action. */
+export function readTicketActionBinding(dir) {
+    let raw;
+    try {
+        raw = JSON.parse(readFileSync(actionBindingPath(dir), 'utf8'));
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return null;
+        throw error;
+    }
+    const parsed = bindingSchema.parse(raw);
+    // `payload` is optional-by-absence in JSON but required in the type; z.unknown()
+    // accepts a missing key, so restore it explicitly as the JSON null the
+    // completion document must carry.
+    return { ...parsed, payload: raw.payload ?? null };
+}

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

@@ -0,0 +1,38 @@
+import type { TicketActionBinding } from './action-binding.js';
+import type { PageSource } from './page-schema.js';
+import type { TicketResult } from './types.js';
+export type HumanCompletionEvent = 'answered' | 'dismissed' | 'canceled';
+export interface HumanCompletionV1 {
+    schema: 'crtr.human-completion/v1';
+    requestId: string;
+    event: HumanCompletionEvent;
+    settledAt: string;
+    /** Present only when `event` is `answered`; absent, never empty, otherwise. */
+    responses?: Record<string, Record<string, unknown>>;
+    action: {
+        name: string;
+        payload: unknown;
+    };
+    provenance: {
+        source: PageSource;
+        actor?: string;
+    };
+    /** The lane overwrites this with the real attempt before writing stdin. */
+    delivery: {
+        attempt: number;
+    };
+}
+/** The one place a cancellation record without `disposition` reads as
+ * `canceled`. Every other reader treats both dispositions alike. */
+export declare function completionEventFor(result: TicketResult): HumanCompletionEvent;
+/** Build the complete document with `delivery.attempt` as the lane's placeholder. */
+export declare function composeHumanCompletion(args: {
+    requestId: string;
+    result: PageTerminalResult;
+    binding: TicketActionBinding;
+    source: PageSource;
+}): HumanCompletionV1;
+/** A review result can never carry an action binding; the composer is total over the rest. */
+export type PageTerminalResult = Extract<TicketResult, {
+    kind: 'page' | 'canceled';
+}>;

package/dist/core/human/completion.js

@@ -0,0 +1,27 @@
+// The `crtr.human-completion/v1` document handed to a completion action on
+// stdin. Composed at settlement from the canonical terminal result, so the
+// delivered document reflects the settlement instant and the delivery lane
+// never reads ticket storage.
+/** The one place a cancellation record without `disposition` reads as
+ * `canceled`. Every other reader treats both dispositions alike. */
+export function completionEventFor(result) {
+    if (result.kind === 'canceled')
+        return result.disposition ?? 'canceled';
+    return 'answered';
+}
+/** Build the complete document with `delivery.attempt` as the lane's placeholder. */
+export function composeHumanCompletion(args) {
+    const { requestId, result, binding, source } = args;
+    const event = completionEventFor(result);
+    const actor = result.actor;
+    return {
+        schema: 'crtr.human-completion/v1',
+        requestId,
+        event,
+        settledAt: result.kind === 'page' ? result.completedAt : result.canceledAt,
+        ...(result.kind === 'page' ? { responses: result.responses } : {}),
+        action: { name: binding.name, payload: binding.payload },
+        provenance: { source, ...(actor === undefined ? {} : { actor }) },
+        delivery: { attempt: 0 },
+    };
+}

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

@@ -8,6 +8,8 @@ export declare function responsePath(dir: string): string;
 export declare function progressPath(dir: string): string;
 export declare function claimPath(dir: string): string;
 export declare function replyRoutePath(dir: string): string;
+/** The frozen completion-action binding, written once at request creation. */
+export declare function actionBindingPath(dir: string): string;
 export interface TicketReplyRoute {
     bridge_node_id: string;
 }

package/dist/core/human/convention.js

@@ -10,6 +10,8 @@ export function responsePath(dir) { return `${dir}/response.json`; }
 export function progressPath(dir) { return `${dir}/progress.json`; }
 export function claimPath(dir) { return `${dir}/claim.json`; }
 export function replyRoutePath(dir) { return `${dir}/reply-route.json`; }
+/** The frozen completion-action binding, written once at request creation. */
+export function actionBindingPath(dir) { return `${dir}/action.json`; }
 /** A reply route exists only when completing the ticket must finish a human
  * bridge and fan its result back to subscribers. Its absence is the complete
  * representation of a standalone page. */

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

@@ -19,9 +19,22 @@ export interface PreparedPage {
     module?: string;
     manifest: PageManifest;
 }
-/** Validate one authored page source into publishable form. Reads only: a page
- *  that fails authoring leaves nothing behind, so a caller that must create a
- *  bridge node prepares first and creates it only once the page is known good.
+export interface PreparePageSourceOptions {
+    /** `jsx` carries .tsx semantics; `html` is a complete document. */
+    dialect: 'jsx' | 'html';
+    /** The complete authored page text, inline. */
+    document: string;
+    source?: PageSource;
+    productKinds?: ProductPageComponents;
+    delivery?: PageDelivery;
+}
+/** Validate one authored page document into publishable form. The single
+ *  validation path: `preparePage` reads a file and lands here, and a
+ *  programmatic request supplies the same text inline. */
+export declare function preparePageSource(opts: PreparePageSourceOptions): PreparedPage;
+/** Validate one authored page source file into publishable form. Reads only: a
+ *  page that fails authoring leaves nothing behind, so a caller that must create
+ *  a bridge node prepares first and creates it only once the page is known good.
  *  The source is read exactly once, so the published document is the same bytes
  *  the manifest was derived from even if the file changes underneath. */
 export declare function preparePage(opts: Omit<SubmitPageOptions, 'dir'>): PreparedPage;
@@ -81,6 +94,8 @@ export interface PageTicket {
 export declare function readPageTicket(dir: string): PageTicket;
 export interface CompletePageOptions {
     completedAt?: string;
+    /** Recorded when an authorized programmatic writer answered instead of a person. */
+    actor?: string;
 }
 export declare function completePage(dir: string, responses: unknown, claimToken: string, opts?: CompletePageOptions): {
     won: boolean;
@@ -94,11 +109,15 @@ export declare function takeoverAndCompletePage(dir: string, responses: unknown,
     won: boolean;
     result: TicketResult;
 };
-/** Cancellation races finalization but never requires or removes another claim. */
-export declare function cancelTicket(dir: string, opts?: {
+export interface CancelTicketOptions {
     reason?: string;
     actor?: string;
-}): {
+    /** The recipient closing it writes `dismissed`; the requester withdrawing it
+     * writes `canceled`. Omitted where the caller is neither. */
+    disposition?: 'canceled' | 'dismissed';
+}
+/** Cancellation races finalization but never requires or removes another claim. */
+export declare function cancelTicket(dir: string, opts?: CancelTicketOptions): {
     status: 'canceled' | 'already_resolved';
     result: TicketResult;
 };

package/dist/core/human/tickets.js

@@ -23,10 +23,10 @@ const feedbackSchema = z.object({ file: z.string().min(1).refine(isAbsolute, 'fi
     });
 });
 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 }).strict();
+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() }).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 only canonical final marker. */
 export function readTicketResult(dir) {
     let raw;
@@ -52,9 +52,19 @@ function publishRequest(path, value) {
     if (!publishJsonExclusive(path, value))
         throw new Error(`ticket request already exists: ${path}`);
 }
-/** Validate one authored page source into publishable form. Reads only: a page
- *  that fails authoring leaves nothing behind, so a caller that must create a
- *  bridge node prepares first and creates it only once the page is known good.
+/** Validate one authored page document into publishable form. The single
+ *  validation path: `preparePage` reads a file and lands here, and a
+ *  programmatic request supplies the same text inline. */
+export function preparePageSource(opts) {
+    const stamped = { ...(opts.source ?? {}), emittedAt: opts.source?.emittedAt ?? new Date().toISOString() };
+    const delivery = opts.delivery ?? { placement: 'inline', inbox: false, reply: false };
+    if (opts.dialect === 'html')
+        return { document: opts.document, manifest: deriveHtmlPageManifest(opts.document, stamped, delivery) };
+    return { document: opts.document, module: compilePage(opts.document), manifest: derivePageManifestFromDocument(opts.document, opts.productKinds ?? [], stamped, delivery) };
+}
+/** Validate one authored page source file into publishable form. Reads only: a
+ *  page that fails authoring leaves nothing behind, so a caller that must create
+ *  a bridge node prepares first and creates it only once the page is known good.
  *  The source is read exactly once, so the published document is the same bytes
  *  the manifest was derived from even if the file changes underneath. */
 export function preparePage(opts) {
@@ -63,12 +73,8 @@ export function preparePage(opts) {
         throw new PageAuthoringError(`page source file must be .tsx, .html, or .htm: ${opts.sourceFile}`);
     if (!existsSync(opts.sourceFile))
         throw new PageAuthoringError(`page source file does not exist: ${opts.sourceFile}`);
-    const document = readFileSync(opts.sourceFile, 'utf8');
-    const stamped = { ...(opts.source ?? {}), emittedAt: opts.source?.emittedAt ?? new Date().toISOString() };
-    const delivery = opts.delivery ?? { placement: 'inline', inbox: false, reply: false };
-    if (html)
-        return { document, manifest: deriveHtmlPageManifest(document, stamped, delivery) };
-    return { document, module: compilePage(document), manifest: derivePageManifestFromDocument(document, opts.productKinds ?? [], stamped, delivery) };
+    const { sourceFile: _sourceFile, ...rest } = opts;
+    return preparePageSource({ ...rest, dialect: html ? 'html' : 'jsx', document: readFileSync(opts.sourceFile, 'utf8') });
 }
 /** Remove a stale generation file. The manifest always switches first, so a
  * failed cleanup leaves one valid current record plus harmless old source. */
@@ -237,7 +243,7 @@ function completePageLocked(dir, responses, claimToken, opts) {
     requireClaimOwnership(dir, claimToken);
     const manifest = requirePage(dir);
     const parsedResponses = validateFinalPageTicketResponses(dir, responses);
-    const result = { schema: 'crtr.page-response/v1', kind: 'page', responses: parsedResponses, summary: buildPageSummary(manifest, parsedResponses), completedAt: opts.completedAt ?? new Date().toISOString() };
+    const result = { schema: 'crtr.page-response/v1', kind: 'page', responses: parsedResponses, summary: buildPageSummary(manifest, parsedResponses), completedAt: opts.completedAt ?? new Date().toISOString(), ...(opts.actor === undefined ? {} : { actor: opts.actor }) };
     const won = exclusiveResult(dir, result);
     clearOwnedWork(dir, claimToken);
     return { won, result: won ? result : readTicketResult(dir) ?? result };
@@ -280,7 +286,7 @@ export function cancelTicket(dir, opts = {}) {
     const canceled = withTicketLock(ticket, () => {
         if (existsSync(pageManifestPath(ticket)))
             requireCancelablePage(ticket);
-        const result = { schema: 'humanloop.cancel/v1', kind: 'canceled', canceledAt: new Date().toISOString(), ...(opts.reason === undefined ? {} : { reason: opts.reason }), ...(opts.actor === undefined ? {} : { actor: opts.actor }) };
+        const result = { schema: 'humanloop.cancel/v1', kind: 'canceled', canceledAt: new Date().toISOString(), ...(opts.reason === undefined ? {} : { reason: opts.reason }), ...(opts.actor === undefined ? {} : { actor: opts.actor }), ...(opts.disposition === undefined ? {} : { disposition: opts.disposition }) };
         const won = exclusiveResult(ticket, result);
         return { status: won ? 'canceled' : 'already_resolved', result: won ? result : readTicketResult(ticket) ?? result };
     });

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

@@ -89,6 +89,8 @@ export interface PageTicketResult {
     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';
@@ -102,6 +104,9 @@ export interface CanceledTicketResult {
     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 sole canonical response.json union. */
 export type TicketResult = PageTicketResult | ReviewTicketResult | CanceledTicketResult;

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/memory-resolver.js

@@ -313,7 +313,7 @@ function matchNormalizedChild(dir, segment, want, ext = '.md') {
  *  directory by normalized name, then resolve the final segment as either a
  *  `.md` file or a directory. Either half is null when
  *  the segment path does not resolve that way. This is what makes
- *  `00-runtime-base.md` findable as `runtime-base` and `01-spine/00-has-manager`
+ *  `00-runtime-base/00-authoring.md` findable as `runtime-base/authoring` and `01-spine/00-has-manager`
  *  findable as `spine/has-manager` — the physical path keeps its pins, only
  *  lookup is prefix-blind. */
 function resolveNormalizedPath(baseDir, segments, ext = '.md') {