zettcode 0.1.2__tar.gz → 0.1.3__tar.gz

zettcode-0.1.3/PKG-INFO

@@ -0,0 +1,142 @@
+Metadata-Version: 2.5
+Name: zettcode
+Version: 0.1.3
+Summary: A focused terminal coding agent powered by zett-agent
+Project-URL: Repository, https://github.com/Chang-LeHung/zettcode
+Project-URL: Issues, https://github.com/Chang-LeHung/zettcode/issues
+Author: Chang-LeHung
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agent,coding-agent,llm,terminal,tui
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: Microsoft :: Windows :: Windows 10
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: exceptiongroup<2,>=1.2; python_version < '3.11'
+Requires-Dist: pyperclip<2,>=1.9
+Requires-Dist: setproctitle<2,>=1.3.7; os_name == 'posix'
+Requires-Dist: tomli<3,>=2; python_version < '3.11'
+Requires-Dist: truststore<1,>=0.10
+Requires-Dist: wcwidth<1,>=0.2
+Requires-Dist: zett-agent<0.2,>=0.1.11
+Description-Content-Type: text/markdown
+
+<p align="center">
+  <img src="docs/public/logo.svg" width="88" height="88" alt="ZettCode pixel robot with a warm heart" />
+</p>
+<h1 align="center">ZettCode</h1>
+<p align="center"><strong>Your terminal. Your coding partner.</strong></p>
+<p align="center">A focused coding agent that reads your project, shows its work, and keeps you in control.</p>
+<p align="center">
+  <strong>English</strong> · <a href="README.zh-CN.md">简体中文</a><br />
+  <a href="https://chang-lehung.github.io/zettcode/guide/getting-started">Get started</a> ·
+  <a href="https://chang-lehung.github.io/zettcode/">Documentation</a> ·
+  <a href="https://chang-lehung.github.io/zettcode/guide/commands">Commands</a>
+</p>
+
+<p align="center">
+  <img src="docs/public/terminal.svg" width="1000" alt="ZettCode showing a task, thinking, file reads, a code edit, passing tests, and a Markdown answer" />
+</p>
+<p align="center"><sub>Illustrative conversation, rendered with ZettCode’s actual terminal widgets.</sub></p>
+
+## Get running
+
+You need **Python 3.10+**, a UTF-8 terminal, and an **OpenAI-compatible API**.
+Works on macOS, Linux, and Windows (use Windows Terminal).
+
+### 1. Install
+
+```bash
+uv tool install zettcode
+# or: pip install zettcode
+```
+
+### 2. Connect a model
+
+Create `~/.zettcode/config.toml` (and its parent directory) with one model:
+
+```toml
+[[models]]
+model = "deepseek-v4-pro"             # the model id sent to DeepSeek
+display_model = "DeepSeek Pro"        # the name shown in ZettCode
+token = "sk-..."                      # replace with your DeepSeek API key
+base_url = "https://api.deepseek.com"  # DeepSeek's OpenAI-compatible API root
+context_window = 1000000               # verify against the endpoint's current limits
+multimodal = false                    # this model accepts text, not images
+```
+
+Get a key from the [DeepSeek platform](https://platform.deepseek.com/), not from
+the chat website. Alternatively, omit `token` and set `OPENAI_API_KEY` to that
+key. Add more `[[models]]` entries to switch with `/model`; the first is selected
+at startup. See the
+[configuration reference](https://chang-lehung.github.io/zettcode/guide/config)
+for complete examples, defaults, and troubleshooting.
+
+### 3. Start a task
+
+```bash
+cd /path/to/project
+zettcode
+# or: zettcode --workspace /path/to/project
+```
+
+Describe a change and press **Enter**. Type `/` for commands, `@` to reference a
+skill, and **Ctrl-C** to stop a request. **Ctrl-D** with an empty composer exits
+and prints the command to resume your session.
+
+## Built for the way you work
+
+| | |
+| --- | --- |
+| **See every step** | Reasoning, answers, and tool calls stream as readable rows — not raw JSON. |
+| **Keep the decision** | Review shell commands before they run. When the agent needs your input, choose an option or type an answer. |
+| **Keep moving** | Send a steering message during a reply. Use `/btw` for a side question that stays out of later context. |
+| **Come back later** | `/resume` restores a conversation; `/export` saves a readable HTML record. |
+| **Understand the context** | Monitor token usage and caching, inspect `/context`, and compact when needed. |
+| **Bring your tools** | Use project `AGENTS.md` instructions, skills, MCP servers, and Python plugins. |
+
+The palette follows your terminal’s background, or your own `theme.toml`.
+Select and copy text, scroll through answers, and paste images when your model
+supports them.
+
+## Find your next step
+
+The **[user guide](https://chang-lehung.github.io/zettcode/guide/overview)** is
+available in English and [简体中文](https://chang-lehung.github.io/zettcode/zh/guide/overview).
+
+| First time | Everyday use | Configuration & extensions |
+| --- | --- | --- |
+| [Getting started](https://chang-lehung.github.io/zettcode/guide/getting-started) | [Keys & mouse](https://chang-lehung.github.io/zettcode/guide/keys) | [Configuration](https://chang-lehung.github.io/zettcode/guide/config) |
+| [The interface](https://chang-lehung.github.io/zettcode/guide/interface) | [Commands](https://chang-lehung.github.io/zettcode/guide/commands) | [Models & context](https://chang-lehung.github.io/zettcode/guide/models) |
+| [Problems & questions](https://chang-lehung.github.io/zettcode/guide/faq) | [Sessions](https://chang-lehung.github.io/zettcode/guide/sessions) | [Project instructions](https://chang-lehung.github.io/zettcode/guide/instructions) |
+| | | [Skills & MCP](https://chang-lehung.github.io/zettcode/guide/skills-and-mcp) · [Plugins](https://chang-lehung.github.io/zettcode/guide/plugins) |
+
+## Development
+
+```bash
+uv sync                         # install dependencies
+make check                      # Ruff, mypy, and tests
+make hooks                      # enforce mypy before commits
+make demo                       # browse terminal widgets
+make docs                       # preview the user guide locally
+uv run zettcode --workspace .    # run from the checkout
+```
+
+ZettCode provides the terminal application; the agent runtime is
+[`zett-agent`](https://github.com/Chang-LeHung/zett-agent). Contributor notes and
+invariants live in [`AGENTS.md`](AGENTS.md) and
+[`docs/internal/`](docs/internal/), separately from the user guide. See
+[`docs/internal/site-design.md`](docs/internal/site-design.md) for preview and
+asset-generation instructions.
+
+## License
+
+MIT. See [`LICENSE`](LICENSE).

zettcode-0.1.3/README.md

@@ -0,0 +1,111 @@
+<p align="center">
+  <img src="docs/public/logo.svg" width="88" height="88" alt="ZettCode pixel robot with a warm heart" />
+</p>
+<h1 align="center">ZettCode</h1>
+<p align="center"><strong>Your terminal. Your coding partner.</strong></p>
+<p align="center">A focused coding agent that reads your project, shows its work, and keeps you in control.</p>
+<p align="center">
+  <strong>English</strong> · <a href="README.zh-CN.md">简体中文</a><br />
+  <a href="https://chang-lehung.github.io/zettcode/guide/getting-started">Get started</a> ·
+  <a href="https://chang-lehung.github.io/zettcode/">Documentation</a> ·
+  <a href="https://chang-lehung.github.io/zettcode/guide/commands">Commands</a>
+</p>
+
+<p align="center">
+  <img src="docs/public/terminal.svg" width="1000" alt="ZettCode showing a task, thinking, file reads, a code edit, passing tests, and a Markdown answer" />
+</p>
+<p align="center"><sub>Illustrative conversation, rendered with ZettCode’s actual terminal widgets.</sub></p>
+
+## Get running
+
+You need **Python 3.10+**, a UTF-8 terminal, and an **OpenAI-compatible API**.
+Works on macOS, Linux, and Windows (use Windows Terminal).
+
+### 1. Install
+
+```bash
+uv tool install zettcode
+# or: pip install zettcode
+```
+
+### 2. Connect a model
+
+Create `~/.zettcode/config.toml` (and its parent directory) with one model:
+
+```toml
+[[models]]
+model = "deepseek-v4-pro"             # the model id sent to DeepSeek
+display_model = "DeepSeek Pro"        # the name shown in ZettCode
+token = "sk-..."                      # replace with your DeepSeek API key
+base_url = "https://api.deepseek.com"  # DeepSeek's OpenAI-compatible API root
+context_window = 1000000               # verify against the endpoint's current limits
+multimodal = false                    # this model accepts text, not images
+```
+
+Get a key from the [DeepSeek platform](https://platform.deepseek.com/), not from
+the chat website. Alternatively, omit `token` and set `OPENAI_API_KEY` to that
+key. Add more `[[models]]` entries to switch with `/model`; the first is selected
+at startup. See the
+[configuration reference](https://chang-lehung.github.io/zettcode/guide/config)
+for complete examples, defaults, and troubleshooting.
+
+### 3. Start a task
+
+```bash
+cd /path/to/project
+zettcode
+# or: zettcode --workspace /path/to/project
+```
+
+Describe a change and press **Enter**. Type `/` for commands, `@` to reference a
+skill, and **Ctrl-C** to stop a request. **Ctrl-D** with an empty composer exits
+and prints the command to resume your session.
+
+## Built for the way you work
+
+| | |
+| --- | --- |
+| **See every step** | Reasoning, answers, and tool calls stream as readable rows — not raw JSON. |
+| **Keep the decision** | Review shell commands before they run. When the agent needs your input, choose an option or type an answer. |
+| **Keep moving** | Send a steering message during a reply. Use `/btw` for a side question that stays out of later context. |
+| **Come back later** | `/resume` restores a conversation; `/export` saves a readable HTML record. |
+| **Understand the context** | Monitor token usage and caching, inspect `/context`, and compact when needed. |
+| **Bring your tools** | Use project `AGENTS.md` instructions, skills, MCP servers, and Python plugins. |
+
+The palette follows your terminal’s background, or your own `theme.toml`.
+Select and copy text, scroll through answers, and paste images when your model
+supports them.
+
+## Find your next step
+
+The **[user guide](https://chang-lehung.github.io/zettcode/guide/overview)** is
+available in English and [简体中文](https://chang-lehung.github.io/zettcode/zh/guide/overview).
+
+| First time | Everyday use | Configuration & extensions |
+| --- | --- | --- |
+| [Getting started](https://chang-lehung.github.io/zettcode/guide/getting-started) | [Keys & mouse](https://chang-lehung.github.io/zettcode/guide/keys) | [Configuration](https://chang-lehung.github.io/zettcode/guide/config) |
+| [The interface](https://chang-lehung.github.io/zettcode/guide/interface) | [Commands](https://chang-lehung.github.io/zettcode/guide/commands) | [Models & context](https://chang-lehung.github.io/zettcode/guide/models) |
+| [Problems & questions](https://chang-lehung.github.io/zettcode/guide/faq) | [Sessions](https://chang-lehung.github.io/zettcode/guide/sessions) | [Project instructions](https://chang-lehung.github.io/zettcode/guide/instructions) |
+| | | [Skills & MCP](https://chang-lehung.github.io/zettcode/guide/skills-and-mcp) · [Plugins](https://chang-lehung.github.io/zettcode/guide/plugins) |
+
+## Development
+
+```bash
+uv sync                         # install dependencies
+make check                      # Ruff, mypy, and tests
+make hooks                      # enforce mypy before commits
+make demo                       # browse terminal widgets
+make docs                       # preview the user guide locally
+uv run zettcode --workspace .    # run from the checkout
+```
+
+ZettCode provides the terminal application; the agent runtime is
+[`zett-agent`](https://github.com/Chang-LeHung/zett-agent). Contributor notes and
+invariants live in [`AGENTS.md`](AGENTS.md) and
+[`docs/internal/`](docs/internal/), separately from the user guide. See
+[`docs/internal/site-design.md`](docs/internal/site-design.md) for preview and
+asset-generation instructions.
+
+## License
+
+MIT. See [`LICENSE`](LICENSE).

zettcode-0.1.3/README.zh-CN.md

@@ -0,0 +1,106 @@
+<p align="center">
+  <img src="docs/public/logo.svg" width="88" height="88" alt="ZettCode 像素机器人，中间是一颗暖色的心" />
+</p>
+<h1 align="center">ZettCode</h1>
+<p align="center"><strong>你的终端。你的编码伙伴。</strong></p>
+<p align="center">专注的编码智能体：读懂项目、展示过程，把决定权留给你。</p>
+<p align="center">
+  <a href="README.md">English</a> · <strong>简体中文</strong><br />
+  <a href="https://chang-lehung.github.io/zettcode/zh/guide/getting-started">快速开始</a> ·
+  <a href="https://chang-lehung.github.io/zettcode/zh/">使用文档</a> ·
+  <a href="https://chang-lehung.github.io/zettcode/zh/guide/commands">命令参考</a>
+</p>
+
+<p align="center">
+  <img src="docs/public/terminal.svg" width="1000" alt="ZettCode 依次展示任务、思考、读文件、改代码、通过的测试和 Markdown 回答" />
+</p>
+<p align="center"><sub>示例对话由 ZettCode 的实际终端组件渲染。</sub></p>
+
+## 先跑起来
+
+需要 **Python 3.10+**、支持 UTF-8 的终端和 **OpenAI 兼容接口**。
+支持 macOS、Linux 和 Windows（请使用 Windows Terminal）。
+
+### 1. 安装
+
+```bash
+uv tool install zettcode
+# 或者：pip install zettcode
+```
+
+### 2. 连接模型
+
+创建 `~/.zettcode/config.toml`（以及父目录），先配置一个模型：
+
+```toml
+[[models]]
+model = "deepseek-v4-pro"             # 发给 DeepSeek 的模型 id
+display_model = "DeepSeek Pro"        # ZettCode 界面中显示的名字
+token = "sk-..."                      # 替换成你的 DeepSeek API key
+base_url = "https://api.deepseek.com"  # DeepSeek 的 OpenAI 兼容接口根地址
+context_window = 1000000               # 以接入点当前公布的实际限制为准
+multimodal = false                    # 这个模型接受文本，不接受图片
+```
+
+在 [DeepSeek 开放平台](https://platform.deepseek.com/)创建 API key，不是聊天网页的登录信息。
+也可以省略 `token`，改用 `OPENAI_API_KEY` 环境变量保存这个 key。
+添加更多 `[[models]]`，就能用 `/model` 切换；启动时默认选择第一项。
+完整示例、默认值和排错步骤见[配置参考](https://chang-lehung.github.io/zettcode/zh/guide/config)。
+
+### 3. 发出任务
+
+```bash
+cd /path/to/project
+zettcode
+# 或者：zettcode --workspace /path/to/project
+```
+
+描述要改什么，按 **Enter**。`/` 打开命令菜单，`@` 引用 skill，**Ctrl-C** 停止请求。
+输入框为空时按 **Ctrl-D** 退出，终端会打印恢复当前会话的命令。
+
+## 按你的方式工作
+
+| | |
+| --- | --- |
+| **看清每一步** | 思考、回答和工具调用实时呈现为可读的行，不是原始 JSON。 |
+| **决定权在你手上** | 执行 shell 命令前先审阅；智能体需要你的决定时，可以选选项，也可以打字回答。 |
+| **工作不中断** | 回复过程中发送 steering（引导）消息；用 `/btw` 问一句，不让它进入后续上下文。 |
+| **随时接着做** | `/resume` 恢复对话，`/export` 导出便于阅读的 HTML。 |
+| **看懂上下文** | 查看 token 与缓存统计，用 `/context` 检查占用，在需要时压缩。 |
+| **接入你的工具** | 使用项目 `AGENTS.md` 指令、skills、MCP 服务器和 Python 插件。 |
+
+主题跟随终端背景，也可以使用你自己的 `theme.toml`。
+选中复制文字、滚动查看回答；模型支持多模态时，还能粘贴图片。
+
+## 找到你的下一步
+
+**[用户指南](https://chang-lehung.github.io/zettcode/zh/guide/overview)** 提供简体中文与
+[English](https://chang-lehung.github.io/zettcode/guide/overview) 两个版本。
+
+| 第一次使用 | 日常使用 | 配置与扩展 |
+| --- | --- | --- |
+| [快速开始](https://chang-lehung.github.io/zettcode/zh/guide/getting-started) | [快捷键与鼠标](https://chang-lehung.github.io/zettcode/zh/guide/keys) | [配置参考](https://chang-lehung.github.io/zettcode/zh/guide/config) |
+| [认识界面](https://chang-lehung.github.io/zettcode/zh/guide/interface) | [命令参考](https://chang-lehung.github.io/zettcode/zh/guide/commands) | [模型与上下文](https://chang-lehung.github.io/zettcode/zh/guide/models) |
+| [常见问题](https://chang-lehung.github.io/zettcode/zh/guide/faq) | [会话管理](https://chang-lehung.github.io/zettcode/zh/guide/sessions) | [项目指令](https://chang-lehung.github.io/zettcode/zh/guide/instructions) |
+| | | [Skills 与 MCP](https://chang-lehung.github.io/zettcode/zh/guide/skills-and-mcp) · [插件](https://chang-lehung.github.io/zettcode/zh/guide/plugins) |
+
+## 开发
+
+```bash
+uv sync                         # 安装依赖
+make check                      # Ruff、mypy 与测试
+make hooks                      # 每次提交前强制检查 mypy
+make demo                       # 浏览终端组件
+make docs                       # 本地预览使用文档
+uv run zettcode --workspace .    # 从源码运行
+```
+
+ZettCode 提供终端应用，智能体运行时来自
+[`zett-agent`](https://github.com/Chang-LeHung/zett-agent)。贡献者约定和不变量放在
+[`AGENTS.md`](AGENTS.md) 与 [`docs/internal/`](docs/internal/)，不进入用户指南。
+本地预览、重新生成效果图的方法见
+[`docs/internal/site-design.md`](docs/internal/site-design.md)。
+
+## 许可证
+
+MIT，见 [`LICENSE`](LICENSE)。

{zettcode-0.1.2 → zettcode-0.1.3}/pyproject.toml

@@ -25,9 +25,18 @@ dependencies = [
   # The stdlib gained both of these in 3.11; older runtimes take the backports.
   "exceptiongroup>=1.2,<2; python_version < '3.11'",
   "pyperclip>=1.9,<2",
+  "setproctitle>=1.3.7,<2; os_name == 'posix'",
   "tomli>=2,<3; python_version < '3.11'",
+  # The system trust store, so the release check works behind a proxy.
+  "truststore>=0.10,<1",
   "wcwidth>=0.2,<1",
-  "zett-agent==0.1.10",
+  # A range, not a pin: 0.1.11 is the oldest runtime with the APIs this client
+  # uses (``AgentsMdExtension`` among them) and the first whose subagent
+  # extension imports its SQLite store lazily, so warming a runtime no longer
+  # loads SQLAlchemy. An exact pin would make zettcode fight every other tool
+  # that shares the dependency — including an upgrade of zett-agent itself,
+  # which pip would downgrade to satisfy it.
+  "zett-agent>=0.1.11,<0.2",
 ]
 
 [project.scripts]

{zettcode-0.1.2 → zettcode-0.1.3}/src/zettcode/__init__.py

@@ -7,7 +7,7 @@ from typing import TYPE_CHECKING
 
 #: The one place the version is written. ``pyproject.toml`` reads it from here
 #: and the release workflow checks the tag against it, so a bump is one edit.
-__version__ = "0.1.2"
+__version__ = "0.1.3"
 
 #: Where each public name lives; read by :func:`__getattr__` on first use.
 _EXPORTS = {

{zettcode-0.1.2 → zettcode-0.1.3}/src/zettcode/app/agent/agent.py

@@ -29,11 +29,13 @@ from zett_agent.model import ReasoningEffort, ToolDefinition
 from ...config import ModelConfig, ZettCodeConfig
 from ...plugins import UiRow
 from ..commands import Command, CommandContext, CommandResult
+from .ask import ASK_USER_RESPONSE_EVENT_NAME, AskUserQuestion, answer_payload, decline_payload
 from .context import ContextReport
 from .export import build_trace, render_html, write_export
 from .mentions import MentionProvider, MentionRegistry
 from .replay import replay
 from .runtime import ZettCodeRuntime, build_system_prompt
+from .side import SIDE, question
 from .storage import Session, SessionInfo
 from .title import summarize_title
 from .transcript import Transcript
@@ -256,6 +258,7 @@ class ZettCodeAgent:
         parts: Sequence[PromptPart],
         *,
         hint: str | None = None,
+        side: bool = False,
     ) -> AsyncIterator[AgentEvent]:
         """Run one turn with the selected session, model, and reasoning effort.
 
@@ -267,11 +270,13 @@ class ZettCodeAgent:
                 reference contributes. The text the user typed then rides along
                 as the message's ``prompt`` attribute, so the stored message is
                 what was typed and a restored session shows it.
+            side: Ask without letting the exchange join the conversation; see
+                :mod:`zettcode.app.agent.side`.
         """
         await self.runtime.start()
         client = self.runtime.started
         async for event in client.stream(
-            self.request(parts, hint=hint),
+            self.request(parts, hint=hint, side=side),
             config=AgentRunConfig(session_id=self.session_id),
             model=self.runtime.provider,
             reasoning_effort=self.runtime.effort,
@@ -279,7 +284,7 @@ class ZettCodeAgent:
             yield event
 
     @staticmethod
-    def request(parts: Sequence[PromptPart], *, hint: str | None = None) -> str | UserMessage:
+    def request(parts: Sequence[PromptPart], *, hint: str | None = None, side: bool = False) -> str | UserMessage:
         """Return the user turn those ordered parts make up.
 
         Text and images keep the order they were written in inside one
@@ -288,7 +293,23 @@ class ZettCodeAgent:
         ``hint`` is appended last — as a trailing part when an image is in the
         turn — and the typed text then rides along as the message's ``prompt``
         attribute, so storage and a restored session keep it.
+
+        Args:
+            parts: The turn in the order it was written.
+            hint: Instructions a ``@`` reference contributes.
+            side: Mark the turn as a side question, which the store records but
+                never replays.
         """
+        message = ZettCodeAgent.turn(parts, hint=hint)
+        if not side:
+            return message
+        if isinstance(message, UserMessage):
+            return replace(message, attributes={**message.attributes, SIDE: True}, include_in_messages=False)
+        return question(message)
+
+    @staticmethod
+    def turn(parts: Sequence[PromptPart], *, hint: str | None = None) -> str | UserMessage:
+        """Return the message those parts make up, before any side marking."""
         if not carries_image(parts):
             text = plain_text(parts)
             if hint is None:
@@ -551,6 +572,31 @@ class ZettCodeAgent:
             config=AgentRunConfig(session_id=session_id),
         )
 
+    def answer_ask(self, question: AskUserQuestion, answer: str) -> None:
+        """Answer the model's question; the suspended tool call resumes with it.
+
+        Args:
+            question: The question being answered, which carries the session and
+                the tool call the runtime routes the reply on.
+            answer: What the reader typed, exactly as it should reach the model.
+        """
+        self._respond_to_ask(question, answer_payload(question, answer))
+
+    def decline_ask(self, question: AskUserQuestion) -> None:
+        """Tell the model the reader cancelled, rather than leaving it waiting.
+
+        ``ask_user`` has no rejection channel in the runtime, so the tool result
+        says the question was declined and why; the model carries on from that.
+        """
+        self._respond_to_ask(question, decline_payload(question))
+
+    def _respond_to_ask(self, question: AskUserQuestion, payload: dict[str, object]) -> None:
+        """Emit one ``ask_user_response`` for the session the question came from."""
+        self.runtime.started.agent.emit_external_event(
+            ExternalEvent(name=ASK_USER_RESPONSE_EVENT_NAME, payload=dict(payload)),
+            config=AgentRunConfig(session_id=question.session_id),
+        )
+
     def steer(self, text: str) -> bool:
         """Queue an urgent user message for the request that is running.
 

zettcode-0.1.3/src/zettcode/app/agent/ask.py

@@ -0,0 +1,96 @@
+"""The ``ask_user`` protocol: what the model asked, and what answers it.
+
+``zett-agent`` owns the tool, the suspension and the routing; this module owns
+the little the shell and the agent have to agree on — the question parsed out of
+the event payload, and the payloads that answer it. Keeping both here means the
+panel never reads a raw payload and the agent never invents one.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+from zett_agent.events import AgentEvent
+from zett_agent.extensions.ask_user import ASK_USER_EVENT_NAME, ASK_USER_RESPONSE_EVENT_NAME
+
+__all__ = [
+    "ASK_USER_RESPONSE_EVENT_NAME",
+    "AskUserQuestion",
+    "answer_payload",
+    "decline_payload",
+    "question_from",
+]
+
+
+@dataclass(frozen=True, slots=True)
+class AskUserQuestion:
+    """One question the model is waiting on.
+
+    Attributes:
+        session_id: Session the question belongs to, echoed back with the answer.
+        call_id: Tool call the answer resolves; the agent routes on it.
+        question: The question, trimmed.
+        options: Choices the model offered, in display order; empty when it
+            offered none.
+        allow_multiple: Whether more than one option may be chosen.
+    """
+
+    session_id: str
+    call_id: str
+    question: str
+    options: tuple[str, ...] = ()
+    allow_multiple: bool = False
+
+
+def _options(value: object) -> tuple[str, ...]:
+    """Return the usable choices in a payload field, dropping anything else."""
+    if not isinstance(value, list):
+        return ()
+    return tuple(item.strip() for item in value if isinstance(item, str) and item.strip())
+
+
+def question_from(event: AgentEvent) -> AskUserQuestion | None:
+    """Return the question an event carries, or ``None`` when it is not one.
+
+    The payload comes from the runtime, but a malformed one must not take the
+    shell down: it is read defensively and reported as "not a question".
+    """
+    if event.name != ASK_USER_EVENT_NAME:
+        return None
+    payload = event.payload if isinstance(event.payload, dict) else {}
+    question = payload.get("question")
+    call_id = payload.get("tool_call_id")
+    if not isinstance(question, str) or not question.strip():
+        return None
+    if not isinstance(call_id, str) or not call_id:
+        return None
+    session_id = payload.get("session_id") or event.session_id
+    return AskUserQuestion(
+        session_id=str(session_id or ""),
+        call_id=call_id,
+        question=question.strip(),
+        options=_options(payload.get("options")),
+        allow_multiple=bool(payload.get("allow_multiple")),
+    )
+
+
+def answer_payload(question: AskUserQuestion, answer: str) -> dict[str, Any]:
+    """Return the response payload for a question the reader answered."""
+    return {"tool_call_id": question.call_id, "answer": answer}
+
+
+def decline_payload(question: AskUserQuestion) -> dict[str, Any]:
+    """Return the response payload for a question the reader cancelled.
+
+    ``ask_user`` has no rejection channel: the tool returns whatever payload the
+    UI sends. A cancel therefore answers with a result that says the question was
+    declined — the model reads that and carries on, instead of a suspended call
+    waiting for a reply that is never coming.
+    """
+    return {
+        "tool_call_id": question.call_id,
+        "answer": None,
+        "declined": True,
+        "reason": "the user cancelled the question",
+    }