iCode-TUI 0.29.1__py3-none-any.whl

chrys/service/trajectory/workflow.py

@@ -0,0 +1,148 @@
+# Copyright (c) Huawei Technologies Co., Ltd. 2026. All rights reserved.
+
+"""Session trajectory spans for a workflow run and each activation attempt.
+
+The runner supplies scheduler states, including failures entering retry waits.
+Values, prompts, source paths and diagnostic prose stay in the workflow store.
+Cancellation terminals wait for the runner's drain so child agent operations
+finish inside their node span. Recorder failures never affect execution.
+"""
+
+from __future__ import annotations
+
+import logging
+import threading
+import time
+from typing import Any
+
+from chrys.foundation.trajectory.context import TrajectoryContext
+from chrys.foundation.trajectory.envelope import EventDraft, MeasurementSource, measurement
+from chrys.foundation.trajectory.event_types import EventType, WorkflowNodeOutcome
+from chrys.foundation.trajectory.ids import new_analytics_id
+from chrys.service.workflows.scheduler import ActivationState, NodeStateChanged
+
+logger = logging.getLogger(__name__)
+
+
+class _Span:
+    """An opening owns its terminal only once the writer commits its sequence."""
+
+    def __init__(
+        self,
+        context: TrajectoryContext,
+        started_type: str,
+        finished_type: str,
+        payload: dict[str, Any],
+        *,
+        operation_id: str | None = None,
+    ) -> None:
+        self.context = context
+        self.operation_id = operation_id or new_analytics_id()
+        self._started_type = started_type
+        self._finished_type = finished_type
+        self._payload = payload
+        self._started_ns = time.monotonic_ns()
+        self._committed = False
+        self._finished = False
+        self._lock = threading.Lock()
+
+    def _draft(self, event_type: str, payload: dict[str, Any]) -> EventDraft:
+        return self.context.draft(
+            event_type,
+            operation_id=self.operation_id,
+            parent_operation_id=self.context.innermost_model_operation_id,
+            payload={**self._payload, **payload},
+            measurements={"/payload/duration_ms": measurement(MeasurementSource.MONOTONIC_CLOCK, method_version=1)}
+            if event_type == self._finished_type
+            else {},
+        )
+
+    async def started(self) -> None:
+        def commit(_sequence: int) -> dict[str, Any]:
+            with self._lock:
+                if self._finished:
+                    raise RuntimeError("Workflow span closed before its start committed")
+                self.context.finalizers.add(self.abandon)
+                self._committed = True
+            return self._payload
+
+        try:
+            await self.context.sink.emit(self._draft(self._started_type, {}), payload_factory=commit)
+        except Exception:
+            logger.debug("Trajectory workflow start emit failed", exc_info=True)
+
+    def finished(self, outcome: str) -> None:
+        with self._lock:
+            if self._finished:
+                return
+            self._finished = True
+            self.context.finalizers.discard(self.abandon)
+            if not self._committed:
+                return
+        try:
+            self.context.sink.emit_soon(
+                self._draft(
+                    self._finished_type,
+                    {"outcome": outcome, "duration_ms": max(0, (time.monotonic_ns() - self._started_ns) // 1_000_000)},
+                )
+            )
+        except Exception:
+            logger.debug("Trajectory workflow finish emit failed", exc_info=True)
+
+    def abandon(self) -> None:
+        self.finished(WorkflowNodeOutcome.ABANDONED)
+
+
+class WorkflowTrace:
+    """One run's recording state; attempts are keyed by activation and attempt, never just node name."""
+
+    def __init__(self, context: TrajectoryContext, *, run_id: str, workflow_id: str) -> None:
+        self._run = _Span(
+            context,
+            EventType.WORKFLOW_RUN_STARTED,
+            EventType.WORKFLOW_RUN_FINISHED,
+            {"workflow": workflow_id, "run_id": run_id},
+            operation_id=run_id,
+        )
+        self._nodes: dict[tuple[str, int], _Span] = {}
+        self._cancelled: set[tuple[str, int]] = set()
+
+    async def started(self) -> None:
+        await self._run.started()
+
+    async def node_state(self, decision: NodeStateChanged, *, kind: str) -> None:
+        ref, state = decision.ref, decision.state
+        key = (ref.activation_id, ref.attempt)
+        span = self._nodes.get(key)
+        if span is None:
+            span = _Span(
+                self._run.context.with_run(self._run.operation_id),
+                EventType.WORKFLOW_NODE_STARTED,
+                EventType.WORKFLOW_NODE_FINISHED,
+                {
+                    "run_id": ref.run_id,
+                    "node": ref.node_id,
+                    "activation": ref.activation_id,
+                    "attempt": ref.attempt,
+                    "kind": kind,
+                },
+            )
+            self._nodes[key] = span
+            await span.started()
+        if state is ActivationState.CANCELLED:
+            self._cancelled.add(key)
+        elif state in (ActivationState.RETRYING, ActivationState.AWAITING_RETRY, ActivationState.FAILED):
+            span.finished(WorkflowNodeOutcome.FAILED)
+        elif state is ActivationState.COMPLETED:
+            span.finished(WorkflowNodeOutcome.COMPLETED)
+        elif state is ActivationState.SKIPPED:
+            span.finished(WorkflowNodeOutcome.SKIPPED)
+
+    def node_context(self, activation: str, attempt: int) -> TrajectoryContext | None:
+        span = self._nodes.get((activation, attempt))
+        return span.context.with_run(span.operation_id) if span is not None else None
+
+    def finished(self, outcome: str) -> None:
+        for key, span in self._nodes.items():
+            span.finished(WorkflowNodeOutcome.CANCELLED if key in self._cancelled else WorkflowNodeOutcome.ABANDONED)
+        self._run.finished(outcome)

chrys/service/vision.py

@@ -0,0 +1,128 @@
+# Copyright (c) Huawei Technologies Co., Ltd. 2026. All rights reserved.
+
+"""Per-agent image capability wiring."""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from typing import Any
+
+from chrys.kernel import GROUP_ANNOTATION_KEY, Content, FunctionTool, Message
+from chrys.kernel import is_image_content as _is_image_content
+from chrys.kernel.compaction import GROUP_TOKEN_COUNT_KEY, GROUP_TOKEN_ESTIMATOR_VERSION_KEY
+from chrys.kernel.middleware import ChatContext, ChatMiddleware
+
+VIEW_IMAGE_TOOL_NAME = "view_image"
+# Persisted with history: token counts may describe the temporary text view
+# even though the stored contents still contain the original image.
+_IMAGE_STUB_TOKEN_VIEW_KEY = "_chrys_image_stub_token_view"
+
+
+def filter_image_tools(tools: Sequence[Any], *, vision_enabled: bool) -> list[Any]:
+    """Return tools with image-reading tools removed for text-only agents."""
+    if vision_enabled:
+        return list(tools)
+    return [item for item in tools if not (isinstance(item, FunctionTool) and item.name == VIEW_IMAGE_TOOL_NAME)]
+
+
+def image_stub_middleware_for_model(*, vision_enabled: bool) -> ChatMiddleware:
+    """Prepare image views and invalidate counts when their representation changes."""
+    if vision_enabled:
+        return VisionImageTokenCacheMiddleware()
+    return NonVisionImageStubMiddleware()
+
+
+def _invalidate_image_token_count(message: Message) -> None:
+    """Drop only the estimate, preserving shared exclusion and summary metadata."""
+    annotation = message.additional_properties.get(GROUP_ANNOTATION_KEY)
+    if isinstance(annotation, dict):
+        annotation = dict(annotation)
+        annotation.pop(GROUP_TOKEN_COUNT_KEY, None)
+        annotation.pop(GROUP_TOKEN_ESTIMATOR_VERSION_KEY, None)
+        message.additional_properties[GROUP_ANNOTATION_KEY] = annotation
+
+
+class VisionImageTokenCacheMiddleware(ChatMiddleware):
+    """Discard persisted placeholder estimates before sending full images."""
+
+    async def process(self, context: ChatContext, call_next: Any) -> None:
+        for message in context.messages:
+            if message.additional_properties.pop(_IMAGE_STUB_TOKEN_VIEW_KEY, False):
+                _invalidate_image_token_count(message)
+        await call_next()
+
+
+class NonVisionImageStubMiddleware(ChatMiddleware):
+    """Replace model-visible image content with text stubs for text-only models."""
+
+    async def process(self, context: ChatContext, call_next: Any) -> None:
+        replacement_messages: list[Message] = []
+        changed = False
+        for message in context.messages:
+            replacement_contents: list[Content] = []
+            message_changed = False
+            for content in message.contents:
+                replacement = _stub_content_images(content)
+                replacement_contents.append(replacement)
+                if replacement is not content:
+                    message_changed = True
+            if message_changed:
+                # The history retains the image, but this call counts its stub.
+                # Invalidate on every replacement: an earlier full-history
+                # annotation may have counted the original image in between calls.
+                _invalidate_image_token_count(message)
+                message.additional_properties[_IMAGE_STUB_TOKEN_VIEW_KEY] = True
+                refreshed = Message(
+                    message.role,
+                    replacement_contents,
+                    author_name=message.author_name,
+                    message_id=message.message_id,
+                    raw_representation=message.raw_representation,
+                )
+                # Downstream compaction flags must write through to owned history.
+                refreshed.additional_properties = message.additional_properties
+                replacement_messages.append(refreshed)
+                changed = True
+            else:
+                replacement_messages.append(message)
+        if changed:
+            context.messages = replacement_messages
+        await call_next()
+
+
+def _stub_content_images(content: Content) -> Content:
+    if content.type == "function_result" and content.items:
+        replacement_items: list[Content] = []
+        changed = False
+        for item in content.items:
+            replacement = _stub_direct_image(item)
+            replacement_items.append(replacement)
+            if replacement is not item:
+                changed = True
+        if not changed:
+            return content
+        return Content.from_function_result(
+            content.call_id or "",
+            result=replacement_items,
+            exception=content.exception,
+            annotations=content.annotations,
+            additional_properties=content.additional_properties,
+            raw_representation=content.raw_representation,
+        )
+    return _stub_direct_image(content)
+
+
+def _stub_direct_image(content: Content) -> Content:
+    if not _is_image_content(content):
+        return content
+    return Content.from_text(_image_stub_text(content), annotations=content.annotations)
+
+
+def _image_stub_text(content: Content) -> str:
+    props = content.additional_properties
+    width = props.get("width")
+    height = props.get("height")
+    media_type = content.media_type or props.get("media_type") or "image"
+    if isinstance(width, int) and isinstance(height, int) and width > 0 and height > 0:
+        return f"[image {width}x{height} {media_type} omitted: model is not vision-capable]"
+    return f"[image {media_type} omitted: model is not vision-capable]"

chrys/service/workflows/__init__.py

@@ -0,0 +1,3 @@
+# Copyright (c) Huawei Technologies Co., Ltd. 2026. All rights reserved.
+
+"""Workflow Mode service tier: SDK source, manifest graph, scheduler, wire contract, run store."""

chrys/service/workflows/admission.py

@@ -0,0 +1,151 @@
+# Copyright (c) Huawei Technologies Co., Ltd. 2026. All rights reserved.
+
+"""Manifest admission: the spec digest, and the agent/model binding every agent node needs before a run starts.
+
+Admission is deterministic and runs no user code. It validates the data-only
+manifest as a graph, then binds each agent node to the profile and model the
+run will use. The binding snapshot is what ``run.json`` and
+``WorkflowRunStarted`` carry, so the user sees exactly which agent and model
+each node runs on, and the shell opens the same objects at activation time.
+"""
+
+from __future__ import annotations
+
+import hashlib
+from collections.abc import Mapping
+from dataclasses import dataclass
+from types import MappingProxyType
+from typing import Any, Final
+
+from chrys.foundation.config.settings import Settings
+from chrys.service.llm.clients import effective_model_base_url
+from chrys.service.profiles.agents.registry import AgentProfileRegistry
+from chrys.service.profiles.agents.schema import AgentProfile
+from chrys.service.profiles.models.registry import ModelProfileRegistry
+from chrys.service.profiles.models.resolver import resolve_for_agent, resolve_selectable_profile
+from chrys.service.profiles.models.schema import ModelProfile, is_model_profile_selectable
+from chrys.service.session.sub_agent_logs import sanitize_base_url_origin
+from chrys.service.workflows.graph import KIND_AGENT, GraphSpec, ManifestError
+from chrys.service.workflows.values import canonical_json
+
+REJECT_MANIFEST_INVALID: Final = "manifest_invalid"
+REJECT_AGENT_PROFILE_MISSING: Final = "agent_profile_missing"
+REJECT_MODEL_UNRESOLVABLE: Final = "model_unresolvable"
+
+
+class AdmissionError(Exception):
+    """The manifest cannot be run against the current registries; ``code`` is the rejection reason.
+
+    ``node_id`` names the agent node that could not be bound, when one is at fault.
+    """
+
+    def __init__(self, code: str, message: str, *, node_id: str | None = None) -> None:
+        super().__init__(message)
+        self.code = code
+        self.message = message
+        self.node_id = node_id
+
+
+def spec_digest(entry_digest: str, manifest_digest: str, schema_version: int) -> str:
+    """One digest over the triple the worker reports; the ledger and every run record pin this."""
+    payload = canonical_json({"entry": entry_digest, "manifest": manifest_digest, "schema": schema_version})
+    return hashlib.sha256(payload.encode("utf-8")).hexdigest()
+
+
+@dataclass(frozen=True, slots=True)
+class AgentBinding:
+    """The profile and model an agent node runs on, plus the data-only snapshot the run records."""
+
+    node_id: str
+    agent: AgentProfile
+    model: ModelProfile | None
+    instructions_suffix: str
+
+    def snapshot(self) -> dict[str, Any]:
+        model = self.model
+        acp = self.agent.acp
+        return {
+            "node_id": self.node_id,
+            "agent": self.agent.name,
+            "agent_id": self.agent.id,
+            "agent_display_name": self.agent.display_name or self.agent.name,
+            "acp": self.agent.acp is not None,
+            "model_profile_id": model.id if model is not None else "",
+            "model_profile_name": model.name if model is not None else "",
+            "provider": model.provider if model is not None else "",
+            "api_style": model.api_style if model is not None else "",
+            "model_id": model.model_id if model is not None else acp.model_id if acp is not None else "",
+            "base_url_origin": sanitize_base_url_origin(effective_model_base_url(model)) if model is not None else "",
+            "instructions_suffix": self.instructions_suffix,
+        }
+
+
+@dataclass(frozen=True, slots=True)
+class AdmittedManifest:
+    graph: GraphSpec
+    bindings: Mapping[str, AgentBinding]
+
+    def binding(self, node_id: str) -> AgentBinding:
+        return self.bindings[node_id]
+
+    def resolved_nodes(self) -> list[dict[str, Any]]:
+        return [binding.snapshot() for binding in self.bindings.values()]
+
+
+def admit_manifest(
+    manifest: Mapping[str, Any],
+    *,
+    agent_registry: AgentProfileRegistry,
+    model_registry: ModelProfileRegistry | None,
+    settings: Settings,
+) -> AdmittedManifest:
+    """Validate the manifest as a graph and bind every agent node, in node order.
+
+    Agent nodes name a profile by selector (id, name or display name); a node
+    that names a model resolves it as a selectable profile, otherwise the
+    profile's own model binding applies exactly as it does for a sub-agent.
+    ACP profiles use their remote model id unless the node explicitly overrides
+    it with a selectable Chrys model profile; no kernel client is constructed.
+    """
+    try:
+        graph = GraphSpec.from_manifest(manifest)
+    except ManifestError as exc:
+        raise AdmissionError(REJECT_MANIFEST_INVALID, str(exc)) from exc
+    bindings: dict[str, AgentBinding] = {}
+    for node_id in graph.node_order:
+        node = graph.nodes[node_id]
+        if node.kind != KIND_AGENT:
+            continue
+        agent = node.agent
+        if agent is None:
+            raise RuntimeError("A validated agent node has no agent specification.")
+        selector = agent.profile
+        profile = agent_registry.resolve_selector(selector)
+        if profile is None:
+            raise AdmissionError(
+                REJECT_AGENT_PROFILE_MISSING,
+                f"Node {node_id!r} names agent profile {selector!r}, which is not available.",
+                node_id=node_id,
+            )
+        model_selector = agent.model
+        if profile.acp is not None and not model_selector:
+            bindings[node_id] = AgentBinding(node_id, profile, None, agent.instructions_suffix)
+            continue
+        if model_selector is not None:
+            model = resolve_selectable_profile(model_registry, model_selector)
+            if model is None:
+                raise AdmissionError(
+                    REJECT_MODEL_UNRESOLVABLE,
+                    f"Node {node_id!r} names model profile {model_selector!r}, which is not available.",
+                    node_id=node_id,
+                )
+        else:
+            model = resolve_for_agent(model_registry, settings, profile)
+            if not is_model_profile_selectable(model):
+                raise AdmissionError(
+                    REJECT_MODEL_UNRESOLVABLE,
+                    f"Node {node_id!r} has no usable model: agent profile {profile.name!r} resolves to no model.",
+                    node_id=node_id,
+                )
+        bindings[node_id] = AgentBinding(node_id, profile, model, agent.instructions_suffix)
+    return AdmittedManifest(graph, MappingProxyType(bindings))

chrys/service/workflows/artifacts.py

@@ -0,0 +1,109 @@
+# Copyright (c) Huawei Technologies Co., Ltd. 2026. All rights reserved.
+
+"""Session run listings and narrow, path-based workflow artifact readers."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from chrys.foundation.events import types as events
+from chrys.foundation.platform.files import read_owner_verified_bounded
+from chrys.service.workflows.discovery import MAX_SOURCE_BYTES
+from chrys.service.workflows.layout import SOURCE_FILE, iter_run_dirs
+from chrys.service.workflows.orphans import read_run_terminal
+from chrys.service.workflows.records import RunRecord, decode_run_event
+from chrys.service.workflows.store import (
+    NODE_RECORD_INPUT,
+    NODE_RECORD_OUTPUT,
+    RunTerminal,
+    node_stderr_path,
+    read_node_diagnostics,
+    read_node_emits,
+    read_node_value,
+    read_run_events,
+    read_run_header,
+)
+
+
+@dataclass(frozen=True, slots=True)
+class NodeRecords:
+    input: dict[str, Any] | None
+    output: dict[str, Any] | None
+    emits: list[tuple[int, str]]
+    diagnostics: dict[str, Any] | None
+    stderr_path: Path | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class WorkflowRunRecord:
+    """A header-only history entry; larger artifacts are read only when requested."""
+
+    directory: Path
+    header: dict[str, Any]
+    terminal: RunTerminal | None = None
+
+
+def read_node_records(directory: Path, activation_id: str, attempt: int, *, node_kind: str = "") -> NodeRecords:
+    stderr = node_stderr_path(directory, activation_id)
+    return NodeRecords(
+        input=read_node_value(directory, activation_id, attempt, NODE_RECORD_INPUT, node_kind=node_kind),
+        output=read_node_value(directory, activation_id, attempt, NODE_RECORD_OUTPUT, node_kind=node_kind),
+        emits=read_node_emits(directory, activation_id, attempt),
+        diagnostics=read_node_diagnostics(directory, activation_id, attempt),
+        stderr_path=stderr if stderr.is_file() else None,
+    )
+
+
+def read_node_output(
+    directory: Path, activation_id: str, attempt: int, *, node_kind: str = ""
+) -> dict[str, Any] | None:
+    """Read a result without loading its input, emit log or diagnostics."""
+    return read_node_value(directory, activation_id, attempt, NODE_RECORD_OUTPUT, node_kind=node_kind)
+
+
+def read_run_source(directory: Path) -> bytes:
+    return read_owner_verified_bounded(directory / SOURCE_FILE, max_bytes=MAX_SOURCE_BYTES)
+
+
+def session_runs(session_dir: Path) -> list[WorkflowRunRecord]:
+    """Read and order headers once when a caller needs history for multiple sources."""
+    try:
+        directories, _truncated = iter_run_dirs(session_dir)
+    except OSError:
+        return []
+    records: list[WorkflowRunRecord] = []
+    for directory in directories:
+        try:
+            header = read_run_header(directory)
+        except OSError, ValueError:
+            continue
+        try:
+            terminal = read_run_terminal(directory)
+        except OSError, ValueError:
+            terminal = None
+        records.append(WorkflowRunRecord(directory, header, terminal))
+    records.sort(key=lambda record: str(record.header.get("started_at", "")), reverse=True)
+    return records
+
+
+def latest_node_output(directory: Path, node_id: str, *, node_kind: str) -> dict[str, Any] | None:
+    """Locate one node's latest stored result without projecting a run or reading usage archives."""
+    candidates: dict[tuple[str, int], None] = {}
+    for record in read_run_events(directory).events:
+        if (
+            record.event_type not in (RunRecord.NODE_STATE, RunRecord.NODE_OUTPUT)
+            or record.payload.get("node") != node_id
+        ):
+            continue
+        event = decode_run_event(record, directory=directory)
+        if isinstance(event, events.WorkflowNodeStateChanged) or (
+            isinstance(event, events.WorkflowNodeOutput) and event.kind == events.WORKFLOW_OUTPUT_FINAL
+        ):
+            candidates[event.activation_id, event.attempt] = None
+    for activation_id, attempt in reversed(candidates):
+        output = read_node_output(directory, activation_id, attempt, node_kind=node_kind)
+        if output is not None:
+            return output
+    return None

chrys/service/workflows/asks.py

@@ -0,0 +1,130 @@
+# Copyright (c) Huawei Technologies Co., Ltd. 2026. All rights reserved.
+
+"""The main-process side of ``ctx.ask``: wire questions in, answers out, bounded summaries.
+
+The SDK (``sdk/_ask.py``) guarantees every rule :func:`questions_from_wire`
+checks, so a violation means a broken worker and ends the connection. The
+chat ask-user model carries the questions to the dialog and back; answers are
+validated by the shared :func:`validate_ask_user_answers` before they get here.
+"""
+
+from __future__ import annotations
+
+from typing import Any, cast
+
+from chrys.foundation.models.ask_user import (
+    MAX_ASK_USER_DESCRIPTION_CHARS,
+    MAX_ASK_USER_HEADER_CHARS,
+    MAX_ASK_USER_LABEL_CHARS,
+    MAX_ASK_USER_OPTIONS,
+    MAX_ASK_USER_QUESTIONS,
+    AskUserAnswer,
+    AskUserOption,
+    AskUserQuestion,
+)
+from chrys.foundation.util.unicode_scalars import find_unpaired_surrogate
+from chrys.service.workflows.protocol import ProtocolError
+
+_QUESTION_KEYS = frozenset({"question", "header", "options", "multi_select"})
+_OPTION_KEYS = frozenset({"label", "description"})
+NO_ANSWER = "(no answer)"
+
+
+def questions_from_wire(raw: object) -> tuple[AskUserQuestion, ...]:
+    """Strictly decode an ask frame's ``questions``; raises :class:`ProtocolError`."""
+    if type(raw) is not list or not 1 <= len(raw) <= MAX_ASK_USER_QUESTIONS:
+        raise ProtocolError(f"ask needs 1 to {MAX_ASK_USER_QUESTIONS} questions.")
+    return tuple(_question_from_wire(item) for item in raw)
+
+
+def _text(raw: dict[str, object], key: str, limit: int | None = None) -> str:
+    value = raw[key]
+    if type(value) is not str or find_unpaired_surrogate(value) >= 0:
+        raise ProtocolError(f"ask {key} must be valid text.")
+    if limit is not None and len(value) > limit:
+        raise ProtocolError(f"ask {key} is longer than {limit} characters.")
+    return value
+
+
+def _question_from_wire(item: object) -> AskUserQuestion:
+    if type(item) is not dict or set(item) != _QUESTION_KEYS:
+        raise ProtocolError("ask question is malformed.")
+    raw = cast("dict[str, object]", item)
+    question = _text(raw, "question")
+    if not question.strip():
+        raise ProtocolError("ask question is blank.")
+    header = _text(raw, "header", MAX_ASK_USER_HEADER_CHARS)
+    multi_select = raw["multi_select"]
+    options_raw = raw["options"]
+    if type(multi_select) is not bool:
+        raise ProtocolError("ask multi_select must be a bool.")
+    if type(options_raw) is not list or len(options_raw) > MAX_ASK_USER_OPTIONS:
+        raise ProtocolError(f"ask options must be a list of at most {MAX_ASK_USER_OPTIONS}.")
+    options = tuple(_option_from_wire(option) for option in options_raw)
+    labels = {option.label for option in options}
+    if len(labels) != len(options):
+        raise ProtocolError("ask option labels must be unique.")
+    if multi_select and not options:
+        raise ProtocolError("ask multi_select needs options.")
+    return AskUserQuestion(question=question, header=header, options=options, multi_select=multi_select)
+
+
+def _option_from_wire(item: object) -> AskUserOption:
+    if type(item) is not dict or set(item) != _OPTION_KEYS:
+        raise ProtocolError("ask option is malformed.")
+    raw = cast("dict[str, object]", item)
+    label = _text(raw, "label", MAX_ASK_USER_LABEL_CHARS)
+    # The shared answer validator strips values, so only a stripped label can come back selected.
+    if not label or label != label.strip():
+        raise ProtocolError("ask option label must be stripped and non-empty.")
+    return AskUserOption(label=label, description=_text(raw, "description", MAX_ASK_USER_DESCRIPTION_CHARS))
+
+
+def answers_to_wire(questions: tuple[AskUserQuestion, ...], answers: tuple[AskUserAnswer, ...]) -> list[dict[str, Any]]:
+    """Map validated answers to the SDK's ``{"selected", "text"}`` shape.
+
+    Values naming offered labels are the selection (option order) and the note
+    is the text; a single other value is custom text. The dialog records no
+    click provenance, so a typed label counts as selected.
+    """
+    wire: list[dict[str, Any]] = []
+    for question, answer in zip(questions, answers, strict=True):
+        labels = [option.label for option in question.options]
+        if answer.values and all(value in labels for value in answer.values):
+            chosen = set(answer.values)
+            wire.append({"selected": [label for label in labels if label in chosen], "text": answer.note})
+        elif len(answer.values) == 1 and not answer.note:
+            wire.append({"selected": [], "text": answer.values[0]})
+        elif not answer.values and not answer.note:
+            wire.append({"selected": [], "text": ""})
+        else:
+            raise ValueError("Workflow ask answers must be validated before they are mapped.")
+    return wire
+
+
+def _prefix(index: int, question: AskUserQuestion) -> str:
+    return question.header or f"Q{index + 1}"
+
+
+def _answer_text(answer: AskUserAnswer) -> str:
+    text = ", ".join(answer.values)
+    if answer.note:
+        text = f"{text} — {answer.note}"
+    return text or NO_ANSWER
+
+
+def ask_summary(questions: tuple[AskUserQuestion, ...]) -> str:
+    """English text for the run store, each of several questions under its header (the journal bounds it)."""
+    if len(questions) == 1:
+        return questions[0].question
+    return "\n".join(f"{_prefix(index, question)}: {question.question}" for index, question in enumerate(questions))
+
+
+def answer_summary(questions: tuple[AskUserQuestion, ...], answers: tuple[AskUserAnswer, ...]) -> str:
+    """English text for the run store and ``WorkflowNodeAnswered``, each of several answers under its header."""
+    if len(answers) == 1:
+        return _answer_text(answers[0])
+    return "\n".join(
+        f"{_prefix(index, question)}: {_answer_text(answer)}"
+        for index, (question, answer) in enumerate(zip(questions, answers, strict=True))
+    )

chrys/service/workflows/builtins/__init__.py

@@ -0,0 +1,12 @@
+# Copyright (c) Huawei Technologies Co., Ltd. 2026. All rights reserved.
+
+"""Workflow templates shipped with chrys.
+
+Every ``*.py`` file here is a workflow the discovery layer lists under the
+``builtin`` source kind, shadowed by a user file of the same id. Templates are
+standard-library only and run on the default interpreter: a read-only install
+location cannot depend on anything the user's machine happens to provide. A
+``<id>.manifest.json`` sibling is the template's pre-generated manifest, so
+listings show its metadata without executing the file. Templates carry no
+copyright header: users copy them as the start of their own workflows.
+"""