zettcode 0.1.6__tar.gz → 0.1.8__tar.gz

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

@@ -20,3 +20,8 @@ node_modules/
 docs/.vitepress/dist/
 docs/.vitepress/cache/
 docs/.vitepress/.temp/
+
+# 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.
+docs/internal/palettes.html

{zettcode-0.1.6 → zettcode-0.1.8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: zettcode
-Version: 0.1.6
+Version: 0.1.8
 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,14 +21,18 @@ 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: zett-agent<0.2,>=0.1.15
+Requires-Dist: websockets<17,>=15
+Requires-Dist: zett-agent<0.2,>=0.1.17
 Description-Content-Type: text/markdown
 
 <p align="center">

{zettcode-0.1.6 → zettcode-0.1.8}/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",
@@ -46,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.15,<0.2",
+  "zett-agent>=0.1.17,<0.2",
 ]
 
 [project.scripts]

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

{zettcode-0.1.6 → zettcode-0.1.8}/src/zettcode/app/agent/agent/__init__.py

@@ -22,7 +22,8 @@ is the composition and the lifecycle — building the runtime, and closing it.
 
 from __future__ import annotations
 
-from ....config import ZettCodeConfig
+from zettcode.config import ZettCodeConfig
+
 from ..runtime import ZettCodeRuntime
 from .commands import CommandsMixin
 from .context import ContextMixin

zettcode-0.1.8/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.8/src/zettcode/app/agent/agent/commands.py

