llms-full.txt

# AbstractFlow Full LLM Context

This file is generated from the root documentation set with `npm run docs:llms`.

## README.md

# AbstractFlow

AbstractFlow is the visual workflow editor for AbstractFramework.

It is a web package (`@abstractframework/flow`). It runs a browser editor and a small Node server that serves the built UI and proxies `/api/*` to AbstractGateway. AbstractGateway owns users, sessions, runtime routing, provider configuration, workflow storage, run execution, ledgers, artifacts, and media catalogs.

## Install

```bash
npx @abstractframework/flow --gateway-url http://127.0.0.1:8080
```

For a local checkout:

```bash
npm install
npm run dev -- --host 0.0.0.0 --port 3003
```

Open http://localhost:3003 and sign in with the Gateway user and token created by AbstractGateway.
Leave provider/model selectors on `Auto (Gateway default)` for portable
workflows. Gateway/Core capability defaults choose the actual provider/model at
run time for the current user/runtime.

Text model selectors use Gateway's Core-backed `capability_route` discovery
filters, so normal LLM pickers request `output.text` models. The Models Catalog
node can store a route such as `input.image,output.text` to discover provider
models for a specific input/output shape while the workflow runs.

LLM Call and Agent nodes include a Reasoning control backed by Core's
`thinking` option. Leave it on Auto to inherit the Gateway/runtime default, or
set/pin values such as `off`, `low`, `medium`, `high`, or `xhigh` for reasoning
models that support explicit effort controls.

LLM Call and Agent response schemas can be defined directly on the unconnected
`resp_schema` pin. The Builder tab creates ordinary JSON Schema, including
Choice fields saved as `enum` values. Connected schema inputs override the
inline default, and published workflows keep the schema in
`data.pinDefaults.resp_schema` for Gateway/Runtime execution. When a response
schema is configured, `response` remains the text output and a structured
`data` object output is shown for Break Object, Switch, and other object-aware
nodes.

Media artifact inputs can be wired from another node or uploaded directly on
the node when the artifact pin is unconnected. Uploaded browser files are stored
as Gateway artifacts. Image generation, editing, restoration/upscaling, video,
voice, music, and transcription nodes all execute through Gateway-advertised
capabilities. During `Listen Voice` waits, Flow records in the browser,
uploads the captured audio artifact, and resumes the Gateway run; Flow does not
execute local audio or transcription logic itself.

Vision media nodes now surface Gateway/Core's richer route contract directly in
authoring:

- task-scoped provider/model discovery for `text_to_image`, `image_to_image`,
  `text_to_video`, and `image_to_video`
- batch generation controls with `count` and explicit ordered `seeds`
- ordered `lora_adapters` stacks for compatible image/video models
- plural media outputs such as `image_artifacts` and `video_artifacts` when a
  route returns more than one artifact in one call

The editor keeps those controls in the right-side Properties drawer and only
surfaces them on nodes whose Gateway contract advertises the corresponding
support.

File and document workflows can use `Write File` for Markdown/JSON/text paths,
`Read File` for UTF-8/JSON inputs, `Read PDF` for extracting PDF text/metadata,
and `Write PDF` for rendering report content to a real PDF path through
Runtime.

The toolbar star opens the Workflow Authoring Assistant in the right drawer.
The assistant reads `docs/workflow-authoring-skill.md` plus a compact generated
node catalog, uses Gateway's default `output.text` model by starting normal
Gateway planner runs unless a model is pinned, and reads planner responses from
run ledgers. The model authors the complete workflow as one JSON document; the
editor diffs it against the draft canvas and applies only validated edits. It can
create or refine common workflows such as internet research, deep research, news
digests, and job searches; Save, Publish, and Run remain explicit user actions.

## Gateway Setup

```bash
export ABSTRACTGATEWAY_USER_AUTH=1
export ABSTRACTGATEWAY_DATA_DIR="$PWD/runtime/gateway"
abstractgateway serve --host 127.0.0.1 --port 8080
cat "$ABSTRACTGATEWAY_DATA_DIR/auth/bootstrap-admin-token"
```

Use:

- Gateway URL: `http://127.0.0.1:8080`
- User: `admin`
- Token: the `agw_...` token printed by Gateway or stored in `auth/bootstrap-admin-token`

## What Lives Here

- `src/` - React/Vite visual editor.
- `bin/cli.js` - npm CLI/static server and Gateway proxy.
- `examples/flows/` - sample VisualFlow JSON files kept for reference/import tests.
- `docs/` - external documentation for users and contributors.

AbstractFlow does not ship a Python package or local execution host. VisualFlow compilation, bundle execution, runtime state, and provider calls are handled by AbstractGateway and AbstractRuntime.

## Scripts

```bash
npm run dev
npm run build
npm run lint
npm run docs:llms
```

## Documentation

- [Getting started](docs/getting-started.md)
- [Web editor](docs/web-editor.md)
- [Architecture](docs/architecture.md)
- [API and contracts](docs/api.md)
- [VisualFlow JSON](docs/visualflow.md)
- [CLI](docs/cli.md)
- [FAQ](docs/faq.md)

## Related Projects

- AbstractFramework: https://github.com/lpalbou/AbstractFramework
- AbstractGateway: https://github.com/lpalbou/AbstractGateway
- AbstractRuntime: https://github.com/lpalbou/AbstractRuntime
- AbstractCore: https://github.com/lpalbou/AbstractCore

## Policies

- Changelog: [CHANGELOG.md](CHANGELOG.md)
- Contributing: [CONTRIBUTING.md](CONTRIBUTING.md)
- Security: [SECURITY.md](SECURITY.md)
- License: [LICENSE](LICENSE)

## docs/README.md

# AbstractFlow Documentation

AbstractFlow is the AbstractFramework visual workflow editor. It is distributed as the npm package `@abstractframework/flow`.

Normal operation:

1. AbstractGateway runs on a server or local machine.
2. AbstractFlow serves the browser editor.
3. The browser signs in with a Gateway user token.
4. Flow proxies authoring, discovery, run, ledger, and artifact calls to Gateway.

AbstractFlow does not own runtime execution or provider secrets. Gateway and Runtime do.

Flow can author runtime-facing pin defaults, including inline JSON Schema
response schemas for LLM Call and Agent nodes. Those schemas are saved in
VisualFlow JSON and enforced later by Runtime/Core after Gateway publish/start.
When a schema is active, `data` is the structured object output and `response`
stays textual for compatibility.

## File-like sources

Flow now teaches one explicit file-like vocabulary across the editor, run modal,
and authoring docs:

- `Artifact`: a saved Runtime-owned durable payload.
- `Local File` / `Local Folder`: client-device intake sources. In hosted/browser
  mode, uploads become artifacts before durable execution.
- `Server File` / `Server Folder`: user-facing wording for workspace-scoped
  server paths under Gateway policy. The engineering/model term remains
  `Workspace File` / `Workspace Folder`.

The canvas reflects that split:

- path-based nodes such as `Read File`, `Write File`, `Read PDF`, `Write PDF`,
  and `List Folder Files` consume workspace-scoped server paths;
- artifact-first nodes such as `Artifact`, `Import Server File`, `Read
  Artifact`, and `Export Artifact` work with durable runtime-owned payloads.

## Pages

- [Getting started](getting-started.md)
- [Web editor](web-editor.md)
- [Workflow authoring skill](workflow-authoring-skill.md)
- [Workflow node catalog](workflow-node-catalog.md)
- [Architecture](architecture.md)
- [API and contracts](api.md)
- [VisualFlow JSON](visualflow.md)
- [CLI](cli.md)
- [FAQ](faq.md)

## Documentation Upkeep

- Keep docs written around the web package layout: `src/`, `bin/`, `examples/flows/`, `docs/`.
- Do not add Python package or local server launch instructions; those surfaces were removed from this repository.
- Regenerate the LLM context after doc changes:

```bash
npm run docs:llms
```

## docs/getting-started.md

# Getting Started

AbstractFlow is a web editor. It needs a reachable AbstractGateway because Gateway owns workflow storage, execution, auth, providers, artifacts, and user/runtime routing.

## 1. Start Gateway

```bash
export ABSTRACTGATEWAY_USER_AUTH=1
export ABSTRACTGATEWAY_DATA_DIR="$PWD/runtime/gateway"
abstractgateway serve --host 127.0.0.1 --port 8080
```

Gateway creates the default admin account on first start. Read the browser-login token:

```bash
cat "$ABSTRACTGATEWAY_DATA_DIR/auth/bootstrap-admin-token"
```

## 2. Start AbstractFlow

```bash
npx @abstractframework/flow --gateway-url http://127.0.0.1:8080
```

Open http://localhost:3003.

Sign in with:

- Gateway URL: `http://127.0.0.1:8080`
- User: `admin`
- Token: the `agw_...` token from Gateway

## 3. Author And Run

Use the canvas to create VisualFlow graphs. The editor sends VisualFlow JSON to Gateway, publishes workflows through Gateway, starts Gateway runs, and renders Gateway ledger/artifact streams.

Provider and model selectors come from Gateway discovery. Configure providers, endpoint profiles, API keys, and default models in the Gateway console.

## Local Development

```bash
git clone https://github.com/lpalbou/AbstractFlow.git
cd AbstractFlow
npm install
npm run dev
```

The Vite dev server proxies `/api/*` to the Gateway URL selected in the connection UI or configured with `ABSTRACTGATEWAY_URL` / `ABSTRACTFLOW_GATEWAY_URL`.

## Build

```bash
npm run build
npm start -- --gateway-url http://127.0.0.1:8080
```

The static server in `bin/cli.js` serves `dist/` and proxies API/SSE calls to Gateway with browser-session auth injection.

## docs/web-editor.md

# Web Editor

AbstractFlow is the browser-based VisualFlow editor.

It talks to AbstractGateway for:

- user sessions and runtime routing
- workflow CRUD and publishing
- provider/model/capability discovery
- run start, commands, ledger replay, and ledger streaming
- artifacts, media previews, and generated output downloads

## Run With A Gateway

```bash
export ABSTRACTGATEWAY_USER_AUTH=1
export ABSTRACTGATEWAY_DATA_DIR="$PWD/runtime/gateway"
abstractgateway serve --host 127.0.0.1 --port 8080
```

```bash
npx @abstractframework/flow --gateway-url http://127.0.0.1:8080
```

Open http://localhost:3003.

## Browser Auth

Each browser signs in with a Gateway user id and that user's token. Flow exchanges the token with Gateway for an opaque browser session and keeps that session in HTTP-only cookies. Raw user tokens are not retained after sign-in.

Server/operator bearer tokens such as `ABSTRACTGATEWAY_AUTH_TOKEN` are not browser sign-in tokens. Use the Gateway user token, normally the bootstrap admin token for a first local install.

Remote browser-supplied Gateway URL changes are blocked by default. A hosted Flow instance should proxy only to its configured Gateway unless the operator explicitly enables `ABSTRACTFLOW_ALLOW_REMOTE_BROWSER_GATEWAY_CONFIG=1` behind their own access control.

## Provider And Model Discovery

Flow does not store API keys or endpoint secrets. It asks Gateway for provider catalogs, endpoint profiles, model lists, capability defaults, and media route descriptors.

Configure these in the Gateway console:

- OpenAI, Anthropic, OpenRouter, Portkey, Ollama, LM Studio
- custom OpenAI-compatible endpoint profiles
- Gateway-level and user-level capability defaults

Flow nodes then select providers and models from Gateway discovery.
Leave provider/model as **Auto (Gateway default)** when a workflow should use
the Gateway/Core capability route configured for the current runtime. This is
the portable default for LLM Call, Agent, and generated media nodes. If you pin
a provider and later want to return to runtime defaults, choose **Auto (Gateway
default)** again from the provider dropdown.

The Model Residency modal shows only provider-reported resident/loaded models.
Configure capability defaults in Gateway Console or with the Gateway/Core
config CLIs; changing a default does not load or unload a model.

## Workflow Authoring Assistant

The star button on the right side of the toolbar opens a conversational
assistant in the right drawer. The drawer shares space with Properties, so users
can switch between assistant guidance and node editing while keeping the canvas
visible.

The assistant uses `docs/workflow-authoring-skill.md` plus a complete generated
node catalog from `src/types/nodes.ts` as its graph-authoring context. This
replaces generic `llms-full.txt` context for workflow construction. By default
it resolves Gateway's configured `output.text` capability route and starts a
short-lived Gateway `basic-agent` planner run through the normal
`/api/gateway/runs/start` path. Users can pin a specific assistant
provider/model from the drawer. The assistant authors the workflow as one
complete JSON document (direct document authoring): each cycle the model emits
the full graph — every node and edge — and the editor diffs that document
against the current draft, compiles the diff into validated graph mutations,
applies them, and continues until the model declares the request satisfied or
is explicitly blocked. Anything the document omits is deleted, so removals are
implicit and the assistant never asks the user to delete nodes manually. The
first cycle aims to one-shot the workflow; later cycles exist to repair
validator errors, readiness issues, and acceptance findings.

Completion is model-owned: readiness checks are a structural floor that can
demand more work, but they never stop the loop while the model returns
`continue`. When the model declares `done` with clean readiness, the editor runs
an acceptance review — a second model pass that compares the draft graph against
the original request and the model's own declared acceptance criteria. Unmet
findings are fed back into the loop as issues; if the review budget is exhausted
the remaining findings are reported with the result instead of being hidden.

The planner run receives a single prompt plus a system prompt with strict JSON
instructions. Its runtime tool list is explicitly empty: authoring edits must
come back as the workflow document JSON, not as Gateway tool calls. Prior user turns
are included inside the current prompt, assistant turns are replayed as trimmed
plan/result summaries (so pending plan items survive across turns), and applied
cycles within a turn carry one-line notes of the model's own next steps. The
visible graph remains the source of applied draft state.

Session policy: one durable Gateway session per workflow conversation. The
session id is scoped to the workflow storage key (never shared across
workflows), follows a draft when it is promoted to a saved flow, and is
rotated by Clear Chat — so gateway-side agent memory restarts together with
the visible conversation. Because the gateway agent replays session memory
into the model context, the prompt anchors a language directive at the request
site and marks replayed conversation as historical, so the active request —
not session history in another language — controls the output language.

Plan responses are parsed tolerantly: the JSON object is extracted even when the
model wraps it in markdown fences or surrounding prose. A planner response that
is still unusable (empty run output, or truncated/invalid plan JSON) does not
abort the turn: the same cycle is retried with a corrective format note (bare
JSON only, shorten free-text fields rather than the graph document), up to
three unusable responses per turn. Each retry is logged in the activity feed.

A `continue` cycle whose document matches the existing graph exactly (no
changes) does not abort the turn either: the model gets a corrective note
(emit a document that addresses the issues, declare done, or ask the user) for
up to two consecutive unchanged cycles, after which the turn ends as "needs
your input" with the model's own reply — never as a hard authoring failure. The system
prompt and skill explicitly tell the model to return `needs_user` with concrete
questions when the request is ambiguous or repair cycles stop making progress;
the user's answer in the next turn resumes with the full draft graph and
conversation context. All user-visible workflow content (flow name, labels,
prompts, replies) must match the language of the user request unless the user
asks otherwise.

