feat(text): support native multimodal message parts

.agents/skills/celeste-python/SKILL.md

@@ -0,0 +1,100 @@
+---
+name: celeste-python
+description: Use whenever writing, modifying, reviewing, or debugging code involving Celeste, celeste-ai, celeste-python, import celeste, src/celeste, or withceleste app integrations. This includes providers, modalities, models, artifacts, MIME types, parameters, tools, multimodal messages, streaming, structured outputs, protocol/base URL support, OpenSpec changes, and tests. Always use this skill before inventing Celeste types, registries, model catalogs, provider abstractions, request/response shapes, or syntax.
+compatibility: Local celeste-python repository skill; no network required.
+---
+
+# Celeste Python Coding
+
+Use this skill to stay aligned with the actual Celeste SDK in this repository.
+Celeste is evolving, so current source and tests are more reliable than model memory.
+
+## First Step
+
+Read `references/repo-map.md` before making Celeste-related code changes or review claims.
+It gives the current public API, internal layering, extension seams, templates, and canonical tests.
+
+Then read only the references relevant to the task:
+
+- App-side integration: `references/public-api.md`
+- SDK-internal provider, modality, model, parameter, protocol, streaming, or tool work: `references/sdk-architecture.md`
+- Review/debugging or suspicious Celeste code: `references/anti-patterns.md`
+- Test selection or final checks: `references/verification.md`
+
+## Source-Of-Truth Order
+
+When sources disagree, follow this order:
+
+1. Current source code in `src/celeste/`
+2. Current tests and templates for existing behavior
+3. README examples and public exports
+4. Active OpenSpec artifacts for intended new behavior and acceptance criteria
+5. Notes such as `common_agent_mistakes.md`
+6. Model memory
+
+Treat `common_agent_mistakes.md` as advisory. Verify every warning against current code and the task context.
+
+## Route The Task
+
+Classify the task before coding:
+
+- App integration: code outside the SDK consuming Celeste. Prefer public namespaces and public exports. Keep the boundary thin.
+- SDK internals: changes inside `src/celeste`, `templates`, or tests. Follow existing modality, provider, protocol, model, mapper, and streaming patterns.
+- Review/debugging: identify whether issues are app-side duplication, SDK pattern drift, unsupported model/parameter assumptions, or test gaps.
+
+## App Integration Rules
+
+Use the public API first:
+
+- `celeste.text.*`
+- `celeste.images.*`
+- `celeste.audio.*`
+- `celeste.videos.*`
+- `celeste.documents.*`
+
+Use `create_client(...)` when explicit client reuse or explicit `modality`, `operation`, `provider`, `protocol`, `base_url`, or auth configuration is needed.
+
+Do not create app-local duplicates for Celeste-owned concepts unless the user explicitly asks for a temporary compatibility layer. Import and use Celeste types for roles, providers, modalities, operations, artifacts, MIME types, tools, and model discovery.
+
+## SDK Internal Rules
+
+Do not flatten Celeste into a single invented abstraction. The SDK intentionally separates:
+
+- provider auth registration
+- modality provider maps
+- provider API mixins
+- modality-specific provider clients
+- per-modality model aggregation
+- parameter enums and `ParameterMapper`s
+- constraints and optional input type inference
+- protocol clients for compatible APIs
+
+Start from nearby existing providers/modalities and templates. Use focused tests as executable documentation.
+
+## Common Failure Modes
+
+Before adding new local code, check whether Celeste already owns the concept.
+Watch for:
+
+- raw provider, role, MIME, modality, operation, or input-type strings where Celeste exposes enums
+- app-side model allowlists where `list_models(...)` or the host app's existing Celeste discovery flow should be used
+- runtime registry patching from app code
+- provider SDK request shapes copied directly into app code
+- new parameter names without modality enums, `TypedDict` fields, model constraints, and provider mappers
+- provider registration changes that update one seam but miss auth, modality maps, model aggregation, or tests
+
+## Verification
+
+Pick focused tests from `references/verification.md` based on the seam touched.
+For broader read-only checks, use the repo commands:
+
+- `make lint`
+- `make typecheck`
+- `make test`
+
+For finalization commands that may rewrite files, use them only when mutation is intended:
+
+- `make format`
+- `make ci` (runs lint-fix and format internally)
+
+If you cannot run a relevant command, say so and explain the remaining risk.

.agents/skills/celeste-python/evals/evals.json

