@nodetool-ai/app-runtime

The runtime core for NodeTool mini apps, with no framework and no dependencies. A mini app is a UI document plus typed bindings to workflow operations — all computation stays in the graph, so the only semantics this layer owns are document parsing, binding resolution, instance state, the streaming fold, run policy, conditions, and the widget catalog.

Four hosts run those semantics: the web runtime, the mobile app, the nodetool app debug harness, and the eval suites. They share this package so they cannot drift. src/fold.ts is here because three of them once folded a run's messages their own way and disagreed about what an app was showing.

Modules

| Module | Owns | | --- | --- | | document.ts | The ApplicationDocument schema and its parser, including lifting legacy workflow.app_doc v1–v3 | | bindings.ts | The binding token (op:<id>/out:<nodeId>, var:<id>, …), its parser, and the state key it resolves to | | state.ts | AppInstanceState, its four value namespaces, and the pure reducer over AppStateEvent | | fold.ts | Turning a run's ProcessingMessages into state events | | operations.ts | Resolving an operation binding into the name-keyed params a run wants | | policy.ts | What to do when an operation is asked to run while already running | | conditions.ts | visibleWhen / disabledWhen evaluation and format templates | | actions.ts | The six-verb action vocabulary a widget event dispatches | | widgets.ts | The widget catalog — one table behind the Puck editor config, the harness, and the app-tools eval | | doc-ops.ts | Immutable edits to the non-UI half of a document (operations, variables, resources) | | bundle.ts | The ApplicationBundle: an app plus the full graphs it binds, as one JSON artifact | | script-run.ts | The contract for an operation that runs a JS script instead of a workflow | | chat.ts | Reading a bound value as a conversation, for the thread and composer widgets | | documents.ts | Unwrapping sketch and timeline refs out of a bound value |

Usage

Everything is a pure function, so a host drives the reducer itself. Folding a run's messages into the state an app displays:

import {
  applyEvents,
  createInstanceState,
  messagesToEvents,
  type InvocationState
} from "@nodetool-ai/app-runtime";

const invocation: InvocationState = {
  id: "job-1",
  operationId: "main",
  status: "running",
  startedAt: Date.now()
};

let state = applyEvents(createInstanceState(), [
  { type: "runStarted", invocation, outputKeys: ["main:out"] }
]);

state = applyEvents(
  state,
  messagesToEvents(
    [
      { type: "chunk", job_id: "job-1", node_id: "out", content: "Hello " },
      { type: "chunk", job_id: "job-1", node_id: "out", content: "world", done: true },
      { type: "chunk", job_id: "other-job", node_id: "out", content: "!" }
    ],
    {
      resolveInvocation: (jobId) => state.invocations[jobId ?? ""] ?? null,
      outputKey: (opId, nodeId) => `${opId}:${nodeId}`
    }
  )
);

state.outputs["main:out"];
// { value: "Hello world", invocationId: "job-1", status: "done", revision: 3 }

Two rules that example pins. Text chunks concatenate rather than giving the slot one value per token. And the message stamped other-job is dropped: matching on job_id is what stops a second tab, an overlapping run, or a run started in the graph editor from writing into this app's values.

No dependencies, on purpose

dependencies is empty and stays empty. The Puck document and the workflow graph are typed structurally here rather than imported from @puckeditor/core and @nodetool-ai/protocol, so the package loads in a browser bundle, in a Node harness, and in React Native without dragging a server-side tree behind it. Mobile compiles it from source — wired in mobile/metro.config.js, mobile/tsconfig.json, and mobile/jest.config.js, all three of which must agree.

Develop

npm run build --workspace=packages/app-runtime
npm run test  --workspace=packages/app-runtime
npm run lint  --workspace=packages/app-runtime   # tsc --noEmit

What a mini app is: docs/mini-apps.md. Every widget, binding, action, and condition in tables: docs/mini-apps-reference.md. Building one: docs/mini-apps-guide.md. The headless harness that drives this package: nodetool app debug, in docs/cli.md.