zettcode 0.1.5__tar.gz → 0.1.7__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: zettcode
-Version: 0.1.5
+Version: 0.1.7
 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,13 +21,17 @@ 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: 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.2,>=0.1.15
 Description-Content-Type: text/markdown
 

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

@@ -29,6 +29,13 @@ dependencies = [
   "pydantic>=2,<3",
   "pyperclip>=1.9,<2",
   "setproctitle>=1.3.7,<2; os_name == 'posix'",
+  # The session broker is an ordinary web server: a Starlette application served by uvicorn. A session reaches it
+  # with httpx (to send) and websockets (to be reachable). The floors are the oldest versions the broker's tests
+  # were run against; all of them arrive through the runtime today and are declared so that is not luck.
+  "starlette>=0.48,<2",
+  "uvicorn>=0.35,<1",
+  "httpx>=0.27,<1",
+  "websockets>=15,<17",
   # 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",

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

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

@@ -0,0 +1,54 @@
+"""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
+from ..storage import SessionLocked
+
+
+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
+
+    @property
+    def session_locked(self) -> bool:
+        """Return whether another process has the active session open, so that this one may only read it.
+
+        Every session is locked by the process that has it open (see :mod:`..storage.locks`). A session this
+        process started is always its own; one it resumed may be somebody else's, and then it is shown and
+        nothing is written to it: no turn, no title, no compaction.
+        """
+        return self.runtime.session_locked
+
+    def retake_session(self) -> bool:
+        """Try again to lock the active session; return whether this process holds it now."""
+        return self.runtime.retake_session()
+
+    def require_session(self) -> None:
+        """Refuse to go on when the active session is another process's.
+
+        Raises:
+            SessionLocked: The lock is not held. A ``ValueError``, which the shell shows as a line in the
+                conversation.
+        """
+        if self.session_locked:
+            raise SessionLocked()

{zettcode-0.1.5 → zettcode-0.1.7}/src/zettcode/app/agent/agent/commands.py

@@ -8,6 +8,7 @@ agent is where the shell asks for everything the runtime loaded.
 from __future__ import annotations
 
 from ....plugins import UiRow
+from ....providers import BUILTIN_PROVIDERS, Provider, merge_providers
 from ...commands import Command, CommandContext, CommandResult
 from ..dialogue.mentions import MentionProvider
 from .exports import ExportsMixin
@@ -44,6 +45,11 @@ class CommandsMixin(ExportsMixin):
         """Return the ``@`` resource providers the installed plugins registered."""
         return self.runtime.plugins.mentions
 
+    @property
+    def providers(self) -> tuple[Provider, ...]:
+        """Return the hosts ``/config`` can offer: the built-in ones, then the plugins' own."""
+        return merge_providers(BUILTIN_PROVIDERS, self.runtime.plugins.providers)
+
     @property
     def plugin_failures(self) -> tuple[str, ...]:
         """Return one message per plugin that could not be loaded or activated."""

{zettcode-0.1.5 → zettcode-0.1.7}/src/zettcode/app/agent/agent/context.py

@@ -80,9 +80,11 @@ class ContextMixin(AgentBase):
             worth replacing.
 
         Raises:
+            SessionLocked: Another process has this session open, and a checkpoint is a write.
             ValueError: When the newest checkpoint already covers the branch —
                 a second pass would summarize nothing but the checkpoint.
         """
+        self.require_session()
         if self._compacted_at_the_head():
             raise ValueError("Already compacted; send a message before compacting again")
         await self.runtime.start()

{zettcode-0.1.5 → zettcode-0.1.7}/src/zettcode/app/agent/agent/prompt.py

@@ -23,6 +23,9 @@ class MentionPart:
     """
 
     token: str
+    #: The words the model reads in the token's place, when it is not to see the token itself. ``None``
+    #: leaves the token as typed; the typed text is what the transcript and the store keep either way.
+    says: str | None = None
 
 
 #: One piece of a user turn, in the order it was written: a run of text, or the
@@ -39,6 +42,29 @@ def plain_text_part(part: PromptPart) -> str:
     return ""
 
 
+def model_text_part(part: PromptPart) -> str:
+    """Return the text one part is to the model: a reference that was resolved reads as what it says."""
+    if isinstance(part, MentionPart) and part.says is not None:
+        return part.says
+    return plain_text_part(part)
+
+
+def mention_parts(parts: Sequence[PromptPart], mentions: MentionRegistry) -> tuple[PromptPart, ...]:
+    """Return a turn with each reference that has words of its own carrying them.
+
+    ``@work`` typed for a session that is running is not a word the model knows, so it is put in the
+    model's reading as ``session "work"`` and :func:`mention_hint` explains it. Anything else — a skill, a
+    file, a name nobody has — keeps the token as it was typed.
+    """
+    if not mentions.providers:
+        return tuple(parts)
+    resolved: list[PromptPart] = []
+    for part in parts:
+        says = mentions.rename_token(part.token) if isinstance(part, MentionPart) else None
+        resolved.append(MentionPart(part.token, says) if says is not None and isinstance(part, MentionPart) else part)
+    return tuple(resolved)
+
+
 def plain_text(parts: Sequence[PromptPart]) -> str:
     """Return a turn as the reader typed it, with its ``@`` tokens back in place."""
     return "".join(plain_text_part(part) for part in parts)

{zettcode-0.1.5 → zettcode-0.1.7}/src/zettcode/app/agent/agent/sessions.py

@@ -180,7 +180,11 @@ class SessionsMixin(ContextMixin):
         Args:
             title: Name to store; surrounding space is trimmed, and a blank or
                 over-long name is rejected by the store.
+
+        Raises:
+            SessionLocked: Another process has this session open.
         """
+        self.require_session()
         await self.runtime.persistence.set_title(self.session_id, title)
         return title.strip()
 
@@ -199,6 +203,8 @@ class SessionsMixin(ContextMixin):
         """
         if self.runtime.persistence.session_title(session_id) is not None:
             return None
+        if session_id == self.session_id and self.session_locked:
+            return None  # a nicety, and not one that is worth writing into a session that is not ours
         session = self.runtime.persistence.read(session_id)
         branch = session.branch()
         question = next(

zettcode-0.1.7/src/zettcode/app/agent/agent/settings.py

@@ -0,0 +1,164 @@
+"""What the reader can change about how the agent runs: model, reasoning effort, shell permission."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from pathlib import Path
+
+from zett_agent.model import ReasoningEffort
+
+from ....config import ModelConfig, _read_models
+from ....config_edit import (
+    ConfigEditError,
+    add_model,
+    file_entries,
+    remove_model,
+    replace_model,
+    write_text_atomically,
+)
+from ....paths import config_path
+from ..permission import PERMISSION_LEVELS, Permission
+from .base import AgentBase
+
+
+class SettingsMixin(AgentBase):
+    """Read and change the model, the reasoning effort, and how much of the shell may run unasked."""
+
+    @property
+    def reduced_motion(self) -> bool:
+        """Return whether decorative animation is disabled."""
+        return self.runtime.config.reduced_motion
+
+    @property
+    def models(self) -> tuple[ModelConfig, ...]:
+        """Return the models available for selection."""
+        return self.runtime.config.models
+
+    @property
+    def active_model(self) -> ModelConfig:
+        """Return the model selected for the next turn."""
+        return self.runtime.active_model
+
+    def find_model(self, name: str) -> ModelConfig | None:
+        """Return the configured model a recorded name stands for, if exactly one does."""
+        return self.runtime.find_model(name)
+
+    def use_model(self, name: str | ModelConfig) -> ModelConfig:
+        """Select a configured model for subsequent turns."""
+        return self.runtime.use_model(name)
+
+    # -- the models in the config file --------------------------------------------------
+    @property
+    def config_file(self) -> Path:
+        """Return the file the models are read from and written to."""
+        return config_path()
+
+    def _read_config_file(self) -> str:
+        """Return the config file's text, or raise :class:`ConfigEditError` saying why not."""
+        path = self.config_file
+        try:
+            return path.read_text(encoding="utf-8")
+        except FileNotFoundError as error:
+            raise ConfigEditError(f"{path} does not exist") from error
+        except (OSError, UnicodeDecodeError) as error:
+            raise ConfigEditError(f"{path} cannot be read: {error}") from error
+
+    def file_models(self) -> tuple[tuple[ModelConfig, Mapping[str, object]], ...]:
+        """Return each model in the file with the keys the file writes for it.
+
+        The file is the source of truth for editing, not the models the session started with: a
+        reader may have changed it by hand since. The keys are what is *written* — a token left to
+        an environment variable is absent — which is what a rewrite has to start from.
+
+        Raises:
+            ConfigEditError: When the file cannot be read, is not valid, or lays its models out in
+                a way the editor cannot safely change.
+        """
+        text = self._read_config_file()
+        path = self.config_file
+        entries = file_entries(text, where=path)
+        try:
+            models = _read_models(entries, path)
+        except ValueError as error:
+            raise ConfigEditError(str(error)) from error
+        return tuple(zip(models, entries, strict=True))
+
+    def _commit_models(self, text: str) -> ModelConfig:
+        """Write the edited text, then make the running session use what it now says.
+
+        The file is written first and the session is changed second, so a write that fails leaves
+        the session as it was, and what the session holds is always something the file holds too.
+        """
+        path = self.config_file
+        try:
+            write_text_atomically(path, text)
+        except OSError as error:
+            raise ConfigEditError(f"{path} could not be written: {error}") from error
+        models = _read_models(file_entries(text, where=path), path)
+        return self.runtime.replace_models(models)
+
+    def add_configured_model(self, entry: Mapping[str, object]) -> ModelConfig:
+        """Add one ``[[models]]`` entry to the file and to this session; return the new model.
+
+        The model in use does not change: adding is not choosing. The new one appears in ``/model``.
+
+        Args:
+            entry: The keys of the new model as the file writes them.
+
+        Raises:
+            ConfigEditError: When the entry is not a model that can be called, or the file cannot
+                be edited. Nothing is written then.
+        """
+        text = add_model(self._read_config_file(), entry, where=self.config_file)
+        self._commit_models(text)
+        return self.runtime.config.models[-1]
+
+    def update_configured_model(self, index: int, entry: Mapping[str, object]) -> ModelConfig:
+        """Rewrite model number ``index`` (from zero) of the file as ``entry``; return the result."""
+        text = replace_model(self._read_config_file(), index, entry, where=self.config_file)
+        self._commit_models(text)
+        return self.runtime.config.models[index]
+
+    def remove_configured_model(self, index: int) -> ModelConfig:
+        """Remove model number ``index`` (from zero) from the file and this session.
+
+        Returns:
+            The model in use afterwards: the one before unless it was the one removed.
+
+        Raises:
+            ConfigEditError: When it is the only model, or the file cannot be edited.
+        """
+        text = remove_model(self._read_config_file(), index, where=self.config_file)
+        return self._commit_models(text)
+
+    @property
+    def effort(self) -> str:
+        """Return the reasoning effort the next request will ask for."""
+        return self.runtime.effort.value
+
+    @property
+    def efforts(self) -> tuple[str, ...]:
+        """Return the reasoning levels the runtime accepts, cheapest first."""
+        return tuple(level.value for level in ReasoningEffort)
+
+    def use_effort(self, name: str) -> str:
+        """Select a reasoning level for later requests and return its value."""
+        return self.runtime.use_effort(name).value
+
+    def approve_all_shell_commands(self) -> None:
+        """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)

{zettcode-0.1.5 → zettcode-0.1.7}/src/zettcode/app/agent/agent/turns.py

@@ -12,9 +12,10 @@ from zett_agent.extensions.external import ExternalEvent
 from zett_agent.extensions.steering import STEERING_MESSAGE_EVENT_NAME
 from zett_agent.messages import ImageBytesSource, ImageContent, TextContent, UserMessage
 
+from ..dialogue.relay import Relayed
 from ..dialogue.side import SIDE, question
 from .base import AgentBase
-from .prompt import MentionPart, PromptPart, carries_image, plain_text, plain_text_part
+from .prompt import MentionPart, PromptPart, carries_image, model_text_part, plain_text
 
 
 class TurnsMixin(AgentBase):
@@ -30,6 +31,7 @@ class TurnsMixin(AgentBase):
         *,
         hint: str | None = None,
         side: bool = False,
+        relayed: Relayed | None = None,
     ) -> AsyncIterator[AgentEvent]:
         """Run one turn with the selected session, model, and reasoning effort.
 
@@ -43,14 +45,21 @@ class TurnsMixin(AgentBase):
                 what was typed and a restored session shows it.
             side: Ask without letting the exchange join the conversation; see
                 :mod:`zettcode.app.agent.side`.
+            relayed: The turn is a message another session sent. It is what the model reads
+                (with where it came from), and ``parts`` and ``hint`` are not used.
+
+        Raises:
+            SessionLocked: Another process has the session open. Checked before anything else, and a side
+                question is no exception: the store records it even though it never replays it.
         """
+        self.require_session()
         await self.runtime.start()
         client = self.runtime.started
         used = self.runtime.active_model.shown_name
         session_id = self.session_id
         try:
             async for event in client.stream(
-                self.request(parts, hint=hint, side=side),
+                self.request(parts, hint=hint, side=side) if relayed is None else relayed.message(),
                 config=AgentRunConfig(session_id=session_id),
                 model=self.runtime.provider,
                 reasoning_effort=self.runtime.effort,
@@ -105,11 +114,12 @@ class TurnsMixin(AgentBase):
             text = plain_text(parts)
             if hint is None:
                 return text
-            return UserMessage(content=f"{text}\n\n{hint}", attributes={"prompt": text})
+            said = "".join(model_text_part(part) for part in parts)
+            return UserMessage(content=f"{said}\n\n{hint}", attributes={"prompt": text})
         content: list[TextContent | ImageContent] = []
         for part in parts:
             if isinstance(part, (str, MentionPart)):
-                text = plain_text_part(part)
+                text = model_text_part(part)
                 if text:
                     content.append(TextContent(text))
                 continue

zettcode-0.1.7/src/zettcode/app/agent/conversation/changes.py

@@ -0,0 +1,64 @@
+"""What a request did to the files, added up: the data behind the summary at the end of a turn."""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+from pathlib import PurePath
+
+from .entries import DeleteEntry, Entry, EntryStatus, FileChangeEntry, FileSummary
+
+
+def shown_path(path: str, workspace: PurePath | None) -> str:
+    """Return a file as the reader knows it: relative to the workspace when it is inside it.
+
+    The model names the same file as ``app.py`` in one call and as ``/work/app.py`` in the next, and
+    the summary must not count them twice. Only the text is looked at, never the disk.
+
+    Args:
+        path: The path as the call named it.
+        workspace: The directory the session works in, or ``None`` to leave every path as it is.
+    """
+    if workspace is None or not path:
+        return path
+    candidate = PurePath(path)
+    # Rooted, not only absolute: on Windows ``/work/a.py`` has a root and no drive, which is not
+    # "absolute" to pathlib, and it still has to be compared with the workspace it is inside.
+    if candidate.is_absolute() or candidate.root:
+        try:
+            return candidate.relative_to(workspace).as_posix()
+        except ValueError:
+            return path
+    return candidate.as_posix()
+
+
+def changed_files(entries: Iterable[Entry], workspace: PurePath | None = None) -> tuple[FileSummary, ...]:
+    """Return the files a run of entries changed, each once, in the order they were first touched.
+
+    Only a call that *succeeded* counts: a failed edit changed nothing, and a skipped one never ran.
+    A file changed several times is one row with the totals. A file deleted and then written again is
+    a file that exists, counted from the write, and one written and then deleted is deleted.
+
+    Args:
+        entries: The entries of one request, in order; anything that is not a file change is ignored.
+        workspace: The directory paths are shown relative to.
+    """
+    order: list[str] = []
+    totals: dict[str, FileSummary] = {}
+    for entry in entries:
+        if not isinstance(entry, (FileChangeEntry, DeleteEntry)) or entry.status is not EntryStatus.COMPLETED:
+            continue
+        if not entry.path:
+            continue
+        path = shown_path(entry.path, workspace)
+        if path not in totals:
+            order.append(path)
+            totals[path] = FileSummary(path)
+        current = totals[path]
+        if isinstance(entry, DeleteEntry):
+            totals[path] = FileSummary(path, deleted=True)
+            continue
+        base = FileSummary(path) if current.deleted else current
+        totals[path] = FileSummary(
+            path, base.added + entry.added, base.removed + getattr(entry, "removed", 0), deleted=False
+        )
+    return tuple(totals[path] for path in order)