@@ -0,0 +1,93 @@
+{
+  "skill_name": "celeste-python",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "Integrate Celeste into an app endpoint that generates text, analyzes uploaded images, and lists available text generation models. Keep the integration thin and type-safe.",
+      "expected_output": "Uses namespace-first public APIs or create_client only where explicit reuse is needed; imports Celeste public types; uses list_models for discovery; avoids local provider/model/role/MIME registries.",
+      "files": [],
+      "expectations": [
+        "Uses celeste.text or celeste.images namespace APIs for app-side operations unless create_client is justified.",
+        "Uses list_models with Modality and Operation instead of a hard-coded app-side model catalog.",
+        "Uses Celeste artifacts, MIME enums, Message, Role, Provider, Modality, and Operation where those concepts appear.",
+        "Does not patch or mutate Celeste internals from app code."
+      ]
+    },
+    {
+      "id": 2,
+      "prompt": "Add support for a new hypothetical text provider named AcmeAI that exposes an OpenAI-compatible chat completions API. Describe or implement the files and tests needed in celeste-python.",
+      "expected_output": "Follows SDK seams: Provider enum, provider auth registration, provider API or protocol reuse, modality provider client/map, model definitions and aggregation, parameter mappers where needed, and focused tests.",
+      "files": [],
+      "expectations": [
+        "Identifies Provider enum registration in src/celeste/core.py.",
+        "Identifies provider auth registration under src/celeste/providers/acmeai/__init__.py.",
+        "Uses a concrete provider API package or the chat completions protocol seam instead of inventing a flat request stack.",
+        "Updates modality text provider registration and model aggregation.",
+        "Defines models with operations and parameter_constraints.",
+        "Selects focused tests such as test_provider_api_templates.py, test_init.py, test_models.py, and parameter/client tests as relevant."
+      ]
+    },
+    {
+      "id": 3,
+      "prompt": "Review this Celeste integration: it defines local Provider and Role enums as strings, keeps a hard-coded BACKEND_MODELS list, maps file extensions to raw MIME strings, and registers unknown models at runtime before calling Celeste. Identify what is wrong and how to fix it.",
+      "expected_output": "Flags app-side duplication and registry mutation, recommends Celeste public enums/types/model discovery/MIME enums, and scopes warnings so SDK-internal registry work is not incorrectly banned.",
+      "files": [],
+      "expectations": [
+        "Flags local Provider and Role enums as duplicates of Celeste-owned concepts.",
+        "Recommends list_models or existing host discovery instead of a hard-coded model catalog.",
+        "Recommends Celeste MIME enums and artifact types instead of raw MIME string maps where applicable.",
+        "Rejects app-side runtime model registry patching while noting SDK-internal model definitions are legitimate.",
+        "Grounds review claims in current Celeste source or skill references rather than memory alone."
+      ]
+    },
+    {
+      "id": 4,
+      "prompt": "A chat app wants to send an uploaded image and user text to a Celeste text model with native multimodal input. Show the Celeste message shape it should build.",
+      "expected_output": "Builds Message(content=[TextPart(...), ImagePart(image=ImageArtifact(...))]) or equivalent ordered MessagePart list; does not pass raw ImageArtifact in content; does not define app-local ImagePart or MessageContent types.",
+      "files": [],
+      "expectations": [
+        "Uses Celeste Message, Role, TextPart, ImagePart, and ImageArtifact.",
+        "Represents media through ordered MessagePart wrappers inside Message.content.",
+        "Does not pass raw artifacts or mixed raw lists as Message.content.",
+        "Does not create app-local duplicate multimodal message models."
+      ]
+    },
+    {
+      "id": 5,
+      "prompt": "Implement a multi-turn text conversation that sends a previous tool result back to the model. The tool result contains structured JSON.",
+      "expected_output": "Uses ToolResult as a separate message-list item with structured content in ToolResult.content; does not subclass or wrap it as Message; keeps normal Message.content narrow.",
+      "files": [],
+      "expectations": [
+        "Uses ToolResult directly in the text messages list.",
+        "Keeps structured tool payloads in ToolResult.content.",
+        "Does not treat ToolResult as a Message subclass.",
+        "Does not put structured Pydantic payloads in normal Message.content."
+      ]
+    },
+    {
+      "id": 6,
+      "prompt": "Configure Celeste to call a custom OpenAI-compatible text endpoint using base_url and protocol. Explain what modalities this supports today.",
+      "expected_output": "Uses create_client with Modality.TEXT plus protocol/base_url; states protocol-based compatible client support is currently text-only; distinguishes root protocol mixins from text modality protocol clients.",
+      "files": [],
+      "expectations": [
+        "Uses create_client with modality=Modality.TEXT and protocol/base_url.",
+        "States compatible protocol client support is currently text-only.",
+        "Does not imply protocol= works for images, audio, videos, documents, or embeddings.",
+        "Mentions text-specific protocol clients under src/celeste/modalities/text/protocols when discussing SDK internals."
+      ]
+    },
+    {
+      "id": 7,
+      "prompt": "Review a provider/template change that added extra_headers support only in one provider client file. What else should be checked?",
+      "expected_output": "Checks templates, provider API mixins, parameter mappers/constraints if public, focused tests, and streaming/telemetry preservation when relevant.",
+      "files": [],
+      "expectations": [
+        "Points to templates as source of truth for generated provider/module shape.",
+        "Checks provider API mixin and concrete modality provider seams.",
+        "Considers parameter mapper and model constraint updates if extra_headers is public configuration.",
+        "Selects focused tests from references/verification.md instead of guessing from memory.",
+        "Does not run mutating commands unless mutation is intended."
+      ]
+    }
+  ]
+}

