swactor/crates/mvp-system/specs/mvp_chat.md

MVP Chat Wrapper Fixed Specification

Status: draft target behavior for mvp-chat.

This document describes the intended public contract. Implementation details that remain in the source but were marked out of scope are not part of this fixed contract.

---

1. Purpose

mvp-chat is the user-facing process that starts the mvp-chat library runtime and attaches an interactive prompt session to it.

The wrapper is responsible for:

• accepting the approved public inputs;
• resolving provider and runtime launch configuration;
• preparing required local runtime artifacts through Cargo unless rebuilds are explicitly skipped;
• starting the library runtime and its orchestrator, prompt, and datastream leaves;
• waiting until the runtime can accept prompt requests;
• running the interactive prompt loop;
• notifying the runtime to shut down on normal exit or interruption;
• reporting errors clearly to the user.

mvp-chat is not responsible for:

• model inference quality;
• worker internals;
• node-image construction internals;
• orchestrator argument naming;
• provider API details beyond the inputs needed to request a provider-backed runtime;
• dashboard rendering;
• non-Linux behavior.

---

2. Supported Platform

This specification covers Linux only.

Linux signal handling, managed component and process-leaf lifecycle, Cargo artifact discovery, and runtime shutdown semantics are the only supported platform behavior. Non-Linux behavior is out of scope until explicitly specified.

---

3. Public Input Surface

mvp-chat accepts inputs only from the surfaces listed in this section. Commented-out or implementation-only inputs from the earlier draft are pruned from the public contract.

3.1 Process Arguments

Provider selectors:

• --process
• --docker
• --vastai

General flags:

• --config <path>
• --yes
• -y
• --pipeline-stages <count>
• --dump-logs
• --dump-logs=<path>
• --cached-model
• --cached-model=<path>
• --skip-rebuild
• --gpu
• --relay-mode <mode>
• --relay-url <url>
• --endpoint-addr-mask <mask>

Any process argument that is not one of the listed flags or a required or attached value for one of those flags is a configuration error.

--process, --docker, and --vastai are mutually exclusive. Supplying more than one provider selector is a configuration error.

If no provider selector is supplied, the provider is process.

--pipeline-stages <count> accepts a positive integer. Zero and invalid values are configuration errors.

--relay-mode <mode> accepts default or disabled.

--endpoint-addr-mask <mask> accepts full or relay-only. relay-only requires a relay URL from --relay-url, [relay].url, or [vastai].relay_url.

--dump-logs writes the consolidated log stream to the default file mvp-chat.log in the current working directory.

--dump-logs=<path> writes the same stream to <path>. The <path> value is the literal string after =, may start with -, and may be relative or absolute. Relative paths are resolved relative to the current working directory. --dump-logs= is a configuration error.

--dump-logs <path> is not accepted. Without --dump-logs, logs are not stored in a file.

--cached-model enables cached-model use and discovers a cached model from .model-cache/.

--cached-model=<path> uses <path> as the cached model file. The <path> value is the literal string after =, may start with -, and may be relative or absolute. Relative paths are resolved relative to the current working directory. --cached-model= is a configuration error.

--cached-model <path> is not accepted. Without --cached-model, cached-model use is disabled.

--skip-rebuild prevents mvp-chat from invoking Cargo builds. If a required runtime artifact is unavailable while rebuilds are skipped, preparation fails with a clear error.

3.2 Environment Variables

The public configuration environment surface is limited to secret material.

Accepted environment variable:

• VAST_API_KEY

VAST_API_KEY supplies the Vast.ai API key when the selected provider is vastai. The value is trimmed before validation; an unset, empty, or whitespace-only value is treated as missing.

No other environment variable is part of the public mvp-chat configuration contract. Normal inherited process environment, such as the environment used by Cargo or child processes, is ordinary OS execution context rather than mvp-chat configuration.

3.3 Configuration File

mvp-chat reads configuration from a TOML file.

The config path is:

• --config <path>, when supplied;
• otherwise .config/config.toml relative to the current working directory.

A supplied --config <path> is required to be a readable file and parse as TOML. The default .config/config.toml is optional and is read only when it exists as a file. If the default config file exists but cannot be read or parsed, configuration fails; if the default path is absent or not a file, built-in defaults are used.

The fixed spec accepts only active behavior fields. Unused schema fields from the earlier draft are pruned. Unknown top-level TOML tables and unknown fields inside accepted tables are configuration errors.

