@nodetool-ai/execution 0.8.1

package/dist/app-debug/runtime.d.ts

@@ -0,0 +1,267 @@
+/**
+ * Headless driver for the shared app runtime core.
+ *
+ * The fold rules, the state namespaces, the run policy, and the action
+ * vocabulary all live in `@nodetool-ai/app-runtime` — the same code the web and
+ * mobile runtimes run. This file only supplies what a headless run needs: a
+ * workflow executor per operation and the bookkeeping that turns an awaited run
+ * into an invocation, plus the in-memory resource collections a run gets in
+ * place of the server-backed ones the web runtime reads.
+ *
+ * The web engine's reactive subgraph runs collapse to full workflow runs here
+ * (the headless kernel has no browser worker), which the report notes rather
+ * than simulates.
+ */
+import { type AppAction, type AppInstanceState, type BindingRef, type BindingScope, type ConditionProps, type OperationBinding, type ResourceBinding, type ResourceKind, type ResourceOperation, type ResourceRef, type RunDecision, type VariableDeclaration } from "@nodetool-ai/app-runtime";
+import type { ResourceDetail } from "@nodetool-ai/protocol/api-schemas/resources.js";
+/** What one run returned: its messages plus where its report landed. */
+export interface HeadlessRunResult {
+    messages: ReadonlyArray<Record<string, unknown>>;
+    /** Index into the harness's `runs` array. */
+    runIndex: number;
+}
+export interface HeadlessOperationInit {
+    binding: OperationBinding;
+    /** Output node id → the state key its value lands in. */
+    outputKeyByNodeId: ReadonlyMap<string, string>;
+    /** Input node ids, in graph order. */
+    inputNodeIds: ReadonlyArray<string>;
+    /** Input node id → the param name the run protocol expects. */
+    inputNameByNodeId: ReadonlyMap<string, string>;
+    /** Input node id → node type, for shared admission checks. */
+    inputNodeTypeByNodeId?: ReadonlyMap<string, string>;
+    /** Input defaults, keyed by input state key. */
+    defaults: Record<string, unknown>;
+    /**
+     * Execute the operation's workflow. Absent when the workflow could not be
+     * loaded — dispatching a run then records why instead of throwing.
+     */
+    runWorkflow?: (params: Record<string, unknown>) => Promise<HeadlessRunResult>;
+}
+/** A widget's declarative logic props, as the document stores them. */
+interface HeadlessWidgetInit {
+    id: string;
+    visibleWhen?: ConditionProps;
+    disabledWhen?: ConditionProps;
+    /** `{binding|filter}` template rendered in place of the raw value. */
+    format?: string;
+}
+/** Whether a widget is on screen and usable, as of the last fold. */
+interface HeadlessWidgetState {
+    visible: boolean;
+    disabled: boolean;
+    /** True once the widget was both visible and enabled at any point. */
+    everReachable: boolean;
+    /** The `visibleWhen` condition in prose, or null when it has none. */
+    visibleWhen: string | null;
+    /** The `disabledWhen` condition in prose, or null when it has none. */
+    disabledWhen: string | null;
+}
+interface HeadlessRuntimeInit {
+    operations: ReadonlyArray<HeadlessOperationInit>;
+    /** The operation a bare `run`/`cancel` targets. */
+    defaultOperationId: string;
+    /** Declared variables, for `seedVariables`. */
+    variables?: ReadonlyArray<VariableDeclaration>;
+    /** Declared resource bindings — what `seedResource` can attach a collection to. */
+    resources?: ReadonlyArray<ResourceBinding>;
+    /** Ceiling on every run, on top of each operation's own `timeoutMs`. */
+    timeoutMs?: number;
+    /** Placed widgets, for condition and `format` evaluation. */
+    widgets?: ReadonlyArray<HeadlessWidgetInit>;
+    /** The scope widget conditions and `format` tokens resolve against. */
+    scope?: BindingScope;
+}
+/**
+ * A condition as a failure message names it: `draft notEmpty`, `count gt 3`.
+ * The stored props are what an author sees in the builder, so the message
+ * points at something they can find.
+ */
+export declare const describeCondition: (props: ConditionProps | null | undefined) => string | null;
+/**
+ * Why a ref cannot be written, or null when it can.
+ *
+ * Only a run fills an output slot or an operation's execution state, so a
+ * script that writes one has named the wrong thing — the value would land in
+ * the inputs namespace, where nothing reads it.
+ */
+export declare const writeRefusal: (ref: BindingRef) => string | null;
+/**
+ * One member of a collection, in the envelope the resources router speaks
+ * (`ResourceDetail`): a `ResourceRef`, the fields a picker lists, and the
+ * provider's payload.
+ */
+export type ResourceItem = ResourceDetail;
+/** A collection member as a seed step or a `resource:` param writes it. */
+export interface SeedResourceItem {
+    id: string;
+    name?: string;
+    /** The provider's payload: a document body, or an asset's metadata. */
+    document?: unknown;
+    contentType?: string | null;
+    projectId?: string | null;
+    revision?: number;
+    updatedAt?: string;
+}
+/** What a `resourceCommand` asks a provider to do. */
+export interface HeadlessResourceCommand {
+    command: ResourceOperation | "upload";
+    /** The item the widget points at. Ignored by `create` and `upload`. */
+    ref?: ResourceRef | null;
+    args?: Record<string, unknown>;
+}
+/** How to seed a collection, named in every message about an unseeded one. */
+export declare const seedResourceHint: (resourceBindingId: string) => string;
+/**
+ * The collection behind one resource binding, held in memory for the length of
+ * one debug run.
+ *
+ * The web runtime reads collections over tRPC and hands widgets a `ResourceRef`
+ * to act on; a headless run has no server and no user, so it gets the same
+ * envelope from a seeded provider instead. Nothing here touches the database —
+ * a run only ever sees what the interaction script or `--params` put in.
+ *
+ * Selection follows `useBoundResource`: a pinned `fixedId` wins, else the item
+ * the last command or `select` chose, else the first member — so a picker that
+ * nobody touched still has something to send.
+ */
+export declare class InMemoryResourceProvider {
+    readonly kind: ResourceKind;
+    private readonly items;
+    private readonly pinnedId;
+    private chosenId;
+    private seq;
+    constructor(init: {
+        kind: ResourceKind;
+        items?: ReadonlyArray<SeedResourceItem>;
+        /** A binding scoped to one document pins its id. */
+        pinnedId?: string;
+    });
+    /**
+     * Timestamps come from a counter, not the clock, so two runs of the same
+     * script produce identical reports.
+     */
+    private toItem;
+    list(): ResourceItem[];
+    get(id: string): ResourceItem | null;
+    /** The item a `from: "resource"` param sends and a command acts on. */
+    selected(): ResourceRef | null;
+    select(ref: ResourceRef | null): void;
+    apply(op: HeadlessResourceCommand): ResourceItem | null;
+    /** An id no member holds, so `create` twice makes two resources. */
+    private nextId;
+}
+/** One simulated invocation, as the report shows it. */
+interface HeadlessInvocationRecord {
+    id: string;
+    operationId: string;
+    decision: RunDecision["kind"];
+    decisionTargets: string[];
+    runIndex: number | null;
+    timedOutMs: number | null;
+    activity: string[];
+}
+/**
+ * The timeout a run actually gets: the operation's own `timeoutMs` capped by
+ * the harness-wide ceiling, so `--timeout` always shortens and never extends.
+ */
+export declare const effectiveTimeoutMs: (operationTimeoutMs: number | null | undefined, ceilingMs: number | null | undefined) => number | null;
+export declare class HeadlessAppRuntime {
+    private _state;
+    runCount: number;
+    /**
+     * Every state write goes through here, so a widget's conditions are re-read
+     * after each fold — exactly where the web runtime re-renders.
+     */
+    get state(): AppInstanceState;
+    set state(next: AppInstanceState);
+    /** Every invocation started, in order. */
+    readonly invocations: HeadlessInvocationRecord[];
+    /** Every activity label reported, in order. */
+    readonly activity: Array<{
+        invocationId: string;
+        operationId: string;
+        label: string;
+    }>;
+    private readonly init;
+    private readonly byId;
+    /** Runs the harness stopped waiting for, still settling in the background. */
+    private readonly inFlight;
+    private invocationSeq;
+    /** Widget conditions, parsed once, plus the state each evaluation writes. */
+    private readonly compiled;
+    private readonly widgetStates;
+    /** Declared resource bindings, keyed by id. */
+    private readonly resourceBindings;
+    /** Seeded collections, keyed by resource binding id. */
+    private readonly providers;
+    /** Every resource command dispatched, in order. */
+    readonly resourceCommands: Array<{
+        resourceBindingId: string;
+        command: string;
+    }>;
+    constructor(init: HeadlessRuntimeInit);
+    /**
+     * Re-evaluate every widget's `visibleWhen`/`disabledWhen` against the current
+     * state. An unset or unresolvable condition leaves the widget visible and
+     * enabled, the same fallback the web runtime uses.
+     */
+    private refreshWidgets;
+    /** A widget's current visibility, or null when the runtime has no such widget. */
+    widgetState(widgetId: string): HeadlessWidgetState | null;
+    /**
+     * What a widget displays: its `format` template rendered against the current
+     * state, or null when it has none and shows its bound value raw.
+     */
+    display(widgetId: string): string | null;
+    /**
+     * Attach a collection to a declared resource binding, replacing whatever was
+     * seeded before. Seeding is the only way a headless run gets resources.
+     */
+    seedResource(resourceBindingId: string, items: ReadonlyArray<SeedResourceItem>): InMemoryResourceProvider;
+    /** The collection behind a resource binding, or null when nothing seeded it. */
+    resourceProvider(resourceBindingId: string): InMemoryResourceProvider | null;
+    /** Resource bindings the document declares, in document order. */
+    get resourceBindingList(): ResourceBinding[];
+    /** Last error reported against an operation's active invocation. */
+    errorFor(operationId: string): string | null;
+    get error(): string | null;
+    /**
+     * Write a value through its resolved binding.
+     *
+     * A ref {@link writeRefusal} rejects throws instead of landing in the inputs
+     * namespace: an output slot only a run fills, written as an input, is a value
+     * no reader ever sees, and the step that wrote it must not report success.
+     */
+    write(ref: BindingRef, value: unknown): void;
+    /**
+     * HOLDOUT (anti-slop/no-unknown-returns): a slot holds a workflow value —
+     * the open domain `AppInstanceState` stores as `unknown`.
+     */
+    read(ref: BindingRef | null): unknown;
+    /**
+     * Params for one operation's run: every input resolved through its mapping
+     * (widget value, variable, constant, or resource), keyed by node name.
+     */
+    collectParams(operationId: string): Record<string, unknown>;
+    /**
+     * Refuse to run an operation whose inputs read a collection nothing seeded.
+     * Sending no param for it would look like a passing run against an app that
+     * cannot work, which is the failure this harness exists to catch.
+     */
+    private assertResourcesSeeded;
+    private assertRequiredInputs;
+    /** Dispatch one action; a `run` executes the workflow and folds its stream. */
+    dispatch(action: AppAction): Promise<void>;
+    /** Cancel an operation's live invocations (or one named invocation). */
+    cancel(operationId: string, invocationId?: string): string[];
+    private timeoutFor;
+    /**
+     * Start one run, after `decideRun` says what the operation's policy makes of
+     * whatever is already in flight.
+     */
+    private run;
+    private recordActivity;
+}
+export {};
+//# sourceMappingURL=runtime.d.ts.map

package/dist/app-debug/runtime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime.d.ts","sourceRoot":"","sources":["../../src/app-debug/runtime.ts"],"names":[],"mappings":"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"}