Feature: add a named image proxy for text-only main models

[Aaronontheweb]

Goal

Let a text-only main model use a named vision model to create a durable image description.

Netclaw must preserve the original image. A later vision-capable main model must receive the original image again.

Configuration

Add an optional named assignment:

{
  "Models": {
    "Definitions": {
      "main-text": {
        "Provider": "primary-provider",
        "ModelId": "text-model"
      },
      "vision-small": {
        "Provider": "vision-provider",
        "ModelId": "vision-model",
        "InputModalities": ["Text", "Image"],
        "OutputModalities": ["Text"]
      }
    },
    "Roles": {
      "Main": "main-text"
    },
    "Proxies": {
      "Image": "vision-small"
    }
  }
}

Models.Proxies.Image references an existing named definition.

Startup must fail when the reference is unknown. Startup must also fail when the model lacks image input or text output.

Runtime foundation

Add the smallest reusable slice of #648.

• Resolve named model definitions at runtime.
• Cache each composed client pipeline.
• Expose the effective capabilities with each client.
• Keep the current role-based API as an adapter.
• Do not add subagent model selection in this issue.

This registry can later support explicit subagent model selection.

Image proxy behavior

• Use the proxy only when the selected main model lacks image input.
• Send one image and a fixed OCR-aware description prompt.
• Do not send the complete session history.
• Do not expose tools to the proxy.
• Persist the proxy result before the main model call.
• Record the source media path, proxy definition, model ID, prompt version, and timestamp.
• Insert the derived description as untrusted user content.
• Include the session-relative image path.
• Neutralize proxy-output delimiters before prompt insertion.
• Reuse the durable result after session recovery.
• Create missing results lazily for historical images.
• Stop the turn when proxy analysis fails or returns empty text.
• Do not silently omit the image.

When the main model supports images, Netclaw sends the original image and omits the proxy description.

Operator surfaces

Support:

netclaw model set image-proxy <provider> <model-id>
netclaw model clear image-proxy
netclaw model list

Add the same optional assignment to the interactive model manager.

The model command must reuse existing named definitions and preserve their metadata.

Acceptance criteria

• A text-only main model receives a durable image description.
• The proxy runs once for each missing image analysis.
• Session recovery reuses the saved description.
• Historical images receive lazy proxy analysis.
• A later vision-capable main model receives the original image.
• Invalid proxy references fail before persistence or startup.
• Proxy failure does not call the main model.
• CLI and TUI tests cover assignment, removal, and validation.
• Native TUI smoke coverage proves the interactive path.

Non-goals

• Audio proxy support
• Video proxy support
• Image crop or follow-up analysis tools
• Full implementation of feat(providers): concurrent multi-model / multi-provider architecture for per-role and per-agent routing #648
• Subagent model selection
• Dynamic load balance

Related issues

• Degrade incompatible session history before model calls #1727 for session history compatibility
• feat(providers): concurrent multi-model / multi-provider architecture for per-role and per-agent routing #648 for named multi-model infrastructure
• Add audio and video as native model input to file_read (currently images only) #1266 for native audio and video input
• Design audio/video egress around how multimodal models ingest them (not ReadAllBytes + inline base64) #1297 for audio and video egress design