Serve mode protocol

scaiflux serve runs ScaiFlux as a long-lived process driven by an external controller (e.g. ScaiForge) over NDJSON on stdio. One process == one session. The controller speaks commands on stdin and reads events from stdout; stderr is for human-readable logs and is never multiplexed with the protocol channel.

This is the channel for programmatic orchestration. For interactive human use, drop into scaiflux repl instead.

At a glance#

1

scaiflux serve --workspace /path/to/project --model scailabs/poolnoodle-omni

The controller writes one JSON object per line on stdin, and receives one JSON object per line on stdout. Newlines inside a payload's strings are escaped — every \n byte on the wire is a record boundary.

Protocol#

The schema is the source of truth: see scaiflux/cli/protocol.py. Every message is a Pydantic v2 model with extra="forbid" — unknown fields fail on both write and read. The current protocol version is 1 (in ReadyEvent.protocol).

Inbound — controller → ScaiFlux#

Closing stdin (EOF) is equivalent to shutdown.

Outbound — ScaiFlux → controller#

stop_reason: "interrupted" distinguishes a controller-cancelled turn from a natural end_turn finish.

Permissions#

Every permission decision is proxied to the controller — the local .scaiflux.json policy is bypassed in serve mode. The controller is expected to either auto-decide based on tool args or forward to a human. On decision: "deny":

• The tool call is not executed.
• The model receives a synthetic tool-error result containing the controller-supplied reason (or "denied by remote controller").
• The turn continues — the model can adapt and try a different approach. This is the configured behavior; if you want a deny to abort the whole turn, send interrupt instead.

On controller disconnect (stdin EOF / crash), any pending permission futures are cancelled, which the prompter surfaces as deny with reason "controller disconnected before responding". The current turn finishes normally.

Slash commands#

Slash commands dispatch through the same registry as the REPL. They do not count as a turn — they return immediately with a slash_result event. Side-effects on runtime state (model swap, mode change, gadget toggle) currently land directly in the runtime but don't auto-emit state_changed yet — track via slash_result.data until that follow-on lands.

Slash output is plain text (the same string the REPL would print). Structured commands like /context populate data with a JSON object.

Versioning#

The contract is the extra="forbid" Pydantic schema plus a single integer PROTOCOL_VERSION (currently 1) advertised in the ready event. The compatibility rules:

• Patch / additive change: new optional field with a default → no version bump. Old controllers ignore the field.
• Breaking change: renamed field, removed field, changed semantics, changed required fields → bump PROTOCOL_VERSION.

Controllers should check ready.protocol and refuse versions they weren't built against.

Running it#

1
2
3
4
5
6

# Spawned by a controller process. Stdin/stdout are bound to pipes;
# stderr typically inherits from the controller's terminal or a log
# file.
scaiflux serve --workspace ./project \
               --model scailabs/poolnoodle-omni \
               --permission-mode prompt

Flags:

For sandboxing, the controller is expected to spawn scaiflux serve inside unshare / firejail / a container — there's no in-process sandbox flag.

End-to-end example#

# controller writes:
{"type":"prompt","text":"list the python files"}

# ScaiFlux replies (one line each):
{"type":"turn_started","turn_id":"abc123"}
{"type":"text_delta","turn_id":"abc123","delta":"I'll glob "}
{"type":"text_delta","turn_id":"abc123","delta":"for *.py."}
{"type":"tool_start","turn_id":"abc123","tool_id":"call_1","name":"glob_search","input":{"pattern":"**/*.py"}}
{"type":"permission_request","request_id":"r-9","tool":"glob_search","active_mode":"prompt","required_mode":"read-only","details":{"tool_input":{"pattern":"**/*.py"},"reason":null}}

# controller writes:
{"type":"permission_response","request_id":"r-9","decision":"allow"}

# ScaiFlux continues:
{"type":"tool_result","turn_id":"abc123","tool_id":"call_1","output":"a.py\nb.py\n","is_error":false,"duration_s":0.04}
{"type":"text_delta","turn_id":"abc123","delta":"Found two: a.py and b.py."}
{"type":"turn_complete","turn_id":"abc123","stop_reason":"end_turn","iterations":1,"input_tokens":820,"output_tokens":34,"mutations":[]}

# controller writes:
{"type":"shutdown"}
# ScaiFlux exits.

Limits & known gaps#

• No state_changed for slash-induced model/mode/gadget swaps yet. Inspect slash_result.data for the new state until that lands.
• No multi-session multiplexing. One process == one session by design. Spawn N processes for N parallel agents.
• No integration test bundled. Unit tests cover the schema, the writer, the prompter, and dispatch; an end-to-end test exercising scaiflux serve as a real subprocess against a mock gateway is on the follow-on list.