zettcode-engine 0.4.1__tar.gz → 0.4.2__tar.gz

{zettcode_engine-0.4.1 → zettcode_engine-0.4.2}/.gitignore

@@ -35,3 +35,8 @@ docs/internal/palettes.html
 
 # The release order is generated from the pyproject.toml files (`make order`); it is not kept in git.
 packages/order.txt
+
+# The desktop and phone apps build the gateway's page into their own folders, and electron-builder writes its
+# installers under release/.
+clients/desktop/renderer/
+clients/desktop/release/

{zettcode_engine-0.4.1 → zettcode_engine-0.4.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: zettcode-engine
-Version: 0.4.1
+Version: 0.4.2
 Summary: The agent core of ZettCode: the runtime over zett-agent, and the leaf types it is written on
 Project-URL: Repository, https://github.com/Chang-LeHung/zettcode
 Author: Chang-LeHung
@@ -18,6 +18,7 @@ Requires-Python: >=3.10
 Requires-Dist: exceptiongroup<2,>=1.2; python_version < '3.11'
 Requires-Dist: pydantic<3,>=2
 Requires-Dist: tomli<3,>=2; python_version < '3.11'
-Requires-Dist: zett-agent<0.3,>=0.2.7
+Requires-Dist: zett-agent<0.3,>=0.2.10
+Requires-Dist: zettcode-tools
 Provides-Extra: tiktoken
 Requires-Dist: tiktoken<1,>=0.12; extra == 'tiktoken'

{zettcode_engine-0.4.1 → zettcode_engine-0.4.2}/pyproject.toml

@@ -17,8 +17,10 @@ classifiers = [
   "Typing :: Typed",
 ]
 dependencies = [
+  # The coding tools the runtime hands the model, a leaf of its own beneath the engine.
+  "zettcode-tools",
   # The runtime this is a core over. Imported directly: the agent, the message types, the approval mode.
-  "zett-agent>=0.2.7,<0.3",
+  "zett-agent>=0.2.10,<0.3",
   # The session store's records are pydantic models.
   "pydantic>=2,<3",
   # The stdlib gained both of these in 3.11; older runtimes take the backports.

{zettcode_engine-0.4.1 → zettcode_engine-0.4.2}/src/zettcode/budget.py

@@ -1,6 +1,6 @@
 """What a context budget is made of: the vocabulary the engine measures with and the views draw with.
 
-A leaf with no imports, shared like :mod:`zettcode.statusline` and :mod:`zettcode.providers`, so the engine that counts
+A leaf with no imports, shared like :mod:`zettcode.statusline_parts` and :mod:`zettcode.providers`, so the engine that counts
 the request and the page that shows the count agree on the names without either importing the other.
 """
 

{zettcode_engine-0.4.1 → zettcode_engine-0.4.2}/src/zettcode/config.py

@@ -112,7 +112,7 @@ SCOPES = frozenset({"global", "workspace", "both"})
 DEFAULT_SCOPE = "both"
 
 #: Keys the ``[plugins]`` table may set.
-PLUGIN_KEYS = frozenset({"enabled", "disable"})
+PLUGIN_KEYS = frozenset({"enabled", "disable", "enable"})
 
 #: Keys the ``[update]`` table may set.
 UPDATE_KEYS = frozenset({"enabled"})
@@ -448,16 +448,18 @@ class ZettCodeConfig:
         self_compaction: Whether a session lets the model request compaction unless it says otherwise;
             the default a new session starts with; the terminal's ``/plugins`` switch writes it.
         statusline_hidden: The names of the header and status-line parts the reader switched off in the
-            ``[statusline]`` table (``ctx = false``); see :mod:`zettcode.statusline`. Every part not named
+            ``[statusline]`` table (``ctx = false``); see :mod:`zettcode.presenters.statusline`. Every part not named
             is shown.
         plugins_enabled: Load third-party plugins published under the
-            ``zettcode.plugins`` entry-point group. The builtin rows always
+            ``zettcode.plugin`` entry-point group. The builtin rows always
             load, so switching this off leaves the shell looking the same.
         disabled_plugins: Entry-point names not to load when
             :attr:`plugins_enabled` is true; a way to switch off one plugin
             without uninstalling it. This is the configuration file's own
             ``[plugins] disable`` list; the names the older switch file adds are merged in by
             :attr:`off_names`, so a switch can tell the two apart.
+        enabled_plugins: Entry-point names to load although the plugin itself says it is off by default
+            (``Plugin.default_enabled``); this is the configuration file's ``[plugins] enable`` list.
         plugin_settings: The ``[plugins.<name>]`` tables, by plugin name, exactly as written. A plugin declares
             what its own keys mean and what they default to (``ctx.settings``); the configuration only carries the
             reader's values, so a key no plugin knows is harmless and a plugin that ships later needs no change
@@ -517,6 +519,8 @@ class ZettCodeConfig:
     statusline_hidden: tuple[str, ...] = ()
     plugins_enabled: bool = True
     disabled_plugins: tuple[str, ...] = ()
+    #: Default-off plugins the reader asked to load; this is ``[plugins] enable``.
+    enabled_plugins: tuple[str, ...] = ()
     #: The reader's own keys for a plugin, from its ``[plugins.<name>]`` table; the plugin supplies the defaults.
     plugin_settings: Mapping[str, Mapping[str, object]] = field(default_factory=dict)
     subagent_enabled: bool = True
@@ -917,17 +921,19 @@ def read_disabled_plugins(path: Path | None = None) -> tuple[str, ...]:
     return tuple(name.strip() for name in names if isinstance(name, str) and name.strip())
 
 
-def _read_disabled_plugins(raw: object, source: Path) -> tuple[str, ...]:
-    """Return the entry-point names the ``[plugins]`` table switches off."""
+def _read_plugin_names(raw: object, source: Path, key: str) -> tuple[str, ...]:
+    """Return the entry-point names a ``[plugins]`` list holds, validating the shape."""
     if raw is None:
         return ()
     if not isinstance(raw, list) or any(not isinstance(entry, str) or not entry.strip() for entry in raw):
-        raise ValueError(f"Config key 'plugins.disable' in {source} must be an array of non-empty strings")
+        raise ValueError(f"Config key 'plugins.{key}' in {source} must be an array of non-empty strings")
     return tuple(entry.strip() for entry in raw)
 
 
-def read_plugins_table(raw: object, source: Path) -> tuple[bool, tuple[str, ...], dict[str, dict[str, object]]]:
-    """Return ``[plugins]`` as ``(enabled, disable, settings)``: the one reading of that table.
+def read_plugins_table(
+    raw: object, source: Path
+) -> tuple[bool, tuple[str, ...], tuple[str, ...], dict[str, dict[str, object]]]:
+    """Return ``[plugins]`` as ``(enabled, disable, enable, settings)``: the one reading of that table.
 
     The configuration and ``zettcode plugin`` both need it, and the second must not build the whole settings object
     (that insists on a model). They used to each write the rules down, and the copies drifted: the command refused a
@@ -938,15 +944,20 @@ def read_plugins_table(raw: object, source: Path) -> tuple[bool, tuple[str, ...]
         source: The file, for messages.
 
     Returns:
-        Whether installed plugins load at all, the entry-point names left out, and each plugin's own settings table by
-        name.
+        Whether installed plugins load at all, the entry-point names left out, the default-off names asked for, and
+        each plugin's own settings table by name.
 
     Raises:
         ValueError: The table, a plugin's table, or a value in one is not what it must be.
     """
     own, settings = _read_plugins(raw, source)
     enabled = _typed(own.get("enabled", True), f"Config key 'plugins.enabled' in {source}", bool)
-    return enabled, _read_disabled_plugins(own.get("disable"), source), settings
+    return (
+        enabled,
+        _read_plugin_names(own.get("disable"), source, "disable"),
+        _read_plugin_names(own.get("enable"), source, "enable"),
+        settings,
+    )
 
 
 def _read_theme_name(raw: object, source: Path) -> str | None:
@@ -1016,7 +1027,9 @@ def load_config(
     ask_user = _read_table(data.get("ask_user"), "ask_user", source, ASK_USER_KEYS)
     skills = _read_table(data.get("skills"), "skills", source, SKILL_KEYS)
     mcp = _read_table(data.get("mcp"), "mcp", source, MCP_KEYS)
-    plugins_enabled, disabled_plugins, plugin_settings = read_plugins_table(data.get("plugins"), source)
+    plugins_enabled, disabled_plugins, enabled_plugins, plugin_settings = read_plugins_table(
+        data.get("plugins"), source
+    )
     transcript = _read_table(data.get("transcript"), "transcript", source, TRANSCRIPT_KEYS)
     update = _read_table(data.get("update"), "update", source, UPDATE_KEYS)
     harness = _read_table(data.get("harness"), "harness", source, HARNESS_KEYS)
@@ -1072,6 +1085,7 @@ def load_config(
         # The configuration file's own list. The legacy switch file's names are read where they are needed
         # (`zettcode.engine.plugins.switches`), so a switch can tell which list it may write.
         disabled_plugins=disabled_plugins,
+        enabled_plugins=enabled_plugins,
         plugin_settings=plugin_settings,
         subagent_enabled=bool(_setting(harness, "subagent", bool, True)),
         subagent_max_iterations=_typed(

{zettcode_engine-0.4.1 → zettcode_engine-0.4.2}/src/zettcode/engine/agent/context.py

@@ -14,7 +14,7 @@ from zett_agent.extensions.events import CompactionEvent
 from zett_agent.messages import AnyMessage, SystemMessage
 from zett_agent.model import ToolDefinition
 
-from zettcode.engine.core import build_system_prompt
+from zettcode.engine.core import ZettCodeEngine, build_system_prompt
 from zettcode.engine.extensions.context import ContextReport
 from zettcode.engine.extensions.usage import UsageSnapshot
 from zettcode.engine.storage import Session
@@ -22,6 +22,23 @@ from zettcode.engine.storage import Session
 from .base import AgentBase
 
 
+async def report_of(runtime: ZettCodeEngine, session_id: str) -> ContextReport | None:
+    """Return what the next request carries, or ``None`` before it was assembled.
+
+    The tokenizer is prepared first; the total is the provider's count of this request, clamped out when it reaches
+    the window, because a window-sized figure is about something else. A rebuilt request is not counted locally:
+    its list carries messages the live request no longer does, so the provider's count is the only honest total.
+    ``window = 0`` means no model is configured; nothing is measured and no share is computed from it.
+    """
+    tokenizer = runtime.tokenizer
+    await tokenizer.prepare()
+    model = runtime.active_model
+    window = 0 if model is None else model.context_window
+    counted = runtime.usage.snapshot(session_id).context_tokens
+    reported = counted if 0 < counted < window else None
+    return runtime.context.report(session_id, window=window, tokenizer=tokenizer, reported=reported)
+
+
 class ContextMixin(AgentBase):
     """Report the request the next turn would send, and compact the conversation behind it."""
 
@@ -36,42 +53,8 @@ class ContextMixin(AgentBase):
         return self.runtime.usage.snapshot(self.session_id)
 
     async def context_report(self) -> ContextReport | None:
-        """Return what the next request carries by source, or None before the first call.
-
-        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()
-        model = self.runtime.active_model
-        # No model configured means no window to measure against. Nothing is reported either way: a request is
-        # refused before one is assembled, so the report is None and no share is ever computed from this 0.
-        window = 0 if model is None else 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=window,
-            tokenizer=tokenizer,
-            reported=reported,
-        )
+        """Return what the next request carries, or ``None`` before it was assembled."""
+        return await report_of(self.runtime, self.session_id)
 
     async def ensure_compactable(self) -> None:
         """Refuse a compaction that would do nothing, before a row is put up for it.

{zettcode_engine-0.4.1 → zettcode_engine-0.4.2}/src/zettcode/engine/agent/turns.py

@@ -19,7 +19,6 @@ from zett_agent.resume import ResumePoint
 
 from zettcode.engine.dialogue.side import ORIGIN, READER, SIDE, WATCHED, question, watched_by
 from zettcode.prompt import MentionPart, PromptPart, carries_image, model_text_part, plain_text
-from zettcode.relay import Relayed
 
 from .base import AgentBase
 
@@ -57,9 +56,47 @@ class TurnsMixin(AgentBase):
         side: bool = False,
         origin: str = READER,
         watched: bool | None = None,
-        relayed: Relayed | None = None,
+        incoming: UserMessage | None = None,
         cache: CacheMode | str | None = None,
     ) -> AsyncIterator[AgentEvent]:
+        """Run one turn, counting it as a running request for as long as its events are read.
+
+        The count is what tells an external event whether it can steer this request or has to wait for the next turn
+        (see :mod:`zettcode.engine.delivery`). A side question is not a request of the conversation: nothing steers
+        into it, and it does not keep a follow-up waiting.
+        """
+        if side:
+            async with aclosing(
+                self._stream(
+                    parts, hint=hint, side=True, origin=origin, watched=watched, incoming=incoming, cache=cache
+                )
+            ) as events:
+                async for event in events:
+                    yield event
+            return
+        self.runtime.run_started()
+        try:
+            async with aclosing(
+                self._stream(
+                    parts, hint=hint, side=False, origin=origin, watched=watched, incoming=incoming, cache=cache
+                )
+            ) as events:
+                async for event in events:
+                    yield event
+        finally:
+            self.runtime.run_finished()
+
+    async def _stream(
+        self,
+        parts: Sequence[PromptPart],
+        *,
+        hint: str | None = None,
+        side: bool = False,
+        origin: str = READER,
+        watched: bool | None = None,
+        incoming: UserMessage | None = None,
+        cache: CacheMode | str | None = None,
+    ) -> AsyncGenerator[AgentEvent, None]:
         """Run one turn with the selected session, model, and reasoning effort.
 
         Args:
@@ -73,8 +110,8 @@ class TurnsMixin(AgentBase):
                 was typed and a restored session shows it.
             side: Ask without letting the exchange join the conversation; see
                 :mod:`zettcode.engine.dialogue.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.
+            incoming: The turn is a message another session sent, already framed by the part that owns the
+                conversation with it. It is what the model reads, and ``parts`` and ``hint`` are not used.
             cache: How this request may use the provider's prompt cache: ``"read_write"`` (the default) extends
                 it, ``"read"`` reuses a warm prefix without marking this request's new content for caching, and
                 ``"off"`` sends no cache directive at all. A side question starts at ``"read"`` unless told
@@ -103,8 +140,8 @@ class TurnsMixin(AgentBase):
                     "AsyncGenerator[AgentEvent]",
                     client.stream(
                         self.request(parts, hint=hint, side=side, origin=origin, watched=watched)
-                        if relayed is None
-                        else relayed.message(),
+                        if incoming is None
+                        else incoming,
                         config=AgentRunConfig(
                             session_id=session_id,
                             cache_mode=cache_mode_of(cache, side=side),
@@ -297,12 +334,21 @@ class TurnsMixin(AgentBase):
             if not message.text.strip() and not message.parts:
                 return False
             payload = {"message": message}
-        try:
-            agent = self.runtime.started.agent
-        except RuntimeError:
-            return False
-        accepted = agent.emit_external_event(
-            ExternalEvent(name=STEERING_MESSAGE_EVENT_NAME, payload=payload),
-            config=AgentRunConfig(session_id=self.session_id),
-        )
-        return bool(accepted)
+        return steer_in_flight(self.runtime, self.session_id, payload)
+
+
+def steer_in_flight(runtime: object, session_id: str, payload: dict[str, object]) -> bool:
+    """Emit the steering event for one message, and say whether the running request took it.
+
+    The engine's own delivery (:class:`zettcode.engine.delivery.Delivery`) and the agent's ``steer`` both come through
+    here, so the one rule for what a request accepts has one home.
+    """
+    try:
+        agent = runtime.started.agent  # type: ignore[attr-defined]
+    except RuntimeError:
+        return False
+    accepted = agent.emit_external_event(
+        ExternalEvent(name=STEERING_MESSAGE_EVENT_NAME, payload=payload),
+        config=AgentRunConfig(session_id=session_id),
+    )
+    return bool(accepted)