zettcode 0.1.9__tar.gz → 0.1.11__tar.gz

{zettcode-0.1.9 → zettcode-0.1.11}/PKG-INFO

@@ -1,14 +1,16 @@
 Metadata-Version: 2.5
 Name: zettcode
-Version: 0.1.9
+Version: 0.1.11
 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: Development Status :: 5 - Production/Stable
 Classifier: Environment :: Console
+Classifier: Environment :: Web Environment
+Classifier: Framework :: FastAPI
 Classifier: Operating System :: MacOS
 Classifier: Operating System :: Microsoft :: Windows :: Windows 10
 Classifier: Operating System :: POSIX :: Linux
@@ -21,6 +23,7 @@ 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: fastapi<1,>=0.115
 Requires-Dist: httpx<1,>=0.27
 Requires-Dist: pydantic<3,>=2
 Requires-Dist: pyperclip<2,>=1.9
@@ -32,7 +35,7 @@ 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.17
+Requires-Dist: zett-agent<0.3,>=0.2.0
 Description-Content-Type: text/markdown
 
 # ZettCode

{zettcode-0.1.9 → zettcode-0.1.11}/pyproject.toml

@@ -8,8 +8,10 @@ license = "MIT"
 authors = [{name = "Chang-LeHung"}]
 keywords = ["agent", "llm", "tui", "terminal", "coding-agent"]
 classifiers = [
-  "Development Status :: 3 - Alpha",
+  "Development Status :: 5 - Production/Stable",
   "Environment :: Console",
+  "Environment :: Web Environment",
+  "Framework :: FastAPI",
   "Operating System :: MacOS",
   "Operating System :: Microsoft :: Windows :: Windows 10",
   "Operating System :: POSIX :: Linux",
@@ -36,6 +38,9 @@ dependencies = [
   "uvicorn>=0.35,<1",
   "httpx>=0.27,<1",
   "websockets>=15,<17",
+  # The HTTP server is part of this package and always installed: `pip install zettcode` writes both console
+  # scripts, so `zettcode-server` may not be a command whose dependencies are an optional extra.
+  "fastapi>=0.115,<1",
   # 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",
@@ -53,11 +58,12 @@ 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]
 zettcode = "zettcode.cli:main"
+zettcode-server = "zettcode.server.cli:main"
 
 [project.urls]
 Repository = "https://github.com/Chang-LeHung/zettcode"

{zettcode-0.1.9 → zettcode-0.1.11}/src/zettcode/__init__.py

@@ -7,21 +7,21 @@ 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.9"
+__version__ = "0.1.11"
 
 #: Where each public name lives; read by :func:`__getattr__` on first use.
 _EXPORTS = {
     "ModelConfig": ".config",
-    "ZettCodeAgent": ".app.agent.agent",
+    "ZettCodeAgent": ".engine.agent",
     "ZettCodeConfig": ".config",
-    "ZettCodeRuntime": ".app.agent.runtime",
+    "ZettCodeEngine": ".engine.core",
 }
 
 
 if TYPE_CHECKING:  # pragma: no cover - for type checkers, not the runtime
-    from .app.agent.agent import ZettCodeAgent
-    from .app.agent.runtime import ZettCodeRuntime
     from .config import ModelConfig, ZettCodeConfig
+    from .engine.agent import ZettCodeAgent
+    from .engine.core import ZettCodeEngine
 
 
 def __getattr__(name: str) -> object:
@@ -44,4 +44,4 @@ def __dir__() -> list[str]:
     return sorted(__all__)
 
 
-__all__ = ["ModelConfig", "ZettCodeAgent", "ZettCodeConfig", "ZettCodeRuntime"]
+__all__ = ["ModelConfig", "ZettCodeAgent", "ZettCodeConfig", "ZettCodeEngine"]

{zettcode-0.1.9 → zettcode-0.1.11}/src/zettcode/app/__init__.py

@@ -18,15 +18,15 @@ _EXPORTS = {
     "TranscriptProjector": ".agent",
     "TranscriptSource": ".ui",
     "TranscriptView": ".ui",
-    "ZettCodeAgent": ".agent",
+    "TerminalAgent": ".agent",
     "ZettCodeApp": ".ui",
     "ZettCodeRoot": ".ui",
-    "ZettCodeRuntime": ".agent",
+    "ZettCodeEngine": ".agent",
 }
 
 
 if TYPE_CHECKING:  # pragma: no cover - for type checkers, not the runtime
-    from .agent import Entry, Transcript, TranscriptProjector, ZettCodeAgent, ZettCodeRuntime
+    from .agent import Entry, TerminalAgent, Transcript, TranscriptProjector, ZettCodeEngine
     from .ui import TranscriptSource, TranscriptView, ZettCodeApp, ZettCodeRoot
 
 
@@ -57,7 +57,7 @@ __all__ = [
     "TranscriptSource",
     "TranscriptView",
     "ZettCodeApp",
-    "ZettCodeAgent",
+    "TerminalAgent",
     "ZettCodeRoot",
-    "ZettCodeRuntime",
+    "ZettCodeEngine",
 ]

{zettcode-0.1.9 → zettcode-0.1.11}/src/zettcode/app/agent/__init__.py

@@ -10,17 +10,18 @@ _EXPORTS = {
     "Entry": ".conversation.entries",
     "Transcript": ".conversation.transcript",
     "TranscriptProjector": ".conversation.projection",
-    "ZettCodeAgent": ".agent",
-    "ZettCodeRuntime": ".runtime",
+    "TerminalAgent": ".agent",
+    "ZettCodeEngine": "zettcode.engine.core",
 }
 
 
 if TYPE_CHECKING:  # pragma: no cover - for type checkers, not the runtime
-    from .agent import ZettCodeAgent
+    from zettcode.engine.core import ZettCodeEngine
+
+    from .agent import TerminalAgent
     from .conversation.entries import Entry
     from .conversation.projection import TranscriptProjector
     from .conversation.transcript import Transcript
-    from .runtime import ZettCodeRuntime
 
 
 def __getattr__(name: str) -> object:
@@ -43,4 +44,4 @@ def __dir__() -> list[str]:
     return sorted(__all__)
 
 
-__all__ = ["Entry", "Transcript", "TranscriptProjector", "ZettCodeAgent", "ZettCodeRuntime"]
+__all__ = ["Entry", "Transcript", "TranscriptProjector", "TerminalAgent", "ZettCodeEngine"]

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

@@ -0,0 +1,69 @@
+"""The terminal's agent: the engine's agent, plus the commands and preferences only a terminal has.
+
+The engine's agent (:class:`zettcode.engine.agent.ZettCodeAgent`) does the work. This subclass adds what the shell
+asks of it that is not work: the slash commands and what plugins contributed (``commands``), and the theme, the pet
+and the status line the reader can change (``settings``). Its engine is built with the terminal's plugin loader, so
+the commands, palettes, pets, presenters and rows of the plugins are there to be read.
+
+This package is also where the terminal is put together from the engine's parts, so it is what names, for the views, the
+engine objects they hold: ``SessionLink`` (the line to the other sessions) and ``StoredSession`` (a session read from
+the store). The views import those names from here and not from the engine.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from zettcode.engine.agent import ZettCodeAgent
+from zettcode.engine.agent.sessions import StoredSession
+from zettcode.engine.core import PluginLoader, ZettCodeEngine
+from zettcode.engine.messenger import Messenger as SessionLink
+
+from .commands import CommandsMixin
+
+if TYPE_CHECKING:  # pragma: no cover - annotations only
+    from zettcode.config import ZettCodeConfig
+    from zettcode.sdk.client import Client
+
+__all__ = ["SessionLink", "StoredSession", "TerminalAgent"]
+
+
+def _terminal_loader() -> PluginLoader:
+    """Return the terminal's plugin loader, imported when an agent is built and not before."""
+    from zettcode.app.plugins.loader import terminal_plugins
+
+    return terminal_plugins
+
+
+class TerminalAgent(CommandsMixin, ZettCodeAgent):
+    """The agent the terminal application drives."""
+
+    _client: Client | None = None
+
+    @property
+    def messenger(self) -> SessionLink | None:
+        """Return the line to the other sessions, or ``None`` when the configuration switches messaging off."""
+        return self.runtime.messenger
+
+    @property
+    def client(self) -> Client:
+        """Return the SDK client over this agent, which is how the shell reaches everything the SDK offers.
+
+        Made on first use and then kept, so the shell and the commands it runs read the same client. The agent still
+        owns closing: the client is a view of it.
+        """
+        if self._client is None:
+            from zettcode.sdk.client import Client
+
+            self._client = Client._around(self)
+        return self._client
+
+    @classmethod
+    async def create(cls, config: ZettCodeConfig) -> TerminalAgent:
+        """Build the engine with the terminal's plugins and start it."""
+        return cls(await ZettCodeEngine.create(config, _terminal_loader()))
+
+    @classmethod
+    def preview(cls, config: ZettCodeConfig) -> TerminalAgent:
+        """Wrap an engine that still has to start, built with the terminal's plugins, so the shell can paint first."""
+        return cls(ZettCodeEngine.preview(config, _terminal_loader()))

{zettcode-0.1.9 → zettcode-0.1.11}/src/zettcode/app/agent/agent/commands.py

@@ -9,23 +9,32 @@ 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.app.plugins.host import HOST_LINK, HostLink
+from zettcode.app.plugins.plugin import TerminalPlugins
+from zettcode.app.plugins.state import TurnSegment, UiRow
+from zettcode.engine.agent.exports import ExportsMixin
 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
+from .settings import AppearanceMixin
 
 #: The words ``/self-compact`` takes after it, or after ``global``.
 _SELF_COMPACT_WORDS = frozenset({"on", "off", "default"})
 
 
-class CommandsMixin(ExportsMixin):
+class CommandsMixin(AppearanceMixin, ExportsMixin):
     """The ``/new``, ``/compact``, and ``/export`` commands, and the plugins' commands, mentions, and rows."""
 
+    @property
+    def terminal_plugins(self) -> TerminalPlugins:
+        """Return what the plugins contributed to the terminal; the engine was built with the terminal's loader."""
+        plugins = self.runtime.plugins
+        if not isinstance(plugins, TerminalPlugins):
+            raise TypeError("This agent's engine was not built with the terminal's plugin loader")
+        return plugins
+
     @property
     def commands(self) -> tuple[Command, ...]:
         """Return the conversation commands the agent owns.
@@ -52,17 +61,12 @@ class CommandsMixin(ExportsMixin):
         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
+        return self.terminal_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
+        return self.terminal_plugins.builtin_commands
 
     @property
     def providers(self) -> tuple[Provider, ...]:
@@ -76,7 +80,7 @@ class CommandsMixin(ExportsMixin):
         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)
+        return ThemeCatalog(self.terminal_plugins.themes, self.runtime.config.themes_dir)
 
     @property
     def pets(self) -> PetCatalog:
@@ -84,13 +88,18 @@ class CommandsMixin(ExportsMixin):
 
         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
+        sources = self.terminal_plugins.pets
         return PetCatalog(sources or bundled_pets())
 
+    @property
+    def turn_segments(self) -> tuple[TurnSegment, ...]:
+        """Return the items of the line a request ends on, the program's own first, then the plugins'."""
+        return self.terminal_plugins.turn_segments
+
     @property
     def plugin_failures(self) -> tuple[str, ...]:
         """Return one message per plugin that could not be loaded or activated."""
-        return self.runtime.plugins.failures
+        return self.terminal_plugins.failures
 
     @property
     def presenters(self) -> Presenters:
@@ -100,12 +109,12 @@ class CommandsMixin(ExportsMixin):
         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)
+        return Presenters(self.terminal_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
+        return self.terminal_plugins.rows
 
     async def _command_new(self, context: CommandContext) -> CommandResult:
         """Start a fresh session."""
@@ -174,10 +183,14 @@ class CommandsMixin(ExportsMixin):
 
     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]
+        hidden = [
+            *(name for name in NAMES if name in self.statusline_hidden),
+            *sorted(self.statusline_hidden - set(NAMES)),
+        ]
         if not hidden:
             return "Status line: every part is shown"
-        return f"Status line: {len(hidden)} of {len(NAMES)} parts hidden ({', '.join(hidden)})"
+        total = len(NAMES) + len({item.name for item in self.turn_segments} - set(NAMES))
+        return f"Status line: {len(hidden)} of {total} 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.

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

@@ -0,0 +1,132 @@
+"""What the reader can change about how the terminal looks: theme, pet, which parts of the status line are shown.
+
+These are the terminal's own preferences. They are kept in the same config file as the engine's settings, and are
+written the same way, which is why this reads the file through the engine's helpers.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import replace
+from pathlib import Path
+
+from zettcode.config_edit import (
+    ConfigEditError,
+    set_pet,
+    set_pet_position,
+    set_statusline,
+    set_theme,
+    write_text_atomically,
+)
+from zettcode.engine.agent.settings import SettingsMixin
+from zettcode.statusline import NAMES
+
+
+class AppearanceMixin(SettingsMixin):
+    """Read and remember the terminal's theme, pet and status line."""
+
+    @property
+    def reduced_motion(self) -> bool:
+        """Return whether decorative animation is disabled."""
+        return self.runtime.config.reduced_motion
+
+    def remember_theme(self, name: str) -> Path:
+        """Write ``[ui] theme = name`` into the config file, so the next start opens in that palette.
+
+        Only that line changes. A config file that does not exist is not created for it: a file with nothing but
+        ``[ui]`` in it would stand where a reader's environment-variable setup is, and say nothing about models.
+
+        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_theme(self._read_config_file(), name, 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
+        return self.config_file
+
+    def remember_pet(self, name: str) -> Path:
+        """Write ``[ui] pet = name`` into the config file, so the next start opens with that pet.
+
+        Only that line changes, and a config file that does not exist is not created for it. The pet in force
+        for this run is the shell's to switch; what this keeps up to date is the setting the shell reads back.
+
+        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(self._read_config_file(), name, 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
+        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."""
+        return frozenset(self.runtime.config.statusline_hidden)
+
+    def remember_statusline(self, shown: Mapping[str, bool]) -> Path:
+        """Write which parts of the header and status line are shown into ``[statusline]``.
+
+        Only the parts that differ from what is in force are written. The file is written first and the
+        running configuration changed second, so a write that fails leaves both as they were; the rows
+        follow at the next paint. A config file that does not exist is not created for it, as for the theme.
+
+        Args:
+            shown: Part name to whether it is shown. A part left out keeps what it has.
+
+        Returns:
+            The file written.
+
+        Raises:
+            ConfigEditError: When there is no config file, it cannot be read or edited safely, or it cannot
+                be written.
+        """
+        hidden = set(self.statusline_hidden)
+        changes = {name: visible for name, visible in shown.items() if (name not in hidden) != visible}
+        if not changes:
+            return self.config_file
+        text = set_statusline(self._read_config_file(), changes, 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
+        hidden = {name for name in hidden if name not in changes} | {name for name, v in changes.items() if not v}
+        # The program's parts in their order, then the ones a plugin added (their names are not in NAMES).
+        ordered = (*(name for name in NAMES if name in hidden), *sorted(hidden - set(NAMES)))
+        self.runtime.config = replace(self.runtime.config, statusline_hidden=ordered)
+        return self.config_file

{zettcode-0.1.9 → zettcode-0.1.11}/src/zettcode/app/agent/conversation/entries.py

@@ -195,6 +195,9 @@ class WaitEntry(TimedEntry):
     tips: tuple[str, ...] = ()
     #: The line the request ended on, written when the row is settled.
     text: str = ""
+    #: The items of the line, one string each, written with the line; the presenter joins them with the separator
+    #: and breaks the row between two, never inside one. Empty means the line is ``text`` alone.
+    parts: tuple[str, ...] = ()
 
 
 @dataclass(slots=True, kw_only=True)

{zettcode-0.1.9 → zettcode-0.1.11}/src/zettcode/app/agent/conversation/presenters.py

@@ -80,6 +80,7 @@ from .text import (
     bounded_rows,
     duration_text,
     elapsed_text,
+    pack_segments,
     quiet_text,
     terminal_safe,
     tip_text,
@@ -106,6 +107,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 +123,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
@@ -483,13 +490,15 @@ class WaitPresenter(Presenter[WaitEntry]):
         """
         if not entry.running:
             settled = entry.text or f"Processed for {elapsed_text(entry.duration or 0.0)}"
+            ink = Style(foreground=theme.muted)
+            room = max(1, width - CONTENT_INDENT)
+            packed = pack_segments(list(entry.parts) or settled.split(f" {SEPARATOR} "), room)
             return [
                 TextLine(),
-                layout_rich_lines(
-                    (TextLine((Span(" " * CONTENT_INDENT + settled, Style(foreground=theme.muted)),)),),
-                    width,
-                    wrap=False,
-                )[0],
+                *(
+                    layout_rich_lines((TextLine((Span(" " * CONTENT_INDENT + row, ink),)),), width, wrap=False)[0]
+                    for row in packed
+                ),
             ]
         spans = list(_running_label(entry.title, theme, frame))
         if entry.duration is not None:
@@ -575,7 +584,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)