Accepted provider field:

• [provider].kind

[provider].kind is trimmed before validation. After trimming, accepted values are case-sensitive and exactly process, docker, or vastai.

Accepted runtime fields:

• [runtime].pipeline_stages
• [runtime].max_tokens

[runtime].max_tokens sets the maximum number of tokens requested for each prompt submission. A value of 0 implies no specified limit.

Accepted observability fields:

• [observability].dump_logs
• [observability].dump_log_path

Accepted image fields:

• [image].node
• [image].tag

[image].node names the desired worker node image.

For provider docker, [image].node may name a local or remote image.

For provider vastai, [image].node must name a remote registry image that the provider can pull.

[image].tag may provide an additional human-selected tag or alias for an image prepared by mvp-chat. It does not replace the resolved image reference used for freshness or content identity.

Accepted Vast.ai fields:

• [vastai].relay_url
• [vastai].bootstrap_command
• [vastai].gpu_name
• [vastai].min_gpu_ram_mb
• [vastai].min_down_mbps
• [vastai].min_up_mbps
• [vastai].min_reliability
• [vastai].require_verified
• [vastai].disk_gb
• [vastai].onstart
• [vastai].ssh_identity

[vastai].ssh_identity is a filesystem path to an SSH private-key identity file used for provider bootstrap access. It is configuration, not a secret-value environment variable.

3.4 Standard Input

Accepted standard input:

• interactive prompt lines;
• EOF or input disconnection;
• standard-input read error during prompt input;
• Vast.ai rental approval response when approval is required.

Prompt lines drive the prompt loop. EOF, input disconnection, and standard-input read errors during prompt input end the prompt loop cleanly and trigger normal runtime cleanup. There are no prompt text commands for exiting.

While waiting for prompt input, mvp-chat must still respond to EOF, input disconnection, standard-input read errors, SIGINT, and SIGTERM. The exact input-read mechanism is an implementation detail.

3.5 Signals

Accepted Linux signals:

• SIGINT
• SIGTERM

Both request controlled shutdown.

3.6 Filesystem Inputs

Filesystem inputs:

• current working directory;
• config file selected by Section 3.3;
• .model-cache/ when --cached-model is supplied;
• cached model file path when --cached-model=<path> is supplied;
• Cargo workspace files needed by Cargo to build or locate runtime artifacts;
• Cargo target artifacts for the orchestrator and worker;
• optional Vast.ai SSH identity file path from config;
• optional dump-log output path parent directories.

Additional filesystem inputs for image preparation:

• node image Dockerfile;
• node image build context;
• worker binary artifact included in the image;
• source files used to determine image freshness;
• local Docker image metadata.

The current working directory is the root for relative paths.

When --cached-model is supplied, mvp-chat reads the direct files in .model-cache/, filters for model files accepted by the runtime, sorts the remaining files alphabetically by filename, and selects the first file. Failure to read .model-cache/, read a direct directory entry, or stat a direct entry is a preparation error. Direct entries that can be statted but do not match the cached-model predicate are ignored. If no usable cached model is present, preparation fails with a clear error.

When --cached-model=<path> is supplied, mvp-chat validates that the path is a usable cached model file. A usable cached model path must resolve to a regular file whose extension is .gguf, matched case-insensitively. If it is missing, not a regular file, or not accepted by this predicate, preparation fails with a clear error. Accepted cached-model paths are canonicalized before being included in the runtime launch request.

3.7 Network and Runtime Inputs

Runtime inputs:

• prompt engine readiness outcome;
• prompt engine PromptEvent stream records;
• orchestrator and component progress events written to the local datastream.

Additional provider/image inputs:

• Docker daemon responses when checking local image availability;
• registry responses when checking remote image availability;
• registry responses when pushing images for remote providers.

Additional relay inputs:

• relay mode from --relay-mode, [relay].mode, or MVP_IROH_RELAY_MODE;
• relay URL from --relay-url, [relay].url, [vastai].relay_url, or relay environment fallbacks;
• endpoint address mask from --endpoint-addr-mask, [relay].endpoint_addr_mask, or MVP_IROH_ENDPOINT_ADDR_MASK.

When the endpoint address mask is relay-only, orchestrator and worker advertisements must preserve relay URLs and strip direct socket addresses before passing endpoints across provider/runtime boundaries. A missing relay URL is a configuration or startup error.

Prompt engine stream records are runtime-local prompt events:

• text delta;
• request completion;
• request fault.

