zettcode 0.1.3__tar.gz → 0.1.4__tar.gz

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

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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: zettcode
-Version: 0.1.3
+Version: 0.1.4
 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.14
 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

{zettcode-0.1.3 → zettcode-0.1.4}/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

{zettcode-0.1.3 → zettcode-0.1.4}/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. 安装

{zettcode-0.1.3 → zettcode-0.1.4}/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.14,<0.2",
 ]
 
 [project.scripts]

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

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

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

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

@@ -33,7 +33,8 @@ from .ask import ASK_USER_RESPONSE_EVENT_NAME, AskUserQuestion, answer_payload,
 from .context import ContextReport
 from .export import build_trace, render_html, write_export
 from .mentions import MentionProvider, MentionRegistry
-from .replay import replay
+from .permission import PERMISSION_LEVELS, Permission
+from .replay import Replayed, replay
 from .runtime import ZettCodeRuntime, build_system_prompt
 from .side import SIDE, question
 from .storage import Session, SessionInfo
@@ -58,6 +59,24 @@ class MentionPart:
 PromptPart: TypeAlias = str | MentionPart | tuple[bytes, str]
 
 
+@dataclass(frozen=True, slots=True)
+class StoredSession:
+    """A session read from the store and rebuilt into rows, not yet made active.
+
+    Attributes:
+        session_id: The session that was read.
+        session: Its parsed file.
+        replayed: The rows, totals, and branch it replays into.
+        title: Its stored display title, if it has one: read here because folding
+            the metadata log is the other thing resuming used to do on the loop.
+    """
+
+    session_id: str
+    session: Session
+    replayed: Replayed
+    title: str | None
+
+
 def plain_text_part(part: PromptPart) -> str:
     """Return the text one part contributes; an image contributes nothing."""
     if isinstance(part, str):
@@ -152,6 +171,15 @@ class ZettCodeAgent:
         """
         return self.runtime.persistence.session_title(self.session_id)
 
+    def session_path(self) -> Path:
+        """Return the file this session is stored in, under the store root.
+
+        The whole conversation, on disk: what ``/context`` shows beside the token
+        breakdown, and what a reader opens when they want the raw records rather
+        than a rendered transcript.
+        """
+        return self.runtime.persistence.session_path(self.session_id)
+
     @property
     def session_name(self) -> str:
         """Return the name to show for the active session.
@@ -175,16 +203,36 @@ class ZettCodeAgent:
     async def context_report(self) -> ContextReport | None:
         """Return what the next request carries by source, or None before the first call.
 
-        The tokenizer 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 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=self.runtime.active_model.context_window,
+            window=window,
             tokenizer=tokenizer,
+            reported=reported,
         )
 
     @property
@@ -344,27 +392,81 @@ class ZettCodeAgent:
         """Switch future turns to a session."""
         self.runtime.use_session(session_id)
 
-    def restore_session(self, session_id: str, transcript: Transcript) -> None:
-        """Load the active stored branch into the UI before switching sessions."""
-        session = self.runtime.persistence.read(session_id)
+    def fork_session(self) -> str:
+        """Copy this conversation's context into a new session, and return its id.
+
+        What is carried over is what a request would send — the newest checkpoint's
+        summary and the messages after it — not the whole stored history: the fork
+        starts from the conversation the model is actually working with. The shell
+        installs the result the way a resume does, so the reader lands in the fork
+        with the same conversation in front of them.
+
+        Synchronous file work on purpose, so the shell can run it on a thread.
+        """
+        return self.runtime.persistence.fork(self.session_id)
+
+    def load_session(self, session_id: str, transcript: Transcript) -> StoredSession:
+        """Read a stored session and rebuild what it will show, changing nothing.
+
+        This is the expensive half of resuming — parsing the file and replaying the
+        newest part of it into rows — and it touches no state the shell is reading:
+        the rows are built into a transcript of their own, and the result is a value.
+        That is what lets the shell run it on a worker thread while the interface
+        keeps answering keys, and hand the result to :meth:`install_session` on the
+        loop. The ``transcript`` is only read, for the renderers, presenters, and cap
+        the rebuilt one has to match.
+
+        Args:
+            session_id: The session to read.
+            transcript: The transcript the result will be installed into.
+
+        Raises:
+            ValueError: The store holds no such session, or its file is corrupt.
+        """
+        persistence = self.runtime.persistence
+        session = persistence.read(session_id)
         if session.header is None:
             raise ValueError(f"Unknown session: {session_id}")
         replayed = replay(
             session,
             renderers=transcript.renderers,
-            processors=transcript.processors,
+            presenters=transcript.presenters,
             frame=transcript.frame,
+            max_entries=transcript.max_entries,
+        )
+        return StoredSession(
+            session_id=session_id,
+            session=session,
+            replayed=replayed,
+            title=persistence.session_title(session_id),
         )
+
+    def install_session(self, stored: StoredSession, transcript: Transcript) -> None:
+        """Make a loaded session the active one: its rows, its totals, its id.
+
+        The cheap half, and the one that changes state, so it runs where the rest of
+        the shell does. Everything it does is assignment.
+        """
+        session_id, session, replayed = stored.session_id, stored.session, stored.replayed
         transcript.replace(replayed.transcript.entries)
         self.runtime.usage.seed(session_id, replayed.usage)
-        # The instructions come from a request this process already assembled, or
-        # from the prompt the runtime would build; the environment and tool notes
-        # only exist inside a request, which the report admits.
-        instructions = self.runtime.context.instructions or (
-            SystemMessage(content=build_system_prompt(self.runtime.config)),
-        )
-        self.runtime.context.remember(session_id, [*instructions, *replayed.history])
         self.use_session(session_id)
+        # Prime the report with what the next turn would send, not with what the
+        # transcript shows: the display keeps every message a compaction folded
+        # away, and measuring those claims a request several times the size of the
+        # real one — 2.9 M tokens against a context of 290 k, which is a share
+        # pinned at a hundred. `_context_request` is the one definition of that
+        # request; the environment and tool notes only exist inside a real one,
+        # which the report admits.
+        #
+        # It is handed over as a function, not built here: the request holds every
+        # message since the last checkpoint, decoding them is most of what a long
+        # resume would cost, and nothing reads the list until `/context` does.
+        self.runtime.context.remember(session_id, lambda: self._stored_request(session))
+
+    def restore_session(self, session_id: str, transcript: Transcript) -> None:
+        """Load the active stored branch into the UI before switching sessions."""
+        self.install_session(self.load_session(session_id, transcript), transcript)
 
     async def list_sessions(self, *, limit: int = 20) -> list[SessionInfo]:
         """List persisted session metadata by recent activity."""
@@ -426,6 +528,20 @@ class ZettCodeAgent:
         """Approve every shell command for the rest of this run, without asking."""
         self.runtime.approve_all_shell_commands()
 
+    @property
+    def permission(self) -> Permission:
+        """Return how much of the shell may run without asking."""
+        return self.runtime.permission
+
+    @property
+    def permissions(self) -> tuple[str, ...]:
+        """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)
+
     async def compact(self) -> CompactionEvent | None:
         """Summarize the conversation now, without adding a turn to it.
 
@@ -477,7 +593,7 @@ class ZettCodeAgent:
     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 processors the shell paints,
+        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.
 
@@ -522,13 +638,22 @@ class ZettCodeAgent:
         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 or ()), *stored), self.runtime.context.tools
+        return (*instructions, *stored)
 
     def _export_meta(self, session: Session) -> tuple[tuple[str, str], ...]:
         """Return the label/value pairs the exported page's sidebar carries."""

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