@@ -0,0 +1,214 @@
+"""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 zettcode.app.commands import Command, CommandContext, CommandHost, CommandResult
+from zettcode.app.pets import PetCatalog, bundled_pets
+from zettcode.plugins import UiRow
+from zettcode.plugins.services import HOST_LINK, HostLink
+from zettcode.providers import BUILTIN_PROVIDERS, Provider, merge_providers
+from zettcode.statusline import NAMES, unknown
+from zettcode.tui import ThemeCatalog
+
+from ..conversation.presenters import Presenters
+from ..dialogue.mentions import MentionProvider
+from .exports import ExportsMixin
+
+#: The words ``/self-compact`` takes after it, or after ``global``.
+_SELF_COMPACT_WORDS = frozenset({"on", "off", "default"})
+
+
+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),
+        )
+
+    def attach_host(self, host: CommandHost) -> None:
+        """Tell the plugins where the shell is, so the words their commands offer can follow the session."""
+        link = self.runtime.plugins.find(HOST_LINK, HostLink)
+        if link is not None:
+            link.attach(host)
+
+    @property
+    def plugin_commands(self) -> tuple[Command, ...]:
+        """Return the commands the installed plugins registered, not counting the built-in ones.
+
+        The shell keeps them after everything built in, so a plugin cannot take over a built-in name;
+        plugin-versus-plugin duplicates are rejected when the plugins load.
+        """
+        return self.runtime.plugins.installed_commands
+
+    @property
+    def builtin_plugin_commands(self) -> tuple[Command, ...]:
+        """Return the commands the program's own plugins registered: ``/resume``, ``/model``, ``/usage`` and the rest."""
+        return self.runtime.plugins.builtin_commands
+
+    @property
+    def plugin_mentions(self) -> tuple[MentionProvider, ...]:
+        """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 themes(self) -> ThemeCatalog:
+        """Return every palette that can be asked for by name: the plugins', then the reader's own files.
+
+        Built fresh each time it is asked: it lists names and builds nothing, and the reader's directory may have
+        gained a file since the last look.
+        """
+        return ThemeCatalog(self.runtime.plugins.themes, self.runtime.config.themes_dir)
+
+    @property
+    def pets(self) -> PetCatalog:
+        """Return every pet that can be asked for by name: the built-in plugin's, then any other plugin's.
+
+        A plugin bundle that offers none (one built by hand, without the built-in plugin) gets the program's own.
+        """
+        sources = self.runtime.plugins.pets
+        return PetCatalog(sources or bundled_pets())
+
+    @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 presenters(self) -> Presenters:
+        """Return how this run draws entries: the built-in presenters, and any a plugin outranks them with.
+
+        Built from the bundle rather than from a module-level default for the same reason the palettes are: the
+        program's own rows are registered through the plugin route, so a plugin that draws a kind or a family of
+        rows reaches the transcript without a second path only plugins could not take.
+        """
+        return Presenters(self.runtime.plugins.presenters)
+
+    @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}`")
+
+    def self_compaction_summary(self) -> str:
+        """Say in one line whether self-compaction is on here, where that comes from, and what the default is."""
+        state = "on" if self.self_compaction else "off"
+        default = "on" if self.self_compaction_default else "off"
+        if self.self_compaction_choice is None:
+            return f"Self-compaction is {state}: this session follows the default ({default})"
+        return f"Self-compaction is {state}: this session chose it; the default is {default}"
+
+    def self_compact_report(self) -> str:
+        """Say what self-compaction is, whether it is on here, and where that comes from."""
+        choice = self.self_compaction_choice
+        default = "on" if self.self_compaction_default else "off"
+        state = "on" if self.self_compaction else "off"
+        source = (
+            f"this session chose it; the config default is **{default}**"
+            if choice is not None
+            else "following the config default (`[compaction] self`)"
+        )
+        return (
+            f"Self-compaction is **{state}** ({source}).\n\n"
+            "When on, the model gets a `compact_context` tool and can summarize its own earlier conversation "
+            "when it judges the detail is no longer needed. The current turn is always kept. "
+            "`/compact` and the automatic threshold work either way.\n\n"
+            "`/self-compact on|off` sets this session; `default` hands it back to the config; "
+            "`global on|off` changes the default for every session that has not chosen."
+        )
+
+    def change_self_compaction(self, argument: str) -> str:
+        """Read or change self-compaction from the words ``/self-compact`` takes, and say what now applies.
+
+        ``on``, ``off`` and ``default`` set this session's own choice; ``global on`` and ``global off``
+        write the default for every session into the config file. A failed write is never reported as saved.
+
+        Raises:
+            ValueError: The words are not ones the command takes, or the change could not be saved.
+        """
+        words = argument.lower().split()
+        scope = "session"
+        if words[:1] == ["global"]:
+            scope, words = "global", words[1:]
+        usage = ValueError("Usage: /self-compact [on|off|default] or /self-compact global on|off")
+        if len(words) > 1 or (scope == "global" and not words) or (words and words[0] not in _SELF_COMPACT_WORDS):
+            raise usage
+        if scope == "global":
+            if words[0] == "default":
+                raise usage
+            self.remember_self_compaction(words[0] == "on")
+        elif words:
+            self.use_self_compaction({"on": True, "off": False, "default": None}[words[0]])
+        return self.self_compact_report()
+
+    def statusline_summary(self) -> str:
+        """Say in one line which parts of the header and the status line are hidden."""
+        hidden = [name for name in NAMES if name in self.statusline_hidden]
+        if not hidden:
+            return "Status line: every part is shown"
+        return f"Status line: {len(hidden)} of {len(NAMES)} parts hidden ({', '.join(hidden)})"
+
+    def change_statusline(self, argument: str) -> str:
+        """Hide or show parts of the header and status line from the words ``/statusline`` takes.
+
+        ``hide <name>...`` and ``show <name>...`` change the named parts, and ``show all`` brings every one
+        back. The change is written to ``[statusline]`` in the config file, and nothing is changed when any
+        name is not a part.
+
+        Raises:
+            ValueError: The words are not ones the command takes, or the change could not be saved.
+        """
+        words = argument.lower().split()
+        usage = ValueError(
+            f"Usage: /statusline [hide|show] <part>... or /statusline show all; parts: {', '.join(NAMES)}"
+        )
+        if len(words) < 2 or words[0] not in {"hide", "show"}:
+            raise usage
+        visible = words[0] == "show"
+        names = list(NAMES) if visible and words[1:] == ["all"] else words[1:]
+        if stray := unknown(names):
+            raise ValueError(f"No such part: {', '.join(stray)}. Parts: {', '.join(NAMES)}")
+        self.remember_statusline({name: visible for name in names})
+        return self.statusline_summary()
+
+    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.6 → zettcode-0.1.8}/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.6 → zettcode-0.1.8}/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.6 → zettcode-0.1.8}/src/zettcode/app/agent/agent/sessions.py

@@ -8,15 +8,17 @@ the rest of the shell does.
 
 from __future__ import annotations
 
+from collections.abc import Sequence
 from dataclasses import dataclass
 from pathlib import Path
 
 from zett_agent.messages import AssistantMessage, UserMessage
+from zett_agent.model import ReasoningEffort
 
 from ..conversation.replay import Replayed, replay
 from ..conversation.transcript import Transcript
 from ..dialogue.title import summarize_title
-from ..storage import Session, SessionInfo
+from ..storage import Session, SessionInfo, SessionStats
 from .context import ContextMixin
 
 #: The name a session shows before the agent has given it a title.
@@ -170,6 +172,13 @@ class SessionsMixin(ContextMixin):
         """List persisted session metadata by recent activity."""
         return await self.runtime.persistence.list_sessions(limit=limit)
 
+    async def session_stats(self, sessions: Sequence[SessionInfo]) -> dict[str, SessionStats]:
+        """Return the entry count and token totals of listed sessions, keyed by session id.
+
+        A session missing from the answer has no totals to show.
+        """
+        return await self.runtime.persistence.session_stats([session.session_id for session in sessions])
+
     async def rename_session(self, title: str) -> str:
         """Store a display title for the active session and return it cleaned.
 
@@ -180,7 +189,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 +212,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(
@@ -212,7 +227,9 @@ class SessionsMixin(ContextMixin):
         if not question or not answer:
             return None
         await self.runtime.start()
-        title = await summarize_title(self.runtime.provider, question=question, answer=answer)
+        # A level the model takes, so naming the session cannot be what fails on an endpoint that lacks `low`.
+        effort = self.runtime.active_model.accepted_effort(ReasoningEffort.LOW)
+        title = await summarize_title(self.runtime.provider, question=question, answer=answer, effort=effort)
         if title is None:
             return None
         await self.runtime.persistence.set_title(session_id, title)