Detailed progress payload schemas are not specified here. This spec only requires that mvp-chat receive enough progress information to present the user-facing progress states defined in Section 7.

3.8 Managed Component Inputs

Managed component inputs observed by mvp-chat:

• orchestrator leaf start success or failure;
• orchestrator leaf readiness result;
• orchestrator leaf fault or exit before readiness;
• prompt engine leaf readiness result;
• prompt engine leaf fault before readiness;
• failure to request or wait for managed-component shutdown.

The OS process APIs, process actors, and actor-runtime notifications used to observe these states are implementation details. The observable contract is the resulting success, failure, readiness, fault, or controlled shutdown.

---

4. Provider Selection

mvp-chat has no public runtime-profile concept. The public provider choices are:

• process
• docker
• vastai

Provider resolution order:

1. CLI provider selector.
2. TOML [provider].kind.
3. default process.

The accepted provider values are exactly:

• process
• docker
• vastai

Compatibility aliases may exist in implementation, but they are not part of the fixed public contract.

If vastai is selected, required Vast.ai configuration must be present before offer preview, approval, or launch. Missing required Vast.ai configuration is a configuration error.

---

5. Configuration Resolution

Configuration is resolved from:

• process arguments;
• TOML configuration;
• approved secret environment variables;
• fixed defaults.

Process arguments override TOML where both define the same behavior.

The only approved environment override is VAST_API_KEY for the Vast.ai API key. Other configuration must come from process arguments, TOML, fixed defaults, or filesystem discovery.

Default values:

• provider: process;
• pipeline stages: 1;
• max tokens: 0;
• dump logs: disabled;
• cached model: disabled unless --cached-model is supplied;
• rebuild: enabled unless --skip-rebuild is supplied.

Invalid values must fail before runtime preparation begins.

For provider process, no node image is required.

For provider docker, an image reference is required. It may be local or remote.

For provider vastai, an image reference is required and must be a remote registry image.

If a provider requires an image and no valid image reference is configured, configuration fails before runtime preparation.

---

6. Runtime and Image Artifact Preparation

6.1 Cargo Runtime Artifacts

mvp-chat obtains the orchestrator and worker artifacts through Cargo.

The wrapper must not infer the orchestrator or worker path by changing the file name of the current executable.

The current working directory is the artifact root and must be available. The default orchestrator artifact path is target/debug/mvp-orchestrator under that directory. The default worker artifact path is target/debug/mvp-worker-node under that directory. No fallback artifact root is defined.

Unless --skip-rebuild is supplied, mvp-chat may invoke Cargo to make required artifacts available.

Approved Cargo builds:

• cargo build --quiet -p mvp-system --bin mvp-orchestrator
• cargo build --quiet -p mvp-system --bin mvp-worker-node

When --skip-rebuild is supplied:

• mvp-chat must not invoke Cargo builds;
• required Cargo artifacts must already be available;
• missing Cargo artifacts are preparation errors.

Worker binary behavior mirrors orchestrator binary behavior: both are resolved through Cargo artifacts, both honor --skip-rebuild, and both fail clearly when required artifacts are unavailable.

6.2 Node Image Preparation

Node image preparation applies only to provider-backed runtimes:

• docker
• vastai

Provider process does not require a node image.

For provider-backed runtimes, mvp-chat performs node image resolution before launching the orchestrator. Node image resolution consumes:

• the selected provider;
• [image].node;
• optional [image].tag;
• rebuild policy from --skip-rebuild;
• the worker binary artifact selected for this run;
• the approved node-image Dockerfile and build context;
• source files and metadata used to determine image freshness;
• Docker daemon observations for local images;
• registry observations for remote images.

Node image resolution produces the resolved image reference included in the orchestrator launch request.

For provider docker, the resolved image must be runnable by the local Docker daemon. The image may be local or remote.

For provider vastai, the resolved image must be pullable by the remote provider and must include a registry/repository namespace. Local-only image names are invalid.

When rebuilds are enabled, mvp-chat must determine whether the requested image is already acceptable for the selected provider and current runtime inputs. If no acceptable image is available, mvp-chat may build, tag, push, and validate an image as required by the selected provider.

An acceptable prepared image is one that:

• is usable by the selected provider;
• was prepared from the approved node-image Dockerfile and build context;
• includes the selected worker binary artifact;
• is not stale with respect to the freshness inputs used by the image-preparation contract;
• has any configured [image].tag alias applied when applicable.