While a turn runs, a live status card shows the current phase with the cycle
number in the header, an elapsed timer, and a real-time activity feed (plan
request/response sizes, per-cycle token usage read from the Gateway run-tree
ledgers with cumulative turn totals in the footer, compiled document change
counts, applied changes with labels, document issues, retries, readiness
counts, and acceptance review events). A shimmering in-flight ticker pinned at
the bottom of the feed shows what the assistant is waiting on right now — the
request purpose ("authoring the full workflow document", "repairing 2
validation issues", "acceptance review") — with a per-stage elapsed counter
that ticks every second.
Feed entries are grouped under per-cycle divider rows so iteration boundaries
are scannable at a glance. The header carries a leading chevron with a hover
state (collapse toggle) and a copy button that exports the whole activity feed
— grouped by cycle, with elapsed timestamps — to the clipboard. The card
persists after the turn ends with its final state (green dot for "Draft graph
updated", red dot for "Authoring failed" or "Interrupted by user") so the
cycle history can be reviewed post-turn. A Stop control — in the status card
and in place of Send while busy — interrupts the autonomous loop between calls
and best-effort cancels the in-flight Gateway planner run; applied edits stay
in the draft and remain undoable via Undo Turn.

Conversation actions are compact icon buttons on the input row (copy
conversation, clear conversation, undo last turn) next to the Send/Stop button;
the estimated context usage appears above the model row while a request is
typed or running. AbstractFlow does not truncate the assistant conversation,
selected docs sections, or graph summary to fit a local limit, and it does not
hardcode model context windows. The drawer conversation and draft text are
persisted locally so closing and reopening the Assistant rail does not erase
the ongoing authoring discussion. Clear resets the local assistant
conversation, rotates the workflow's durable Gateway session, and clears the
persisted status card without changing the current graph. If the Gateway run, model call, structured
response, or ledger read fails after the retry budget, the drawer reports that
failure directly.

Assistant output is treated as an untrusted edit proposal. The emitted
document is compiled by a diff against the current graph into the editor's
internal validated command set (node creation/deletion, safe dynamic pins,
pin defaults, literals, Code node bodies, labels, concat separators, and
validated connections), so every existing validator and security guard stays
the single source of truth for graph mutation. The reducer rejects unknown
node types, invalid edges, secret-looking values, Code `full_access`, and Tool
Calls nodes without an explicit `allowed_tools` allowlist. Node deletions are
allowed as part of document ownership and remain recoverable with Undo Turn;
secrets are serialized to the model as `<redacted>` and the diff never writes
that sentinel back. `pin_defaults` merge per key, node ids are stable
identities (a type change requires a new id), existing node positions are
never moved, and new nodes without explicit positions get execution-depth
auto-layout.

Compiled changes are applied per-command in dependency order (nodes first, then
configuration, then connections, with disconnects before connects). Valid
changes are kept even when others fail; the failures are reported back to the
planner as document-issue feedback for the next cycle. The validator also
performs deterministic repairs that a human author would make: connecting an
already-connected execution output is rewired through an auto-inserted (or
extended) Sequence node, and loop-back edges from a loop body to the loop's
`exec-in` are dropped with a warning because AbstractRuntime control frames
return to the loop automatically when the body chain ends. Rejection messages
list the node's real pins so a wrong handle guess can be corrected on the next
cycle, and Variable nodes are configurable through the same document fields
used elsewhere (`pin_defaults` on `name`/`value`, or `literal` with the
declaration config). Unlabeled nodes are flagged as non-blocking notes so
generated graphs stay readable.

Research-oriented readiness checks require an authored Agent system prompt,
explicit tool configuration when web tools are needed, prompt-building nodes,
sources/citations that are not `Agent.meta`, an audit trace, and final outputs.
`Agent Trace Report` is accepted only for audit output, not as a report source.
These checks apply only when the request's deliverable is researched content
(deep research, internet/web research, news, digests, job search, or "research"
coupled to a workflow/report deliverable in the same sentence); an incidental
mention of "research" — such as "discussion, research, and deepening of ideas"
— does not force the research scaffold onto an unrelated workflow.
When a request asks for Markdown/PDF artifacts, the assistant must create
an executable `Write File` node for Markdown and an executable `Write PDF` node
for PDF. `Write PDF` renders report text or Markdown-style content to real PDF
bytes in Runtime and exposes the resulting path through `On Flow End`. Generic
`Write File` and sandbox Code are not treated as PDF generation.

Tool-dependent requests use Gateway's advertised tool inventory and exact tool
names. If Gateway defaults, advertised discovery endpoints, the planner run,
strict JSON parsing, or document validation fail, the assistant reports the error
instead of synthesizing a substitute plan. Completed cycle edits remain visible in
the draft; the failed cycle is not applied, and Undo Turn restores the pre-turn
snapshot.

Each assistant turn ends with how the draft works, how to test it, and what to
expect. The assistant changes the in-memory draft only. Users still review the
graph, Save, Publish, and Run through the normal Gateway-backed controls.

## Execution View

The toolbar's execution-view toggle (node-to-node arrow icon) condenses the
canvas to the control-flow skeleton. Only nodes linked by execution edges
remain visible, along with those edges; data-only nodes (literals, concat,
parsers) and data edges are hidden. Node positions are unchanged, so the
layout matches the full view when switching back and forth.

Each condensed node reuses the full-view node header — the same header color,
uppercase title, and sheen — so a node is instantly recognizable across both
modes. A family icon and silhouette add a second cue: events (pill), control
flow such as Sequence or If/Else (sharp corners, with named branch rows in the
dark node body), user interaction (speech-bubble corner), generative AI and
generated media (rounded), tools & files, memory, subflow (double border), and
logic/state. Runtime highlights (executing/recent) still apply in this view.

The execution view is a reading mode: dropping new palette nodes is blocked
with a hint, while moving nodes and rewiring execution pins remain available.

## Structured Output Schemas

LLM Call and Agent nodes expose `resp_schema` as an optional JSON Schema input.
When that input is not connected, the node shows an inline schema editor. The
Builder tab is for object fields, required/optional fields, descriptions, and
Choice fields. Choice fields are saved as standard JSON Schema string enums.

The JSON Schema tab accepts advanced object schemas directly, including `$ref`
schemas that Runtime can resolve. Switching back to Builder preserves supported
top-level fields and Choice values.

Connected schema inputs always override the inline default. When a workflow is
published, Gateway stores and packs the VisualFlow JSON unchanged; Runtime then
applies unconnected `pinDefaults.resp_schema` values and Core enforces the
structured output schema.

For branch routing, define a Choice field such as `choice`, wire the
LLM/Agent `data` output into Break Object, expose `choice`, and connect it to a
Switch node. `response` remains available as text for display and compatibility.
The Switch panel can sync explicit cases from the discovered enum values, so the
published workflow contains stable `switchConfig.cases`.

## Media Nodes

Flow exposes media nodes only when Gateway advertises the corresponding capability:

- Generate Image
- Edit Image / Image-to-Image
- Restore / Upscale Image
- Generate Video
- Image-to-Video
- Generate Voice
- Generate Music
- Transcribe Audio
- Listen Voice

Generated outputs are Gateway artifacts. The run modal renders image/video/audio previews and keeps the artifact content link available for open/download. When Gateway returns a media child run, Flow streams the child-run ledger and renders `abstract.progress` records for image, image-edit, image-upscale, video, and image-to-video runs when available.

Unconnected artifact input pins expose a browser upload affordance directly on the node. Uploads go to Gateway and are stored as session-visible artifacts, then the node stores the canonical artifact ref as its pin default. Flow does not use server workspace paths for browser-local uploads.

`Listen Voice` waits are handled as Gateway/Runtime waits. Flow only captures audio in the browser, uploads it to Gateway as an audio artifact, and resumes the waiting run with that artifact ref; transcription and downstream execution remain Gateway/Runtime work.

For the vision routes, the Properties drawer now follows the Gateway media
contract closely:

- `Generate Image`, `Edit Image`, `Generate Video`, and `Image To Video` expose
  task-filtered provider/model selectors backed by Gateway discovery.
- Compatible routes expose batch controls through `count` and ordered `seeds`.
- Compatible routes expose ordered `lora_adapters` stacks with per-adapter
  scale and optional target role.
- Batched routes surface plural artifact outputs such as `image_artifacts` and
  `video_artifacts` alongside the singular compatibility pins.

Flow only shows those editors when the current node contract advertises the
corresponding support. Provider/model selection remains optional; leaving them
on `Auto (Gateway default)` keeps the workflow portable across runtimes and
users.

![Generate Image batch + LoRA authoring](assets/flow-generate-image-batch-lora.png)

## Files, folders, and artifacts

Flow uses one explicit source model for file-like work:

- `Artifact`: a saved Runtime-owned payload that can be reused across runs.
- `Local File`: a browser upload from this computer. For artifact-style inputs,
  Flow uploads it to Gateway and stores the resulting artifact ref.
- `Local Folder`: a browser-selected folder from this computer. In hosted
  Flow, each file is uploaded to Gateway and the workflow receives an ordered
  multi-artifact input with preserved relative member paths.
- `Server File` / `Server Folder`: a file or folder inside the active Gateway
  workspace scope. The underlying engineering contract is a canonical
  `Workspace File` / `Workspace Folder` path such as `docs/report.md` or
  `mount_alias/reports`.

The run modal and node defaults now expose workspace path browsing for
`Workspace File` / `Workspace Folder` pins, plus artifact-backed local intake
for one file, many files, or one or more local folders. Typical graph patterns are:

- `List Folder Files` to enumerate a workspace-scoped server folder with family
  and extension filters.
- `Import Server File` to snapshot a server file into a durable artifact.
- `Read Artifact` to inspect text, JSON, or bounded binary projections from any
  artifact-backed file.
- `Read Artifact` -> `content_family` / `content_type` -> `Switch` to route
  image, audio, text, PDF, or other file inputs through different subgraphs.
- `Export Artifact` to write a durable artifact back into the current server
  workspace.
- `ForEach` / array nodes over an `array<file>` input to analyze local files or
  local-folder contents file by file. `Local Folder` in the run form is a
  source for `array<file>`, so the workflow still receives files with
  preserved relative member paths rather than a live folder path.

## Development

```bash
npm install
npm run dev
```

Useful environment variables:

- `ABSTRACTGATEWAY_URL` or `ABSTRACTFLOW_GATEWAY_URL`: default Gateway target for the proxy.
- `ABSTRACTFLOW_ALLOW_REMOTE_BROWSER_GATEWAY_CONFIG=1`: allow non-local browsers to change the Gateway URL.
- `ABSTRACTFLOW_TRUST_PROXY_HEADERS=1`: honor forwarded host/proto headers behind a trusted reverse proxy.

## Build And Serve

```bash
npm run build
npm start -- --host 0.0.0.0 --port 3003 --gateway-url http://127.0.0.1:8080
```

## docs/workflow-authoring-skill.md

# AbstractFlow Workflow Authoring Skill

This is the operational guide for agents that author AbstractFlow VisualFlow
graphs. It is not general product documentation. It is the procedure and domain
model an authoring agent must use to create inspectable, runnable workflows.

The authoring prompt includes two sources of truth:

1. This skill document, which explains how to think and compose workflows.
2. A complete generated node catalog from `src/types/nodes.ts` — one line per
   palette template with exact node types, template variants, input/output pins
   and pin types, dynamic-pin allowance, document config fields, and Gateway
   capability availability. The catalog is authoritative for exact types and
   pins.

Use this guide for semantics and patterns. Use the generated catalog for exact
parameters. The committed companion catalog is `docs/workflow-node-catalog.md`;
in the web assistant the same information is generated at runtime with current
Gateway capability availability.

## Document Authoring Model

You author the COMPLETE workflow as one JSON document per cycle. The editor
diffs your document against the current graph, compiles the diff into validated
mutations, applies them, and reports any problems back.

Document shape:

```json
{
  "flow_name": "Deep Research",
  "nodes": [
    {"id": "start", "type": "on_flow_start", "outputs": [{"id": "topic", "type": "string"}]},
    {"id": "research_agent", "type": "agent", "label": "Research agent",
     "pin_defaults": {"system": "You are...", "max_iterations": 50}},
    {"id": "end", "type": "on_flow_end", "inputs": [{"id": "report", "type": "string"}]}
  ],
  "edges": [
    "start.exec-out -> research_agent.exec-in",
    "start.topic -> research_agent.prompt",
    "research_agent.exec-out -> end.exec-in",
    "research_agent.response -> end.report"
  ]
}
```

Node fields:

- `id`: stable identity. Keep existing ids unchanged so configuration and
  edges survive. A node cannot change type under the same id — give the
  replacement a new id and omit the old node.
- `type`: exact `nodeType` from the catalog. `template`: the palette variant
  label, required when the catalog line shows `template="..."`.
- `label`: short descriptive role, in the request language ("Discussion
  transcript", not "Variable"). Only On Flow Start / On Flow End may keep
  defaults.
- `pin_defaults`: values for unconnected input pins. Merged per key — omitted
  keys keep their current values; emit a key to change it.
- `literal`: value of literal/config nodes. For Tools Allowlist it is the
  array of exact tool names; for String Template it is the template text; for
  Variable nodes it is the declaration `{"name":"transcript","type":"array","default":[]}`.
- `code` / `function_name`: Code node Python body (sandbox only).
- `inputs` / `outputs`: the FULL dynamic data-pin list for dynamic-pin nodes
  (see Dynamic Pins). Pins omitted from an emitted list are removed.
- `switch_cases` (Switch), `branch_count` (Sequence/Parallel), `event`
  (event entry nodes), `tool` + `tool_parameters` (Tool Parameters),
  `concat_separator` (Concat).
- `position`: optional; omit it and existing nodes stay where the user put
  them while new nodes are auto-laid-out by execution depth.
- `agent_config` / `effect_config` / `subflow_id` appear in the serialized
  current document as read-only context; do not author them — use
  `pin_defaults` instead.

Edges are `"sourceNode.sourcePin -> targetNode.targetPin"` strings.

Ownership semantics:

- Emit the complete document every cycle: every node and every edge the
  workflow needs.
- Anything you omit is DELETED. Nodes and edges absent from your document are
  removed from the canvas. Never label a node "unused" or ask the user to
  remove anything — omit it and it is gone.
- Values shown as `<redacted>` are secrets; re-emit them verbatim or omit
  them. Never invent replacements.
- Re-emitting an unchanged document changes nothing and counts as a stalled
  cycle.

## Authoring Loop

One-shot first, repair after:

1. Parse the user intent into workflow responsibilities: trigger, inputs,
   context building, model/tool/generative actions, transforms, state, side
   effects, outputs, observability.
2. Author the COMPLETE workflow document in your first response. Preserve
   useful existing nodes (same ids) when the request builds on the current
   draft.
3. Later cycles exist to repair: validator errors, document issues, readiness
   issues, and acceptance review findings come back; fix only the reported
   problems and re-emit the full corrected document.
4. Return `status: continue` while more graph work remains; the editor applies
   your document and cycles again. Return `done` only when the graph visibly
   implements the request — an acceptance review then compares the graph
   against the request, and unmet findings come back as issues to fix.
5. On the first cycle of a new request, declare `acceptance_criteria`: 3-8
   concrete, checkable statements derived from the request, such as "one LLM
   Call per participant, each with a distinct model pin default".

Partial application: valid changes from your document are applied even when
others fail; failed items come back as document issues / skipped feedback.
Everything not listed was accepted and is in the current workflow document.
Repair against the current document, not against your earlier response.

Ask instead of stalling. If the request is ambiguous, requirements conflict,
or repair cycles keep failing without progress, return `status: needs_user`
with concrete questions in `reply` (in the request language). A cycle that
changes nothing and asks nothing wastes the whole turn.

A good workflow is not just a chain that "runs". It is readable: node labels
explain responsibility, data edges expose intent, and final outputs are wired
to On Flow End.

## Non-Negotiable Contract

- Match the request language. All user-visible content — flow name, node
  labels, prompts, system texts, templates, replies — must be written in the
  language of the user request unless the user asks otherwise.
- Use only node types and pins present in the generated catalog, plus
  explicitly allowed dynamic pins.
- Do not invent tools, providers, models, pins, node types, or Gateway routes.
- Do not silently fall back to a simpler workflow.
- If a required capability is missing or a configuration is not document-
  authorable, do not pretend it is done: return `failed` or `needs_user`.
- Respond with one bare JSON object only: no markdown fences, no prose around
  it.

## Gateway Capability Contract

Some nodes require Gateway capabilities (tool execution, generated image/
video/voice/music, model residency, KG memory). The live catalog line carries
`cap:<capability>(available | checking | UNAVAILABLE: reason)`:

- `available`: the node can be authored.
- `checking`: capability data still loading; be conservative and say execution
  depends on Gateway support.
- `UNAVAILABLE`: do not build a workflow that depends on the node unless the
  user explicitly accepts a blocked workflow; otherwise return `failed` or
  `needs_user` naming the missing capability.

Tool-dependent workflows must use the discovered Gateway tool inventory. Never
invent tool names.

## Dynamic Pins

Dynamic pins are the only pins you can author. All other pins are
template-owned and fixed. The document `inputs`/`outputs` lists are the full
desired pin list: pins you add appear, pins you omit are removed. Omitting the
field entirely keeps the current pins.

Dynamic input nodes (`inputs` list):

- `on_flow_end`: final outputs such as `markdown_report`, `sources`,
  `audit_trace`, `pdf_path`.
- `make_object` (Build JSON): object fields such as `topic`, `instructions`.
- `string_template`: extra template variable inputs when not using `vars`.
- `concat`: additional string inputs beyond `a` and `b`.

Dynamic output nodes (`outputs` list):

- `on_flow_start`: runtime inputs such as `research_topic`, `max_sources`.
- `break_object`: extracted object-field outputs such as `markdown_report`,
  `sources`. The emitted list also drives `breakConfig.selectedPaths`.

Never author execution pins; they are template-owned.

## Pin Types And Data Discipline

Use exact pin types from the catalog:

- `execution`: control flow only.
- `string`, `number`, `boolean`: scalars. `object`, `array`: JSON data.
- `json_schema`: JSON Schema objects for structured outputs.
- `tools`: tool-name allowlists for Agent/LLM/tool nodes.
- `artifact`, `artifact_image`, `artifact_audio`, `artifact_text`,
  `artifact_video`: saved reusable artifact references.
- `array`: generic collections. On workflow boundaries such as `On Flow Start`
  and `On Flow End`, keep the visible type as `array` and use the second
  selector to choose the item type. Use `array` of `file` when a runner should
  provide many local files or a local folder from this computer; a selected
  local folder expands into files with relative paths preserved.
- `provider_*`, `model_*`: provider/model selectors per capability.
- `memory`, `assertion`, `assertions`: memory/KG configuration and data.
- `any`: flexible data pin.

Never connect data to execution or execution to data. Avoid `any` when a more
precise pin exists.

Connection compatibility beyond exact matches:

- `tools <-> array`; `tools -> object`.
- `assertions <-> array`; `assertions <-> object`; `assertion <-> object`.
- `json_schema <-> object`; `memory <-> object`.
- `array -> object`; `number -> string`; `boolean -> string`.
- Artifact pins connect only to compatible modalities (generic artifact
  bridges typed ones). Media node `outputs`/`meta` object pins are not
  artifact refs.
- File arrays connect to generic `array` workflows. Use `ForEach`,
  `Array Length`, `Array Map`, `Array Filter`, or `Get Element` to analyze
  multi-file and folder inputs.
- Provider pins are nominal and modality-scoped; model pins are nominal —
  typed payload pins do not connect to model pins.
- `any` connects to everything except execution pins, including model and
  provider pins. This is how dynamic values reach nominal pins, e.g. a ForEach
  `item` from a model array into `llm_call.model`.

When a validator reports a type mismatch, change the target dynamic pin type,
wire a compatible source, or insert a transform/schema/break node. Do not
re-emit the same invalid edge.

Common rejected-edge mistakes (observed in real authoring runs — avoid them
in the FIRST emitted document):

- Scalars into object inputs: `string`/`number`/`boolean` outputs do NOT
  connect to an `object` input such as `string_template.vars`. Build the
  object first — `make_object` with one dynamic input per variable, then
  `make_object.result -> string_template.vars` — or skip `vars` entirely by
  declaring extra dynamic inputs on the `string_template` node and
  referencing them as `{{name}}` in the template.
- Wiring into loop outputs: `loop` and `done` on `for`/`loop`/`while` are
  execution OUTPUTS, never targets. Nested loops: `outer.loop ->
  inner.exec-in` (directly or after body steps); after `inner.done` the body
  chain simply ends or continues with more outer-body steps — the runtime
  returns to the outer loop automatically. Never emit `inner.done ->
  outer.loop` or `inner.done -> outer.done`.
- Edge grammar and identity: both endpoints must be `node_id.pin_id` and the
  node ids must exist in `nodes[]`. `literal_one -> add.b` is invalid
  (missing source pin); `literal_one.value -> add.b` is valid only when a
  node with id `literal_one` is defined in the same document.

## Connection Cardinality

- Data inputs accept at most one incoming edge. Emitting a different source
  for an occupied data input replaces the edge.
- Execution inputs allow fan-in.
- Execution outputs are one-to-one. For fan-out, insert `sequence` (ordered)
  or `parallel` (concurrent) and connect each `then:<n>` output once. The
  editor auto-inserts a `sequence` when an exec output is double-connected and
  reports the rewiring as a warning.
- Data self-wiring is rejected.
- Multi-entry exception: when a node has 2+ incoming execution edges, a data
  input may carry the base edge plus at most one route override per execution
  path; connecting the data pin from a direct execution predecessor creates
  the override automatically.

## Execution Model

Execution nodes must be in the execution chain; pure data/config nodes are
evaluated from data dependencies and have no exec pins (Build JSON, String
Template, JSON Schema, Tools Allowlist, Parse JSON, Break Object, Agent Trace
Report, math, string, and most transforms).

Entry and terminal:

- `on_flow_start`: standard run entry; add runtime input outputs here.
- `on_user_request`: chat entry (user `message` and `context`).
- `on_schedule`, `on_event`, `on_agent_message`: event entries.
- `on_flow_end`: terminal; add an input for every output the run exposes.

Common chains:

- Simple AI workflow: `on_flow_start.exec-out -> agent.exec-in -> on_flow_end.exec-in`.
- LLM plus tools: `on_flow_start -> llm_call -> tool_calls -> llm_call/agent -> on_flow_end`.
- File side effect: `agent.exec-out -> write_file.exec-in -> on_flow_end.exec-in`.
- Branches: `if` (boolean true/false), `switch` (string cases).
- Loops: `loop` (foreach array), `for` (numeric), `while` (boolean).

Loop body semantics (control frames):

- Connect `<loop>.loop` to the first body node and chain the body with exec
  edges. When the body chain ends, the runtime returns to the loop node
  automatically for the next iteration.
- NEVER wire the last body node back to the loop's `exec-in` — that resets the
  iteration counter (infinite loop). The editor removes such loop-backs with a
  warning.
- `done` is an execution OUTPUT that fires after the final iteration:
  `<loop>.done -> <next step>.exec-in`. Never wire anything into `done`.
- For several body steps per iteration, chain them or use
  `<loop>.loop -> sequence.exec-in` with `then:<n>` branches.

## Node Family Guide

The catalog gives exact pins; this section explains usage.

### Events And Timing

`on_flow_start` (default manual entry), `on_flow_end` (final boundary),
`on_user_request` (chat), `on_agent_message`, `on_schedule` (configure
`event.schedule`/`event.recurrent`), `on_event` (durable custom events),
`wait_event` (pause for event), `emit_event`, `wait_until` (delay),
`system_datetime` (pure current-time metadata for prompts/filenames/digests).

Scheduled digest pattern: `on_schedule` -> prompt builder -> Agent/LLM ->
write/report -> `on_flow_end`, with `system_datetime.iso` in prompt variables.

### LLM And Agent Nodes

`llm_call` — one model call. Classification, rewriting, extraction,
summarization, routing, synthesis. Inputs: `system`, `prompt`, `context`,
`memory`, provider/model, `tools`, generation controls, `resp_schema`.
Outputs: `response` text, structured `data` (when schema active),
`tool_calls`, `meta`, `success`. Tools exposed to `llm_call` produce tool-call
requests; a separate `tool_calls` node executes them.

`agent` — autonomous multi-step work with tools and iterative reasoning (deep
research, planning, multi-source synthesis):

- Always author a non-empty `system`: role, quality bar, citation/source
  requirements, iteration strategy, final output contract.
- `prompt` carries the concrete task (usually from String Template).
- `tools` from Tools Allowlist or discovered runtime tool names.
- `max_iterations` 50 for deep iterative work unless the user asks smaller.
- `resp_schema` when downstream needs structured fields; wire `agent.data` ->
  Break Object. `agent.response` is final text. `agent.scratchpad` is for
  audit/trace only. `agent.meta` is execution metadata — never sources,
  citations, or user-facing research data.

Structured agent report pattern: On Flow Start fields -> Build JSON ->
String Template.vars; String Template.result -> Agent.prompt; JSON Schema ->
Agent.resp_schema; Tools Allowlist -> Agent.tools; Agent.data -> Break Object
-> On Flow End; Agent.scratchpad -> Agent Trace Report -> On Flow End
audit_trace.

Choosing between `llm_call`, `agent`, and direct tool calls — decide per
step, not per workflow:

- `llm_call`: ONE model pass over inputs already in the graph (classify,
  rewrite, extract, summarize, route, synthesize a provided transcript). No
  external information is gathered. Cheapest and most deterministic.
- `agent`: the step must DISCOVER information or iterate (search the web,
  read sources, retry, refine across multiple tool calls). One agent per
  responsibility; give it tools and an authored `system`.
- `tool_parameters` -> `make_array` -> `tool_calls`: exactly one known tool
  call with known arguments (deterministic fetch/write); no model needed to
  decide anything.
- If the request demands fresh external knowledge (research, news, current
  facts) inside a step, a bare `llm_call` CANNOT satisfy it — use an `agent`
  with search/fetch tools there, or return `needs_user` if no suitable tool
  exists in the inventory.

### Tools

Use the discovered Gateway tool inventory from the prompt; names must match
exactly. `recommended_for_request=true` is a relevance hint only.

Tool selection discipline (per agent, least privilege):

- Match each agent's allowlist to ITS role using the inventory's
  `description`/`when_to_use`: a web-research agent gets search + fetch
  tools; a file-report agent gets file-write tools; never both "just in
  case". Different agents in one workflow normally get DIFFERENT allowlists.
- Leaving `agent.tools` unset gives the agent the FULL runtime tool set at
  execution time. That is a deliberate broad-access choice, acceptable only
  for general-purpose assistants — tool-dependent workflows must declare
  explicit allowlists.
- Never invent tool names; if the capability a step needs is missing from
  the inventory, say so via `needs_user` instead of substituting a
  hallucinated tool.

- `tools_allowlist`: reusable tool-name list; set via `literal` array.
- `tool_parameters`: builds one tool-call object for a selected tool
  (deterministic direct calls); configure via `tool` + `tool_parameters`.
- `tool_calls`: executes tool-call objects; requires
  `pin_defaults.allowed_tools` in the same document node that creates it.
- `format_tool_results`: tool results -> readable text for prompts/reports.

Patterns: agentic research = Tools Allowlist -> Agent.tools. Deterministic
step = Tool Parameters -> Make Array -> Tool Calls. LLM-planned calls =
LLM Call.tool_calls -> Tool Calls.tool_calls -> Format Tool Results -> next
prompt.

### Generative Media And Capability Nodes

`generate_image`, `edit_image`, `upscale_image`, `generate_video`,
`image_to_video`, `generate_voice`, `generate_music`, `transcribe_audio`,
`listen_voice`, `model_residency`. They call Gateway capabilities and return
artifact references: typed artifact outputs plus generic `artifact_ref`,
`artifact_id`, `content_type`, `outputs`, `meta`, `success`. Prefer typed
artifact outputs for downstream media nodes; expose artifact refs/ids at
On Flow End. Leave provider/model pins blank unless the user pins a backend.

Patterns: illustrated report = Agent/LLM image prompt -> Generate Image ->
On Flow End image artifact. Voice summary = report text -> Generate
Voice.text -> On Flow End audio artifact. Chained media = typed artifact
output -> next media node input (Edit Image.image_artifact,
Image To Video.source_image).

### Code

`code` runs a Python transform body in the Runtime sandbox when no dedicated
transform node exists. Input pin `input` is the payload; outputs are `output`,
`success`, `execution`. Keep permissions `sandbox`; never `full_access` (the
validator rejects it and secret-looking code). The sandbox rejects imports,
network, subprocesses, and filesystem access. Use Code for deterministic
transforms: formatting, parsing, shaping, checksums, filenames, validation.
Never use Code to fake PDF generation — use Write PDF.

### Files vs Artifacts

Use the same source contract the product UI teaches:

- `Artifact`: saved reusable file data already in AbstractFlow. Artifact pins
  expect this shape.
- `Local File`: a file uploaded from this computer. For artifact inputs, the
  upload becomes a saved artifact before the run.
- `Local Folder`: a folder chosen from this computer. In hosted Flow, each
  file is uploaded before the run and the workflow receives an ordered saved
  file list with preserved relative member paths in artifact provenance.
- `Server File`: a workspace-scoped server file. For artifact inputs, server
  import creates a saved artifact snapshot. For file nodes, the flow uses the
  server path directly.

Node behavior:

- `read_file` / `write_file`: execution nodes reading/writing workspace-scoped
  server text files (`.md`, `.json`, `.txt`). In Gateway-hosted runs, these
  paths stay within workspace policy. In local Runtime-only runs without a
  workspace scope, relative paths fall back to the process working directory.
  Write File outputs byte count and `file_path`. Not a PDF generator.
- `read_pdf` / `write_pdf`: execution nodes for real workspace-scoped server
  `.pdf` files; Write PDF renders text/Markdown report content and outputs
  bytes, sha256, `file_path`.
- Expose file paths through On Flow End when the user asked for files.
- Artifact literal nodes (`template` variants: Text/Image/Voice/Music/Video
  Artifact) create typed refs for existing saved artifacts.
- For one local file input, use an `artifact*` output pin on `On Flow Start`.
  In the editor this appears as `file`.
- For many local files or a local folder whose files should be analyzed, use an
  `array` boundary input with item type `file`.
- Local Folder in the run form is a source for `array<file>`. It still arrives
  as files with preserved relative member paths, not as a live folder path
  string. If the workflow needs a writable live folder path, use `server
  folder` (`workspace_folder`), not a local-folder upload.
- To branch on uploaded/imported file kinds, use `Read Artifact` and switch on
  `content_family` (simple routing) or `content_type` (exact MIME routing).

File pattern: content -> Write File.content; path default ->
Write File.file_path; exec chain through Write File before On Flow End;
Write File.file_path -> On Flow End `markdown_path`/`report_path`. Same shape
for Write PDF with a `.pdf` path -> `pdf_path`. Do not claim an asset exists
unless the graph creates and exposes it.

### Data, JSON, And Prompt Building

`make_object` (Build JSON, dynamic fields), `make_array`, `get`, `set`,
`merge`, `get_element`, `get_random_element`, `parse_json`, `stringify_json`,
`break_object`, `coalesce`, `make_context`, `add_message`, `get_context`,
array utilities (length, append, dedup, map, filter, concat),
`format_tool_results`, `make_meta`, `make_scratchpad`, `agent_trace_report`.

Prompt-building pattern: On Flow Start fields -> Build JSON inputs; Build
JSON.result -> String Template.vars; template text via `literal` or
`pin_defaults.template`; String Template.result -> Agent/LLM prompt. Prefer
String Template over embedding large prompt text when runtime variables are
needed.

### String And Math Nodes

Pure transforms: `concat`, `split`, `join`, `format`, `string_template`,
`uppercase`, `lowercase`, `trim`, `contains`, `replace`, `substring`,
`length`, `is_empty_string`; arithmetic (add/subtract/multiply/divide/modulo/
power/abs/round) and random (random_int, random_float). For complex
transforms, prefer Code.

### Control Flow

`if` (boolean), `switch` (string cases via `switch_cases`), `sequence`,
`parallel` (branch outputs via `branch_count`), `loop` (foreach: `item`,
`index`), `for` (numeric), `while` (conditional), plus pure helpers
`compare`, `and`, `or`, `not`.

Classify-and-branch pattern: LLM Call with JSON Schema enum -> LLM Call.data
-> Break Object.choice -> Switch.value; LLM Call.exec-out -> Switch.exec-in;
case outputs -> branch nodes.

### Variables And Runtime State

- `var_decl` / `bool_var`: declare workflow-scope variables; no input pins.
  Configure via `literal` `{"name":"transcript","type":"array","default":[]}`
  (canonical) or `pin_defaults` `name`/`value`. The declared name is the key
  `get_var`/`set_var` use.
- `get_var`, `set_var` (dotted nested paths), `set_var_property`, `set_vars`,
  `get_context`.

Use variables for counters, accumulated arrays, branch decisions, and loop
state; use pure data nodes for local transforms.

### Memory And Knowledge Graph

Execution nodes: `memory_note`, `memory_query`, `memory_tag`,
`memory_compact`, `memory_rehydrate`, `memory_kg_query`, `memory_kg_resolve`,
`memory_kg_assert`, `memact_compose`. Use memory when the workflow should
remember, recall, ground, or update durable knowledge — not as a substitute
for prompt building.

Pattern: question -> Memory Query.query; Memory Query.rendered + question ->
prompt scaffold -> Agent; Agent output -> Memory Note when worth remembering.

### Schemas And Structured Output

`json_schema` (static literal -> `resp_schema`), `edit_json_schema` (extend
incoming schema). Agent/LLM with schema exposes `response` text and `data`
object; use Break Object for fields. When Markdown is a field inside a
structured result, extract the string before writing files:
`Agent.data -> Break Object.markdown_report -> Write File.content` (or
Parse JSON first if the model returned JSON as text). Use structured output
for report sections + citations, classifications, extracted entities, result
arrays, validation results, and file path plans.

### Provider And Model Catalog Nodes

`provider_catalog`, `provider_models`, `model_residency` — only when the
workflow itself inspects providers/models. For ordinary workflows leave
provider/model pins blank so Gateway defaults apply. Dynamic model wiring
(model pool -> `llm_call.model` through a loop item) with provider blank is
valid. Validation only flags a half-typed default pair (provider typed while
model blank, or the reverse).

## Best-In-Class Patterns

These are worked exemplars, not a closed list. Derive graph structure from the
request. The most common authoring failure is collapsing requested structure
into a single Agent prompt that "simulates" it: if the user asks for multiple
AI participants, distinct models, rounds/cycles, or visible intermediate
state, those must exist as nodes and edges, not as sentences inside one
prompt.

### Iterative Multi-Participant Discussion (Loop + State)

Request shape: "N AIs discuss a topic for up to M rounds, then a final answer
is synthesized from the whole discussion."

- On Flow Start outputs: topic, participant count, max rounds.
- Model pool: `literal_array` of model id strings (or `provider_models`).
- Round loop: `for` with `end` from max rounds; `for.loop -> participant
  loop.exec-in`; `for.done -> synthesis`.
- Participant loop: `loop` over the model array; `loop.item -> llm_call.model`
  so each participant uses a different model.
- Discussion state: declare a transcript variable; `get_var(transcript)` feeds
  prompt building (topic, round index, transcript, role); after the call
  Array Append (or Concat) -> `set_var(transcript)`.
- Body exec chain ends at the state update; the loop re-enters by itself:
  `loop.loop -> llm_call.exec-in -> set_var.exec-in` and STOP. No edge back to
  the loop. `get_var`, String Template, Array Append are pure data nodes.
- Each participant prompt must instruct the model to advance the discussion,
  not repeat prior turns.
- Synthesis after `for.done`: final LLM Call over topic + full transcript.
- On Flow End: final answer, transcript (or path), round count.

One Agent prompted to "simulate a discussion between N AIs" does not satisfy
this request: one model, one call, no visible rounds.

### Multi-Model Fan-Out (Different Model Per Call)

One `llm_call` per pinned model (per-node `model` default) wired in
`sequence`/`parallel`, or a `loop` over a model array feeding one
`llm_call.model` with accumulation when the list is dynamic. Accumulate into a
variable, synthesize with a final LLM Call, expose answers + synthesis at
On Flow End.

### Deep Research With Markdown And PDF Outputs

- On Flow Start outputs: topic/query, optional scope, source policy.
- Build JSON: topic, instructions, report structure, citation rules.
- String Template: final research prompt. Tools Allowlist: discovered
  web/search/fetch tools. JSON Schema: markdown_report, sources, optional
  confidence/limitations.
- Agent: authored system, prompt, tools, resp_schema, max_iterations 50.
- Break Object: markdown_report + sources from Agent.data. Never wire
  Agent.data or a stringified whole object directly into a Markdown file —
  the `.md` Write File content must be the Markdown string field.
- Write File `.md` and Write PDF `.pdf` on the exec path; expose both paths.
- Agent Trace Report: Agent.scratchpad -> audit_trace.
- On Flow End: markdown_report, sources, audit_trace, markdown_path, pdf_path.

A single Agent connected straight to On Flow End is not enough when the user
requested files, citations, and auditability.

### News Digest

On Flow Start (topic, region, date range, audience) + System Date/Time ->
prompt scaffold with freshness/source policy -> Tools Allowlist -> Agent or
LLM + Tool Calls -> structured output (headlines, links, dates, reliability,
digest) -> optional Markdown Write File -> On Flow End.

### Job Search

On Flow Start (field, seniority, location, remote, exclusions) -> Tools
Allowlist -> Agent with dedup/source-capture rules -> JSON Schema jobs array
(title, company, location, URL, fit score, reason, date) -> Break Object ->
On Flow End; optional Markdown/CSV file outputs.

### Human-In-The-Loop

Ask User only when the workflow must pause mid-execution; On Flow Start inputs
for normal parameters; Answer User for host-visible messages; Wait Event for
durable external waits.

## Validation And Repair

The assistant runs graph readiness checks after each cycle. For research/news/
job-search/deep-research requests, readiness requires: On Flow Start and
On Flow End; an Agent for research/reporting; at least one On Flow Start data
output; a Build JSON -> String Template prompt scaffold; exec flow
`On Flow Start -> Agent -> On Flow End`; `Build JSON.result -> String
Template.vars`; `String Template.result -> Agent.prompt`; a connected or
configured Agent prompt; a non-empty Agent system; `max_iterations >= 50`;
final report, sources/citations, and an audit/trace output exposed through
connected On Flow End inputs; no `Agent.meta` edge as sources; no Agent Trace
Report edge as the final report; `Agent.scratchpad -> Agent Trace
Report.scratchpad` when using trace report; Tools Allowlist wired to
Agent.tools (or explicit Agent tools) when tools are required.

Markdown file requests additionally require a Write File targeting a Markdown
path, report content into `Write File.content`, Write File on the exec path
before On Flow End, and `file_path` exposed through On Flow End. PDF file
requests require the same shape with Write PDF and a `.pdf` path.

When repairing:

- Read every validator error and document issue.
- Do not re-emit the same invalid edge or nonexistent pin.
- If a pure node lacks exec pins, remove exec edges touching it.
- If a data pin type mismatches, change the dynamic pin type or insert a
  transform.
- If an output is missing, add the On Flow End input and connect a real
  producer.
- If a requested artifact is missing, add the file/media path and wire it
  visibly.

If readiness issues remain after a successful cycle, continue with a corrected
full document. Do not declare completion early.

### Acceptance Review

Readiness checks are structural floors; they cannot verify that the graph
means what the user asked. When you return `status: done` with clean
readiness, the editor runs an acceptance review: a reviewer receives the user
request, your declared `acceptance_criteria`, and the current workflow
document, and returns unmet findings. Findings come back under `ACCEPTANCE
REVIEW FINDINGS TO RESOLVE` and must be implemented in the graph (not argued
with) before `done` is accepted.

## Response Requirements

Every turn must include: how the workflow works, how to test it with the
normal Save/Run path, what to expect from outputs and artifacts, and
`acceptance_criteria` on the first cycle of each new request.

Successful chat replies should be concise. Failure replies should include
enough planner and validator detail to debug the graph.

The first field of the response JSON must be `language`: the ISO 639-1 code of
the USER REQUEST language (e.g. `en`, `fr`). All user-visible text fields and
all user-visible text inside the graph document (labels, prompts, templates)
must be written in that language. The editor verifies the reply language every
cycle and rejects mismatched responses with a correction note.

## docs/workflow-node-catalog.md

# AbstractFlow Workflow Node Catalog

This catalog is generated from `src/types/nodes.ts` by `npm run docs:llms`.
It is the stable AI-readable companion to `docs/workflow-authoring-skill.md`.

Workflows are authored as one JSON document: `{"flow_name", "nodes": [...], "edges": ["node.pin -> node.pin", ...]}`. Each document node uses `type` matching the value shown here; if several visible palette entries share a `type`, set `template` to the exact variant label shown in the document node snippet.

## Visible Authoring Templates

### artifacts / Artifact

- Node type: `literal_json`
- Document node: `{"id":"<unique_id>","type":"literal_json","template":"Artifact"}`
- Utility: Saved artifact reference object for any runtime-owned file or payload. Use this with Read Artifact or artifact-aware media/file nodes.
- Gateway capability: none
- Dynamic pin policy: template pins only
- Authorable config: select with `"template": "Artifact"`; literal value with `literal`
- Inputs: none
- Outputs: `value` artifact (artifact)
- Default config: none

### artifacts / Image Artifact

- Node type: `literal_json`
- Document node: `{"id":"<unique_id>","type":"literal_json","template":"Image Artifact"}`
- Utility: Saved artifact reference object for an image artifact. Wire this into Edit Image image_artifact or mask_artifact.
- Gateway capability: none
- Dynamic pin policy: template pins only
- Authorable config: select with `"template": "Image Artifact"`; literal value with `literal`
- Inputs: none
- Outputs: `value` artifact_image (image_artifact)
- Default config: {
  "literalValue": {
    "$artifact": "",
    "content_type": "image/png",
    "modality": "image"
  }
}

### artifacts / Music Artifact

- Node type: `literal_json`
- Document node: `{"id":"<unique_id>","type":"literal_json","template":"Music Artifact"}`
- Utility: Saved artifact reference object for a music/audio artifact.
- Gateway capability: none
- Dynamic pin policy: template pins only
- Authorable config: select with `"template": "Music Artifact"`; literal value with `literal`
- Inputs: none
- Outputs: `value` artifact_audio (music_artifact)
- Default config: {
  "literalValue": {
    "$artifact": "",
    "content_type": "audio/wav",
    "modality": "music"
  }
}

### artifacts / Text Artifact

- Node type: `literal_json`
- Document node: `{"id":"<unique_id>","type":"literal_json","template":"Text Artifact"}`
- Utility: Saved artifact reference object for a text/plain artifact. Paste an uploaded, imported, or generated artifact id into $artifact.
- Gateway capability: none
- Dynamic pin policy: template pins only
- Authorable config: select with `"template": "Text Artifact"`; literal value with `literal`
- Inputs: none
- Outputs: `value` artifact_text (text_artifact)
- Default config: {
  "literalValue": {
    "$artifact": "",
    "content_type": "text/plain",
    "modality": "text"
  }
}

### artifacts / Video Artifact

- Node type: `literal_json`
- Document node: `{"id":"<unique_id>","type":"literal_json","template":"Video Artifact"}`
- Utility: Saved artifact reference object for a video artifact.
- Gateway capability: none
- Dynamic pin policy: template pins only
- Authorable config: select with `"template": "Video Artifact"`; literal value with `literal`
- Inputs: none
- Outputs: `value` artifact_video (video_artifact)
- Default config: {
  "literalValue": {
    "$artifact": "",
    "content_type": "video/mp4",
    "modality": "video"
  }
}

### artifacts / Voice Artifact

- Node type: `literal_json`
- Document node: `{"id":"<unique_id>","type":"literal_json","template":"Voice Artifact"}`
- Utility: Saved artifact reference object for a speech/audio artifact.
- Gateway capability: none
- Dynamic pin policy: template pins only
- Authorable config: select with `"template": "Voice Artifact"`; literal value with `literal`
- Inputs: none
- Outputs: `value` artifact_audio (voice_artifact)
- Default config: {
  "literalValue": {
    "$artifact": "",
    "content_type": "audio/wav",
    "modality": "voice"
  }
}

### control / AND

- Node type: `and`
- Document node: `{"id":"<unique_id>","type":"and"}`
- Utility: Logical AND.
- Gateway capability: none
- Dynamic pin policy: template pins only
- Authorable config: input defaults with `pin_defaults`
- Inputs: `a` boolean; `b` boolean
- Outputs: `result` boolean
- Default config: none

### control / Compare

- Node type: `compare`
- Document node: `{"id":"<unique_id>","type":"compare"}`
- Utility: Compare a and b using operator op (==, !=, <, <=, >, >=).
- Gateway capability: none
- Dynamic pin policy: template pins only
- Authorable config: input defaults with `pin_defaults`
- Inputs: `a` any; `op` string; `b` any
- Outputs: `result` boolean
- Default config: none

### control / For

- Node type: `for`
- Document node: `{"id":"<unique_id>","type":"for"}`
- Utility: Numeric loop from start to end with step. Outputs i and a 0-based index.
- Gateway capability: none
- Dynamic pin policy: template pins only
- Authorable config: input defaults with `pin_defaults`
- Inputs: `exec-in` execution; `start` number; `end` number; `step` number
- Outputs: `loop` execution; `done` execution; `i` number; `index` number
- Default config: none

### control / If/Else

- Node type: `if`
- Document node: `{"id":"<unique_id>","type":"if"}`
- Utility: Branch execution based on a boolean condition.
- Gateway capability: none
- Dynamic pin policy: template pins only
- Authorable config: input defaults with `pin_defaults`
- Inputs: `exec-in` execution; `condition` boolean
- Outputs: `true` execution; `false` execution
- Default config: none

### control / ForEach

- Node type: `loop`
- Document node: `{"id":"<unique_id>","type":"loop"}`
- Utility: Iterate over an array. Outputs current item and 0-based index.
- Gateway capability: none
- Dynamic pin policy: template pins only
- Authorable config: input defaults with `pin_defaults`
- Inputs: `exec-in` execution; `items` array
- Outputs: `loop` execution; `done` execution; `item` any; `index` number
- Default config: none

### control / NOT

- Node type: `not`
- Document node: `{"id":"<unique_id>","type":"not"}`
- Utility: Logical NOT.
- Gateway capability: none
- Dynamic pin policy: template pins only
- Authorable config: input defaults with `pin_defaults`
- Inputs: `value` boolean
- Outputs: `result` boolean
- Default config: none

### control / OR

- Node type: `or`
- Document node: `{"id":"<unique_id>","type":"or"}`
- Utility: Logical OR.
- Gateway capability: none
- Dynamic pin policy: template pins only
- Authorable config: input defaults with `pin_defaults`
- Inputs: `a` boolean; `b` boolean
- Outputs: `result` boolean
- Default config: none

### control / Parallel

- Node type: `parallel`
- Document node: `{"id":"<unique_id>","type":"parallel"}`
- Utility: Run multiple branches concurrently and emit Completed when all finish.
- Gateway capability: none
- Dynamic pin policy: template pins only
- Authorable config: input defaults with `pin_defaults`; branch count with `branch_count`
- Inputs: `exec-in` execution
- Outputs: `then:0` execution (Then 0); `then:1` execution (Then 1); `completed` execution (Completed)
- Default config: none

### control / Sequence

- Node type: `sequence`
- Document node: `{"id":"<unique_id>","type":"sequence"}`
- Utility: Run multiple branches in order (Then 0, Then 1, ...).
- Gateway capability: none
- Dynamic pin policy: template pins only
- Authorable config: input defaults with `pin_defaults`; branch count with `branch_count`
- Inputs: `exec-in` execution
- Outputs: `then:0` execution (Then 0); `then:1` execution (Then 1)
- Default config: none

### control / Switch

- Node type: `switch`
- Document node: `{"id":"<unique_id>","type":"switch"}`
- Utility: Branch execution by matching a string value to configured cases (default branch always exists).
- Gateway capability: none
- Dynamic pin policy: template pins only
- Authorable config: input defaults with `pin_defaults`; cases with `switch_cases`
- Inputs: `exec-in` execution; `value` string
- Outputs: `default` execution
- Default config: {
  "switchConfig": {
    "cases": []
  }
}

### control / While

- Node type: `while`
- Document node: `{"id":"<unique_id>","type":"while"}`
- Utility: Loop while condition is true. Outputs a pass-through item and a 0-based iteration index.
- Gateway capability: none
- Dynamic pin policy: template pins only
- Authorable config: input defaults with `pin_defaults`
- Inputs: `exec-in` execution; `condition` boolean
- Outputs: `loop` execution; `done` execution; `item` any; `index` number
- Default config: none

### core / Add Message

- Node type: `add_message`
- Document node: `{"id":"<unique_id>","type":"add_message"}`
- Utility: Append a canonical message to the run active context (context.messages).
- Gateway capability: none
- Dynamic pin policy: template pins only
- Authorable config: input defaults with `pin_defaults`
- Inputs: `exec-in` execution; `role` string: Message role (e.g. user, assistant, system, tool).; `content` string: Message content.
- Outputs: `exec-out` execution; `message` object: Message object {role, content, timestamp, metadata.message_id}.; `context` object: Updated active context object (run.vars.context).; `task` string: Convenience output for context.task.; `messages` array: Updated context.messages list.
- Default config: none

### core / Agent

- Node type: `agent`
- Document node: `{"id":"<unique_id>","type":"agent"}`
- Utility: Run an agent (ReAct) that can call tools. Outputs response, success, meta, and a runtime scratchpad.
- Gateway capability: none
- Dynamic pin policy: template pins only
- Authorable config: input defaults with `pin_defaults`
- Inputs: `exec-in` execution; `use_context` boolean: When true, include this run's active context messages (context.messages) as agent history. If the pin is not connected, the node checkbox is used. Default: false.; `context` object: Optional explicit context object for the agent (e.g. {messages:[...]}). If provided, context.messages overrides the inherited run context messages.; `memory` memory: Memory configuration object (KG/span/session controls). If set, overrides this node’s recall/ingest behavior; if unset, runtime defaults apply.; `provider` provider_text: Text/LLM provider id (e.g. LMStudio). If unset, uses the node’s configured provider.; `model` model: Text/LLM model id/name. If unset, uses the node’s configured model.; `system` string: Optional system prompt for this agent instance (high priority instructions).; `prompt` string: User prompt/task string for the agent to solve.; `tools` tools: Allowlist of tool names this agent can call (defense-in-depth; runtime still enforces allowlists).; `prompt_cache_binding` any: Advanced: durable exact-reuse prompt-cache binding from Gateway blocs. Accepts a binding object or binding_id string; this does not create or load blocs during the run.; `max_iterations` number: Maximum internal ReAct iterations (safety cap). Higher values allow more tool-use steps.; `max_in_tokens` number: Optional per-agent input token budget (max_input_tokens). When set, overrides the run's default _limits.max_input_tokens for the agent sub-run.; `temperature` number: Sampling temperature (0 = deterministic). If unset, uses the node’s configured temperature.; `seed` number: Seed for deterministic sampling (-1 = random/unset). If unset, uses the node’s configured seed.; `thinking` string: Reasoning/thinking control for supported models. If unset, uses the Gateway/runtime default.; `resp_schema` json_schema: Optional JSON Schema object (type=object) the final answer must conform to.
- Outputs: `exec-out` execution; `response` string: Final response text. When resp_schema is provided, the structured object is also exposed on data.; `data` object: Structured response object matching resp_schema. Visible by default when a response schema is configured.; `success` boolean: True if the Agent node completed successfully.; `meta` object: Host-facing meta envelope (schema=abstractcode.agent.v1.meta). Includes provider/model and lightweight execution metadata.; `scratchpad` object: Runtime-owned execution trace/scratchpad for observability (LLM/tool steps, timings). Includes best-effort tool_calls/tool_results extracted post-run.
- Default config: {
  "pinDefaults": {
    "max_iterations": 50
  }
}

### core / Answer User

- Node type: `answer_user`
- Document node: `{"id":"<unique_id>","type":"answer_user"}`
- Utility: Display a message to the user (UI output).
- Gateway capability: none
- Dynamic pin policy: template pins only
- Authorable config: input defaults with `pin_defaults`
- Inputs: `exec-in` execution; `message` string; `level` string: Message level for hosts (message|warning|error). Defaults to 'message' when unset.
- Outputs: `exec-out` execution; `message` string
- Default config: none

### core / Ask User

- Node type: `ask_user`
- Document node: `{"id":"<unique_id>","type":"ask_user"}`
- Utility: Pause execution and ask the user for input (free text or choices).
- Gateway capability: none
- Dynamic pin policy: template pins only
- Authorable config: input defaults with `pin_defaults`
- Inputs: `exec-in` execution; `prompt` string; `choices` array
- Outputs: `exec-out` execution; `response` string
- Default config: none

### core / Code

- Node type: `code`
- Document node: `{"id":"<unique_id>","type":"code"}`
- Utility: Run a Python transform body as `transform(_input)` in the Runtime sandbox.
- Gateway capability: none
- Dynamic pin policy: template pins only
- Authorable config: input defaults with `pin_defaults`; body/function with `code`/`function_name`; permissions must remain `sandbox`
- Inputs: `exec-in` execution; `input` any; `permissions` string: Execution policy for this Code node. sandbox is the protected default. full_access requires explicit Runtime/Gateway policy and otherwise fails closed.
- Outputs: `exec-out` execution; `output` any: Value returned by transform(_input).; `success` boolean: True when the transform ran without error.; `execution` object: Execution metrics such as duration_ms, cpu_time_ms, cpu_percent, memory_rss_mb, and memory_rss_delta_mb.
- Default config: {
  "pinDefaults": {
    "permissions": "sandbox"
  },
  "codeBody": "# Available variables:\n# _input (dict)\n# input (any)\n\nreturn _input",
  "functionName": "transform"
}

### core / LLM Call

- Node type: `llm_call`
- Document node: `{"id":"<unique_id>","type":"llm_call"}`
- Utility: Single LLM call (no autonomous loop). Can optionally request tool calls via the tools allowlist.
- Gateway capability: none
- Dynamic pin policy: template pins only
- Authorable config: input defaults with `pin_defaults`
- Inputs: `exec-in` execution; `use_context` boolean: When true, include this run's active context messages (context.messages) in the LLM request. If the pin is not connected, the node checkbox is used. Default: false.; `context` object: Optional explicit context object for this call (e.g. {messages:[...]}). If provided, context.messages overrides inherited run context messages.; `memory` memory: Memory configuration object (KG/span/session controls). If set, overrides this call’s recall behavior; if unset, runtime defaults apply.; `provider` provider_text: Text/LLM provider id (e.g. LMStudio). If unset, uses the node’s configured provider.; `model` model: Text/LLM model id/name. If unset, uses the node’s configured model.; `system` string: Optional system prompt for this single call.; `prompt` string: User prompt/content for this single call.; `tools` tools: Allowlist of tools exposed to the model as ToolSpecs (model may request tool calls; execution is done via a Tool Calls node).; `prompt_cache_binding` any: Advanced: durable exact-reuse prompt-cache binding from Gateway blocs. Accepts a binding object or binding_id string; this does not create or load blocs during the run.; `max_in_tokens` number: Optional per-call input token budget (max_input_tokens). When set, overrides the run's default _limits.max_input_tokens for this call.; `temperature` number: Sampling temperature (0 = deterministic). If unset, uses the node’s configured temperature.; `seed` number: Seed for deterministic sampling (-1 = random/unset). If unset, uses the node’s configured seed.; `thinking` string: Reasoning/thinking control for supported models. If unset, uses the Gateway/runtime default.; `resp_schema` json_schema: Optional JSON Schema object (type=object) the assistant content must conform to.
- Outputs: `exec-out` execution; `response` string: Assistant text content (best-effort). For tool calls, content may be empty.; `data` object: Structured assistant output object matching resp_schema. Visible by default when a response schema is configured.; `success` boolean: True if the LLM call completed successfully.; `meta` object: Host-facing meta envelope (schema=abstractflow.llm_call.v1.meta). Includes provider/model, usage, trace ids, and lightweight execution metadata.; `tool_calls` array: Normalized tool call requests. This pin exists to make wiring into Tool Calls / Emit Event nodes simpler.
- Default config: none

### core / Model Residency

- Node type: `model_residency`
- Document node: `{"id":"<unique_id>","type":"model_residency"}`
- Utility: Gateway/Runtime model residency controls for listing, loading, and unloading resident models.
- Gateway capability: model_residency
- Dynamic pin policy: template pins only
- Authorable config: input defaults with `pin_defaults`
- Inputs: `exec-in` execution; `operation` string: list_loaded, load, or unload.; `task` string: text_generation, image_generation, image_to_image, image_upscale, text_to_video, image_to_video, tts, stt, or music_generation.; `provider` provider: Provider/backend id to load or filter.; `model` model: Model id to load or filter.
- Outputs: `exec-out` execution; `success` boolean; `affected_models` array; `models` array; `error` string; `warnings` array; `result` object
- Default config: {
  "pinDefaults": {
    "operation": "load",
    "task": "text_generation"
  },
  "effectConfig": {
    "operation": "load",
    "task": "text_generation"
  }
}

### core / Subflow

- Node type: `subflow`
- Document node: `{"id":"<unique_id>","type":"subflow"}`
- Utility: Run another saved workflow (subflow) and return its output object.
- Gateway capability: none
- Dynamic pin policy: template pins only
- Authorable config: input defaults with `pin_defaults`; subflow id is UI-owned; do not create an unconfigured subflow as a finished workflow
- Inputs: `exec-in` execution; `inherit_context` boolean: When true, seed the child run's context.messages from the parent's active context messages. If the pin is not connected, the node checkbox is used. Default: false.; `input` object
- Outputs: `exec-out` execution; `output` object
- Default config: none

### core / Tool Calls

- Node type: `tool_calls`
- Document node: `{"id":"<unique_id>","type":"tool_calls","pin_defaults":{"allowed_tools":["<exact_tool_name>"]}}`
- Utility: Execute one or more tool calls via the runtime. Outputs per-call results and a success boolean.
- Gateway capability: tools
- Dynamic pin policy: template pins only
- Authorable config: input defaults with `pin_defaults`; must include `pin_defaults.allowed_tools` when the node is created
- Inputs: `exec-in` execution; `tool_calls` array: List of tool call requests. Each entry shape: {name, arguments, call_id?}. Often comes from LLM Call.tool_calls.; `allowed_tools` array: Optional allowlist of tool names enforced by the runtime effect handler (empty list => allow none). If not connected, the node config (if any) is used.
- Outputs: `exec-out` execution; `results` array: Per-call results in input order. Each entry shape: {call_id, name, success, output, error}. When success=true, output contains the tool output and error is null; when success=false, error contains the failure message and output is null (or best-effort structured output for some tools).; `success` boolean: Aggregate: true only if all per-call results have success=true (see results[].success/results[].error for per-call failures).
- Default config: none

### data / Agent Trace Report

- Node type: `agent_trace_report`
- Document node: `{"id":"<unique_id>","type":"agent_trace_report"}`
- Utility: Render an agent scratchpad (runtime-owned node_traces) into a condensed Markdown report of actions and tool results.
- Gateway capability: none
- Dynamic pin policy: template pins only
- Authorable config: input defaults with `pin_defaults`
- Inputs: `scratchpad` object: Agent scratchpad object (typically contains node_traces).
- Outputs: `result` string
- Default config: none

### data / Array Append

- Node type: `array_append`
- Document node: `{"id":"<unique_id>","type":"array_append"}`
- Utility: Append an item to an array (returns a new array).
- Gateway capability: none
- Dynamic pin policy: template pins only
- Authorable config: input defaults with `pin_defaults`
- Inputs: `array` array; `item` any
- Outputs: `result` array
- Default config: none

### data / Array Concat

- Node type: `array_concat`
- Document node: `{"id":"<unique_id>","type":"array_concat"}`
- Utility: Concatenate arrays (a then b).
- Gateway capability: none
- Dynamic pin policy: template pins only
- Authorable config: input defaults with `pin_defaults`
- Inputs: `a` array; `b` array
- Outputs: `result` array
- Default config: none

### data / Array Dedup

- Node type: `array_dedup`
- Document node: `{"id":"<unique_id>","type":"array_dedup"}`
- Utility: Stable-order dedup for arrays (optionally by key path).
- Gateway capability: none
- Dynamic pin policy: template pins only
- Authorable config: input defaults with `pin_defaults`
- Inputs: `array` array; `key` string
- Outputs: `result` array
- Default config: none

### data / Filter Array

- Node type: `array_filter`
- Document node: `{"id":"<unique_id>","type":"array_filter"}`
- Utility: Filter array items where item[key] == value (or item == value).
- Gateway capability: none
- Dynamic pin policy: template pins only
- Authorable config: input defaults with `pin_defaults`
- Inputs: `items` array; `key` string; `value` any
- Outputs: `result` array
- Default config: none

### data / Array Length

- Node type: `array_length`
- Document node: `{"id":"<unique_id>","type":"array_length"}`
- Utility: Return the length of an array.
- Gateway capability: none
- Dynamic pin policy: template pins only
- Authorable config: input defaults with `pin_defaults`
- Inputs: `array` array
- Outputs: `result` number
- Default config: none

### data / Map Array

- Node type: `array_map`
- Document node: `{"id":"<unique_id>","type":"array_map"}`
- Utility: Map array items by extracting a field (key) from objects.
- Gateway capability: none
- Dynamic pin policy: template pins only
- Authorable config: input defaults with `pin_defaults`
- Inputs: `items` array; `key` string
- Outputs: `result` array
- Default config: none

### data / Break Object

- Node type: `break_object`
- Document node: `{"id":"<unique_id>","type":"break_object"}`
- Utility: Expose selected fields of an object as individual output pins (configured paths).
- Gateway capability: none
- Dynamic pin policy: dynamic outputs via the document `outputs` list (also drives `breakConfig.selectedPaths`)
- Authorable config: input defaults with `pin_defaults`
- Inputs: `object` object: Input object to decompose into selected output fields.
- Outputs: none
- Default config: {
  "breakConfig": {
    "selectedPaths": []
  }
}

### data / Coalesce

- Node type: `coalesce`
- Document node: `{"id":"<unique_id>","type":"coalesce"}`
- Utility: Return the first non-null value (A, then B, ...).
- Gateway capability: none
- Dynamic pin policy: template pins only
- Authorable config: input defaults with `pin_defaults`
- Inputs: `a` any; `b` any
- Outputs: `result` any
- Default config: none

### data / Concat

- Node type: `concat`
- Document node: `{"id":"<unique_id>","type":"concat"}`
- Utility: Concatenate two strings.
- Gateway capability: none
- Dynamic pin policy: dynamic inputs via the document `inputs` list
- Authorable config: input defaults with `pin_defaults`; separator with `concat_separator`
- Inputs: `a` string; `b` string
- Outputs: `result` string
- Default config: {
  "concatConfig": {
    "separator": " "
  }
}

### data / Contains

- Node type: `contains`
- Document node: `{"id":"<unique_id>","type":"contains"}`
- Utility: True if text contains pattern.
- Gateway capability: none
- Dynamic pin policy: template pins only
- Authorable config: input defaults with `pin_defaults`
- Inputs: `text` string; `pattern` string
- Outputs: `result` boolean
- Default config: none

### data / Format Tool Results

- Node type: `format_tool_results`
- Document node: `{"id":"<unique_id>","type":"format_tool_results"}`
- Utility: Convert Tool Calls results [{call_id,name,success,output,error}, ...] into a condensed human-readable digest string.
- Gateway capability: none
- Dynamic pin policy: template pins only
- Authorable config: input defaults with `pin_defaults`
- Inputs: `tool_results` array: Array of tool results (typically from Tool Calls.results).
- Outputs: `result` string
- Default config: none

### data / Format

- Node type: `format`
- Document node: `{"id":"<unique_id>","type":"format"}`
- Utility: Python-style string format: template.format(**values).
- Gateway capability: none
- Dynamic pin policy: template pins only
- Authorable config: input defaults with `pin_defaults`
- Inputs: `template` string; `values` object
- Outputs: `result` string
- Default config: none

### data / Get Element

- Node type: `get_element`
- Document node: `{"id":"<unique_id>","type":"get_element"}`
- Utility: Get a single array element by index (supports negative indices).
- Gateway capability: none
- Dynamic pin policy: template pins only
- Authorable config: input defaults with `pin_defaults`
- Inputs: `array` array: Input array (list/tuple).; `index` number: 0-based index (negative allowed; -1 is last).; `default` any: Fallback value when index is invalid (default null).
- Outputs: `result` any: Element value (or default when not found).; `found` boolean: True when index is valid for the given array.
- Default config: none

### data / Get Random Element

- Node type: `get_random_element`
- Document node: `{"id":"<unique_id>","type":"get_random_element"}`
- Utility: Pick a random element from an array.
- Gateway capability: none
- Dynamic pin policy: template pins only
- Authorable config: input defaults with `pin_defaults`
- Inputs: `array` array: Input array (list/tuple).; `default` any: Fallback value when the array is empty (default null).
- Outputs: `result` any: Random element (or default when not found).; `found` boolean: True when an element was selected.
- Default config: none

### data / Get Property

- Node type: `get`
- Document node: `{"id":"<unique_id>","type":"get"}`
- Utility: Safely read a nested path from an object (dot/bracket path) with an optional default.
- Gateway capability: none
- Dynamic pin policy: template pins only
- Authorable config: input defaults with `pin_defaults`
- Inputs: `object` object; `key` string; `default` any
- Outputs: `value` any
- Default config: none

### data / Has Tools

- Node type: `has_tools`
- Document node: `{"id":"<unique_id>","type":"has_tools"}`
- Utility: True if the input array has at least one element (commonly: LLM tool_calls).
- Gateway capability: none
- Dynamic pin policy: template pins only
- Authorable config: input defaults with `pin_defaults`
- Inputs: `array` array
- Outputs: `result` boolean
- Default config: none

### data / Is Empty

- Node type: `is_empty_string`
- Document node: `{"id":"<unique_id>","type":"is_empty_string"}`
- Utility: True if text is empty.
- Gateway capability: none
- Dynamic pin policy: template pins only
- Authorable config: input defaults with `pin_defaults`
- Inputs: `text` string
- Outputs: `result` boolean
- Default config: none

### data / Join

- Node type: `join`
- Document node: `{"id":"<unique_id>","type":"join"}`
- Utility: Join array items into a string using a delimiter.
- Gateway capability: none
- Dynamic pin policy: template pins only
- Authorable config: input defaults with `pin_defaults`
- Inputs: `items` array; `delimiter` string
- Outputs: `result` string
- Default config: none

### data / Length

- Node type: `length`
- Document node: `{"id":"<unique_id>","type":"length"}`
- Utility: String length (number of characters).
- Gateway capability: none
- Dynamic pin policy: template pins only
- Authorable config: input defaults with `pin_defaults`
- Inputs: `text` string
- Outputs: `result` number
- Default config: none

### data / Lowercase

- Node type: `lowercase`
- Document node: `{"id":"<unique_id>","type":"lowercase"}`
- Utility: Convert text to lowercase.
- Gateway capability: none
- Dynamic pin policy: template pins only
- Authorable config: input defaults with `pin_defaults`
- Inputs: `text` string
- Outputs: `result` string
- Default config: none

### data / Make Array

- Node type: `make_array`
- Document node: `{"id":"<unique_id>","type":"make_array"}`
- Utility: Build an array from 1+ inputs in pin order (Blueprint-style). Skips null/unset inputs.
- Gateway capability: none
- Dynamic pin policy: template pins only
- Authorable config: input defaults with `pin_defaults`
- Inputs: `a` any
- Outputs: `result` array
- Default config: none

### data / Make Context

- Node type: `make_context`
- Document node: `{"id":"<unique_id>","type":"make_context"}`
- Utility: Build a context object {task, messages, ...context_extra}.
- Gateway capability: none
- Dynamic pin policy: template pins only
- Authorable config: input defaults with `pin_defaults`
- Inputs: `task` string: Task / user request string (context.task).; `messages` array: Conversation messages list (context.messages).; `context_extra` object: Optional extra context fields merged into the context (task/messages win). Common: session, attachments.
- Outputs: `context` object: Context object {task, messages, ...context_extra}.
- Default config: none

### data / Make Meta

- Node type: `make_meta`
- Document node: `{"id":"<unique_id>","type":"make_meta"}`
- Utility: Build a host-facing meta envelope (Agent / LLM Call).
- Gateway capability: none
- Dynamic pin policy: template pins only
- Authorable config: input defaults with `pin_defaults`
- Inputs: `schema` string: Schema identifier (default: abstractcode.agent.v1.meta).; `version` number: Schema version number (default: 1).; `output_mode` string: Output mode: unstructured | structured.; `provider` provider_text: Text/LLM provider id/name (e.g. lmstudio).; `model` model: Text/LLM model id/name.; `sub_run_id` string: Optional sub-run id (Agent nodes).; `iterations` number: Optional iteration count (Agent nodes).; `tool_calls` number: Optional tool call count.; `tool_results` number: Optional tool result count.; `finish_reason` string: Optional finish reason (LLM Call nodes).; `gen_time` number: Optional generation time (LLM Call nodes).; `ttft_ms` number: Optional time-to-first-token in ms (LLM Call nodes).; `usage` object: Usage object (e.g. {input_tokens, output_tokens}).; `trace` object: Optional trace object (e.g. {trace_id:"..."}). Treat as opaque.; `warnings` array: Optional list of warning strings.; `debug` object: Optional debug payload (host-facing).; `extra` object: Optional extra fields merged into the meta object (reserved keys win).
- Outputs: `meta` object: Meta object (portable host-friendly envelope).
- Default config: none

### data / Build JSON

- Node type: `make_object`
- Document node: `{"id":"<unique_id>","type":"make_object"}`
- Utility: Build a JSON object from live input pins. Use the JSON literal node for static objects.
- Gateway capability: none
- Dynamic pin policy: dynamic inputs via the document `inputs` list
- Authorable config: input defaults with `pin_defaults`
- Inputs: `value` any: First object field. Rename/add fields in the Properties panel.
- Outputs: `result` object
- Default config: none

### data / Make Scratchpad

- Node type: `make_scratchpad`
- Document node: `{"id":"<unique_id>","type":"make_scratchpad"}`
- Utility: Build a scratchpad/trace envelope (commonly from Agent outputs).
- Gateway capability: none
- Dynamic pin policy: template pins only
- Authorable config: input defaults with `pin_defaults`
- Inputs: `sub_run_id` string: Optional sub-run id associated with the trace.; `workflow_id` string: Optional workflow id associated with the trace.; `task` string: Agent task/prompt string for this run.; `messages` array: Agent-internal transcript messages for this run.; `context_extra` object: Additional context fields passed into the agent (excluding task/messages).; `node_traces` object: Per-node trace mapping (node_id -> trace object).; `steps` array: Flattened trace steps list (optional; used by some UIs).; `tool_calls` array: Tool calls extracted from steps (best-effort).; `tool_results` array: Tool results extracted from steps (best-effort).
- Outputs: `scratchpad` object: Scratchpad object containing trace info.
- Default config: none

### data / Merge Objects

- Node type: `merge`
- Document node: `{"id":"<unique_id>","type":"merge"}`
- Utility: Shallow merge two objects (b overrides a).
- Gateway capability: none
- Dynamic pin policy: template pins only
- Authorable config: input defaults with `pin_defaults`
- Inputs: `a` object; `b` object
- Outputs: `result` object
- Default config: none

### data / Parse JSON

- Node type: `parse_json`
- Document node: `{"id":"<unique_id>","type":"parse_json"}`
- Utility: Parse JSON (or JSON-ish) text into an object/array suitable for downstream nodes.
- Gateway capability: none
- Dynamic pin policy: template pins only
- Authorable config: input defaults with `pin_defaults`
- Inputs: `text` string
- Outputs: `result` object
- Default config: none

### data / Replace

- Node type: `replace`
- Document node: `{"id":"<unique_id>","type":"replace"}`
- Utility: Replace pattern with replacement (mode: first|all).
- Gateway capability: none
- Dynamic pin policy: template pins only
- Authorable config: input defaults with `pin_defaults`
- Inputs: `text` string; `pattern` string; `replacement` string; `mode` string: Replacement mode: 'first' or 'all' (default: all).
- Outputs: `result` string
- Default config: none

### data / Set Property

- Node type: `set`
- Document node: `{"id":"<unique_id>","type":"set"}`
- Utility: Pure transform: return a new object with key set. To persist state, use Set Variable (dotted path) or Set Variable Property.
- Gateway capability: none
- Dynamic pin policy: template pins only
- Authorable config: input defaults with `pin_defaults`
- Inputs: `object` object; `key` string; `value` any
- Outputs: `result` object
- Default config: none

### data / Split

- Node type: `split`
- Document node: `{"id":"<unique_id>","type":"split"}`
- Utility: Split text by a delimiter into an array (with trimming/drop-empty defaults).
- Gateway capability: none
- Dynamic pin policy: template pins only
- Authorable config: input defaults with `pin_defaults`
- Inputs: `text` string; `delimiter` string
- Outputs: `result` array
- Default config: none

### data / String Template

- Node type: `string_template`
- Document node: `{"id":"<unique_id>","type":"string_template"}`
- Utility: Render a template like "Hello {{user.name}}" using a vars object (supports filters).
- Gateway capability: none
- Dynamic pin policy: dynamic inputs via the document `inputs` list
- Authorable config: input defaults with `pin_defaults`; template text with `literal` or `pin_defaults.template`
- Inputs: `template` string; `vars` object
- Outputs: `result` string
- Default config: none

### data / Stringify JSON

- Node type: `stringify_json`
- Document node: `{"id":"<unique_id>","type":"stringify_json"}`
- Utility: Render a JSON value (object/array/scalar) into a string. Mode: none | beautify | minified.
- Gateway capability: none
- Dynamic pin policy: template pins only
- Authorable config: input defaults with `pin_defaults`
- Inputs: `value` any: JSON value (or JSON-ish string) to stringify.; `mode` string: Rendering mode: none | beautify | minified. Default beautify.
- Outputs: `result` string
- Default config: none

### data / Substring

- Node type: `substring`
- Document node: `{"id":"<unique_id>","type":"substring"}`
- Utility: Extract a substring by start/end indices (end is optional).
- Gateway capability: none
- Dynamic pin policy: template pins only
- Authorable config: input defaults with `pin_defaults`
- Inputs: `text` string; `start` number; `end` number
- Outputs: `result` string
- Default config: none

### data / Trim

- Node type: `trim`
- Document node: `{"id":"<unique_id>","type":"trim"}`
- Utility: Trim whitespace from both ends of a string.
- Gateway capability: none
- Dynamic pin policy: template pins only
- Authorable config: input defaults with `pin_defaults`
- Inputs: `text` string
- Outputs: `result` string
- Default config: none

### data / Uppercase

- Node type: `uppercase`
- Document node: `{"id":"<unique_id>","type":"uppercase"}`
- Utility: Convert text to UPPERCASE.
- Gateway capability: none
- Dynamic pin policy: template pins only
- Authorable config: input defaults with `pin_defaults`
- Inputs: `text` string
- Outputs: `result` string
- Default config: none

### events / Emit Event

- Node type: `emit_event`
- Document node: `{"id":"<unique_id>","type":"emit_event"}`
- Utility: Emit a durable event (scope/session) with payload. Useful for cross-node or cross-agent signaling.
- Gateway capability: none
- Dynamic pin policy: template pins only
- Authorable config: input defaults with `pin_defaults`
- Inputs: `exec-in` execution; `name` string; `scope` string; `payload` any; `session_id` string
- Outputs: `exec-out` execution; `delivered` number; `delivered_to` array; `wait_key` string
- Default config: {
  "effectConfig": {
    "name": "my_event",
    "scope": "session",
    "sessionId": ""
  }
}

### events / On Agent Message

- Node type: `on_agent_message`
- Document node: `{"id":"<unique_id>","type":"on_agent_message"}`
- Utility: Entry point triggered by an agent-to-agent message (broadcast or direct).
- Gateway capability: none
- Dynamic pin policy: template pins only
- Authorable config: event settings with `event`
- Inputs: none
- Outputs: `exec-out` execution; `sender` agent; `message` string; `channel` string
- Default config: none

### events / On Event

- Node type: `on_event`
- Document node: `{"id":"<unique_id>","type":"on_event"}`
- Utility: Entry point triggered by a durable custom event. Outputs event metadata + payload.
- Gateway capability: none
- Dynamic pin policy: template pins only
- Authorable config: input defaults with `pin_defaults`; event settings with `event`
- Inputs: `scope` string
- Outputs: `exec-out` execution; `event` object; `payload` any
- Default config: {
  "eventConfig": {
    "name": "my_event",
    "scope": "session"
  }
}

### events / On Flow End

- Node type: `on_flow_end`
- Document node: `{"id":"<unique_id>","type":"on_flow_end"}`
- Utility: Terminal node. End execution and expose the flow result via upstream data wiring.
- Gateway capability: none
- Dynamic pin policy: dynamic inputs via the document `inputs` list
- Authorable config: input defaults with `pin_defaults`
- Inputs: `exec-in` execution
- Outputs: none
- Default config: none

### events / On Flow Start

- Node type: `on_flow_start`
- Document node: `{"id":"<unique_id>","type":"on_flow_start"}`
- Utility: Entry point for a workflow run. Emits exec-out and any configured inputs as outputs.
- Gateway capability: none
- Dynamic pin policy: dynamic outputs via the document `outputs` list
- Authorable config: no node-specific document config beyond label/pin_defaults
- Inputs: none
- Outputs: `exec-out` execution
- Default config: none

### events / On Schedule

- Node type: `on_schedule`
- Document node: `{"id":"<unique_id>","type":"on_schedule"}`
- Utility: Entry point triggered by a schedule (timestamp or recurring). Outputs the trigger time.
- Gateway capability: none
- Dynamic pin policy: template pins only
- Authorable config: input defaults with `pin_defaults`; event settings with `event`
- Inputs: `schedule` string (timestamp); `recurrent` boolean
- Outputs: `exec-out` execution; `timestamp` string (time)
- Default config: {
  "eventConfig": {
    "schedule": "15s",
    "recurrent": true
  }
}

### events / On User Request

- Node type: `on_user_request`
- Document node: `{"id":"<unique_id>","type":"on_user_request"}`
- Utility: Entry point for a run started from a user prompt. Outputs the user message and initial context.
- Gateway capability: none
- Dynamic pin policy: template pins only
- Authorable config: no node-specific document config beyond label/pin_defaults
- Inputs: none
- Outputs: `exec-out` execution; `message` string; `context` object
- Default config: none

### events / System Date/Time

- Node type: `system_datetime`
- Document node: `{"id":"<unique_id>","type":"system_datetime"}`
- Utility: Return current time metadata (ISO string, timezone, UTC offset, locale).
- Gateway capability: none
- Dynamic pin policy: template pins only
- Authorable config: no node-specific document config beyond label/pin_defaults
- Inputs: none
- Outputs: `iso` string; `timezone` string; `utc_offset_minutes` number; `locale` string
- Default config: none

### events / Wait Event

- Node type: `wait_event`
- Document node: `{"id":"<unique_id>","type":"wait_event"}`
- Utility: Pause the workflow until an event matching event_key is received, then resume with event_data. Optional pins (prompt/choices/allow_free_text) enable durable “ask + wait” UX for hosts like AbstractCode.
- Gateway capability: none
- Dynamic pin policy: template pins only
- Authorable config: input defaults with `pin_defaults`
- Inputs: `exec-in` execution; `event_key` string; `prompt` string; `choices` array; `allow_free_text` boolean
- Outputs: `exec-out` execution; `event_data` object
- Default config: none

### events / Delay

- Node type: `wait_until`
- Document node: `{"id":"<unique_id>","type":"wait_until"}`
- Utility: Pause execution for a duration (seconds), then continue.
- Gateway capability: none
- Dynamic pin policy: template pins only
- Authorable config: input defaults with `pin_defaults`
- Inputs: `exec-in` execution; `duration` number
- Outputs: `exec-out` execution
- Default config: none

### literals / JSON Schema

- Node type: `json_schema`
- Document node: `{"id":"<unique_id>","type":"json_schema"}`
- Utility: Define a JSON Schema object for schema-constrained responses. Connect to `resp_schema` on LLM Call / Agent nodes.
- Gateway capability: none
- Dynamic pin policy: template pins only
- Authorable config: literal value with `literal`
- Inputs: none
- Outputs: `value` json_schema (schema)
- Default config: {
  "literalValue": {
    "type": "object",
    "properties": {
      "data": {
        "type": "string"
      }
    },
    "required": [
      "data"
    ]
  }
}

### literals / Array

- Node type: `literal_array`
- Document node: `{"id":"<unique_id>","type":"literal_array","template":"Array"}`
- Utility: Array literal value.
- Gateway capability: none
- Dynamic pin policy: template pins only
- Authorable config: select with `"template": "Array"`; literal value with `literal`
- Inputs: none
- Outputs: `value` array
- Default config: none

### literals / Assertions

- Node type: `literal_array`
- Document node: `{"id":"<unique_id>","type":"literal_array","template":"Assertions"}`
- Utility: KG assertion list literal value (assertion[]).
- Gateway capability: none
- Dynamic pin policy: template pins only
- Authorable config: select with `"template": "Assertions"`; literal value with `literal`
- Inputs: none
- Outputs: `value` assertions (assertions)
- Default config: none

### literals / Boolean

- Node type: `literal_boolean`
- Document node: `{"id":"<unique_id>","type":"literal_boolean"}`
- Utility: Boolean literal value.
- Gateway capability: none
- Dynamic pin policy: template pins only
- Authorable config: literal value with `literal`
- Inputs: none
- Outputs: `value` boolean
- Default config: {
  "literalValue": false
}

### literals / Assertion

- Node type: `literal_json`
- Document node: `{"id":"<unique_id>","type":"literal_json","template":"Assertion"}`
- Utility: KG assertion literal value (subject/predicate/object + optional metadata).
- Gateway capability: none
- Dynamic pin policy: template pins only
- Authorable config: select with `"template": "Assertion"`; literal value with `literal`
- Inputs: none
- Outputs: `value` assertion (assertion)
- Default config: none

### literals / JSON

- Node type: `literal_json`
- Document node: `{"id":"<unique_id>","type":"literal_json","template":"JSON"}`
- Utility: Object (JSON) literal value.
- Gateway capability: none
- Dynamic pin policy: template pins only
- Authorable config: select with `"template": "JSON"`; literal value with `literal`
- Inputs: none
- Outputs: `value` object
- Default config: none

### literals / Memory

- Node type: `literal_json`
- Document node: `{"id":"<unique_id>","type":"literal_json","template":"Memory"}`
- Utility: Memory configuration object for Agent/LLM Call recall and KG settings.
- Gateway capability: none
- Dynamic pin policy: template pins only
- Authorable config: select with `"template": "Memory"`; literal value with `literal`
- Inputs: none
- Outputs: `value` memory (memory)
- Default config: {
  "literalValue": {
    "use_session_attachments": true,
    "use_span_memory": false,
    "use_semantic_search": false,
    "use_kg_memory": true,
    "memory_query": "",
    "memory_scope": "session",
    "recall_level": "standard",
    "max_span_messages": 24,
    "kg_max_input_tokens": 1200,
    "kg_limit": 80,
    "kg_min_score": 0.35,
    "kg_write_scope": "session",
    "kg_domain_focus": "",
    "kg_max_out_tokens": 0
  }
}

### literals / Number

- Node type: `literal_number`
- Document node: `{"id":"<unique_id>","type":"literal_number"}`
- Utility: Number literal value.
- Gateway capability: none
- Dynamic pin policy: template pins only
- Authorable config: literal value with `literal`
- Inputs: none
- Outputs: `value` number
- Default config: {
  "literalValue": 0
}

### literals / String

- Node type: `literal_string`
- Document node: `{"id":"<unique_id>","type":"literal_string"}`
- Utility: String literal value.
- Gateway capability: none
- Dynamic pin policy: template pins only
- Authorable config: literal value with `literal`
- Inputs: none
- Outputs: `value` string
- Default config: {
  "literalValue": ""
}

### literals / Provider Catalog

- Node type: `provider_catalog`
- Document node: `{"id":"<unique_id>","type":"provider_catalog"}`
- Utility: List available LLM providers (optionally filtered by an allowlist).
- Gateway capability: none
- Dynamic pin policy: template pins only
- Authorable config: input defaults with `pin_defaults`
- Inputs: `allowed_providers` array
- Outputs: `providers` array
- Default config: none

### literals / Models Catalog

- Node type: `provider_models`
- Document node: `{"id":"<unique_id>","type":"provider_models"}`
- Utility: List models for a provider. Optionally restrict the list by capability route and selected allowed models.
- Gateway capability: none
- Dynamic pin policy: template pins only
- Authorable config: input defaults with `pin_defaults`; provider models config is UI-owned; use provider/capability pins when possible
- Inputs: `provider` provider_text: Provider id to list models for. If this pin is not connected, the node’s selected provider is used.; `capability_route` string: Optional comma-separated route filter such as output.text or input.image,output.text.
- Outputs: `provider` provider_text: Resolved provider id used to compute the models list.; `models` array: Array of model ids/names for the provider (filtered to the selected allowed models when set).
- Default config: {
  "providerModelsConfig": {
    "provider": "",
    "capabilityRoute": "output.text",
    "allowedModels": []
  }
}

### literals / Tool Parameters

- Node type: `tool_parameters`
- Document node: `{"id":"<unique_id>","type":"tool_parameters"}`
- Utility: Pick a tool and set its arguments (typed + defaults). Outputs a tool call object for Tool Calls.
- Gateway capability: none
- Dynamic pin policy: template pins only
- Authorable config: tool and argument pins with `tool` + `tool_parameters`
- Inputs: none
- Outputs: `tool_call` object: Single tool call request object: {name, arguments, call_id?}.
- Default config: {
  "toolParametersConfig": {
    "tool": ""
  }
}

### literals / Tools Allowlist

- Node type: `tools_allowlist`
- Document node: `{"id":"<unique_id>","type":"tools_allowlist"}`
- Utility: Select an allowlist of tool names once and reuse it across LLM/Agent/Tool Calls nodes.
- Gateway capability: none
- Dynamic pin policy: template pins only
- Authorable config: tool names array with `literal`
- Inputs: none
- Outputs: `tools` tools
- Default config: none

### math / Absolute

- Node type: `abs`
- Document node: `{"id":"<unique_id>","type":"abs"}`
- Utility: Absolute value of a number.
- Gateway capability: none
- Dynamic pin policy: template pins only
- Authorable config: input defaults with `pin_defaults`
- Inputs: `value` number
- Outputs: `result` number
- Default config: none

### math / Add

- Node type: `add`
- Document node: `{"id":"<unique_id>","type":"add"}`
- Utility: Add two numbers.
- Gateway capability: none
- Dynamic pin policy: template pins only
- Authorable config: input defaults with `pin_defaults`
- Inputs: `a` number; `b` number
- Outputs: `result` number
- Default config: none

### math / Divide

- Node type: `divide`
- Document node: `{"id":"<unique_id>","type":"divide"}`
- Utility: Compute a / b (error on division by zero).
- Gateway capability: none
- Dynamic pin policy: template pins only
- Authorable config: input defaults with `pin_defaults`
- Inputs: `a` number; `b` number
- Outputs: `result` number
- Default config: none

### math / Modulo

- Node type: `modulo`
- Document node: `{"id":"<unique_id>","type":"modulo"}`
- Utility: Compute a % b (error on modulo by zero).
- Gateway capability: none
- Dynamic pin policy: template pins only
- Authorable config: input defaults with `pin_defaults`
- Inputs: `a` number; `b` number
- Outputs: `result` number
- Default config: none

### math / Multiply

- Node type: `multiply`
- Document node: `{"id":"<unique_id>","type":"multiply"}`
- Utility: Multiply two numbers.
- Gateway capability: none
- Dynamic pin policy: template pins only
- Authorable config: input defaults with `pin_defaults`
- Inputs: `a` number; `b` number
- Outputs: `result` number
- Default config: none

### math / Power

- Node type: `power`
- Document node: `{"id":"<unique_id>","type":"power"}`
- Utility: Compute base ** exp.
- Gateway capability: none
- Dynamic pin policy: template pins only
- Authorable config: input defaults with `pin_defaults`
- Inputs: `base` number; `exp` number
- Outputs: `result` number
- Default config: none

### math / Random Float

- Node type: `random_float`
- Document node: `{"id":"<unique_id>","type":"random_float"}`
- Utility: Generate a random float in [min, max].
- Gateway capability: none
- Dynamic pin policy: template pins only
- Authorable config: input defaults with `pin_defaults`
- Inputs: `min` number: Minimum (inclusive).; `max` number: Maximum (inclusive).
- Outputs: `result` number
- Default config: none

### math / Random Int

- Node type: `random_int`
- Document node: `{"id":"<unique_id>","type":"random_int"}`
- Utility: Generate a random integer in [min, max] (inclusive).
- Gateway capability: none
- Dynamic pin policy: template pins only
- Authorable config: input defaults with `pin_defaults`
- Inputs: `min` number: Minimum integer (inclusive).; `max` number: Maximum integer (inclusive).
- Outputs: `result` number
- Default config: none

### math / Round

- Node type: `round`
- Document node: `{"id":"<unique_id>","type":"round"}`
- Utility: Round a number to N decimals.
- Gateway capability: none
- Dynamic pin policy: template pins only
- Authorable config: input defaults with `pin_defaults`
- Inputs: `value` number; `decimals` number
- Outputs: `result` number
- Default config: none

### math / Subtract

- Node type: `subtract`
- Document node: `{"id":"<unique_id>","type":"subtract"}`
- Utility: Compute a - b.
- Gateway capability: none
- Dynamic pin policy: template pins only
- Authorable config: input defaults with `pin_defaults`
- Inputs: `a` number; `b` number
- Outputs: `result` number
- Default config: none

### media / Edit Image

- Node type: `edit_image`
- Document node: `{"id":"<unique_id>","type":"edit_image"}`
- Utility: Edit or transform an input image through Gateway image editing and return an image artifact.
- Gateway capability: edited_image
- Dynamic pin policy: template pins only
- Authorable config: input defaults with `pin_defaults`
- Inputs: `exec-in` execution; `prompt` string: Instruction for the image edit.; `image_artifact` artifact_image: Source image artifact ref. Wire from Generate Image, or use an uploaded/selected artifact.; `mask_artifact` artifact_image: Optional mask artifact ref.; `image_provider` provider_image (provider): Optional image edit provider/backend.; `image_model` model (model): Optional image edit model id for the selected provider.; `format` string: png, jpg, or webp.; `seed` number; `steps` number; `guidance_scale` number (guidance); `guidance_2` number: Optional second-stage guidance for models that expose it.; `count` number: Optional number of edited images to generate in one call.; `seeds` array: Optional explicit batch seeds. When provided, their length defines the batch size unless count is also set.; `lora_adapters` array: Optional ordered LoRA adapter stack for compatible image-edit models.; `strength` number: Optional edit strength for image-to-image backends.; `negative_prompt` string (negative); `extra` object: Optional provider-specific image edit options.
- Outputs: `exec-out` execution; `image_artifact` artifact_image: Artifact ref for the edited image.; `image_artifacts` artifacts_image: Ordered artifact refs for batched image editing.; `artifact_ref` artifact; `artifact_id` string; `content_type` string; `outputs` object; `meta` object; `success` boolean
- Default config: {
  "pinDefaults": {
    "format": "png",
    "steps": 20
  }
}

### media / Generate Image

- Node type: `generate_image`
- Document node: `{"id":"<unique_id>","type":"generate_image"}`
- Utility: Generate an image through Gateway vision capability and return an artifact reference.
- Gateway capability: generated_image
- Dynamic pin policy: template pins only
- Authorable config: input defaults with `pin_defaults`
- Inputs: `exec-in` execution; `prompt` string: Image prompt.; `image_provider` provider_image (provider): Optional image provider/backend.; `image_model` model (model): Optional image model id for the selected image provider.; `width` number; `height` number; `format` string: png, jpg, or webp.; `seed` number; `steps` number; `guidance_scale` number (guidance); `guidance_2` number: Optional second-stage guidance for models that expose it.; `count` number: Optional number of images to generate in one call.; `seeds` array: Optional explicit batch seeds. When provided, their length defines the batch size unless count is also set.; `lora_adapters` array: Optional ordered LoRA adapter stack for compatible image models.; `negative_prompt` string (negative)
- Outputs: `exec-out` execution; `image_artifact` artifact_image: Artifact ref for the generated image.; `image_artifacts` artifacts_image: Ordered artifact refs for batched image generation.; `artifact_ref` artifact; `artifact_id` string; `content_type` string; `outputs` object; `meta` object; `success` boolean
- Default config: {
  "pinDefaults": {
    "format": "png",
    "steps": 20
  }
}

### media / Generate Music

- Node type: `generate_music`
- Document node: `{"id":"<unique_id>","type":"generate_music"}`
- Utility: Generate music through Gateway music capability and return an audio artifact.
- Gateway capability: generated_music
- Dynamic pin policy: template pins only
- Authorable config: input defaults with `pin_defaults`
- Inputs: `exec-in` execution; `prompt` string: Music prompt.; `music_provider` provider_music (provider): Optional Gateway music backend/provider.; `music_model` model (model): Optional music model id for the selected music provider.; `lyrics` string: Optional lyrics for vocal music backends.; `duration_s` number: Optional requested duration in seconds.; `format` string: wav, mp3, or flac.; `seed` number; `num_inference_steps` number (steps); `guidance_scale` number (guidance); `instrumental` boolean; `enhance_prompt` boolean (enhance); `structure_prompt` boolean (structure); `auto_lyrics` boolean; `text_planner_mode` string (planner); `vocal_language` string (language); `negative_prompt` string (negative); `sample_rate` number; `bpm` number; `keyscale` string (key); `timesignature` string (time); `composition_plan` object (plan); `positive_styles` array (styles); `negative_styles` array (avoid_styles); `planning` boolean; `extra` object: Optional provider-specific music-generation options.
- Outputs: `exec-out` execution; `music_artifact` artifact_audio: Artifact ref for generated music.; `audio_artifact` artifact_audio: Alias artifact ref for audio-compatible downstream nodes.; `artifact_ref` artifact; `artifact_id` string; `content_type` string; `outputs` object; `meta` object; `success` boolean
- Default config: {
  "pinDefaults": {
    "format": "wav"
  }
}

### media / Generate Video

- Node type: `generate_video`
- Document node: `{"id":"<unique_id>","type":"generate_video"}`
- Utility: Generate a video through Gateway vision capability and return a video artifact.
- Gateway capability: generated_video
- Dynamic pin policy: template pins only
- Authorable config: input defaults with `pin_defaults`
- Inputs: `exec-in` execution; `prompt` string: Video prompt.; `video_provider` provider_video (provider): Optional video provider/backend.; `video_model` model (model): Optional video model id for the selected video provider.; `width` number; `height` number; `frames` number; `fps` number; `format` string: mp4, mov, or gif.; `seed` number; `steps` number; `guidance_scale` number (guidance); `guidance_2` number: Optional second-stage guidance for dual-transformer video models.; `count` number: Optional number of videos to generate in one call.; `seeds` array: Optional explicit batch seeds. When provided, their length defines the batch size unless count is also set.; `flow_shift` number: Optional flow-shift control for compatible video models.; `lora_adapters` array: Optional ordered LoRA adapter stack for compatible video models.; `negative_prompt` string (negative); `extra` object: Optional provider-specific video-generation options.
- Outputs: `exec-out` execution; `video_artifact` artifact_video: Artifact ref for the generated video.; `video_artifacts` artifacts_video: Ordered artifact refs for batched video generation.; `artifact_ref` artifact; `artifact_id` string; `content_type` string; `outputs` object; `meta` object; `success` boolean
- Default config: {
  "pinDefaults": {
    "format": "mp4",
    "width": 512,
    "height": 512,
    "frames": 41,
    "fps": 24,
    "steps": 20,
    "guidance_scale": 5
  }
}

### media / Generate Voice

- Node type: `generate_voice`
- Document node: `{"id":"<unique_id>","type":"generate_voice"}`
- Utility: Generate speech audio through Gateway voice capability and return an audio artifact.
- Gateway capability: generated_voice
- Dynamic pin policy: template pins only
- Authorable config: input defaults with `pin_defaults`
- Inputs: `exec-in` execution; `text` string: Text to speak.; `tts_provider` provider_voice (provider): Optional media/voice provider id.; `tts_model` model (model): Optional TTS model/language/voice model for the selected provider.; `voice` string: Optional base or cloned voice for the selected provider.; `profile` string: Optional voice profile override.; `quality_preset` string (quality): Optional AbstractVoice quality preset: low, standard, or high.; `format` string: wav or mp3.; `speed` number; `instructions` string
- Outputs: `exec-out` execution; `audio_artifact` artifact_audio: Artifact ref for generated audio.; `artifact_ref` artifact; `artifact_id` string; `content_type` string; `outputs` object; `meta` object; `success` boolean
- Default config: {
  "pinDefaults": {
    "format": "wav",
    "quality_preset": "standard",
    "speed": 1
  }
}

### media / Image To Video

- Node type: `image_to_video`
- Document node: `{"id":"<unique_id>","type":"image_to_video"}`
- Utility: Animate an input image through Gateway image-to-video capability and return a video artifact.
- Gateway capability: image_to_video
- Dynamic pin policy: template pins only
- Authorable config: input defaults with `pin_defaults`
- Inputs: `exec-in` execution; `prompt` string: Instruction for the image-to-video generation.; `source_image` artifact_image: Source image artifact ref.; `video_provider` provider_video (provider): Optional image-to-video provider/backend.; `video_model` model (model): Optional image-to-video model id for the selected provider.; `width` number; `height` number; `frames` number; `fps` number; `format` string: mp4, mov, or gif.; `seed` number; `steps` number; `guidance_scale` number (guidance); `guidance_2` number: Optional second-stage guidance for dual-transformer video models.; `count` number: Optional number of videos to generate in one call.; `seeds` array: Optional explicit batch seeds. When provided, their length defines the batch size unless count is also set.; `flow_shift` number: Optional flow-shift control for compatible video models.; `lora_adapters` array: Optional ordered LoRA adapter stack for compatible video models.; `strength` number: Optional conditioning strength for image-to-video backends.; `negative_prompt` string (negative); `extra` object: Optional provider-specific image-to-video options.
- Outputs: `exec-out` execution; `video_artifact` artifact_video: Artifact ref for the generated video.; `video_artifacts` artifacts_video: Ordered artifact refs for batched image-to-video generation.; `artifact_ref` artifact; `artifact_id` string; `content_type` string; `outputs` object; `meta` object; `success` boolean
- Default config: {
  "pinDefaults": {
    "format": "mp4",
    "width": 512,
    "height": 512,
    "frames": 41,
    "fps": 24,
    "steps": 20,
    "guidance_scale": 5
  }
}

### media / Listen Voice

- Node type: `listen_voice`
- Document node: `{"id":"<unique_id>","type":"listen_voice"}`
- Utility: Pause the workflow and ask the host UI to capture a voice/audio response.
- Gateway capability: none
- Dynamic pin policy: template pins only
- Authorable config: input defaults with `pin_defaults`
- Inputs: `exec-in` execution; `prompt` string; `language` string; `stt_provider` provider_voice (provider): Optional STT provider id for host-side voice transcription.; `stt_model` model (model): Optional STT model id for the selected voice provider.; `max_duration_s` number; `wait_key` string
- Outputs: `exec-out` execution; `audio_artifact` artifact_audio; `artifact_ref` artifact; `artifact_id` string; `text` string
- Default config: {
  "pinDefaults": {
    "max_duration_s": 30
  }
}

### media / Transcribe Audio

- Node type: `transcribe_audio`
- Document node: `{"id":"<unique_id>","type":"transcribe_audio"}`
- Utility: Transcribe an audio artifact through Gateway audio capability.
- Gateway capability: none
- Dynamic pin policy: template pins only
- Authorable config: input defaults with `pin_defaults`
- Inputs: `exec-in` execution; `audio_artifact` artifact_audio: Audio artifact ref.; `stt_provider` provider_voice (provider): Optional audio/STT provider id.; `language` string; `stt_model` model (model): Optional STT model id for the selected voice provider.; `prompt` string; `format` string; `temperature` number
- Outputs: `exec-out` execution; `text` string; `transcript_artifact` artifact_text; `artifact_ref` artifact; `artifact_id` string; `meta` object; `success` boolean
- Default config: {
  "pinDefaults": {
    "format": "json",
    "temperature": 0
  }
}

### media / Restore / Upscale Image

- Node type: `upscale_image`
- Document node: `{"id":"<unique_id>","type":"upscale_image"}`
- Utility: Restore or upscale an input image through Gateway image upscaling and return an image artifact.
- Gateway capability: upscaled_image
- Dynamic pin policy: template pins only
- Authorable config: input defaults with `pin_defaults`
- Inputs: `exec-in` execution; `image_artifact` artifact_image: Source image artifact ref. Wire from an image node, or use an uploaded/selected artifact.; `image_provider` provider_image (provider): Optional image upscaler provider/backend.; `image_model` model (model): Optional image upscaler model id for the selected provider.; `scale` string: Upscale factor such as 2x.; `resolution` string: Target shortest edge in pixels or scale factor such as 2x.; `softness` number: Optional restoration softness in [0.0, 1.0].; `seed` number; `quantize` number: Optional backend quantization hint.; `vae_tiling` boolean: Force tiled VAE encode/decode when true, explicitly disable it when false, or leave unset for the MLX-Gen SeedVR2 runtime policy.; `format` string: png, jpg, or webp.; `extra` object: Optional provider-specific image upscaler options.
- Outputs: `exec-out` execution; `image_artifact` artifact_image: Artifact ref for the upscaled image.; `artifact_ref` artifact; `artifact_id` string; `content_type` string; `outputs` object; `meta` object; `success` boolean
- Default config: {
  "pinDefaults": {
    "format": "png",
    "resolution": "2x",
    "softness": 0.25
  }
}

### memory / Export Artifact

- Node type: `export_artifact`
- Document node: `{"id":"<unique_id>","type":"export_artifact"}`
- Utility: Write an Artifact payload to a workspace-scoped server file path.
- Gateway capability: none
- Dynamic pin policy: template pins only
- Authorable config: input defaults with `pin_defaults`
- Inputs: `exec-in` execution; `artifact` artifact; `file_path` workspace_file
- Outputs: `exec-out` execution; `artifact_id` string; `file_path` workspace_file; `bytes` number; `sha256` string; `content_type` string
- Default config: none

### memory / Import Server File

- Node type: `import_workspace_file`
- Document node: `{"id":"<unique_id>","type":"import_workspace_file"}`
- Utility: Snapshot a workspace-scoped server file into a runtime-owned Artifact for reuse across downstream steps and future runs.
- Gateway capability: none
- Dynamic pin policy: template pins only
- Authorable config: input defaults with `pin_defaults`
- Inputs: `exec-in` execution; `file_path` workspace_file; `content_type` string: Optional MIME override when the filename extension is misleading.
- Outputs: `exec-out` execution; `artifact` artifact; `artifact_ref` artifact; `artifact_id` string; `content_type` string; `size_bytes` number; `source_path` workspace_file
- Default config: none

### memory / List Folder Files

- Node type: `list_folder_files`
- Document node: `{"id":"<unique_id>","type":"list_folder_files"}`
- Utility: List files inside a workspace-scoped server folder, with optional family and extension filters.
- Gateway capability: none
- Dynamic pin policy: template pins only
- Authorable config: input defaults with `pin_defaults`
- Inputs: `exec-in` execution; `folder_path` workspace_folder; `recursive` boolean: When true, recurse into subfolders.; `family` string: Optional family filter: any | image | video | audio | document | text | code | json | archive | other.; `extensions` array: Optional list of file extensions without dots.; `include_directories` boolean: When true, include folder entries in the structured results.; `limit` number: Maximum number of returned entries. Default: 500.; `max_depth` number: Optional recursive depth limit. Use 0 for unlimited depth.
- Outputs: `exec-out` execution; `folder_path` workspace_folder; `files` array; `entries` array; `count` number; `truncated` boolean
- Default config: none

### memory / MemAct Compose

- Node type: `memact_compose`
- Document node: `{"id":"<unique_id>","type":"memact_compose"}`
- Utility: Map KG query results (packets/items) into MemAct CURRENT CONTEXT and render a MemAct system prompt for inspection.
- Gateway capability: none
- Dynamic pin policy: template pins only
- Authorable config: input defaults with `pin_defaults`
- Inputs: `exec-in` execution; `kg_result` object: Connect memory_kg_query.raw (or the full node output).; `stimulus` string: Optional stimulus label for trace (defaults to query_text/task).; `marker` string: Prefix marker used to replace previous KG-composed context entries. Default: KG:; `max_items` number: Optional cap on inserted packets (after packetization/packing).
- Outputs: `exec-out` execution; `ok` boolean: True when composition succeeded.; `delta` object: MemAct delta applied to Active Memory (current_context added/removed).; `trace` object: JSON-safe composition trace (selected packets, budgets, warnings).; `active_memory` object: Raw MemAct Active Memory object (run.vars._runtime.active_memory).; `memact_blocks` array: Rendered MemAct block list (for UI/debug).; `memact_system_prompt` string: Rendered MemAct system prompt (memory blueprints + blocks).
- Default config: none

### memory / Compact memory

- Node type: `memory_compact`
- Document node: `{"id":"<unique_id>","type":"memory_compact"}`
- Utility: Runtime-owned compaction: archives older messages into an artifact span and inserts a summary message with an LLM-visible span_id handle.
- Gateway capability: none
- Dynamic pin policy: template pins only
- Authorable config: input defaults with `pin_defaults`
- Inputs: `exec-in` execution; `preserve_recent` number: Number of most recent non-system messages to keep verbatim (default 6).; `compression_mode` string: light | standard | heavy (default standard).; `focus` string: Optional topic/focus hint for the compaction summary.
- Outputs: `exec-out` execution; `span_id` string: The archived conversation span_id (artifact id). Use it for tagging or recall.
- Default config: none

### memory / KG Assert

- Node type: `memory_kg_assert`
- Document node: `{"id":"<unique_id>","type":"memory_kg_assert"}`
- Utility: Append triple assertions into AbstractMemory (provenance-first, no destructive updates).
- Gateway capability: kg_memory
- Dynamic pin policy: template pins only
- Authorable config: input defaults with `pin_defaults`
- Inputs: `exec-in` execution; `assertions` assertions: List of {subject,predicate,object,...} assertion objects.; `scope` string: run | session | global. Determines the owner_id when not explicitly provided.; `span_id` string: Optional provenance pointer to a runtime span/artifact id.; `owner_id` string: Optional explicit owner id override (advanced; normally derived from scope).; `attributes_defaults` object: Optional attributes merged into each assertion.attributes (defaults only; assertion keys win).; `allow_custom_predicates` boolean: If true, allow custom predicates under the ex:* namespace (advanced; default false).
- Outputs: `exec-out` execution; `assertion_ids` array: IDs assigned by the store (implementation-specific).; `count` number: Number of asserted triples.; `ok` boolean: True when assertion succeeded.
- Default config: none

### memory / KG Query

- Node type: `memory_kg_query`
- Document node: `{"id":"<unique_id>","type":"memory_kg_query"}`
- Utility: Query the AbstractMemory triple store (pattern filters + optional semantic query_text).
- Gateway capability: kg_memory
- Dynamic pin policy: template pins only
- Authorable config: input defaults with `pin_defaults`
- Inputs: `exec-in` execution; `query_text` string: Optional semantic query. Requires embeddings to be configured in the host.; `subject` string: Optional subject filter (case-insensitive exact match).; `predicate` string: Optional predicate filter (case-insensitive exact match).; `object` string: Optional object filter (case-insensitive exact match).; `since` string: Optional observed_at lower bound (ISO8601).; `until` string: Optional observed_at upper bound (ISO8601).; `active_at` string: Optional validity window selector (ISO8601). Filters assertions active at that time.; `scope` string: run | session | global | all (fan-out over run+session+global).; `recall_level` string: Recall effort policy: urgent | standard | deep (optional; when set, applies bounded budgets and no-silent-downgrade semantics).; `owner_id` string: Optional explicit owner id override (advanced; normally derived from scope).; `min_score` number: Optional cosine similarity threshold (semantic query_text only). Range ~[-1..1]; start with 0.2–0.4.; `max_input_tokens` number: Optional token budget for Active Memory packing (KG → prompt). If set, returns active_memory_text + packets.; `model` model: Optional text model id used for token estimation (improves budgeting accuracy).; `limit` number: Max assertions to return (default 100).
- Outputs: `exec-out` execution; `items` assertions: List of triple assertions (dicts).; `count` number: Number of returned assertions.; `ok` boolean: True when query succeeded.; `packets` array: Packed Memory Packets (v0) for Active Memory injection (when max_input_tokens is set).; `active_memory_text` string: Token-budgeted Active Memory block (when max_input_tokens is set).; `packed_count` number: Number of packets included in active_memory_text.; `dropped` number: Packets dropped due to the Active Memory token budget.; `estimated_tokens` number: Estimated token count of active_memory_text.; `raw` object: Raw result object (debug).
- Default config: none

### memory / KG Resolve Entity

- Node type: `memory_kg_resolve`
- Document node: `{"id":"<unique_id>","type":"memory_kg_resolve"}`
- Utility: Resolve candidate ex:* entity ids by label (+ optional rdf:type filter), using bounded exact-match rules and optional semantic fallback.
- Gateway capability: kg_memory
- Dynamic pin policy: template pins only
- Authorable config: input defaults with `pin_defaults`
- Inputs: `exec-in` execution; `label` string: Entity label text to resolve (case-insensitive; whitespace collapsed).; `expected_type` string: Optional rdf:type filter (e.g. schema:person, skos:concept).; `scope` string: run | session | global | all (fan-out over run+session+global).; `recall_level` string: Recall effort policy: urgent | standard | deep (optional; no silent downgrade).; `max_candidates` number: Optional cap on returned candidates (default depends on recall_level; max 50).; `min_score` number: Optional cosine similarity threshold for semantic fallback (when enabled).; `include_semantic` boolean: Optional override to disable/enable semantic fallback (defaults depend on recall_level).; `owner_id` string: Optional explicit owner id override (advanced; normally derived from scope).
- Outputs: `exec-out` execution; `candidates` array: Resolved candidates (bounded list): {id,label,types,scope,owner_id,score,evidence}.; `count` number: Number of returned candidates.; `ok` boolean: True when the resolver executed successfully.; `raw` object: Raw result object (debug).
- Default config: none

### memory / Memorize

- Node type: `memory_note`
- Document node: `{"id":"<unique_id>","type":"memory_note"}`
- Utility: Store a durable memory note with optional tags/sources and a scope (run/session/global).
- Gateway capability: none
- Dynamic pin policy: template pins only
- Authorable config: input defaults with `pin_defaults`
- Inputs: `exec-in` execution; `keep_in_context` boolean (in_context): When true, also insert the stored note into this run's context.messages (synthetic system message). If the pin is not connected, the node checkbox is used. Default: false.; `scope` string: Where to store/index the note: run (this run), session (all runs with the same session_id; owned by an internal session memory run), or global (shared global memory run). If session_id is missing, session falls back to the run-tree root.; `content` string: The note text to store durably (keep it short; prefer references in sources for large payloads).; `location` string: Optional location label (where the note was produced, e.g. "flow:my_flow/node-12"). Useful for filtering.; `tags` object: Key/value tags for filtering (e.g. {topic:"memory", person:"laurent"}). Values must be strings.; `sources` object: Optional provenance refs (e.g. {run_id, span_ids, message_ids}). The note stores refs, not the full source content.
- Outputs: `exec-out` execution; `note_id` string: The stored note’s span_id / artifact_id. Use it for Recall into context (span_ids) or for precise Recall.
- Default config: none

### memory / Recall

- Node type: `memory_query`
- Document node: `{"id":"<unique_id>","type":"memory_query"}`
- Utility: Query memory by text/tags and return structured results plus a rendered summary.
- Gateway capability: none
- Dynamic pin policy: template pins only
- Authorable config: input defaults with `pin_defaults`
- Inputs: `exec-in` execution; `query` string: Keyword query (substring match over span metadata and small previews). Combined with tags/authors/locations using AND semantics.; `recall_level` string: Recall effort policy: urgent | standard | deep (optional; when set, applies bounded budgets and no-silent-downgrade semantics).; `limit` number: Maximum number of spans to return (limit_spans). Default: 5.; `tags` object: Tag filters as key→string or key→list[string]. Reserved key "kind" is ignored.; `tags_mode` string: How to combine tag keys: all (AND) or any (OR). Within a single key, list values are OR.; `usernames` array: Filter by created_by (actor id). Case-insensitive exact match. Empty means no filter.; `locations` array: Filter by location metadata (or tags.location). Case-insensitive exact match.; `since` string: ISO8601 start time. Matches spans whose [from,to] intersects this range.; `until` string: ISO8601 end time. Matches spans whose [from,to] intersects this range.; `scope` string: Which span index to query: run | session | global | all. (all queries run+session+global. session uses session_id authority; if session_id is missing, it falls back to the run-tree root.)
- Outputs: `exec-out` execution; `results` array: Structured match list (meta.matches). Use it to extract span_ids for Recall into context.; `rendered` string: Human-readable recall summary (tool-style output string).
- Default config: none

### memory / Recall into context

- Node type: `memory_rehydrate`
- Document node: `{"id":"<unique_id>","type":"memory_rehydrate"}`
- Utility: Insert recalled message spans into the active context so future LLM/Agent calls can “see” them.
- Gateway capability: none
- Dynamic pin policy: template pins only
- Authorable config: input defaults with `pin_defaults`
- Inputs: `exec-in` execution; `span_ids` array: List of span_ids (artifact_ids) to insert into context.messages. Typically comes from Recall results.; `placement` string: Where to insert: after_summary | after_system | end.; `recall_level` string: Recall effort policy: urgent | standard | deep (optional; when set, applies bounded budgets and no-silent-downgrade semantics).; `max_messages` number: Optional cap on inserted messages across all spans (None/empty = unlimited). Useful to avoid huge contexts.
- Outputs: `exec-out` execution; `inserted` number: Number of messages inserted into context.messages.; `skipped` number: Number of messages skipped (usually due to dedup).
- Default config: none

### memory / Tag memory

- Node type: `memory_tag`
- Document node: `{"id":"<unique_id>","type":"memory_tag"}`
- Utility: Apply/merge tags onto an existing memory span record (conversation span or memory note).
- Gateway capability: none
- Dynamic pin policy: template pins only
- Authorable config: input defaults with `pin_defaults`
- Inputs: `exec-in` execution; `span_id` string: Target span_id (artifact id). Also accepts a 1-based span index as a string/number in some hosts.; `scope` string: Which span index to tag: run | session | global | all. (all tags every matching record across run+session+global; indices are not allowed with all.); `tags` object: Key/value tags to set (values must be strings). Reserved key "kind" is ignored.; `merge` boolean: When true, merges with existing tags. When false, replaces the tag dict. Default: true.
- Outputs: `exec-out` execution; `success` boolean: Whether the tag operation succeeded.; `rendered` string: Human-readable result string.
- Default config: none

### memory / Read Artifact

- Node type: `read_artifact`
- Document node: `{"id":"<unique_id>","type":"read_artifact"}`
- Utility: Read any Artifact payload and expose bounded text, JSON, or base64 projections plus content metadata.
- Gateway capability: none
- Dynamic pin policy: template pins only
- Authorable config: input defaults with `pin_defaults`
- Inputs: `exec-in` execution; `artifact` artifact
- Outputs: `exec-out` execution; `artifact` artifact; `artifact_ref` artifact; `artifact_id` string; `content_type` string; `content_family` string; `size_bytes` number; `filename` string; `source_path` string; `content` any; `text` string; `json` object; `binary_base64` string; `is_binary` boolean; `warnings` array; `truncated` boolean
- Default config: none

### memory / Read File

- Node type: `read_file`
- Document node: `{"id":"<unique_id>","type":"read_file"}`
- Utility: Read a workspace-scoped server file path and output UTF-8 text or JSON content. In Gateway-hosted runs, access stays within the allowed workspace policy.
- Gateway capability: none
- Dynamic pin policy: template pins only
- Authorable config: input defaults with `pin_defaults`
- Inputs: `exec-in` execution; `file_path` workspace_file
- Outputs: `exec-out` execution; `content` any; `file_path` workspace_file
- Default config: none

### memory / Read PDF

- Node type: `read_pdf`
- Document node: `{"id":"<unique_id>","type":"read_pdf"}`
- Utility: Extract text and metadata from a workspace-scoped server PDF path using the Runtime permissive PDF reader.
- Gateway capability: none
- Dynamic pin policy: template pins only
- Authorable config: input defaults with `pin_defaults`
- Inputs: `exec-in` execution; `file_path` workspace_file; `page_start` number: Optional 1-based first page to read.; `page_end` number: Optional 1-based last page to read.; `max_chars` number: Optional explicit text limit. If used, output warnings include #TRUNCATION.
- Outputs: `exec-out` execution; `content` string; `pages` number; `processed_pages` number; `metadata` object; `warnings` array; `truncated` boolean; `file_path` workspace_file; `content_type` string
- Default config: none

### memory / Write File

- Node type: `write_file`
- Document node: `{"id":"<unique_id>","type":"write_file"}`
- Utility: Write content to a workspace-scoped server file path (creates parent folders if needed). In local Runtime-only runs without workspace scope, relative paths fall back to the process working directory.
- Gateway capability: none
- Dynamic pin policy: template pins only
- Authorable config: input defaults with `pin_defaults`
- Inputs: `exec-in` execution; `file_path` workspace_file; `content` any
- Outputs: `exec-out` execution; `bytes` number; `file_path` workspace_file
- Default config: none

### memory / Write PDF

- Node type: `write_pdf`
- Document node: `{"id":"<unique_id>","type":"write_pdf"}`
- Utility: Render text or Markdown-style report content to a real workspace-scoped server PDF path using the Runtime permissive PDF writer.
- Gateway capability: none
- Dynamic pin policy: template pins only
- Authorable config: input defaults with `pin_defaults`
- Inputs: `exec-in` execution; `file_path` workspace_file; `content` any; `title` string: Optional PDF document title.
- Outputs: `exec-out` execution; `bytes` number; `file_path` workspace_file; `sha256` string; `content_type` string
- Default config: none

### schema / Add Schema Fields

- Node type: `edit_json_schema`
- Document node: `{"id":"<unique_id>","type":"edit_json_schema"}`
- Utility: Add fields to an incoming JSON Schema object. Existing schema fields are preserved; if the input is unavailable, outputs only the added fields.
- Gateway capability: none
- Dynamic pin policy: template pins only
- Authorable config: input defaults with `pin_defaults`; literal value with `literal`
- Inputs: `schema` json_schema: Base JSON Schema object. Leave unconnected to output only the added fields.
- Outputs: `schema` json_schema: JSON Schema with added fields.
- Default config: none

### variables / Bool Variable

- Node type: `bool_var`
- Document node: `{"id":"<unique_id>","type":"bool_var"}`
- Utility: Declare a workflow-scope boolean variable (name + default).
- Gateway capability: none
- Dynamic pin policy: template pins only
- Authorable config: no node-specific document config beyond label/pin_defaults
- Inputs: none
- Outputs: `name` string; `value` boolean
- Default config: none

### variables / Get Context

- Node type: `get_context`
- Document node: `{"id":"<unique_id>","type":"get_context"}`
- Utility: Read the current run's context namespace (run.vars.context).
- Gateway capability: none
- Dynamic pin policy: template pins only
- Authorable config: no node-specific document config beyond label/pin_defaults
- Inputs: none
- Outputs: `context` object: Full context object from workflow state (run.vars.context).; `task` string: Convenience output for context.task.; `messages` array: Convenience output for context.messages (conversation history).
- Default config: none

### variables / Get Variable

- Node type: `get_var`
- Document node: `{"id":"<unique_id>","type":"get_var"}`
- Utility: Read a variable from workflow state by name.
- Gateway capability: none
- Dynamic pin policy: template pins only
- Authorable config: input defaults with `pin_defaults`
- Inputs: `name` string
- Outputs: `value` any
- Default config: none

### variables / Set Variable Property

- Node type: `set_var_property`
- Document node: `{"id":"<unique_id>","type":"set_var_property"}`
- Utility: Update a nested property on an object variable in workflow state (name + key), then continue.
- Gateway capability: none
- Dynamic pin policy: template pins only
- Authorable config: input defaults with `pin_defaults`
- Inputs: `exec-in` execution; `name` string; `key` string; `value` any
- Outputs: `exec-out` execution; `value` object
- Default config: none

### variables / Set Variable

- Node type: `set_var`
- Document node: `{"id":"<unique_id>","type":"set_var"}`
- Utility: Write a variable into workflow state by name (supports dotted paths for nested updates; updates run vars).
- Gateway capability: none
- Dynamic pin policy: template pins only
- Authorable config: input defaults with `pin_defaults`
- Inputs: `exec-in` execution; `name` string; `value` any
- Outputs: `exec-out` execution; `value` any
- Default config: none

### variables / Set Variables

- Node type: `set_vars`
- Document node: `{"id":"<unique_id>","type":"set_vars"}`
- Utility: Write multiple variables into workflow state in a single step (updates is an object of name→value).
- Gateway capability: none
- Dynamic pin policy: template pins only
- Authorable config: input defaults with `pin_defaults`
- Inputs: `exec-in` execution; `updates` object
- Outputs: `exec-out` execution; `updates` object
- Default config: none

### variables / Variable

- Node type: `var_decl`
- Document node: `{"id":"<unique_id>","type":"var_decl"}`
- Utility: Declare a workflow-scope typed variable (name/type/default) and output its current value.
- Gateway capability: none
- Dynamic pin policy: template pins only
- Authorable config: no node-specific document config beyond label/pin_defaults
- Inputs: none
- Outputs: `name` string; `value` any
- Default config: none

## Hidden Or Deprecated Templates

- `call_tool` / Call Tool: rejected by the authoring validator (hidden, deprecated).
- `image_to_image` / Image To Image: rejected by the authoring validator (hidden).
- `text_to_video` / Text To Video: rejected by the authoring validator (hidden).

## docs/architecture.md

# Architecture

AbstractFlow is the web authoring surface for VisualFlow workflows.

## Product Boundary

AbstractFlow owns:

- the React/Vite visual editor in `src/`
- the npm CLI/static server and Gateway proxy in `bin/cli.js`
- browser-session UX for connecting to a Gateway user
- client-side mapping of Gateway discovery, run ledgers, artifacts, and media catalogs into editor controls
- VisualFlow authoring UX for node pin defaults, including inline JSON Schema response schemas on unconnected schema pins
- the right-drawer Workflow Authoring Assistant, including its Gateway-routed model call and validated draft-graph command reducer
- sample VisualFlow JSON files in `examples/flows/`

AbstractFlow delegates:

- user and role management to AbstractGateway
- provider credentials, endpoint profiles, and model defaults to AbstractGateway
- VisualFlow persistence and publish lifecycle to AbstractGateway
- run execution, waits, ledgers, artifacts, and runtime isolation to AbstractGateway/AbstractRuntime
- VisualFlow compilation and `.flow` bundle semantics to AbstractRuntime
- provider calls and capability plugins to AbstractCore through Gateway/Runtime

Flow authors schemas; it does not enforce model responses. Gateway persists and
publishes the VisualFlow JSON. Runtime applies unconnected `pinDefaults` and
normalizes structured-output schemas. Core/provider integrations enforce the
schema for the actual model call when supported.

The Workflow Authoring Assistant is an editor feature, not a runtime. It
resolves Gateway's default `output.text` route unless the user pins a specific
assistant provider/model, then starts a Gateway `basic-agent` planner run and
reads the terminal authoring response from the run ledger. The planner run
explicitly receives an empty runtime tool list so authoring edits are returned
as a workflow document JSON instead of Gateway tool calls. Generated content is
never applied as raw VisualFlow JSON: the emitted document is diffed against
the current graph in the browser and compiled into validated graph edits, and
Save/Publish/Run remain user-controlled Gateway operations.

## Runtime Shape

```mermaid
flowchart LR
  Browser[Browser editor] --> Flow[AbstractFlow Node server]
  Flow --> Gateway[AbstractGateway]
  Gateway --> Runtime[AbstractRuntime]
  Runtime --> Core[AbstractCore]
  Gateway --> Stores[(Users / Workflows / Runs / Ledgers / Artifacts)]
```

Flow serves static assets and proxies HTTP/SSE calls. The browser does not talk directly to provider APIs or runtime stores.

## Repository Layout

```
bin/                  npm CLI and Gateway proxy
src/                  React editor source
examples/flows/       sample VisualFlow JSON files
docs/                 user and contributor docs
package.json          npm package manifest
```

There is intentionally no Python package, no FastAPI host, and no local execution server in this repository.

## Auth Boundary

The Flow connection form collects a Gateway URL, Gateway user id, and Gateway user token. The Node proxy validates/exchanges that token with Gateway and stores only opaque browser-session cookies. Mutating proxy calls carry the Gateway CSRF token.

Hosted Flow deployments block arbitrary browser-supplied Gateway URLs by default so the Flow server cannot become a user-directed same-origin proxy.

## Discovery Boundary

Flow must discover capabilities from Gateway instead of hardcoding local providers. That includes:

- text/model providers
- OpenAI-compatible endpoint profiles
- media providers and task-specific model lists
- tool inventory and approval policy
- workspace and artifact affordances

Provider secrets stay in Gateway.

## Authoring Assistant Boundary

The assistant reads `docs/workflow-authoring-skill.md` bundled with the web app
plus a complete generated node catalog from `src/types/nodes.ts`. This
authoring skill replaces generic `llms-full.txt` context for graph
construction. The UI shows the prompt size it will send to Gateway and displays
the selected model's context/output limits from Gateway model-capability
discovery when available. AbstractFlow does not hardcode model context windows
or clip chat, skill docs, or graph context. The planner is invoked through
Gateway's normal run lifecycle, not the console sandbox.

The assistant is an iterative Flow-owned authoring controller using direct
document authoring. Each turn can run multiple Gateway planner runs: the model
emits the complete workflow document, the editor diffs it against the current
graph and applies the compiled changes through the validated command reducer,
recomputes preflight/readiness issues, and continues until the graph is ready
or explicitly blocked. Nodes and edges omitted from the document are deleted
(removal is implicit; deletions remain undoable via Undo Turn). Research,
news, job-search, and deep-research requests are checked for a multi-step
scaffold: start inputs, prompt building, explicit tools, an Agent with the
standard `max_iterations=50` setting, and end outputs.

Model output is restricted to the document JSON. The editor refuses changes
that would embed secrets, create unknown templates, bypass connection
validation, enable Code `full_access`, or create Tool Calls without an
explicit allowlist; secrets in the serialized document are redacted before
they reach the model. Tool-dependent authoring uses only Gateway's advertised
tool inventory and exact discovered tool names. The assistant has no local
template planner: if Gateway defaults, advertised discovery endpoints, the
planner run, JSON parsing, or document validation fail, the drawer surfaces the error instead
of synthesizing a substitute workflow.

## Defaults And Residency

Provider/model pins in saved workflows are optional. A blank provider/model
means `Auto (Gateway default)` and resolves through the current Gateway/Core
capability route at run time. This keeps portable workflows independent of a
specific deployment's OpenAI, Anthropic, LM Studio, Ollama, or endpoint-profile
setup.

The Model Residency modal is intentionally loaded-state only. It lists
provider-reported resident models and does not edit capability defaults.
Gateway Console and the Core/Gateway config CLIs own default route
configuration.

## docs/api.md

# API And Contracts

AbstractFlow's public package surface is the npm package `@abstractframework/flow`.

## CLI

```bash
npx @abstractframework/flow --gateway-url http://127.0.0.1:8080
```

Options:

- `--host <host>`: host for the Flow static/proxy server.
- `--port <port>`: port for the Flow static/proxy server.
- `--gateway-url <url>`: Gateway target used by the proxy.

Environment:

- `HOST`
- `PORT`
- `ABSTRACTGATEWAY_URL`
- `ABSTRACTFLOW_GATEWAY_URL`
- `ABSTRACTFLOW_ALLOW_REMOTE_BROWSER_GATEWAY_CONFIG`
- `ABSTRACTFLOW_TRUST_PROXY_HEADERS`

## Proxy Contract

The Flow server proxies browser calls under `/api/*` to the configured Gateway. The important Gateway surfaces are:

- `/api/gateway/session/login`
- `/api/gateway/me`
- `/api/gateway/discovery/capabilities`
- `/api/gateway/providers`
- `/api/gateway/config/capability-defaults`
- `/api/gateway/visualflows`
- `/api/gateway/visualflows/{flow_id}/publish`
- `/api/gateway/runs/start`
- `/api/gateway/runs/{run_id}/ledger`
- `/api/gateway/runs/{run_id}/ledger/stream`
- `/api/gateway/runs/{run_id}/artifacts`
- Gateway media catalog and artifact content routes

The Workflow Authoring Assistant uses the normal run and ledger routes to start
Gateway planner runs and read their terminal responses.

Flow treats Gateway as the source of truth. Any local fallback must be visible in UI state and should be limited to degraded editor display, not execution.

## VisualFlow JSON

The editor imports and exports VisualFlow JSON. See [visualflow.md](visualflow.md).

Execution semantics are not implemented in this package. Gateway/Runtime execute the workflow after publish/start.

## Frontend Modules

High-value source modules:

- `src/utils/gatewayClient.ts`: Gateway HTTP/SSE client helpers.
- `src/utils/flowAuthoringCommands.ts`: typed Workflow Authoring Assistant command validation and graph mutation helpers.
- `src/utils/gatewayCatalog.ts`: provider/model/media catalog normalization.
- `src/utils/ledgerEvents.ts`: Gateway ledger to UI execution-event mapping.
- `src/utils/artifactInputs.ts`: artifact references and modality-aware UI helpers.
- `src/utils/jsonSchemaEditor.ts`: shared JSON Schema builder helpers, including Choice/enum round-tripping.
- `src/components/GatewayConnectionModal.tsx`: browser sign-in UX.
- `src/components/AuthoringAssistantDrawer.tsx`: right-drawer conversational workflow authoring assistant.
- `src/components/RunFlowModal.tsx`: run start, replay, stream, artifact, progress, and Gateway wait/resume UX, including browser-captured `Listen Voice` audio upload before run resume.
- `src/components/JsonSchemaEditor.tsx` and `src/components/JsonSchemaPinEditorModal.tsx`: inline schema-pin editing for unconnected JSON Schema inputs.
- `src/components/nodes/BaseNode.tsx`: node rendering, connection feedback, unconnected artifact-input upload affordances, and schema-pin edit buttons.
- `src/types/nodes.ts`: editor node templates and pins.

Schema pin defaults are stored under `node.data.pinDefaults`, for example
`pinDefaults.resp_schema` on LLM Call and Agent nodes. Gateway persists and
publishes that JSON as part of the VisualFlow document; Runtime decides whether
the pin default is used or overridden by a connected input.

Structured LLM Call and Agent results have two outputs: `response` remains a
string, while `data` is the object that conforms to `resp_schema`. Editors and
clients should wire `data` into Break Object, Switch, or other object-aware
nodes when schema fields are needed.

## docs/visualflow.md

# VisualFlow JSON

VisualFlow is the portable workflow document produced by the AbstractFlow editor and persisted by AbstractGateway.

Execution semantics are owned by AbstractRuntime. Flow's job is to author and serialize the graph.

## Shape

```json
{
  "id": "workflow-id",
  "name": "Workflow Name",
  "nodes": [
    {
      "id": "node-1",
      "type": "llm_call",
      "position": { "x": 100, "y": 80 },
      "data": {
        "nodeType": "llm_call",
        "pinDefaults": {}
      }
    }
  ],
  "edges": [
    {
      "id": "edge-1",
      "source": "node-1",
      "sourceHandle": "exec-out",
      "target": "node-2",
      "targetHandle": "exec-in"
    }
  ],
  "entryNode": "node-1"
}
```

## Authoring Rules

- Nodes contain editor data and runtime-facing pin defaults.
- Execution edges connect `exec-out` to `exec-in`.
- Data edges connect typed pins.
- Provider/model pins should use Gateway-discovered provider ids and models.
- Secrets must not be embedded in VisualFlow JSON.
- Reusable endpoint credentials belong in Gateway provider endpoint profiles.

## File And Document Nodes

File/document side effects are execution nodes and must be on the execution path
before `on_flow_end` if their outputs are part of the requested result.

- `read_file` reads UTF-8 text or JSON from a workspace path.
- `write_file` writes UTF-8 text or JSON to a workspace path.
- `read_pdf` extracts text and metadata from a `.pdf` path using Runtime's
  permissive PDF reader.
- `write_pdf` renders text or Markdown-style report content to real PDF bytes
  using Runtime's permissive PDF writer.

In Gateway-hosted runs, these are workspace-scoped server paths, not browser
local files. Artifact inputs use the separate `Artifact` / `Local File` /
`Server File` source model. Use `write_file` for Markdown, JSON, and text
files. Use `write_pdf` for PDF files; do not represent PDF generation by
writing Markdown to a `.pdf` path.

## Structured Output And Switch Cases

Inline response schemas for LLM Call and Agent nodes are stored as pin defaults.
Connected schema edges override these defaults at runtime.

When a schema is active, LLM Call and Agent nodes keep `response` as a text
output for compatibility and expose `data` as the structured object output. Wire
`data` directly into Break Object or other object-aware nodes; use `response`
when you explicitly want the textual assistant content.

```json
{
  "id": "classify",
  "type": "llm_call",
  "position": { "x": 240, "y": 80 },
  "data": {
    "nodeType": "llm_call",
    "pinDefaults": {
      "prompt": "Classify the request.",
      "resp_schema": {
        "type": "object",
        "properties": {
          "choice": {
            "type": "string",
            "enum": ["approve", "reject", "escalate"]
          }
        },
        "required": ["choice"]
      }
    }
  }
}
```

For enum-driven control flow, wire the structured `data` output into Break
Object, expose the enum field, and connect that field to Switch. Flow stores
explicit Switch cases. Gateway publishes these fields unchanged, and Runtime
routes by the saved case handles.

```json
{
  "id": "route_choice",
  "type": "switch",
  "position": { "x": 640, "y": 80 },
  "data": {
    "nodeType": "switch",
    "switchConfig": {
      "cases": [
        { "id": "approve", "value": "approve" },
        { "id": "reject", "value": "reject" },
        { "id": "escalate", "value": "escalate" }
      ]
    },
    "outputs": [
      { "id": "case:approve", "label": "approve", "type": "execution" },
      { "id": "case:reject", "label": "reject", "type": "execution" },
      { "id": "case:escalate", "label": "escalate", "type": "execution" },
      { "id": "default", "label": "default", "type": "execution" }
    ]
  }
}
```

## Sharing Workflows

For portable workflows, prefer exposing environment-specific values as start inputs or Gateway defaults:

- provider id
- model id
- optional base URL override when the workflow intentionally targets an OpenAI-compatible route
- non-secret parameters such as temperature, max tokens, dimensions, steps, and seed

API keys and user credentials should be configured by the receiving Gateway, not exported with the workflow.

## Examples

Sample JSON files live in `examples/flows/`.

## docs/cli.md

# CLI

AbstractFlow ships one CLI through npm:

```bash
npx @abstractframework/flow
```

It serves the built editor and proxies `/api/*` to AbstractGateway.

## Usage

```bash
npx @abstractframework/flow \
  --host 0.0.0.0 \
  --port 3003 \
  --gateway-url http://127.0.0.1:8080
```

Equivalent installed command:

```bash
npm install -g @abstractframework/flow
abstractflow-editor --gateway-url http://127.0.0.1:8080
```

## What The CLI Does

- Serves `dist/` static assets.
- Proxies Gateway HTTP and SSE routes.
- Handles browser-session cookie forwarding and CSRF headers.
- Rejects unsafe hosted Gateway URL changes by default.

It does not execute workflows locally. Workflow execution is a Gateway/Runtime responsibility.

## docs/faq.md

# FAQ

## Does AbstractFlow Need Python?

No. AbstractFlow is the web editor package `@abstractframework/flow`.

Python services are used by other framework packages such as AbstractGateway, AbstractRuntime, AbstractCore, and capability plugins. Flow itself does not ship a Python package or local execution host.

## Why Do I Need A Gateway Token?

Flow is only the editor. Gateway owns user authentication and runtime isolation. Each browser must sign in with a Gateway user token so Gateway can route requests to the right user/runtime.

## Can Flow Store Provider API Keys?

No. Configure provider credentials, OpenAI-compatible endpoint profiles, and model defaults in the Gateway console. Flow discovers those providers and models from Gateway.

## Where Are Workflows Stored?

Gateway stores VisualFlow drafts, published workflow bundles, run ledgers, and artifacts. Flow may import/export JSON in the browser, but persistent state belongs to Gateway.

## How Do I Use A Custom OpenAI-Compatible Endpoint?

Create a provider endpoint profile in Gateway with its base URL, API key, description, and discovered models. It will surface in Flow as a virtual provider.

## What Happens If Gateway Is Down?

The editor can load its static UI, but discovery, save, publish, run, artifact, and history features require Gateway.

## Where Did The Python `abstractflow` Package Go?

Its responsibilities were moved to their owners:

- visual execution and bundle semantics: AbstractRuntime
- users, auth, runtime routing, workflow registry, runs, artifacts: AbstractGateway
- provider calls and capability plugins: AbstractCore
- visual authoring UI: `@abstractframework/flow`

## CHANGELOG.md

# Changelog

All notable changes to AbstractFlow will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [Unreleased]

## [0.3.19] - 2026-06-14

### Changed
- Media node authoring now surfaces Gateway/Core vision route features directly in the Properties drawer: `Generate Image`, `Edit Image`, `Generate Video`, and `Image To Video` expose task-filtered provider/model discovery, batch controls (`count`, `seeds`), ordered `lora_adapters` stacks, and plural media outputs (`image_artifacts`, `video_artifacts`) for compatible routes. Legacy node normalization now rebuilds media input pins from the shared node templates so reopened/imported flows retain the newer vision fields instead of dropping them.
- Workflow Authoring Assistant switched from incremental command-batch negotiation to direct document authoring: the model now emits the complete workflow as one JSON document (`flow_name`, `nodes`, `edges`) every cycle, and the editor diffs it against the current graph (`src/utils/flowAuthoringDocument.ts`) and compiles the diff into the existing validated command machinery, so all validators, canonicalization (exec fan-out, loop-back removal, route overrides), and security guards remain the single source of truth. Nodes, edges, and dynamic pins omitted from the document are deleted — removal is implicit, and the assistant can no longer ask the user to "remove manually". `pin_defaults` merge per key, node ids are stable identities (type changes require a new id), existing node positions never move, new nodes get execution-depth auto-layout, and secrets round-trip as a `<redacted>` sentinel the diff never writes back. An idempotent re-emit compiles to zero changes, so unchanged documents are correctly detected as stalls. The first cycle aims to one-shot the workflow; later cycles only repair validator errors, readiness issues, and acceptance findings.
- Workflow Authoring Assistant prompt is leaner per cycle (~86k chars / ~21k tokens baseline, down from ~151k chars) with **zero semantic loss** (ADR-0026): the node catalog renders one line per template (`type [template] (category) in[...] out[...] dyn[...] cfg[...] cap:... :: description`) keeping every full node description, pin label, and pin description intact — only repeated headings and command-JSON scaffolding were removed. `docs/workflow-authoring-skill.md` was rewritten for document authoring (the obsolete 17-command schema is gone because it would contradict document mode; ownership semantics, dynamic-pin lists, and repair guidance replace it). A catalog-fidelity test asserts no template or pin description is ever dropped or sliced from the prompt; there is no prompt size budget and no imposed output token budget on planner runs.
- Workflow Authoring Assistant now reports token usage in token terms end to end: every outgoing planner request is logged with an explicit estimated size (`Sending plan request (~21k tokens est. (86k chars) — authoring the full workflow document)`), and after each planner response, `result.usage` is summed across the Gateway run-tree ledgers (root run and subruns, tolerant of `input/output_tokens` and `prompt/completion_tokens` field families) and logged as `Response received (41.2k in / 1.1k out tokens · 12k chars · 1:59)`; cumulative turn totals appear in the status card footer. Usage collection is best-effort observability and never blocks the loop; estimates are labeled `est.` and never used for budgeting decisions.
- Workflow Authoring Assistant requests and responses are now inspectable: `Sending plan request`, `Response received`, and acceptance-review activity entries carry an expandable "Inspect payload" section with the exact system prompt + user prompt sent (or the raw model response) and a one-click copy. Payloads are session-only (persisted activity keeps the entry text but drops the attached payload to protect the localStorage quota).
- Workflow Authoring Assistant live status: the card header now carries the cycle number (`Cycle 3 · Planning workflow graph`), and a shimmering in-flight ticker pinned at the bottom of the activity feed shows what the assistant is waiting on right now — including the request purpose ("authoring the full workflow document", "repairing 2 validation issues", "acceptance review") and the estimated tokens sent — with a per-stage elapsed counter that ticks every second (static under `prefers-reduced-motion`).
- Canvas maximum zoom-out increased from 13 to 17 zoom steps (min zoom ≈ 0.09, roughly 2x more dezoom) so large authored workflows fit on screen.
- `docs/workflow-node-catalog.md` generation now documents the authoring document format (document node snippets, `template` variant selection, document config fields) instead of `add_node` command JSON.

### Added
- Added a `remove_pin` authoring command (the document-ownership counterpart of `add_input_pin`/`add_output_pin`): dynamic, non-execution pins omitted from an emitted document pin list are removed together with their edges; template-owned pins are refused.
- Added a toolbar Execution View toggle that condenses the canvas to the control-flow skeleton: only nodes linked by execution edges (and those edges) stay visible, rendered as compact cards with per-family color, shape, and iconography (events, control flow, user interaction, generative AI, generated media, tools & files, memory, subflow, logic & state). Node positions are preserved so switching between views keeps the same layout.
- Added a `Ctrl/⌘+S` keyboard shortcut that saves the current flow and suppresses the browser "Save page" dialog inside the editor.
- Added a leave-page confirmation (`beforeunload`) when the flow has unsaved changes or a save is still in flight, preventing silent loss of graph edits.
- Added a node palette search empty state ("No nodes match …" with a Clear search action) instead of a blank list when a search has no results.
- Added a first-use empty-canvas hint that explains dragging nodes from the palette and disappears once the flow has nodes.
- Added first-class `Read PDF` and `Write PDF` VisualFlow nodes so workflows can extract PDF text/metadata and render report content to real PDF files through Runtime.
- Added a first-class Restore / Upscale Image media node backed by Gateway's `upscaled_image` contract and `image_upscale` vision catalog task.
- Added a right-drawer Workflow Authoring Assistant that reads `docs/workflow-authoring-skill.md` plus a complete generated node catalog, drafts edits through Gateway's default `output.text` model unless a model is pinned, applies only validated graph commands, and fails closed without draft changes when Gateway/model/JSON/command validation fails.
- Added capability-route filtering for text model discovery, including reusable `output.text` defaults and Models Catalog support for input/output-shaped routes such as `input.image,output.text`.
- Added reasoning/thinking controls for Agent and LLM Call nodes, with Gateway/Core-backed model capability lookup and inline/right-panel selectors for supported reasoning models.
- Added Vitest coverage for node pin disclosure behavior, including compact media nodes, default-value handling, and generated-video defaults.
- Added inline JSON Schema editing for unconnected schema input pins, including a Builder tab for fields and Choice/enum values plus an expert JSON Schema tab.
- Added switch-friendly structured-output authoring: enum-backed response fields can be discovered through Parse JSON / Break Object and synced into explicit Switch cases.

### Added
- The Workflow Authoring Assistant input row now has a max-cycles dropdown next to Send (10/20/40/60/80 autonomous planning cycles per turn, default 40, persisted across sessions). The cap is captured when a turn starts; changing it mid-turn applies from the next turn.

### Fixed
- The provider/model preflight rule for LLM Call and Agent nodes no longer produces unsatisfiable demands. The old rule ("Set both provider and model, or leave both blank for Gateway defaults") fired when the model pin was wired dynamically (e.g. a model pool feeding `llm_call.model` through a loop item) with provider on Gateway defaults — a valid runtime configuration the rule made impossible to satisfy without deleting a needed wire. It also read only the effect config, so typed pin defaults could never clear it. The rule now skips pairs where either pin is connected, reads pin defaults, and the remaining half-typed-default message names the current values (`Provider is "openai" but model is blank — …`) so users and the authoring model can see what to fix. This single false positive cost an authoring run 10 wasted cycles (~15 minutes) before failing the turn.
- Authoring loop stall guard: a cycle whose applied batch is identical to the previous one and leaves identical readiness issues counts as repetition, not progress. The first repeat sends the model a corrective note; the second stops the turn as "needs your input" with the remaining issues instead of grinding the full cycle budget. Rewriting an identical pin default is also now a warning no-op instead of counting as an applied change.
- Authoring applied-change logs now include the written value (`Set llm.provider = "openai"` instead of `Set llm.provider`), so users can see which provider/model/value the assistant actually chose.
- The authoring assistant now enforces its language contract at the boundary instead of trusting the model. A full ledger audit proved the planner model can reply in another language (English reasoning, French reply) with a 100% single-language 157k-char context at temperature 0 — and a replay of the exact same payload returned English, demonstrating serving-layer non-determinism no prompt can prevent. Every cycle's user-visible plan text is now language-checked against the user request (conservative stopword/script detector that abstains on ambiguity); mismatches trigger a bounded retry with a LANGUAGE CORRECTION note (2 per turn, live-validated to rewrite the same plan in the request language), then accept with a `#FALLBACK` activity note. The response schema also requires a leading `language` field as a decoding anchor.
- Switching to the Properties tab (or collapsing the right drawer) no longer wipes the Workflow Authoring Assistant: the drawer now stays mounted once opened (it renders nothing while hidden), so the in-flight autonomous authoring loop, conversation, plan, and activity feed all survive tab switches. Previously the tab switch unmounted the component, destroying the running turn and all in-memory state.
- The authoring status card (plan + activity feed + collapse state) is now persisted per workflow alongside the conversation: it survives page reloads and workflow switches, follows a draft promoted to a saved flow, and is only removed by Clear Chat. A turn that was in flight when the page reloaded is restored as "Interrupted (editor reloaded)" instead of pretending to still run; switching workflows now loads that workflow's own activity feed instead of leaking the previous one.

### Changed
- Workflow Authoring Assistant `connect` now mirrors the canvas connection semantics: connecting a different valid source to an occupied single-entry data input replaces the existing edge (the re-drag gesture), an exact duplicate connect is a no-op warning, and on multi-entry nodes (2+ incoming execution paths) connecting a data pin from a direct execution predecessor adds a per-path route override instead of replacing the base edge. A new `disconnect` command removes an edge by endpoints without replacing it, and "already connected" rejections now name the existing source so the planner can rewire instead of looping. When replacement is blocked by an invalid new edge (e.g. type mismatch), the underlying reason is reported instead of a misleading "already connected".
- Workflow Authoring Assistant planner runs now pin `temperature: 0` so structured command batches are deterministic instead of inheriting the Gateway agent default (0.7), which produced run-to-run language and command variance.
- Workflow Authoring Assistant session policy is now explicit: one durable Gateway session per workflow conversation (scoped to the workflow storage key, never shared across workflows), carried over when a draft is promoted to a saved flow, and rotated by Clear Chat so gateway-side agent memory restarts together with the visible conversation.
- Workflow Authoring Assistant prompt now anchors the language directive at the request site ("write … in the language of THIS request") and marks the replayed conversation as historical context that does not control the language. The gateway agent replays durable session memory into the model context, so without the anchored directive an English request kept producing French workflows when the session/conversation history was French.
- Workflow Authoring Assistant no longer hard-fails a turn when the planner returns `continue` with zero commands ("Gateway assistant returned no graph commands" discarded otherwise-progressing builds): command-less cycles get a corrective note for up to two consecutive cycles, then the turn ends as a "needs your input" message carrying the model's own reply so the user can guide the next turn.
- Workflow Authoring Assistant system prompt and skill now require all user-visible workflow content (flow name, node labels, prompts, replies) to match the language of the user request; the prompt's example label was also de-localized (an English request previously produced a French workflow because the only label example in the prompt was French).
- Workflow Authoring Assistant is now encouraged to ask follow-up questions mid-loop: the prompt/skill instruct the model to return `needs_user` with concrete questions when the request is ambiguous or repair cycles stop progressing, and `needs_user` replies render under an explicit "The assistant needs your input to continue" header.
- Research-scaffold readiness checks (Agent node, sources/citations, audit trace) now apply only when the request's deliverable is researched content (deep research, internet/web research, news, digest, jobs, or "research" coupled to a workflow/report deliverable in the same sentence). An incidental mention of "research" — e.g. "genuine discussion, research, and deepening of ideas" — previously forced 8 unfixable readiness issues onto a multi-LLM discussion workflow and stalled the loop.
- Workflow Authoring Assistant activity feed now groups entries under per-cycle divider rows, making iteration boundaries visible; the status card header gained a leading chevron with hover affordance (clear collapse signal) and a copy button that exports the activity feed (grouped by cycle with elapsed timestamps) to the clipboard.
- Workflow Authoring Assistant command batches are no longer atomic: commands are applied per-command in dependency order (nodes, then configuration, then connections), valid commands are kept even when others fail, and failed commands return to the planner as "skipped commands" feedback. Atomic rejection previously discarded whole batches, so the planner kept referencing nodes that never existed ("Source or target node not found" cascades across repair cycles).
- Workflow Authoring Assistant validator now auto-repairs execution fan-out: connecting an already-connected execution output inserts (or extends) a Sequence node and reports the rewiring as a warning instead of rejecting the edge ("Execution output pin already connected" was a recurring repair-loop trap).
- Workflow Authoring Assistant validator now drops loop-back edges from a loop body to the loop's `exec-in` (with a warning): AbstractRuntime control frames return to the loop automatically when the body chain ends, and an explicit loop-back resets the iteration counter. The authoring skill and system prompt now document these loop/control-frame semantics.
- Workflow Authoring Assistant working state is now a live activity feed (per-cycle plan request/response sizes, plan status and command counts, applied changes with labels, skipped/rejected commands, readiness and acceptance review events) with a spinner, elapsed timer, and cycle label, replacing the two static progress bars that conveyed no real-time information.
- Workflow Authoring Assistant turns can now be interrupted: a Stop control (in the status card and in place of Send while busy) aborts the autonomous loop between calls, best-effort cancels the in-flight Gateway planner run, and reports an explicit "Interrupted" message; applied edits stay in the draft and remain undoable via Undo Turn.
- Workflow Authoring Assistant drawer actions are now compact high-contrast icon buttons (copy, clear, undo at 19px/2px stroke in full text color) on the bottom row next to Send/Stop; the dedicated topbar action row is gone and the top of the drawer only shows the context-usage line while a request is being typed or running. Drawer chrome uses theme variables (`color-mix` on theme tokens) instead of hardcoded dark-biased rgba values so light themes render correctly.
- Workflow Authoring Assistant activity card is now collapsible (header toggles the log) and persists after the turn ends with a final state (green dot "Draft graph updated", red dot "Authoring failed"/"Interrupted by user") so the per-cycle history can be reviewed post-turn; Clear resets it.
- Fixed a loop-exit bug where an accepted `done` (including a passed acceptance review) was re-labeled "Autonomous authoring reached N cycles after validator rejections" because a stale rejected-batch marker from an earlier cycle survived the successful break; cap-exhaustion errors now apply only when the loop genuinely runs out of cycles.
- Workflow Authoring Assistant completion is now model-owned: the autonomous loop keeps cycling while the planner returns `continue` instead of force-stopping as soon as heuristic readiness checks pass (which previously cut the model off mid-build on requests outside the research/PDF/Markdown keyword heuristics, e.g. non-English multi-AI discussion workflows).
- Workflow Authoring Assistant now runs an acceptance review before accepting `done`: the planner declares per-request acceptance criteria, and a second model pass compares the draft graph against the original request; unmet findings are fed back into the loop as issues, and any findings left when the review budget is exhausted are reported with the result instead of being hidden.
- Workflow Authoring Assistant now preserves the planner's own plan memory: applied cycles carry one-line next-step notes into later cycles, and assistant turns are replayed across user turns as trimmed plan/result summaries (`#TRUNCATION`-labeled) so pending plan items are no longer forgotten between turns.
- Workflow authoring skill now documents iterative multi-participant discussion (loop + state) and multi-model fan-out patterns, and the system prompt explicitly forbids collapsing requested multi-participant/multi-model/iteration structure into a single Agent prompt simulation.
- Redesigned the editor toolbar: consistent stroke SVG icons replace mixed emoji/glyphs, actions are organized into segmented groups (file, import/export, run + history, gateway publish/lifecycle/models, workspace tools), Run is a labeled primary button with a running spinner, and the Connect/Disconnect button shows a live connection status dot.
- Execution View compact nodes now reuse the full-view node header (same per-node header color, uppercase title, and sheen) over a dark node body, so node identity carries across both modes while family icon and silhouette cues remain; the full-view header gained the same subtle sheen for harmony.
- Replaced the Execution View toolbar glyph (three dots on a line, easily read as a plain line) with a clearer node-to-node arrow icon, and toggle buttons now use accent-tinted pressed styling that works in all themes.
- Toolbar buttons now use fast AfTooltip hints (with disabled-state explanations and the save shortcut) instead of slow native `title` tooltips; `AfTooltip` gained a `minWidthPx` override for compact hints.
- Model residency and media provider/model selectors now include the `image_upscale` task for Gateway/Core upscaler discovery and explicit load/unload steps.
- Workflow Authoring Assistant PDF readiness now requires an executable `Write PDF` node and exposed PDF path instead of accepting Code or generic Write File workarounds.
- Compact node rendering now uses a shared pin disclosure policy so nodes show required, connected, or explicitly configured pins by default and hide optional/default/diagnostic pins behind a chevron.
- Workflow Authoring Assistant now shows prompt size plus Gateway-discovered model context/output limits and includes a Clear Chat control instead of trimming conversation history.
- Workflow Authoring Assistant now persists drawer chat/draft/session state across close/reopen and uses the authoring skill instead of generic `llms-full.txt` context for graph construction.
- Improved canvas rendering with clearer node cards, stronger edge readability, state-aware MiniMap node styling, and a pannable/zoomable preview.
- Restyled the MiniMap collapse/expand control as an icon button and moved React Flow attribution away from the preview while removing its grey backing.
- Restyled the schema-pin editor modal with clearer titles, validation, and editable Choice chips while keeping saved data as standard JSON Schema.

### Fixed
- Pin type compatibility now lets the dynamic `any` type connect to nominal provider/model pins: ForEach `item`, Get Variable `value`, Code outputs, and Parse JSON results are all `any`, so the documented multi-model pattern `loop.item -> llm_call.model` (and reading a model-typed variable) was unconstructible for both the authoring assistant and canvas users. Execution pins and non-`any` payload types (e.g. `string -> model`) keep their nominal guards.
- Authoring commands can now configure Variable nodes (`var_decl`/`bool_var`), which have no input pins: `set_pin_default` on pin `name`/`value` maps onto the declaration config, and `set_literal` accepts the canonical `{name, type, default}` object (or a bare value as the default), keeping the value output pin type in sync with the declared type. Previously these commands were refused ("unknown input pin 'name' on var_transcript") with no supported alternative.
- Connection and pin-default rejections now list the real pins so authors can self-correct: "Output pin 'end' not found (available outputs: loop, done, i, index)" and "unknown input pin 'instructions' on llm (available input pins: ...)" instead of dead-end messages.
- `add_node` without a descriptive label now records a non-blocking validator note (event nodes excepted), and the authoring prompt/skill instruct the model to label every node with its role in the user's language, so generated workflows stop shipping walls of "Variable"/"Array" default labels.
- Workflow Authoring Assistant plan parsing is now tolerant of model formatting: plan and acceptance-review JSON is extracted from markdown fences and prose-wrapped responses via a string-aware balanced-brace scan, instead of requiring the raw response to be bare JSON. Strict parsing previously made a fenced or prose-prefixed answer look like a missing response and killed the turn as "completed without an authoring response in its run tree ledger".
- Workflow Authoring Assistant no longer aborts the whole turn on one unusable planner response: an empty run output or unparseable/truncated plan JSON now retries the same cycle (up to 3 unusable responses per turn) with a corrective format note asking for bare JSON and smaller command batches, and the retry is logged in the activity feed. Previously a single bad cycle-2 response discarded an otherwise progressing turn, leaving nodes without edges.
- Theme support: the theme selector dropdown (and other AfSelect popovers) no longer hardcodes dark panel colors that broke light themes — app-level overrides were removed in favor of the ui-kit's theme-aware styles, with node-scoped colors kept for inline pin selects inside the intentionally dark node frames.
- Theme support: toolbar group chrome, toggle states, the offline connection dot, and the empty-canvas hint now derive from theme variables instead of white-alpha/hardcoded darks, so they stay visible in light themes.
- Theme support: the edge underlay now follows the canvas background color per theme, removing the chain-link edge artifacts that appeared on light themes.
- Workflow Authoring Assistant requests now keep full prior turns inside the current prompt instead of sending assistant-led chat history to OpenAI-compatible endpoints, avoiding LM Studio/Qwen prompt-template failures without imposing a local model-context cap.
- Model selectors now request provider models with the appropriate capability route so discovery stays aligned with Gateway/Core model capability metadata.
- Optional single-pin disclosures no longer collapse unnecessarily, and thinking pins stay hidden for models without detected thinking support unless already configured.
- Schema Builder mode no longer drops JSON Schema `enum` values when switching between Builder and JSON Schema editing.

## [0.3.18] - 2026-06-03

### Changed
- Reorganized AbstractFlow as the web editor package `@abstractframework/flow` at the repository root.
- Moved sample VisualFlow JSON files from `web/flows/` to `examples/flows/`.
- Rewrote current docs around the web package, Gateway connection flow, and Gateway/Runtime ownership boundaries.

### Removed
- Removed the Python package, Python packaging metadata, Python tests, FastAPI compatibility backend, generated Python docs site, and local runtime artifacts from the AbstractFlow repository.

## [0.3.17] - 2026-05-31

### Added
- Hosted Flow sessions can sign in with Gateway URL, user id, and token. Flow validates that the token resolves to the requested Gateway user, exchanges it for an opaque Gateway browser session, and stores only that session id in an HTTP-only browser-session cookie; the `/api/gateway/*` proxy resolves that request session before any server-wide Gateway token so different browsers can connect as different Gateway principals.
- Flow provider/model discovery now includes Gateway provider endpoint profiles as virtual providers, including OpenAI-compatible endpoints configured in the Gateway Console.

### Changed
- Remote browser connection updates may provide a token for the server-configured Gateway URL without mutating Flow server environment state. Remote browsers still cannot change the Gateway URL unless `ABSTRACTFLOW_ALLOW_REMOTE_BROWSER_GATEWAY_CONFIG=1` is enabled.
- Apple/GPU Flow profiles now require Gateway `>=0.2.23` and Agent `>=0.3.10`.

### Fixed
- Flow's Gateway proxy now strips browser-supplied `Authorization`, `Cookie`, forwarded, and other unapproved request headers before proxying, then injects only the resolved opaque Gateway browser session and CSRF token where required.

## [0.3.16] - 2026-05-29

### Added
- Artifact input selection in the Run modal, including Gateway-backed search/filtering for reusable text, document, image, video, voice, audio, and music artifacts.
- Artifact search/import/export contract support in the Gateway client layer, while keeping file read/write behavior as graph-level nodes rather than modal-only actions.
- Staged Deep Research demo workflow for authoring demonstrations.

### Changed
- Media nodes now surface the critical sampling controls (`steps`, `seed`, and `guidance`) consistently for image and video generation/editing, with model defaults used when fields are left empty.
- Run progress rendering now includes elapsed/estimated remaining time when Gateway progress events provide enough timing data.
- The Run modal now uses a window-style top bar and only shows lifecycle actions that match the current run state.
- Apple/GPU Flow profiles now require Gateway `>=0.2.21` and Agent `>=0.3.9`; hosted CI/release tests install the base Gateway package because HTTP/SSE is part of the light install.

### Fixed
- Media provider selectors now keep image/video provider defaults scoped to media providers instead of showing text-only providers.
- Canvas interactions avoid stale pointer-capture state after trackpad/mouse release events.
- Generated media cards no longer expose a modal-level export button; artifact-to-file workflows should use graph nodes.

## [0.3.15] - 2026-05-26

### Added
- Native Generate Video and Image-to-Video authoring in the Flow editor, including scoped video provider/model pins, Gateway readiness checks, run preflight, artifact previews, and Runtime compatibility execution.
- Gateway `abstract.progress` ledger events now render as running-step progress in the Run modal.

### Changed
- Apple/GPU Flow profiles now require Gateway `>=0.2.20` for the video media, progress, catalog, and model-residency contracts.
- Model residency and default routing now use task-scoped Gateway vision catalogs for `text_to_video` and `image_to_video` instead of reusing image defaults.
- Hosted CI/release tests now install the host-neutral Gateway HTTP stack instead of macOS-only Apple extras on Ubuntu runners.

## [0.3.14] - 2026-05-26

### Added
- Gateway-aware palette, preflight, live connection feedback, run lifecycle, workflow bundle, variable-name, and media artifact helpers for the thin-client editor.
- Validated code-editor execution policy and prompt-free variable selector improvements.

### Changed
- Apple/GPU Flow profiles now require Gateway `>=0.2.19` and Agent `>=0.3.8`; Runtime/Core are still consumed through Gateway extras.
- Media defaults and advanced media pin disclosure now use one editor surface backed by Gateway discovery.

### Fixed
- Repaired code node, pin, media artifact, and run UI regressions around resumed runs, validated variables, and modality-specific source selection.

## [0.3.13] - 2026-05-22

### Added
- Native Generate Music authoring against the released Runtime/Gateway media contract, including Gateway music catalog selectors, music residency targeting, and advanced music controls.
- Image edit/image-to-image node templates and controls aligned with Gateway's generated media contracts.
- Gateway catalog v1 helpers that prefer canonical `items` envelopes while retaining legacy catalog fallbacks.
- Artifact reference primitives for text, image, voice, music, and video references in the palette.
- Artifact literal editor and built-in artifact content previews (image/audio/video) backed by Gateway artifact content endpoints.

### Changed
- Apple/GPU Flow profiles now require Gateway `>=0.2.18`; Runtime/Core are consumed through Gateway extras instead of direct Flow dependencies.
- Generated media readiness honors Gateway's `common.readiness` surface summary when available while remaining compatible with legacy direct endpoint descriptors.
- Gateway proxy/model residency operations now allow long media and warmup requests without the previous short frontend/backend timeout path.

### Fixed
- Removed browser-side Generate Music lowering. Old lowered flows are normalized back to native `generate_music` when loaded or saved.
- Python VisualFlow models now accept the new native media node types without importing Runtime/Core at package import time.
- Warm/unload authoring is Gateway-only, allows Gateway default provider/model selection, and no longer disables all media residency controls from stale per-task support flags.
- Music provider/model changes clear stale backend overrides so Stable Audio 3 and Stable Audio Open do not inherit the wrong backend.
- Media previews are modality-aware and can fetch child-run/projected artifacts without using the wrong run id.
- Run preflight now catches missing media prompts and required source artifacts before starting a run.

## [0.3.12] - 2026-05-19

### Fixed
- Generate Image, Generate Voice, Transcribe Audio, and Listen Voice selectors now rely on Gateway provider catalogs instead of hardcoded media model fallbacks.
- Supertonic voice options now come from the Gateway voice catalog, so Flow surfaces the same voices that Gateway can execute.
- Media nodes keep image, TTS, and STT provider/model selections in media-specific fields instead of falling back to generic LLM `provider`/`model` values.

### Changed
- Apple/GPU Flow profiles now require Gateway `>=0.2.14`, Runtime `>=0.4.14`, and Core `>=2.13.15`.

## [0.3.11] - 2026-05-13

### Fixed
- Media node controls keep image, TTS, and STT model selectors in media-specific fields so runtime LLM provider/model inputs no longer overwrite generated media routing.
- Listen Voice nodes now expose the Gateway STT model selector and pass the chosen transcription model through wait metadata.

### Changed
- Apple/GPU Flow profiles now require Runtime `>=0.4.11` and Core `>=2.13.14`.
- Frontend npm package metadata is aligned with the Python release version for the next npm publication.


## [0.3.10] - 2026-05-12

### Added
- AbstractFlow media node properties now load Gateway voice profiles, TTS models, STT models, provider image models, and cached local vision models from Gateway catalog routes.
- Generate Image, Generate Voice, Transcribe Audio, and Listen Voice nodes now expose simple Gateway Media controls for local/provider model selection.

### Fixed
- Image, TTS, and STT selectors now write media-specific fields (`image_provider`/`image_model`, `tts_model`, `stt_model`) instead of overloading LLM routing `provider`/`model`.
- Apple/GPU Flow release-profile installs now include `abstractagent>=0.3.7`, so Agent-node workflow validation matches the capabilities shipped in the local host profiles.

### Changed
- Apple/GPU Flow install profiles now require Runtime `>=0.4.10` and Core `>=2.13.13` while keeping Gateway as a separately installed server dependency to avoid a Flow/Gateway release-order cycle.

## [0.3.9] - 2026-05-11

### Changed
- Release/install profile guidance now consistently targets canonical install profiles: `abstractflow`, `abstractflow[apple]`, `abstractflow[gpu]`.
- Runtime profile references and CLI error messages were updated across docs/code paths to remove `all-apple`, `all-gpu`, `runtime`, and `standalone` guidance.

### Fixed
- Release workflow manual dispatch now handles existing tags safely:
  - existing `vX.Y.Z` tags for the same commit are reused,
  - mismatched tag/commit state now fails with a clear remediation message.

### Added
- Release notes/packaging metadata refresh for the corrected profile taxonomy and corrected dependency/error messaging.

## [0.3.8] - 2026-05-09

### Added
- **Gateway contract strictness for run detail helpers**: AbstractFlow now requires Gateway discovery descriptors for
  `capabilities.contracts.common.runs.input_data` and `capabilities.contracts.common.runs.history_bundle` (or
  `contracts.flow_editor.runs.*`) before enabling run rehydration and run history replay in the editor UX.
  Missing helper descriptors in versioned contracts now produce explicit readiness failures instead of
  implicit path assumptions.
- **Gateway capability readiness checks**: New `gatewayClient` helpers (`getGatewayFlowEditorReadiness`,
  `endpointFromDescriptor`, `descriptorEndpointAvailable`) and the `useGatewayCapabilities` hook
  (`gatewayReadinessFromCapabilities`) for frontend capability discovery.
- **Gateway connectivity check**: New `check_gateway_connection()` and `require_gateway_connectivity()`
  functions in `gateway_options.py` for early validation of gateway reachability.
- **Lazy runtime exports**: `abstractflow.__init__.py` now uses `__getattr__` to lazily import runtime
  dependencies (Flow, FlowRunner, compile_flow, etc.), enabling a true thin-client install profile.
- **npm publish job**: Release workflow now publishes the frontend CLI (`@abstractframework/flow`) to npm
  alongside the PyPI release.

### Changed
- **Descriptor-driven endpoint usage in editor paths**: `RunFlowModal` and `Toolbar` now resolve
  run helper endpoints through descriptors and only use fallback canonical paths for legacy, non-versioned
  Gateway contracts.
- **CLI workflow bundle loading**: `abstractflow bundle` commands now lazily import `abstractruntime` to
  avoid hard dependencies on the runtime stack for thin-client users.
- **Install profile names**: Updated all documentation and CLI error messages to use canonical profiles
  (`abstractflow`, `abstractflow[apple]`, `abstractflow[gpu]`).

### Fixed
- **Gateway auth token resolution**: Simplified `resolve_gateway_token()` to use a single env var
  (`ABSTRACTGATEWAY_AUTH_TOKEN`) and removed fragile comma-split fallback.

### Notable cleanup for thin-client direction
- Documentation and install guidance now use the canonical profiles:
  - `abstractflow` (thin client)
  - `abstractflow[apple]` / `abstractflow[gpu]` (local execution + gateway-compatible host stack)

## [0.3.7] - 2026-05-06

### Added
- **Release and documentation automation**:
  - GitHub Actions now builds the MkDocs documentation site in CI and on releases.
  - Tagged releases deploy the docs site to the `gh-pages` branch after PyPI and GitHub Release publication.
  - Added a MkDocs Material documentation site configuration.
- **Centralized package version source**: `abstractflow/_version.py` is now the single source of truth for release version metadata.
- **AbstractCode UI event demo flows** (`web/flows/*.json`):
  - `acagent_message_demo.json`: `abstractcode.message`
  - `acagent_ask_demo.json`: durable ask+wait via `wait_event.prompt`
  - `acagent_tool_events_demo.json`: `abstractcode.tool_execution` + `abstractcode.tool_result`
- **Tool observability wiring improvements (Visual nodes)**:
  - `LLM Call` exposes `tool_calls` as a first-class output pin (same as `result.tool_calls`) for easier wiring into `Tool Calls` / `Emit Event`.
  - `Agent` exposes best-effort `tool_calls` / `tool_results` extracted from its scratchpad trace (post-run ergonomics).
- **Pure Utility Nodes (Runtime-backed)**:
  - `Stringify JSON` (`stringify_json`): Render JSON (or JSON-ish strings) into text with a `mode` dropdown (`none` | `beautify` | `minified`). Implementation delegates to `abstractruntime.rendering.stringify_json` for consistent host behavior.
  - `Agent Trace Report` (`agent_trace_report`): Render an agent scratchpad (`node_traces`) into a condensed Markdown timeline of LLM calls and tool actions (full tool args + results, no truncation). Implementation delegates to `abstractruntime.rendering.render_agent_trace_markdown`.

### Changed
- **Run Flow modal (array parameters)**: Array pins now render as a Blueprint-style item list (add/remove items) with a "Raw JSON (advanced)" escape hatch for non-string arrays.

### Fixed
- **FlowRunner SUBWORKFLOW auto-drive**: `FlowRunner.run()` no longer hangs if the runtime registry contains only subworkflow specs (common in unit tests). It now falls back to the runner’s own root `WorkflowSpec` when resuming/bubbling parents.
- **GitHub CI portability**: Tests and frontend build now work from a clean GitHub checkout instead of relying on local workspace-only paths.

## [0.3.4] - 2026-02-06

### Added
- **More AbstractCore “common tools” in the editor**: `skim_url` and `skim_websearch` are now included in `/api/tools` and are executable by the default host tool executor.
- **Comms tools documentation**: clarified how to opt into email/WhatsApp/Telegram tools via env flags.

## [0.3.3] - 2026-02-06

### Added
- **Historical install profile**: `abstractflow[standalone]` was the then-current profile for the Visual Editor backend.
  It is now replaced by the current split: `abstractflow` (thin client),
  `abstractflow[apple]`, and `abstractflow[gpu]`.

## [0.3.2] - 2026-02-06

### Added
- **Packaged visual editor backend** (FastAPI) as part of the then-current `abstractflow[standalone]` profile:
  - `abstractflow serve ...` CLI subcommand
  - `abstractflow-backend ...` console script (alias of `python -m backend`)

### Changed
- **Backend runtime directory defaults**:
  - source checkout: `web/runtime/`
  - installed package: `~/.abstractflow/runtime`
  - override: `ABSTRACTFLOW_RUNTIME_DIR`
- **Backend flow storage can be overridden** via `ABSTRACTFLOW_FLOWS_DIR` (default remains `./flows`).
- **Default publish directory** is now `./flows/bundles/` (override via `ABSTRACTFLOW_PUBLISH_DIR`).

### Fixed
- **`npx @abstractframework/flow` UI server now proxies `/api/*`** (HTTP + WebSocket) to the backend, preventing “Save failed: JSON.parse …” when the backend is running.

## [0.3.1] - 2026-02-04

### Added
- **User-facing documentation set** for public release:
  - Core docs: `README.md`, `docs/getting-started.md`, `docs/architecture.md`, `docs/api.md`, `docs/faq.md`
  - Repo policies: `CONTRIBUTING.md`, `SECURITY.md`, `ACKNOWLEDMENTS.md`
  - Agentic index: `llms.txt`, `llms-full.txt`

### Changed
- **Documentation accuracy + structure**: refreshed docs to match the implemented code (VisualFlow portability, runtime wiring, CLI bundle tooling, web editor layout) and improved cross-references for first-time users.

## [0.3.0] - 2025-01-06

### Added
- **VisualFlow Interface System** (`abstractflow/visual/interfaces.py`): Declarative workflow interface markers for portable host validation, enabling workflows to be run as specialized capabilities with known IO contracts
  - `abstractcode.agent.v1` interface: Host-configurable prompt → response contract for running a workflow as an AbstractCode agent
  - Interface validation with required/recommended pin specifications (provider/model/tools/prompt/response)
  - Auto-scaffolding support: enabling `abstractcode.agent.v1` auto-creates `On Flow Start` / `On Flow End` nodes with required pins
- **Structured Output Support**: Visual `LLM Call` and `Agent` nodes accept optional `response_schema` input pin (JSON Schema object) for schema-conformant responses
  - New literal node `JSON Schema` (`json_schema`) to author schema objects
  - New `JsonSchemaNodeEditor` UI component for authoring schemas in the visual editor
  - Pin-driven schema overrides node config and enables durable structured-output enforcement via AbstractRuntime `LLM_CALL`
- **Tool Calling Infrastructure**:
  - Visual `LLM Call` nodes support optional **tool calling** via `tools` allowlist input (pin or node config)
  - Expose structured `result` output object (normalized LLM response including `tool_calls`, `usage`, `trace_id`)
  - Inline tools dropdown in node UI (when `tools` pin not connected)
  - Visual `Tool Calls` node (`tool_calls`) to execute tool call requests via AbstractRuntime `EffectType.TOOL_CALLS`
  - New pure node `Tools Allowlist` (`tools_allowlist`) with inline multi-select for workflow-scope tool lists
  - Dedicated `tools` pin type (specialized `string[]`) for `On Flow Start` parameters
- **Control Flow & Loop Enhancements**:
  - New control node `For` (`for`) for numeric loops with `start`/`end`/`step` inputs and `i`/`index` outputs
  - `While` node now exposes `index` output pin (0-based iteration count) and `item:any` output pin for parity with `ForEach`
  - `Loop` (Foreach) now invalidates cached pure-node outputs per-iteration (fixes scratchpad accumulation)
- **Workflow Variables**:
  - New pure node `Variable` (`var_decl`) to declare workflow-scope persistent variables with explicit types
  - New pure node `Bool Variable` (`bool_var`) for boolean variables with typed outputs
  - New execution node `Set Variables` (`set_vars`) to update multiple variables in a single step
  - New execution node `Set Variable Property` (`set_var_property`) to update nested object properties
  - `Get Variable` (`get_var`) reads from durable `run.vars` by dotted path
  - `Set Variable` (`set_var`) updates `run.vars` with pass-through execution semantics
- **Custom Events** (Blueprint-style):
  - `On Event` listeners compiled into dedicated durable subworkflows (auto-started, session-scoped)
  - `Emit Event` node dispatches durable events via AbstractRuntime
- **Run History & Observability**:
  - New web API endpoints: `/api/runs`, `/api/runs/{run_id}/history`, `/api/runs/{run_id}/artifacts/{artifact_id}`
  - UI "Run History" picker (🕘) to open past runs and apply pause/resume/cancel controls
  - Run modal shows clickable **run id** pill (hover → copy to clipboard)
  - Run modal header token badge reflects cumulative LLM usage across entire run tree
  - WebSocket events include JSON-safe ISO timestamp (`ts`)
  - Runtime node trace entries streamed incrementally over WebSocket (`trace_update`)
  - Agent details panel renders live sub-run trace with expandable prompts/responses/errors
- **Pure Utility Nodes**:
  - `Parse JSON` (`parse_json`) to convert JSON/JSON-ish strings into objects
  - `coalesce` (first non-null selection by pin order)
  - `string_template` (render `{{path.to.value}}` with filters: json, join, trim)
  - `array_length`, `array_append`, `array_dedup`
  - `Compare` (`compare`) now has `op` input pin supporting `==`, `>=`, `>`, `<=`, `<`
  - `get` (Get Property) supports `default` input and safer nested path handling (e.g. `a[0].b`)
- **Memory Node Enhancements**:
  - `Memorize` (`memory_note`) adds optional `location` input
  - `Memorize` supports **Keep in context** toggle to rehydrate notes into `context.messages`
  - `Recall` (`memory_query`) adds `tags_mode` (all/any), `usernames`, `locations` inputs
- **Subflow Enhancements**:
  - `Subflow` supports **Inherit context** toggle to seed child run's `context.messages` from parent
  - `multi_agent_state_machine` accepts `workspace_root` parameter to scope agent file/system tools
- **Visual Execution Defaults**:
  - Default **LLM HTTP timeout** (7200s, overrideable via `ABSTRACTFLOW_LLM_TIMEOUT_S`)
  - Default **max output token cap** (4096, overrideable via `ABSTRACTFLOW_LLM_MAX_OUTPUT_TOKENS`)
- **UI/UX Improvements**:
  - Run preflight validation panel with itemized "Fix before running" checklist
  - Node tooltips available in palette and on-canvas (hover > 1s)
  - Node palette exposed transforms (`trim`, `substring`, `format`) and math ops (`modulo`, `power`)
  - Enhanced `PropertiesPanel` with structured output configuration
  - Improved `RunFlowModal` with better input validation and error display
  - JSON validation and error handling across executor and frontend (`web/frontend/src/utils/validation.ts`)

### Changed
- **Workflow-Agent Interface UX**: Enabling `abstractcode.agent.v1` auto-scaffolds `On Flow Start` / `On Flow End` pins (provider/model/tools)
- **Memory Nodes UX**: `memory_note` labeled **Memorize** (was Remember) to align with AbstractCode `/memorize`
- **Flow Library Modal**: Flow name/description edited via inline pencil icons (removed Rename/Edit Description buttons)
- **Run Modal UX**:
  - String inputs default to 3-line textarea
  - Modal actions pinned in footer (body scrolls)
  - No truncation of sub-run/memory previews (full content on demand)
  - JSON panels (`Raw JSON`, `Trace JSON`, `Scratchpad`) syntax-highlighted
- **Node Palette Organization**:
  - Removed **Effects** category
  - Added **Memory** category (memories + file IO)
  - Added **Math** category (after Variables)
  - Moved **Delay** to **Events**
  - Split into **Literals**, **Variables**, **Data** (renamed from "Data" to **Transforms**)
  - Reordered **Control** nodes (loops → branching → conditions)
  - `System Date/Time` moved to **Events**
  - `Provider Catalog` + `Models Catalog` moved to **Literals**
  - `Tool Calls` moved from **Effects** to **Core** (reordered: Subflow, Agent, LLM Call, Tool Calls, Ask User, Answer User)
- **Models Catalog**: Removed deprecated `allowed_models` input pin (in-node multi-select synced with right panel)
- **Node/Pin Tooltips**: Appear after 2s hover, rendered in overlay layer (no clipping)
- **Python Code Nodes**: Include in-node **Edit Code** button; editor injects "Available variables" comment block
- **Execution Highlighting**: Stronger, more diffuse bloom for readability during runs; afterglow decays smoothly (3s), highlights only taken edges
- **Data Edges**: Colored by data type (based on source pin type)

### Fixed
- **Recursive Subflows**: Visual data-edge cache (`flow._node_outputs`) now isolated per `run_id` to prevent stale outputs leaking across nested runs (fixes self/mutual recursion with pure nodes like `compare`, `subtract`)
- **Durable Persistence**: `on_flow_start` no longer leaks internal `_temp` into cached node outputs (prevented `RecursionError: maximum recursion depth exceeded`)
- **WebSocket Run Controls**: Pause/resume/cancel no longer block on per-connection execution lock (responsive during long-running LLM/Agent nodes)
- **WebSocket Resilience**:
  - Controls resilient to transient disconnects (can send with explicit `run_id`, UI reconnects-and-sends)
  - Execution resilient to UI disconnects (dropped connection doesn't cancel in-flight run)
- **VisualFlow Execution**: Ignores unreachable/disconnected execution nodes (orphan `llm_call`/`subflow` can't fail initialization)
- **Loop Nodes**:
  - `Split` avoids spurious empty trailing items (e.g. `"A@@B@@"`) so `Loop` doesn't execute extra empty iteration
  - Scheduler-node outputs in WebSocket `node_complete`: Loop/While/For sync persisted `{index,...}` outputs to `flow._node_outputs` (UI no longer shows stale index)
- **Pure Node Behavior**:
  - `Concat` infers stable pin order (a..z) when template metadata missing
  - `Set Variable` defaulting for typed primitives: `boolean/number/string` pins default to `false/0/""` instead of `None`
- **Agent Nodes**: Reset per-node state when re-entered (e.g. inside `Loop` iterations) so each iteration re-resolves inputs
- **Run Modal Observability**:
  - WebSocket `node_start`/`node_complete` events include `runId` (distinguish root vs child runs)
  - Visual Agent nodes start ReAct subworkflow in **async+wait** mode for incremental ticking
  - Run history replay synthesizes missing `node_complete` events for steps left open in durable ledger
- **Canvas Highlighting**: Robust to fast child-run emissions (race with `node_start` before `runId` state update fixed)
- **WebSocket Subworkflow Waits**: Correctly close waiting node when run resumes past `WAITING(reason=SUBWORKFLOW)`
- **Web Run History**: Reliably shows persisted runs regardless of server working directory (backend defaults to `web/runtime` unless `ABSTRACTFLOW_RUNTIME_DIR` set)
- **Cancel Run**: No longer surfaces as `flow_error` from `asyncio.CancelledError` (treated as expected control-plane operation)
- **Markdown Code Blocks**: "Copy" now copies original raw code (preserves newlines/indentation) after syntax highlighting

### Technical Details
- **13 commits**, **48 files changed**: 12,142 insertions, 368 deletions
- New module: `abstractflow/visual/interfaces.py` (347 lines)
- New UI component: `web/frontend/src/components/JsonSchemaNodeEditor.tsx` (460 lines)
- New tests: `test_visual_interfaces.py`, `test_visual_agent_structured_output_pin.py`, `test_visual_llm_call_structured_output_pin.py`, `test_visual_subflow_recursion.py`
- Compiler enhancements: Interface validation, per-run cache isolation, structured output pin support
- Executor optimizations: Performance improvements for VisualFlow execution
- 12 new example workflow JSON files in `web/flows/`

### Notes
- This repository includes the published Python package (`abstractflow/`) and a reference visual editor app (`web/`).

## [0.1.0] - 2025-01-15

### Added
- Initial placeholder package to reserve PyPI name
- Basic project structure and packaging configuration
- Comprehensive README with project vision and roadmap
- MIT license and contribution guidelines
- CLI placeholder with planned command structure

### Notes
- This is a placeholder release to secure the `abstractflow` name on PyPI
- No functional code is included in this version
- Follow the GitHub repository for development updates and release timeline

## CONTRIBUTING.md

# Contributing

Thanks for contributing to AbstractFlow.

## Development Setup

Requirements:

- Node.js 18+
- npm
- a reachable AbstractGateway for integration testing

```bash
npm install
npm run dev
```

Run quality checks:

```bash
npm run build
npm run lint
```

## Repository Shape

- `src/`: React/Vite editor.
- `bin/cli.js`: static server and Gateway proxy.
- `examples/flows/`: sample VisualFlow JSON files.
- `docs/`: user and contributor docs.

Do not add local Python execution/server code to this repository. Runtime execution belongs to AbstractGateway and AbstractRuntime.

## Docs

After doc changes:

```bash
npm run docs:llms
```

## Releases

Release version source of truth is `package.json`.

For a release:

1. Update `package.json`.
2. Add the matching `CHANGELOG.md` entry.
3. Run `npm run build` and `npm run lint`.
4. Publish through the GitHub release workflow to npm.

## Pull Request Checklist

- `npm run build` passes.
- `npm run lint` passes or any failures are explicitly documented.
- User-facing behavior changes are reflected in docs and changelog.

## SECURITY.md

# Security Policy

Please do not open a public GitHub issue for security-sensitive reports.

Report vulnerabilities by email:

- `contact@abstractflow.ai`

Include:

- impact and reproduction steps
- affected package version (`@abstractframework/flow`)
- browser/server deployment details
- Gateway URL topology when relevant
- logs with secrets redacted
- minimal VisualFlow JSON when relevant

## Scope

This repository covers the AbstractFlow web editor, npm CLI/static server, and Gateway proxy behavior.

Gateway authentication, provider secrets, runtime isolation, workflow execution, artifacts, and user management are owned by AbstractGateway/AbstractRuntime. Security reports for those surfaces should still be reported; they may be fixed in the owning package.

## Supported Versions

AbstractFlow is pre-1.0. Use the latest released version.