knods

# Knods

## Overview

Handle Knods chat turns that request new flows or edits on a visual canvas. Parse Knods polling payload messages, generate assistant text, and include `[KNODS_ACTION]...[/KNODS_ACTION]` blocks when the canvas should change.

## Workflow

1. Parse incoming payload fields.
- Treat `message` as the primary request.
- Use `history` for continuity.
- On first turn in a conversation, expect prepended context in `message` describing node types and action rules.
- Use `messageId` to map all response chunks to the correct message.

2. Choose whether to emit a canvas action block.
- Use `addNode` for single-node additions.
- Use `addFlow` for multi-node workflows or any request requiring edges.
- If the user only asks a question, respond with normal text and no action block.

3. Build strict action JSON.
- Wrap each action exactly as:
  - `[KNODS_ACTION]{"action":"addNode",...}[/KNODS_ACTION]`
  - `[KNODS_ACTION]{"action":"addFlow",...}[/KNODS_ACTION]`
- For `addFlow`, ensure every edge `source` and `target` references an existing node id.
- Always end flows with an `Output` node.
- Never connect two generator nodes directly; route through `Output` or through appropriate input/output structure.
- Use stable node IDs (for example `input_1`, `image_1`, `output_1`) so follow-up edits are easy.
- Avoid unknown keys in action JSON.

4. Stream response back to Knods.
- Send assistant text as delta chunks to `/respond` for the same `messageId`.
- Send `{"messageId":"...","done":true}` when complete.
- Keep first chunk quick to avoid timeout perception.

## Output Rules

- Return normal assistant text; do not wrap the full reply in a custom envelope.
- Include `[KNODS_ACTION]...[/KNODS_ACTION]` inline only when a canvas mutation is intended.
- Do not mention internal polling URLs/tokens in user-facing text.
- Keep action JSON valid and compact.

## Flow Design Heuristics

- Build the smallest flow that satisfies the request.
- Prefer node types listed in the fir...