zettcode 0.1.3__tar.gz → 0.1.5__tar.gz

{zettcode-0.1.3 → zettcode-0.1.5}/.gitignore

@@ -4,6 +4,7 @@
 *.egg-info/
 build/
 dist/
+.smoke/
 .coverage
 **/.pytest_cache/
 **/.ruff_cache/

{zettcode-0.1.3 → zettcode-0.1.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: zettcode
-Version: 0.1.3
+Version: 0.1.5
 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
@@ -21,12 +21,14 @@ 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: pydantic<3,>=2
 Requires-Dist: pyperclip<2,>=1.9
 Requires-Dist: setproctitle<2,>=1.3.7; os_name == 'posix'
+Requires-Dist: tiktoken<1,>=0.12
 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
+Requires-Dist: zett-agent<0.2,>=0.1.15
 Description-Content-Type: text/markdown
 
 <p align="center">
@@ -49,7 +51,8 @@ Description-Content-Type: text/markdown
 
 ## Get running
 
-You need **Python 3.10+**, a UTF-8 terminal, and an **OpenAI-compatible API**.
+You need **Python 3.10+**, a UTF-8 terminal, and an **OpenAI-compatible API**
+(or Anthropic's **Messages API**).
 Works on macOS, Linux, and Windows (use Windows Terminal).
 
 ### 1. Install
@@ -98,7 +101,7 @@ and prints the command to resume your session.
 | --- | --- |
 | **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. |
+| **Keep moving** | Type during a reply and choose: steer it now, or queue a follow-up you can edit, delete and reorder with `Option`+`↑`/`↓`. 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. |

{zettcode-0.1.3 → zettcode-0.1.5}/README.md

@@ -18,7 +18,8 @@
 
 ## Get running
 
-You need **Python 3.10+**, a UTF-8 terminal, and an **OpenAI-compatible API**.
+You need **Python 3.10+**, a UTF-8 terminal, and an **OpenAI-compatible API**
+(or Anthropic's **Messages API**).
 Works on macOS, Linux, and Windows (use Windows Terminal).
 
 ### 1. Install
@@ -67,7 +68,7 @@ and prints the command to resume your session.
 | --- | --- |
 | **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. |
+| **Keep moving** | Type during a reply and choose: steer it now, or queue a follow-up you can edit, delete and reorder with `Option`+`↑`/`↓`. 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. |

{zettcode-0.1.3 → zettcode-0.1.5}/README.zh-CN.md

@@ -18,7 +18,7 @@
 
 ## 先跑起来
 
-需要 **Python 3.10+**、支持 UTF-8 的终端和 **OpenAI 兼容接口**。
+需要 **Python 3.10+**、支持 UTF-8 的终端和 **OpenAI 兼容接口**（或 Anthropic 的 **Messages API**）。
 支持 macOS、Linux 和 Windows（请使用 Windows Terminal）。
 
 ### 1. 安装
@@ -64,7 +64,7 @@ zettcode
 | --- | --- |
 | **看清每一步** | 思考、回答和工具调用实时呈现为可读的行，不是原始 JSON。 |
 | **决定权在你手上** | 执行 shell 命令前先审阅；智能体需要你的决定时，可以选选项，也可以打字回答。 |
-| **工作不中断** | 回复过程中发送 steering（引导）消息；用 `/btw` 问一句，不让它进入后续上下文。 |
+| **工作不中断** | 回复过程中直接输入并选择：立刻引导，或排成可用 `Option`+`↑`/`↓` 调整顺序、可编辑可删除的后续消息；用 `/btw` 问一句，不让它进入后续上下文。 |
 | **随时接着做** | `/resume` 恢复对话，`/export` 导出便于阅读的 HTML。 |
 | **看懂上下文** | 查看 token 与缓存统计，用 `/context` 检查占用，在需要时压缩。 |
 | **接入你的工具** | 使用项目 `AGENTS.md` 指令、skills、MCP 服务器和 Python 插件。 |

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

@@ -24,19 +24,29 @@ classifiers = [
 dependencies = [
   # The stdlib gained both of these in 3.11; older runtimes take the backports.
   "exceptiongroup>=1.2,<2; python_version < '3.11'",
+  # Imported directly by the session store's record and metadata codecs, so it
+  # is declared here rather than borrowed from the runtime that brings it today.
+  "pydantic>=2,<3",
   "pyperclip>=1.9,<2",
   "setproctitle>=1.3.7,<2; os_name == 'posix'",
+  # The counter behind ``/context`` measures a request with it, and imports it
+  # itself: the floor matches the runtime's, so neither resolver has to fight.
+  "tiktoken>=0.12,<1",
   "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",
-  # 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",
+  # A range, not a pin: 0.1.13 is the oldest runtime whose tool argument schemas
+  # are self-contained — Pydantic's ``$defs``/``$ref`` are expanded when the
+  # schema is built — and a gateway that refuses to resolve a pointer otherwise
+  # answers 400 to every request on its Messages route. It also keeps the two
+  # the floor below it was raised for: the shell tool called ``bash``, which this
+  # client's phrasing, colours, and approval path are keyed on, and SQLAlchemy,
+  # tiktoken, and httpx behind their first use, so warming a runtime costs less
+  # than it did. 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.15,<0.2",
 ]
 
 [project.scripts]

{zettcode-0.1.3 → zettcode-0.1.5}/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.3"
+__version__ = "0.1.5"
 
 #: Where each public name lives; read by :func:`__getattr__` on first use.
 _EXPORTS = {

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

@@ -7,9 +7,9 @@ from typing import TYPE_CHECKING
 
 #: Where each public name lives; read by :func:`__getattr__` on first use.
 _EXPORTS = {
-    "Entry": ".transcript",
-    "Transcript": ".transcript",
-    "TranscriptProjector": ".projection",
+    "Entry": ".conversation.entries",
+    "Transcript": ".conversation.transcript",
+    "TranscriptProjector": ".conversation.projection",
     "ZettCodeAgent": ".agent",
     "ZettCodeRuntime": ".runtime",
 }
@@ -17,9 +17,10 @@ _EXPORTS = {
 
 if TYPE_CHECKING:  # pragma: no cover - for type checkers, not the runtime
     from .agent import ZettCodeAgent
-    from .projection import TranscriptProjector
+    from .conversation.entries import Entry
+    from .conversation.projection import TranscriptProjector
+    from .conversation.transcript import Transcript
     from .runtime import ZettCodeRuntime
-    from .transcript import Entry, Transcript
 
 
 def __getattr__(name: str) -> object:

zettcode-0.1.5/src/zettcode/app/agent/agent/__init__.py

@@ -0,0 +1,74 @@
+"""The application-facing coding agent: one class, assembled from the parts that make it up.
+
+The class used to be one 750-line body doing eight unrelated jobs. It is divided the way the
+transcript and the shell are, by what each part is responsible for:
+
+==============  ===========================================================================
+``base``        :class:`AgentBase` — the runtime, the workspace, the active session id
+``settings``    :class:`SettingsMixin` — model, reasoning effort, shell permission
+``context``     :class:`ContextMixin` — the request the next turn carries; compaction
+``sessions``    :class:`SessionsMixin` — switch, resume, fork, list, and title sessions
+``turns``       :class:`TurnsMixin` — build a request, stream its events, steer it
+``interaction`` :class:`InteractionMixin` — answer an approval request or a question
+``exports``     :class:`ExportsMixin` — write a session out as a page
+``commands``    :class:`CommandsMixin` — the agent's commands and what plugins contributed
+``prompt``      the parts of a user turn: text, ``@`` references, images (no class)
+==============  ===========================================================================
+
+A mixin inherits the ones whose methods it really calls, and :class:`AgentBase` below all of
+them, so each is type-checked against what it relies on; nothing is declared twice. This class
+is the composition and the lifecycle — building the runtime, and closing it.
+"""
+
+from __future__ import annotations
+
+from ....config import ZettCodeConfig
+from ..runtime import ZettCodeRuntime
+from .commands import CommandsMixin
+from .context import ContextMixin
+from .exports import ExportsMixin
+from .interaction import InteractionMixin
+from .sessions import SessionsMixin
+from .settings import SettingsMixin
+from .turns import TurnsMixin
+
+
+class ZettCodeAgent(
+    CommandsMixin,
+    InteractionMixin,
+    TurnsMixin,
+    ExportsMixin,
+    SessionsMixin,
+    SettingsMixin,
+    ContextMixin,
+):
+    """Expose agent operations without leaking runtime resources to the UI.
+
+    The runtime assembles the vendor client and extensions; this class is the
+    application's entry point for turns, session and model selection, progress,
+    and responses to approval requests.
+    """
+
+    def __init__(self, runtime: ZettCodeRuntime) -> None:
+        self.runtime = runtime
+
+    @classmethod
+    async def create(cls, config: ZettCodeConfig) -> ZettCodeAgent:
+        """Build the runtime and wrap it in the application agent."""
+        return cls(await ZettCodeRuntime.create(config))
+
+    @classmethod
+    def preview(cls, config: ZettCodeConfig) -> ZettCodeAgent:
+        """Wrap a runtime that still has to start, so a shell can paint first.
+
+        The runtime here holds the session and this application's own
+        extensions; the provider SDK and the client are built by the first
+        :meth:`runtime.start`, which a turn or a command awaits. Everything the
+        shell reads per frame — the model, the effort, the session, the usage —
+        is answered from that preview.
+        """
+        return cls(ZettCodeRuntime.preview(config))
+
+    async def aclose(self) -> None:
+        """Release the underlying runtime resources."""
+        await self.runtime.aclose()

zettcode-0.1.5/src/zettcode/app/agent/agent/base.py

@@ -0,0 +1,29 @@
+"""What every part of the agent shares: the runtime it speaks to, and who and where it is.
+
+The mixins in this package are split by what they are responsible for, and each one
+inherits this class only to be type-checked against what the others rely on. The two
+properties here are read by nearly all of them, which is why they live below all of them.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from ..runtime import ZettCodeRuntime
+
+
+class AgentBase:
+    """The runtime, the workspace it works in, and the session the next turn belongs to."""
+
+    #: The runtime this agent speaks to; the one thing the application agent holds.
+    runtime: ZettCodeRuntime
+
+    @property
+    def workspace(self) -> Path:
+        """Return the workspace displayed in the header."""
+        return self.runtime.config.workspace
+
+    @property
+    def session_id(self) -> str:
+        """Return the session used for the next turn."""
+        return self.runtime.session_id

zettcode-0.1.5/src/zettcode/app/agent/agent/commands.py

@@ -0,0 +1,80 @@
+"""What the agent offers the shell to run and to show: its own commands, and what plugins added.
+
+The commands report through transcript Markdown; commands that present a widget belong to
+the shell, which owns the widgets. The plugin contributions are listed here because the
+agent is where the shell asks for everything the runtime loaded.
+"""
+
+from __future__ import annotations
+
+from ....plugins import UiRow
+from ...commands import Command, CommandContext, CommandResult
+from ..dialogue.mentions import MentionProvider
+from .exports import ExportsMixin
+
+
+class CommandsMixin(ExportsMixin):
+    """The ``/new``, ``/compact``, and ``/export`` commands, and the plugins' commands, mentions, and rows."""
+
+    @property
+    def commands(self) -> tuple[Command, ...]:
+        """Return the conversation commands the agent owns.
+
+        They report through transcript Markdown; commands that present a widget
+        (such as the model picker) belong to the shell, which owns the widgets.
+        """
+        return (
+            Command("/new", "start a fresh session", "agent", self._command_new),
+            Command("/compact", "summarize the context now", "agent", self._command_compact),
+            Command("/export", "write this session to an HTML file: /export [path]", "agent", self._command_export),
+        )
+
+    @property
+    def plugin_commands(self) -> tuple[Command, ...]:
+        """Return the commands the installed plugins registered.
+
+        The shell keeps them after its own commands, so a plugin cannot take
+        over a built-in name; plugin-versus-plugin duplicates are rejected when
+        the plugins load.
+        """
+        return self.runtime.plugins.commands
+
+    @property
+    def plugin_mentions(self) -> tuple[MentionProvider, ...]:
+        """Return the ``@`` resource providers the installed plugins registered."""
+        return self.runtime.plugins.mentions
+
+    @property
+    def plugin_failures(self) -> tuple[str, ...]:
+        """Return one message per plugin that could not be loaded or activated."""
+        return self.runtime.plugins.failures
+
+    @property
+    def plugin_rows(self) -> tuple[UiRow, ...]:
+        """Return the header and status rows plugins asked the shell to draw."""
+        return self.runtime.plugins.rows
+
+    async def _command_new(self, context: CommandContext) -> CommandResult:
+        """Start a fresh session."""
+        session_id = self.new_session()
+        return CommandResult(notification=f"started session {session_id[:8]}")
+
+    async def _command_export(self, context: CommandContext) -> CommandResult:
+        """Write the session and its context to one HTML file.
+
+        The path argument is optional; without it the file lands in the
+        workspace, named after the session, and the result says where.
+        """
+        path = await self.export_session(context.argument.strip() or None)
+        return CommandResult(message=f"Exported to `{path}`")
+
+    async def _command_compact(self, context: CommandContext) -> CommandResult:
+        """Summarize the conversation now, whatever its size.
+
+        The row and the outcome notice arrive while this await runs: the pass
+        dispatches through the same event dispatcher a turn does, so the
+        transcript animates ``Compacting`` and ends with ``Context compaction
+        applied`` (or ``skipped`` when the summary would not be smaller).
+        """
+        await self.compact()
+        return CommandResult()

zettcode-0.1.5/src/zettcode/app/agent/agent/context.py

@@ -0,0 +1,139 @@
+"""What the next request carries: its size, its breakdown, and shrinking it.
+
+Counting a request and summarizing one are the same subject seen from two ends — one says
+how full the window is, the other makes room in it — and both are answered from what the
+runtime assembled or, before it has assembled one, from what the store holds.
+"""
+
+from __future__ import annotations
+
+from zett_agent.agent import AgentRunConfig
+from zett_agent.extensions.events import CompactionEvent
+from zett_agent.messages import AnyMessage, SystemMessage
+from zett_agent.model import ToolDefinition
+
+from ..extensions.context import ContextReport
+from ..extensions.usage import UsageSnapshot
+from ..runtime import build_system_prompt
+from ..storage import Session
+from .base import AgentBase
+
+
+class ContextMixin(AgentBase):
+    """Report the request the next turn would send, and compact the conversation behind it."""
+
+    @property
+    def usage(self) -> UsageSnapshot:
+        """Return the active session's cumulative token counters.
+
+        The numbers come from the usage extension's in-memory totals, so the
+        status line can read them every frame; a session replayed from the store
+        is seeded before this is asked.
+        """
+        return self.runtime.usage.snapshot(self.session_id)
+
+    async def context_report(self) -> ContextReport | None:
+        """Return what the next request carries by source, or None before the first call.
+
+        The shares come from the tokenizer, which is prepared first: it prefers
+        tiktoken and falls back to a character estimate when that vocabulary
+        cannot be opened, which the report names so the numbers are not mistaken
+        for exact ones. The total comes from the provider when it counted this
+        very request — it counts what it bills — and from the tokenizer when the
+        request was primed from the store, whose stored figure belongs to a call
+        the dialogue may have outgrown.
+        """
+        tokenizer = self.runtime.tokenizer
+        await tokenizer.prepare()
+        window = self.runtime.active_model.context_window
+        counted = self.runtime.usage.snapshot(self.session_id).context_tokens
+        # The provider's own count of this conversation is the total: what it
+        # billed for the request this process assembled, or — for a session
+        # rebuilt from the store, which has no call of its own yet — what it
+        # billed for the last call that session made. Locally counting a rebuilt
+        # request is not a substitute: on this machine's own session the rebuilt
+        # list measured 1.65 M tokens against a provider's 326 k, because a
+        # rebuilt list holds messages the live request no longer carries.
+        #
+        # A count that reaches the window is refused instead: a request cannot
+        # carry more than the window it is measured against, so a figure that does
+        # is about something else, and a share pinned at a hundred is worse than
+        # the measurement.
+        reported = counted if 0 < counted < window else None
+        return self.runtime.context.report(
+            self.session_id,
+            window=window,
+            tokenizer=tokenizer,
+            reported=reported,
+        )
+
+    async def compact(self) -> CompactionEvent | None:
+        """Summarize the conversation now, without adding a turn to it.
+
+        zett-agent runs one pass over the restored session and dispatches every
+        event it emits, so the transcript animates the same ``Compacting`` row an
+        automatic compaction shows. Nothing is appended to the conversation and
+        no primary model call is made: the only work is the summary itself.
+
+        Returns:
+            The checkpoint that was stored, or ``None`` when there was nothing
+            worth replacing.
+
+        Raises:
+            ValueError: When the newest checkpoint already covers the branch —
+                a second pass would summarize nothing but the checkpoint.
+        """
+        if self._compacted_at_the_head():
+            raise ValueError("Already compacted; send a message before compacting again")
+        await self.runtime.start()
+        return await self.runtime.started.compact(
+            config=AgentRunConfig(session_id=self.session_id),
+            model=self.runtime.provider,
+        )
+
+    def _compacted_at_the_head(self) -> bool:
+        """Return whether nothing has been appended since the newest checkpoint.
+
+        Messages and checkpoints both carry ``created_at``, so the last message
+        being older than the last checkpoint is what says the branch has not
+        moved since it was summarized — no matter which session is active or
+        whether the transcript in this process ever showed that compaction.
+        """
+        try:
+            session = self.runtime.persistence.read(self.session_id)
+        except ValueError:
+            # A runtime without a store to read: no checkpoint can cover it.
+            return False
+        latest = session.latest_compaction
+        if latest is None or session.head_id is None:
+            return False
+        head = session.message(session.head_id)
+        return head is not None and head.created_at <= latest.created_at
+
+    def _context_request(self, session: Session) -> tuple[tuple[AnyMessage, ...], tuple[ToolDefinition, ...]]:
+        """Return the messages and tools the next turn would send.
+
+        The request this process assembled is the honest answer; before one has
+        run — a session restored into a fresh process — the instructions and the
+        active branch stand in for it, which is all that can be known there.
+        """
+        assembled = self.runtime.context.assembled(self.session_id)
+        if assembled is not None:
+            messages, tools = assembled
+            return tuple(messages), tuple(tools)
+        return self._stored_request(session), self.runtime.context.tools
+
+    def _stored_request(self, session: Session) -> tuple[AnyMessage, ...]:
+        """Return the messages a request for ``session`` would carry, from what is stored.
+
+        This depends on the session it is given and on nothing that changes with the
+        active one, so it can be run later — a restore hands it over unrun, and the
+        reader may have moved to another session by the time it is wanted.
+        """
+        instructions = self.runtime.context.instructions or (
+            SystemMessage(content=build_system_prompt(self.runtime.config)),
+        )
+        checkpoint, tail = session.active()
+        stored: list[AnyMessage] = [checkpoint.message[0]] if checkpoint is not None else []
+        stored.extend(line.message[0] for line in tail if line.message[0].include_in_messages)
+        return (*instructions, *stored)

zettcode-0.1.5/src/zettcode/app/agent/agent/exports.py

@@ -0,0 +1,66 @@
+"""Writing a session out as a page a reader can open."""
+
+from __future__ import annotations
+
+from dataclasses import replace
+from datetime import datetime
+from pathlib import Path
+
+from ..export import build_trace, render_html, write_export
+from ..storage import Session
+from .context import ContextMixin
+from .sessions import SessionsMixin
+from .settings import SettingsMixin
+
+
+class ExportsMixin(SessionsMixin, SettingsMixin, ContextMixin):
+    """Export the active session together with the request the next turn would send."""
+
+    async def export_session(self, path: str | Path | None = None) -> Path:
+        """Write the active session, and the context it now carries, to HTML.
+
+        The conversation is rendered with the same presenters the shell paints,
+        and the request the next turn would send is included beside it, so a
+        reader sees both the history and what the model is down to.
+
+        Args:
+            path: File to write; ``None`` puts ``zettcode-<id8>.html`` in the
+                workspace. A relative path is taken from the working directory.
+
+        Returns:
+            The absolute path that was written.
+
+        Raises:
+            ValueError: When the session has no stored header, so there is
+                nothing to export yet.
+        """
+        session = self.runtime.persistence.read(self.session_id)
+        if session.header is None:
+            raise ValueError("Nothing to export: this session has not been stored yet")
+        report = await self.context_report()
+        messages, tools = self._context_request(session)
+        trace = build_trace(
+            session,
+            title=self.session_name,
+            subtitle=f"Session {self.session_id} · {self.workspace}",
+            meta=self._export_meta(session),
+            tags=(self.runtime.active_model.shown_name, self.effort),
+            context_messages=messages,
+            tools=tuple(tool.name for tool in tools),
+            report=report,
+        )
+        trace = replace(trace, exported_at=datetime.now().astimezone().strftime("%Y-%m-%d %H:%M"))
+        target = path if path is not None else self.workspace / f"zettcode-{self.session_id[:8]}.html"
+        return write_export(target, render_html(trace))
+
+    def _export_meta(self, session: Session) -> tuple[tuple[str, str], ...]:
+        """Return the label/value pairs the exported page's sidebar carries."""
+        model = self.runtime.active_model
+        return (
+            ("Workspace", str(self.workspace)),
+            ("Model", f"{model.shown_name} ({model.model})"),
+            ("Effort", self.effort),
+            ("Created", session.created_at.astimezone().strftime("%Y-%m-%d %H:%M")),
+            ("Updated", session.updated_at.astimezone().strftime("%Y-%m-%d %H:%M")),
+            ("Messages", f"{session.message_count}"),
+        )

zettcode-0.1.5/src/zettcode/app/agent/agent/interaction.py

@@ -0,0 +1,53 @@
+"""Answering what the model asked for: a shell approval, or a question for the reader.
+
+The agent is suspended inside a tool call while it waits, so the answer is an external
+event routed to the session and the call the request came from.
+"""
+
+from __future__ import annotations
+
+from zett_agent.agent import AgentRunConfig
+from zett_agent.extensions.external import ExternalEvent
+from zett_agent.extensions.shell_approval import SHELL_APPROVAL_RESPONSE_EVENT_NAME
+
+from ..dialogue.ask import ASK_USER_RESPONSE_EVENT_NAME, AskUserQuestion, answer_payload, decline_payload
+from .base import AgentBase
+
+
+class InteractionMixin(AgentBase):
+    """Send the reader's answer to an approval request or a question back to the running agent."""
+
+    def respond_approval(self, session_id: str, call_id: str, decision: str, remember: bool) -> None:
+        """Answer a pending shell approval for the originating session."""
+        self.runtime.started.agent.emit_external_event(
+            ExternalEvent(
+                name=SHELL_APPROVAL_RESPONSE_EVENT_NAME,
+                payload={"tool_call_id": call_id, "decision": decision, "remember": remember},
+            ),
+            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),
+        )