zettcode 0.1.8__tar.gz → 0.1.10__tar.gz

{zettcode-0.1.8 → zettcode-0.1.10}/.gitignore

@@ -21,6 +21,9 @@ docs/.vitepress/dist/
 docs/.vitepress/cache/
 docs/.vitepress/.temp/
 
+# The TypeScript client is built from its sources; only dist/ is published.
+clients/typescript/dist/
+
 # The palette gallery is generated by `make palettes`: every widget painted in
 # every palette, written by docs/scripts/palette_gallery.py. Regenerate it
 # rather than committing a 2 MB copy that goes stale the moment a colour moves.

zettcode-0.1.10/PKG-INFO

@@ -0,0 +1,60 @@
+Metadata-Version: 2.5
+Name: zettcode
+Version: 0.1.10
+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
+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: Programming Language :: Python :: 3.15
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: exceptiongroup<2,>=1.2; python_version < '3.11'
+Requires-Dist: httpx<1,>=0.27
+Requires-Dist: pydantic<3,>=2
+Requires-Dist: pyperclip<2,>=1.9
+Requires-Dist: setproctitle<2,>=1.3.7; os_name == 'posix'
+Requires-Dist: starlette<2,>=0.48
+Requires-Dist: tiktoken<1,>=0.12
+Requires-Dist: tomli<3,>=2; python_version < '3.11'
+Requires-Dist: truststore<1,>=0.10
+Requires-Dist: uvicorn<1,>=0.35
+Requires-Dist: wcwidth<1,>=0.2
+Requires-Dist: websockets<17,>=15
+Requires-Dist: zett-agent<0.3,>=0.2.0
+Description-Content-Type: text/markdown
+
+# ZettCode
+
+A focused terminal coding agent powered by [zett-agent](https://pypi.org/project/zett-agent/): it reads and edits your
+code, runs commands with your permission, and is driven by a model you choose. The repository also ships a Python SDK
+and an HTTP server.
+
+```bash
+pip install zettcode
+zettcode
+```
+
+- [The guide](https://chang-lehung.github.io/zettcode/) — commands, keys, plugins, configuration
+- [The SDK](https://chang-lehung.github.io/zettcode/sdk/) — drive the agent from Python
+- [The server](https://chang-lehung.github.io/zettcode/server/) — drive it over HTTP
+
+The full README, with the screenshots, is at the root of the repository.
+
+```python
+import zettcode.sdk as zc
+
+result = await zc.prompt("summarize the README", permission="deny")
+print(result.text)
+```

zettcode-0.1.10/README.md

@@ -0,0 +1,23 @@
+# ZettCode
+
+A focused terminal coding agent powered by [zett-agent](https://pypi.org/project/zett-agent/): it reads and edits your
+code, runs commands with your permission, and is driven by a model you choose. The repository also ships a Python SDK
+and an HTTP server.
+
+```bash
+pip install zettcode
+zettcode
+```
+
+- [The guide](https://chang-lehung.github.io/zettcode/) — commands, keys, plugins, configuration
+- [The SDK](https://chang-lehung.github.io/zettcode/sdk/) — drive the agent from Python
+- [The server](https://chang-lehung.github.io/zettcode/server/) — drive it over HTTP
+
+The full README, with the screenshots, is at the root of the repository.
+
+```python
+import zettcode.sdk as zc
+
+result = await zc.prompt("summarize the README", permission="deny")
+print(result.text)
+```

{zettcode-0.1.8 → zettcode-0.1.10}/pyproject.toml

@@ -5,7 +5,6 @@ readme = "README.md"
 requires-python = ">=3.10"
 dynamic = ["version"]
 license = "MIT"
-license-files = ["LICENSE"]
 authors = [{name = "Chang-LeHung"}]
 keywords = ["agent", "llm", "tui", "terminal", "coding-agent"]
 classifiers = [
@@ -19,6 +18,7 @@ classifiers = [
   "Programming Language :: Python :: 3.12",
   "Programming Language :: Python :: 3.13",
   "Programming Language :: Python :: 3.14",
+  "Programming Language :: Python :: 3.15",
   "Typing :: Typed",
 ]
 dependencies = [
@@ -53,7 +53,7 @@ dependencies = [
   # 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.17,<0.2",
+  "zett-agent>=0.2.0,<0.3",
 ]
 
 [project.scripts]
@@ -75,53 +75,8 @@ path = "src/zettcode/__init__.py"
 packages = ["src/zettcode"]
 
 [tool.hatch.build.targets.sdist]
-include = ["/src", "/README.md", "/README.zh-CN.md", "/LICENSE", "/pyproject.toml"]
-
-[dependency-groups]
-dev = [
-  # Unlike the conditional runtime deps, these are installed on every
-  # interpreter so mypy can check the 3.10 branch of ``_compat`` for real.
-  "exceptiongroup>=1.2,<2",
-  "mypy>=1.14,<2",
-  "pytest>=8,<9",
-  "pytest-asyncio>=0.26,<2",
-  "pytest-cov>=7.1.0",
-  "ruff>=0.11,<1",
-  "tomli>=2,<3",
-  "viztracer>=1.1.1",
-]
+include = ["/src", "/README.md", "/pyproject.toml"]
 
 [tool.pytest.ini_options]
 testpaths = ["tests"]
 asyncio_mode = "auto"
-
-[tool.mypy]
-python_version = "3.10"
-files = ["src", "perf"]
-# Check the pydantic storage models as models, not as plain classes.
-plugins = ["pydantic.mypy"]
-warn_unused_ignores = true
-warn_redundant_casts = true
-no_implicit_optional = true
-
-[[tool.mypy.overrides]]
-# Ships no stubs; the runner only calls the two documented functions.
-module = ["pyperclip"]
-ignore_missing_imports = true
-
-[tool.ruff]
-line-length = 120
-target-version = "py310"
-src = ["src", "tests", "perf"]
-
-[tool.ruff.lint]
-select = ["E", "F", "I", "UP", "B"]
-ignore = ["E501"]
-
-[tool.ruff.lint.isort]
-known-first-party = ["zettcode"]
-
-[tool.ruff.format]
-quote-style = "double"
-indent-style = "space"
-line-ending = "lf"

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

{zettcode-0.1.8 → zettcode-0.1.10}/src/zettcode/_compat.py

@@ -1,6 +1,6 @@
 """Small shims for the language versions this project supports.
 
-ZettCode runs on Python 3.10 through 3.14, so the few things the standard
+ZettCode runs on Python 3.10 through 3.15, so the few things the standard
 library grew in between live here instead of behind version checks at each use.
 """
 

{zettcode-0.1.8 → zettcode-0.1.10}/src/zettcode/app/agent/agent/settings.py

@@ -14,6 +14,7 @@ from zettcode.config_edit import (
     remove_model,
     replace_model,
     set_pet,
+    set_pet_position,
     set_self_compaction,
     set_statusline,
     set_theme,
@@ -208,6 +209,29 @@ class SettingsMixin(AgentBase):
         self.runtime.config = replace(self.runtime.config, pet=name)
         return self.config_file
 
+    def remember_pet_position(self, across: float, down: float) -> Path:
+        """Write ``[ui] pet_position`` into the config file, so the next start puts the pet back where it was left.
+
+        The file is global to the reader (``~/.zettcode/config.toml``), not to a project: a pet is the reader's
+        companion, and it does not move house when they open another folder. Only that line changes, and a
+        config file that does not exist is not created for it.
+
+        Returns:
+            The file written.
+
+        Raises:
+            ConfigEditError: When there is no config file, it cannot be read or edited safely, or it cannot be
+                written. Nothing is written then.
+        """
+        text = set_pet_position(self._read_config_file(), across, down, where=self.config_file)
+        try:
+            write_text_atomically(self.config_file, text)
+        except OSError as error:
+            raise ConfigEditError(f"{self.config_file} could not be written: {error}") from error
+        position = (round(min(1.0, max(0.0, across)), 3), round(min(1.0, max(0.0, down)), 3))
+        self.runtime.config = replace(self.runtime.config, pet_position=position)
+        return self.config_file
+
     @property
     def statusline_hidden(self) -> frozenset[str]:
         """Return the names of the header and status-line parts the reader switched off."""
@@ -322,6 +346,15 @@ class SettingsMixin(AgentBase):
         """Return the permission levels, strictest first."""
         return tuple(level.value for level in PERMISSION_LEVELS)
 
-    def use_permission(self, name: str | Permission) -> Permission:
-        """Set how much of the shell may run without asking, for the rest of this run."""
-        return self.runtime.use_permission(name)
+    def use_permission(self, name: str | Permission, *, remember: bool = True) -> Permission:
+        """Set how much of the shell may run without asking, and by default remember it for this session."""
+        return self.runtime.use_permission(name, remember=remember)
+
+    @property
+    def harness(self) -> bool:
+        """Return whether the just-in-time harness is on for the next request."""
+        return self.runtime.harness.on
+
+    def use_harness(self, on: bool) -> bool:
+        """Turn the just-in-time harness on or off for later requests, for the rest of this run."""
+        return self.runtime.use_harness(on)

{zettcode-0.1.8 → zettcode-0.1.10}/src/zettcode/app/agent/conversation/presenters.py

@@ -106,6 +106,8 @@ TOOL_ROLES = {
     "view_image": "image",
     "glob": "search",
     "grep": "search",
+    "web_search": "web-search",
+    "ask_user": "ask-user",
     "write_file": "write",
     "edit": "write",
     "replace_in_file": "write",  # what a session stored before the rename called it
@@ -120,8 +122,12 @@ TOOL_ROLES = {
 
 
 def tool_color(tool: str, theme: Theme) -> str:
-    """Return the colour one tool paints its rows with."""
-    return getattr(theme.tools, TOOL_ROLES.get(tool, ""), theme.accent)
+    """Return the colour one tool paints its rows with.
+
+    A role spelled with a hyphen (``web-search``) names the theme field it stands for (``web_search``).
+    """
+    role = TOOL_ROLES.get(tool, "").replace("-", "_")
+    return getattr(theme.tools, role, theme.accent)
 
 
 #: The entry fields that are not part of how a row looks: its identity, and the
@@ -575,7 +581,12 @@ class ToolPresenter(Presenter[T]):
             }.get(entry.status, STATUS)
         )
         hue = tool_color(entry.tool, theme)
-        colour = theme.error if entry.status is EntryStatus.FAILED else hue
+        # A failure is the error colour, and a row that did not happen at all — a skipped tool, a cancelled
+        # question — is a caution rather than a result, so it is amber and not the tool's own hue.
+        colour = {
+            EntryStatus.FAILED: theme.error,
+            EntryStatus.SKIPPED: theme.warning,
+        }.get(entry.status, hue)
         marker = Style(foreground=colour)
         label = Style(foreground=colour)
         muted = Style(foreground=theme.muted)

{zettcode-0.1.8 → zettcode-0.1.10}/src/zettcode/app/agent/conversation/projection.py

@@ -10,11 +10,12 @@ from zett_agent.events import AgentEvent
 from zett_agent.extensions.shell_approval import SHELL_APPROVAL_EVENT_NAME
 from zett_agent.messages import ToolMessage
 
-from ..dialogue.ask import AskUserQuestion, question_from
+from ..dialogue.ask import AskUserQuestion, declined_answer, question_from
 from ..dialogue.relay import Relayed
 from ..extensions.mcp_notice import MCP_NOTICE_EVENT_NAME, notice_from
 from ..extensions.usage import USAGE_EVENT_NAME
 from .entries import EntryStatus
+from .server_tools import ServerToolRun, describe_output
 from .stops import stop_text
 from .transcript import Transcript
 
@@ -82,6 +83,10 @@ class TranscriptProjector(AgentEventDispatcher):
         self.on_usage = on_usage
         self.on_steering_started = on_steering_started
         self.on_steering_interrupted = on_steering_interrupted
+        #: What a hosted tool was called with while it streams: a start may carry the whole input, or only its
+        #: opening and then fragments. Kept per request and dropped when the call reports back.
+        self._server_inputs: dict[str, dict[str, object]] = {}
+        self._server_fragments: dict[str, str] = {}
 
     def begin_turn(self, prompt: str, *, side: bool = False, relayed: Relayed | None = None) -> None:
         """Echo the prompt into the transcript before the run starts.
@@ -171,9 +176,19 @@ class TranscriptProjector(AgentEventDispatcher):
             self.transcript.start_tool(call.id, call.name, call.arguments)
 
     async def on_tool_completed_event(self, event: AgentEvent) -> None:
-        """Attach the returned message to the row of the call it answers."""
+        """Attach the returned message to the row of the call it answers.
+
+        A question the reader cancelled comes back as a result, not a failure: the model reads that it was declined
+        and carries on. The row is marked skipped so it does not look like a question that was answered.
+        """
         if isinstance(event.message, ToolMessage):
-            self.transcript.complete_tool(event.message.tool_call_id, tool_output(event.message))
+            output = tool_output(event.message)
+            declined = event.message.name == "ask_user" and declined_answer(output)
+            self.transcript.complete_tool(
+                event.message.tool_call_id,
+                output,
+                status=EntryStatus.SKIPPED if declined else EntryStatus.COMPLETED,
+            )
 
     async def on_tool_failed_event(self, event: AgentEvent) -> None:
         """Fail every call in the batch and record the error text."""
@@ -188,23 +203,56 @@ class TranscriptProjector(AgentEventDispatcher):
             self.transcript.complete_tool(call.id, output, status=EntryStatus.SKIPPED)
 
     async def on_server_tool_started_event(self, event: AgentEvent) -> None:
-        """Open a row for a tool the server runs on the agent's behalf."""
-        if event.server_tool_call is not None:
-            self.transcript.start_tool(event.server_tool_call.id, event.server_tool_call.name, {})
+        """Open a row for a tool the server runs on the agent's behalf, with what it was asked."""
+        call = event.server_tool_call
+        if call is None:
+            return
+        arguments = dict(call.input or {})
+        self._server_inputs[call.id] = arguments
+        self._server_fragments.pop(call.id, None)
+        self.transcript.start_tool(call.id, call.name, arguments)
+
+    async def on_server_tool_input_delta_event(self, event: AgentEvent) -> None:
+        """Keep the fragments of a hosted call's input; the query a search ran is in there."""
+        delta = event.server_tool_input_delta
+        if delta is not None:
+            self._server_fragments[delta.call_id] = self._server_fragments.get(delta.call_id, "") + delta.delta
+
+    def _server_arguments(self, call_id: str) -> dict[str, object]:
+        """Return what a hosted call turned out to be called with: its opening input and its fragments."""
+        arguments = dict(self._server_inputs.pop(call_id, {}))
+        fragments = self._server_fragments.pop(call_id, "")
+        if fragments:
+            try:
+                parsed = json.loads(fragments)
+            except ValueError:
+                parsed = None
+            if isinstance(parsed, dict):
+                arguments.update(parsed)
+        return arguments
 
     async def on_server_tool_completed_event(self, event: AgentEvent) -> None:
-        """Attach a server tool result to its row."""
+        """Attach a hosted tool's result to its row: the pages it found, never the provider's payload."""
         result = event.server_tool_result
         if result is not None:
-            self.transcript.complete_tool(result.call_id, serialize(result.output))
+            arguments = self._server_arguments(result.call_id)
+            if arguments:
+                # The row opened before its input had streamed in; now it knows what was searched for.
+                self.transcript.restate_tool(result.call_id, arguments)
+            run = ServerToolRun(result.call_id, result.name, arguments, output=result.output, error=result.error_code)
+            self.transcript.complete_tool(result.call_id, describe_output(run) or serialize(result.output))
 
     async def on_server_tool_failed_event(self, event: AgentEvent) -> None:
-        """Attach a server tool failure, preferring the error code over the payload."""
+        """Attach a hosted tool's failure, preferring the error code over the payload."""
         result = event.server_tool_result
         if result is not None:
+            arguments = self._server_arguments(result.call_id)
+            if arguments:
+                self.transcript.restate_tool(result.call_id, arguments)
+            run = ServerToolRun(result.call_id, result.name, arguments, output=result.output, error=result.error_code)
             self.transcript.complete_tool(
                 result.call_id,
-                result.error_code or serialize(result.output),
+                describe_output(run) or serialize(result.output),
                 status=EntryStatus.FAILED,
             )
 

{zettcode-0.1.8 → zettcode-0.1.10}/src/zettcode/app/agent/conversation/rendering.py

@@ -34,7 +34,7 @@ from zettcode.tui import ELLIPSIS, SEPARATOR
 from zettcode.tui.render import GENERIC, language_for
 
 from .entries import DeleteEntry, EditEntry, MessageEntry, ReadEntry, ToolEntry, WriteEntry
-from .text import limit_output
+from .text import DECLINED_NOTE, limit_output
 
 #: Output kinds the chain shapes; a link claims one or more of them.
 TOOL = "tool"
@@ -386,8 +386,8 @@ class WriteTool(ToolHandler):
     names = frozenset({"write_file"})
 
     def describe(self, name: str, arguments: Mapping[str, object]) -> ToolRow:
-        """Show the file being written."""
-        return ToolRow(f"Wrote {argument(arguments, 'path', '(unknown file)')}")
+        """Show the file being written: the row is the call, so it says what the call does, not what it did."""
+        return ToolRow(f"Write {argument(arguments, 'path', '(unknown file)')}")
 
     def open_tool(
         self, name: str, arguments: Mapping[str, object], *, id: int, call_id: str, started_at: float
@@ -497,6 +497,60 @@ class SearchTool(ToolHandler):
         return ToolRow(f"Searched {pattern or 'the workspace'}" + (f" in {where}" if where else ""))
 
 
+class WebSearchTool(ToolHandler):
+    """``web_search``: a search the endpoint ran, so the row says what was searched for."""
+
+    names = frozenset({"web_search"})
+
+    def describe(self, name: str, arguments: Mapping[str, object]) -> ToolRow:
+        """Name the query; the call is the endpoint's, so nothing else of it is ours to show."""
+        query = argument(arguments, "query")
+        return ToolRow(f'Searched the web for "{query}"' if query else "Searched the web")
+
+
+class AskUserTool(ToolHandler):
+    """``ask_user``: the one row that waited for a person, so it is named as a thing, not as a verb.
+
+    The body is what the person did, not the protocol: the tool answers with the payload the shell sent, and that
+    JSON is neither readable nor useful in a transcript.
+    """
+
+    names = frozenset({"ask_user"})
+
+    def describe(self, name: str, arguments: Mapping[str, object]) -> ToolRow:
+        """Show the question that was put, under the name the shell gives that tool."""
+        question = argument(arguments, "question")
+        return ToolRow(f"Ask-User: {question}" if question else "Ask-User")
+
+    def body(self, name: str, output: str) -> str:
+        """Say what the person did: declined, answered, or answered with a picture.
+
+        Anything that is not the answer payload is left exactly as it came, so a failure or another tool's result
+        is never rewritten by this row.
+        """
+        payload = _ask_payload(output)
+        if payload is None:
+            return output
+        if payload.get("declined") is True:
+            return DECLINED_NOTE
+        answer = payload.get("answer")
+        if isinstance(answer, str) and answer.strip():
+            return f"You answered: {answer.strip()}"
+        if isinstance(payload.get("parts"), list) and payload["parts"]:
+            return "You answered with a picture."
+        return output
+
+
+def _ask_payload(output: str) -> Mapping[str, object] | None:
+    """Return the payload of an ``ask_user`` result, or ``None`` when the text is not one."""
+    try:
+        result = json.loads(output)
+    except ValueError:
+        return None
+    payload = result.get("payload") if isinstance(result, Mapping) else None
+    return payload if isinstance(payload, Mapping) else None
+
+
 class TodoTool(ToolHandler):
     """``todo_write``: a plan, so the number of steps is the story."""
 
@@ -645,6 +699,8 @@ DEFAULT_RENDERERS = Renderers(
         DeleteTool(),
         ShellTool(),
         SearchTool(),
+        WebSearchTool(),
+        AskUserTool(),
         TodoTool(),
         SkillTool(),
         TaskTool(),

{zettcode-0.1.8 → zettcode-0.1.10}/src/zettcode/app/agent/conversation/replay.py

@@ -19,6 +19,7 @@ from zett_agent.messages import AnyMessage, AssistantMessage, SystemMessage, Too
 
 from zettcode.config import DEFAULT_TRANSCRIPT_MAX_ENTRIES
 
+from ..dialogue.ask import declined_answer
 from ..dialogue.relay import relay_of
 from ..dialogue.side import is_side_line
 from ..extensions.usage import UsageSnapshot
@@ -26,6 +27,7 @@ from ..storage import MessageLine, Session
 from .entries import EntryStatus
 from .presenters import DEFAULT_PRESENTERS, Presenters
 from .rendering import DEFAULT_RENDERERS, Renderers
+from .server_tools import ServerToolRun, answer_after_tools, describe_output, runs_in_blocks
 from .stops import stop_text
 from .transcript import Transcript
 
@@ -75,7 +77,13 @@ def entries_added_by(message: AnyMessage) -> int:
             return 1
         case AssistantMessage():
             stopped = message.stop is not None and not message.stop.ok
-            return bool(message.reasoning) + bool(message.content) + len(message.tool_calls) + stopped
+            return (
+                bool(message.reasoning)
+                + bool(message.content)
+                + len(message.tool_calls)
+                + len(runs_in_blocks(message.replay_blocks))
+                + stopped
+            )
         case _:
             return 0
 
@@ -152,7 +160,26 @@ def replay(
             case AssistantMessage():
                 if message.reasoning:
                     transcript.restore_thinking(message.reasoning, line.timing.reasoning_duration_ns)
-                if message.content:
+                runs = runs_in_blocks(message.replay_blocks)
+
+                def hosted(rows: Sequence[ServerToolRun] = runs) -> None:
+                    """Add the rows of the tools the endpoint ran, each closed by its own result."""
+                    for run in rows:
+                        transcript.start_tool(run.call_id, run.name, run.arguments)
+                        transcript.complete_tool(
+                            run.call_id,
+                            describe_output(run),
+                            status=EntryStatus.FAILED if run.error else EntryStatus.COMPLETED,
+                            wait=False,
+                        )
+
+                # A hosted tool has no message of its own: its call and result are both in the answer's blocks, kept
+                # because the provider needs them back. Where the answer's text sits in those blocks is where the row
+                # goes relative to it, so a reopened session reads in the order the run did.
+                if not answer_after_tools(message.replay_blocks) and message.content:
+                    transcript.append_answer(message.content)
+                hosted()
+                if answer_after_tools(message.replay_blocks) and message.content:
                     transcript.append_answer(message.content)
                 for call in message.tool_calls:
                     transcript.start_tool(call.id, call.name, call.arguments)
@@ -160,6 +187,9 @@ def replay(
                     transcript.error(stop_text(message.stop))
             case ToolMessage():
                 status = EntryStatus.COMPLETED if message.success else EntryStatus.FAILED
+                if message.name == "ask_user" and declined_answer(message.text):
+                    # A cancelled question is an answer of its own, not a failure.
+                    status = EntryStatus.SKIPPED
                 transcript.complete_tool(message.tool_call_id, message.text, status=status, wait=False)
             case _:
                 continue