@@ -14,6 +14,8 @@ from __future__ import annotations
 
 from zett_agent.extensions.shell_approval import ShellApprovalMode
 
+from .permission import ShellPolicy
+
 
 class ShellApprovalMemory:
     """Approval memory for one process: a policy per session, exact commands.
@@ -21,12 +23,25 @@ class ShellApprovalMemory:
     This satisfies ``zett-agent``'s ``ShellApprovalStorage``, which the shell
     extension uses to look up a session's mode and to check and record one
     approved command.
+
+    The shell extension asks :meth:`is_allowed` before it puts a command to the
+    reader, which makes it the one place a permission level can say "do not ask":
+    ``safe`` answers yes for a command that cannot change anything and ``auto``
+    answers yes for every command, while ``ask`` falls through to the commands the
+    reader approved by hand. ``deny`` is not decided here, because refusing is not
+    a thing this question can express.
     """
 
-    def __init__(self) -> None:
-        """Start with no session policy and nothing approved."""
+    def __init__(self, policy: ShellPolicy | None = None) -> None:
+        """Start with no session policy and nothing approved.
+
+        Args:
+            policy: The permission level to consult; without one every command
+                is put to the reader, which is what ``ask`` does.
+        """
         self._modes: dict[str, ShellApprovalMode] = {}
         self._allowed: set[str] = set()
+        self._policy = policy
 
     async def get_session_mode(self, session_id: str) -> ShellApprovalMode:
         """Return a session's policy, which is review until one is set."""
@@ -41,7 +56,9 @@ class ShellApprovalMemory:
         self._modes.pop(session_id, None)
 
     async def is_allowed(self, session_id: str, command: str) -> bool:
-        """Return whether this run already approved one exact command."""
+        """Return whether a command may run without asking: by level, or approved by hand."""
+        if self._policy is not None and self._policy.allows_unasked(command):
+            return True
         return command in self._allowed
 
     async def allow_command(self, command: str) -> None:

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

@@ -6,7 +6,7 @@ from collections.abc import Mapping
 
 from zett_agent.agent import AgentRunContext
 from zett_agent.extensions.base import AgentExtension
-from zett_agent.providers.openai import OpenAIProvider
+from zett_agent.model import AgentModel
 from zett_agent.tools.images import view_image
 
 from ...config import ModelConfig
@@ -29,7 +29,7 @@ class ModelCapabilities(AgentExtension):
     #: After the coding bundle, which is what registers the tool being filtered.
     priority = 110
 
-    def __init__(self, models: Mapping[ModelConfig, OpenAIProvider]) -> None:
+    def __init__(self, models: Mapping[ModelConfig, AgentModel]) -> None:
         """Remember the runtime's providers, keyed by the model each one serves.
 
         The mapping is the runtime's own and grows as models are selected, so