When --skip-rebuild is supplied, mvp-chat must not build, tag, or push images. It must use only existing image artifacts and fail clearly if the required image is missing, stale, unavailable, or unsuitable for the selected provider.

The exact freshness algorithm, metadata format, Docker commands, cache policy, and registry authentication mechanics are owned by the node-image preparation contract.

6.3 Cached Models and Images

Cached model selection is independent from node image preparation unless an approved image-preparation contract explicitly says otherwise.

By default, mvp-chat treats cached models as runtime inputs, not as image contents. It must not silently bake cached models into prepared images.

---

7. Progress, Logs, and Datastream

Normal runtime logs are consolidated into one mvp-chat log stream.

Without --dump-logs, the stream is not stored in a file.

With --dump-logs, the stream is written to the default file defined in Section 3.1.

With --dump-logs=<path>, the stream is written to the specified path according to the path parsing rules in Section 3.1.

mvp-chat must not create hidden startup archive files as part of the public contract.

Progress observation uses the mvp-chat local datastream endpoint, not archive-file polling.

The runtime owns one local endpoint:

• stream id: StreamId::new(NodeId::new("mvp-chat"), Lifetime(run_id));
• label: "mvp chat";
• origin: StreamOrigin::Orchestrator until a chat-specific origin exists.

Required channels:

• mvp.chat.lifecycle;
• mvp.chat.runtime;
• mvp.chat.prompt;
• mvp.chat.component.

Components write through cloned DatastreamProducer handles or through local adapters installed when a component leaf starts. The datastream task drains the local endpoint and fans frames out to subscribers. Payload schemas remain owned by the datastream/progress contract.

The user-facing progress model must eventually define visible transitions for runtime startup. Until that model is approved, this spec only fixes prompt-loop output in Section 10 and keeps non-prompt progress output deferred.

---

8. Vast.ai Behavior

When provider is not vastai, Vast.ai config and approval are not used.

When provider is vastai, required configuration must be present before any offer preview or launch.

Required Vast.ai inputs:

• API key from VAST_API_KEY;
• relay URL from config;
• node image reference from config;
• bootstrap command when required by the provider contract.

Optional Vast.ai selection inputs:

• GPU name;
• minimum GPU RAM;
• minimum downlink bandwidth;
• minimum uplink bandwidth;
• minimum reliability;
• verified-host requirement;
• disk size;
• onstart command;
• SSH identity file path.

If approval is required and --yes is not supplied, mvp-chat asks the user for approval through the terminal. Only y and yes, after trimming and case-folding, approve the rental. Any other answer declines.

If --yes or -y is supplied, approval is accepted non-interactively after required configuration is validated.

If approval is required but standard input is not interactive, mvp-chat fails unless --yes or -y is supplied.

---

9. Orchestrator Launch and Shutdown

Exact orchestrator argv is out of scope until the orchestrator launch contract is specified.

mvp-chat is responsible for handing the resolved runtime request to the orchestrator leaf through the library runtime. The production process-backed leaf owns binary resolution, ProcessSpec construction, and managed process actor startup; successor in-process leaves start the orchestrator actor group directly.

The semantic launch request must include, as applicable:

• selected provider;
• resolved node image reference for provider-backed runtimes;
• pipeline stage count;
• cached model selection result;
• dump-log configuration;
• provider-specific runtime configuration;
• datastream producer or adapter wiring required by the orchestrator leaf.

The orchestrator launch contract does not define prompt transport. Prompt work is handled by the mvp-chat prompt engine actor/task through runtime-local messages.

The resolved node image reference is the image the orchestrator must use for the provider-backed node. Exact argv or wire encoding remains owned by the orchestrator launch contract.

The wrapper starts the mvp-chat library runtime. The runtime starts the orchestrator leaf, prompt engine leaf, datastream task, swactor runtime, and control path. Production process-backed leaves are managed by process actors; mvp-chat must not directly own std::process::Child for long-lived components.

On shutdown, mvp-chat must request shutdown through the runtime control path. The shutdown mechanism for each managed component is owned by that component's leaf contract.

Shutdown must be idempotent from the user's perspective. Normal prompt exit, input EOF, startup interruption, and signal interruption must not leave the runtime running when mvp-chat can notify it.

---

10. Prompt Loop

The prompt loop accepts user prompt lines from standard input.

For each cycle, mvp-chat must:

• display a prompt marker;
• read one line of input;
• remove trailing whitespace from the input line before prompt handling, while preserving leading whitespace;
• exit cleanly for EOF, input disconnection, or standard-input read error;
• ignore prompts that are empty after whitespace trimming;
• submit non-empty prompts to the prompt engine actor/task;
• display that decoding has started;
• stream response text as PromptEvent values arrive;
• return to the prompt marker after completion or prompt fault.

Prompt requests carry:

• request id;
• prompt text;
• max token limit resolved from mvp-chat configuration;
• reply target for the PromptEvent stream.

Prompt responses are:

• PromptEvent::TextDelta;
• PromptEvent::Done;
• PromptEvent::Fault.

mvp-chat submits at most one prompt at a time to the prompt engine. It waits for a terminal Done or Fault event before submitting the next prompt. The prompt engine guarantees that response events for an active request arrive in order on the reply target.

The prompt-loop output states are:

• waiting for prompt;
• prompt submitted;
• decoding;
• streaming response;
• request completed;
• request faulted;
• prompt loop exited.

Prompt-loop user output goes to standard output unless it is an actual wrapper error. Expected model faults are prompt-loop results, not wrapper diagnostics.

A fixed transport or read timeout is not part of the contract. The implementation must remain interruptible, but this spec does not require a timeout-based mechanism.

---

11. Public Output Surface

11.1 Exit Codes

Exit code 0 means clean completion or controlled interrupted shutdown.

Exit code 1 means configuration failure, preparation failure, startup failure, prompt engine failure, managed runtime failure, or another wrapper error.

11.2 Standard Output

Standard output is for expected user-facing behavior.

Standard output includes:

• prompt marker;
• decoding marker;
• response prefix;
• response text;
• prompt-loop completion formatting;
• expected prompt fault display;
• Vast.ai approval prompt when interactive approval is required.

Non-prompt startup progress output is deferred until the progress event model is approved.

11.3 Standard Error

Standard error is for actual wrapper errors and exceptional diagnostics.

Standard error must not be used for ordinary status messages such as successful provider selection, normal build status, normal cached-model selection, or normal prompt-loop events.

Errors must be clear enough for the user to identify the failed input or failed runtime phase.

Image preparation errors must be displayed clearly when image preparation fails.

Image-preparation errors include:

• missing required image reference;
• invalid image reference;
• required rebuild skipped;
• local image unavailable;
• remote image unavailable;
• image build failure;
• image tag failure;
• image push failure.

11.4 Filesystem Outputs

Filesystem outputs are limited to:

• Cargo build artifacts when rebuilds are enabled;
• dump-log file when --dump-logs is supplied;
• local Docker image layers when image rebuilds are allowed;
• local Docker image tags or aliases when image rebuilds are allowed;
• image build cache entries when image rebuilds are allowed;
• provider/runtime artifacts owned by external contracts, if those contracts are invoked.

mvp-chat MUST NOT create unspecified filesystem outputs.

11.5 Network Outputs

Network-visible outputs:

• mvp-chat datastream endpoint for dashboard/user observers when progress observation is active.

Additional network-visible outputs when preparing remote images:

• registry manifest checks;
• image layer uploads;
• image manifest or tag pushes.

Prompt submissions are runtime-local messages to the prompt engine actor/task; they are not network-visible outputs.

11.6 Managed Runtime Outputs

Outputs to managed runtime components are limited to the approved orchestrator leaf launch and shutdown contracts, prompt engine request messages, and datastream frames.

This spec does not define exact argv names, stdin control strings, private orchestrator flags, or internal actor message encodings beyond the prompt request and event shapes in Section 10.

---

12. Error Handling

Configuration errors must be detected before runtime preparation where possible.

Preparation errors must identify the missing artifact, invalid file, failed Cargo operation, or invalid provider configuration.

Startup errors must identify the failed startup phase when progress information is available.

Unexpected prompt engine errors must identify whether request submission, event-stream closure, prompt event handling, or component fault failed.

Controlled shutdown is not an error.

Errors are displayed clearly to the user and cause nonzero exit unless the error occurs during a controlled shutdown path defined as successful by this spec.

---

13. Out of Scope

Out of scope for this document:

• path display formatting as a standalone contract;
• exact orchestrator argv;
• detailed datastream payload schemas;
• non-Linux support;
• Dockerfile contents;
• base-image implementation details;
• registry authentication UX beyond clear preparation errors;
• image optimization policy;
• image garbage-collection policy;