.agents/skills/celeste-python/references/anti-patterns.md

@@ -0,0 +1,104 @@
+# Celeste Anti-Patterns
+
+Use this for reviews, debugging, and suspicious Celeste integrations.
+
+## Scope The Rule
+
+Many warnings apply differently depending on context.
+
+App-side integration:
+
+- consume Celeste public APIs
+- avoid local duplicates of Celeste concepts
+- keep wrappers thin
+- prefer `list_models(...)` and existing model discovery
+
+SDK-internal work:
+
+- may update Celeste registries and model definitions
+- must follow existing provider/modality/protocol/mapper/test patterns
+- should not be blocked by app-side "do not register models" warnings
+
+## Do Not Duplicate Celeste Concepts
+
+Avoid local copies of:
+
+- provider strings when `Provider` applies
+- role strings when `Role` applies
+- MIME strings when Celeste MIME enums apply
+- artifact shapes when `ImageArtifact`, `AudioArtifact`, `VideoArtifact`, or `DocumentArtifact` apply
+- message part shapes when `MessageContent`, `MessagePart`, `TextPart`, `ImagePart`, `AudioPart`, `VideoPart`, or `DocumentPart` apply
+- model catalogs when `list_models(...)` or existing registry flow applies
+- tool result/error wrappers when `ToolOutput` or `ToolError` applies
+
+Local types are fine for truly app-specific transport events or persistence shapes.
+
+## Do Not Bypass Message Semantics
+
+Celeste owns semantic chat message content.
+
+Avoid:
+
+- raw artifacts directly in `Message.content`
+- mixed raw lists such as `["text", ImageArtifact(...)]`
+- structured Pydantic payloads as normal `Message.content`
+- treating `ToolResult` as a `Message` subclass
+- hand-rolled provider message serializers in app code or new SDK paths
+
+Use ordered message parts for chat input. Use `ToolResult.content` for structured tool outputs.
+
+## Do Not Invent A Flat Provider Registry
+
+Celeste provider support is intentionally split:
+
+- provider auth registration
+- provider enum registration
+- provider API mixins
+- modality provider maps
+- modality-specific provider clients
+- per-modality model aggregation
+- per-provider model definitions
+- parameter mappers and constraints
+
+A new single registry that bypasses these seams is probably wrong.
+Directory presence alone is not support; every active provider must be wired through the relevant enum, auth, client, model, map, and test seams.
+
+## Do Not Copy Vendor SDK Shapes Into App Code
+
+Celeste exists to hide provider-specific request/response differences. In app code, avoid OpenAI/Anthropic/Gemini request structures unless the user explicitly asks for provider-specific fallback behavior outside Celeste.
+
+Inside the SDK, provider wire shapes belong in provider API mixins, protocol clients, provider tools, and provider parameter mappers.
+
+## Do Not Add Parameters In Only One Place
+
+New SDK parameters usually need several updates:
+
+- modality parameter enum
+- modality `TypedDict`
+- model `parameter_constraints`
+- provider or protocol mapper
+- tests
+
+If only a request-body field was added, the change is probably incomplete.
+
+## Do Not Treat Notes As Canonical
+
+`common_agent_mistakes.md` is useful but not perfect. Verify every warning against:
+
+1. current source
+2. current tests/templates
+3. public exports and README
+
+Example: app code should not patch Celeste's model registry, but SDK code may legitimately update model definitions or registry behavior.
+
+## Review Checklist
+
+Ask:
+
+- Is this app code or SDK code?
+- Is the code using public namespaces where app usage is enough?
+- Did it invent local enums or string literals for Celeste-owned concepts?
+- Did it duplicate model catalog logic?
+- Did it update every provider/modality/model/mapper seam required by the change?
+- Did it pick focused tests that match the touched seam?
+- Is a warning based on current code, or only on stale memory/notes?