zettcode 0.1.8__tar.gz → 0.1.9__tar.gz

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

@@ -21,6 +21,9 @@ docs/.vitepress/dist/
 docs/.vitepress/cache/
 docs/.vitepress/.temp/
 
+# The TypeScript client is built from its sources; only dist/ is published.
+clients/typescript/dist/
+
 # 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.

zettcode-0.1.9/PKG-INFO

@@ -0,0 +1,60 @@
+Metadata-Version: 2.5
+Name: zettcode
+Version: 0.1.9
+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: Environment :: Console
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: Microsoft :: Windows :: Windows 10
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+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: 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.17
+Description-Content-Type: text/markdown
+
+# ZettCode
+
+A focused terminal coding agent powered by [zett-agent](https://pypi.org/project/zett-agent/): it reads and edits your
+code, runs commands with your permission, and is driven by a model you choose. The repository also ships a Python SDK
+and an HTTP server.
+
+```bash
+pip install zettcode
+zettcode
+```
+
+- [The guide](https://chang-lehung.github.io/zettcode/) — commands, keys, plugins, configuration
+- [The SDK](https://chang-lehung.github.io/zettcode/sdk/) — drive the agent from Python
+- [The server](https://chang-lehung.github.io/zettcode/server/) — drive it over HTTP
+
+The full README, with the screenshots, is at the root of the repository.
+
+```python
+import zettcode.sdk as zc
+
+result = await zc.prompt("summarize the README", permission="deny")
+print(result.text)
+```

zettcode-0.1.9/README.md

@@ -0,0 +1,23 @@
+# ZettCode
+
+A focused terminal coding agent powered by [zett-agent](https://pypi.org/project/zett-agent/): it reads and edits your
+code, runs commands with your permission, and is driven by a model you choose. The repository also ships a Python SDK
+and an HTTP server.
+
+```bash
+pip install zettcode
+zettcode
+```
+
+- [The guide](https://chang-lehung.github.io/zettcode/) — commands, keys, plugins, configuration
+- [The SDK](https://chang-lehung.github.io/zettcode/sdk/) — drive the agent from Python
+- [The server](https://chang-lehung.github.io/zettcode/server/) — drive it over HTTP
+
+The full README, with the screenshots, is at the root of the repository.
+
+```python
+import zettcode.sdk as zc
+
+result = await zc.prompt("summarize the README", permission="deny")
+print(result.text)
+```

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

@@ -5,7 +5,6 @@ readme = "README.md"
 requires-python = ">=3.10"
 dynamic = ["version"]
 license = "MIT"
-license-files = ["LICENSE"]
 authors = [{name = "Chang-LeHung"}]
 keywords = ["agent", "llm", "tui", "terminal", "coding-agent"]
 classifiers = [
@@ -19,6 +18,7 @@ classifiers = [
   "Programming Language :: Python :: 3.12",
   "Programming Language :: Python :: 3.13",
   "Programming Language :: Python :: 3.14",
+  "Programming Language :: Python :: 3.15",
   "Typing :: Typed",
 ]
 dependencies = [
@@ -75,53 +75,8 @@ path = "src/zettcode/__init__.py"
 packages = ["src/zettcode"]
 
 [tool.hatch.build.targets.sdist]
-include = ["/src", "/README.md", "/README.zh-CN.md", "/LICENSE", "/pyproject.toml"]
-
-[dependency-groups]
-dev = [
-  # Unlike the conditional runtime deps, these are installed on every
-  # interpreter so mypy can check the 3.10 branch of ``_compat`` for real.
-  "exceptiongroup>=1.2,<2",
-  "mypy>=1.14,<2",
-  "pytest>=8,<9",
-  "pytest-asyncio>=0.26,<2",
-  "pytest-cov>=7.1.0",
-  "ruff>=0.11,<1",
-  "tomli>=2,<3",
-  "viztracer>=1.1.1",
-]
+include = ["/src", "/README.md", "/pyproject.toml"]
 
 [tool.pytest.ini_options]
 testpaths = ["tests"]
 asyncio_mode = "auto"
-
-[tool.mypy]
-python_version = "3.10"
-files = ["src", "perf"]
-# Check the pydantic storage models as models, not as plain classes.
-plugins = ["pydantic.mypy"]
-warn_unused_ignores = true
-warn_redundant_casts = true
-no_implicit_optional = true
-
-[[tool.mypy.overrides]]
-# Ships no stubs; the runner only calls the two documented functions.
-module = ["pyperclip"]
-ignore_missing_imports = true
-
-[tool.ruff]
-line-length = 120
-target-version = "py310"
-src = ["src", "tests", "perf"]
-
-[tool.ruff.lint]
-select = ["E", "F", "I", "UP", "B"]
-ignore = ["E501"]
-
-[tool.ruff.lint.isort]
-known-first-party = ["zettcode"]
-
-[tool.ruff.format]
-quote-style = "double"
-indent-style = "space"
-line-ending = "lf"

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

{zettcode-0.1.8 → zettcode-0.1.9}/src/zettcode/_compat.py

@@ -1,6 +1,6 @@
 """Small shims for the language versions this project supports.
 
-ZettCode runs on Python 3.10 through 3.14, so the few things the standard
+ZettCode runs on Python 3.10 through 3.15, so the few things the standard
 library grew in between live here instead of behind version checks at each use.
 """
 

{zettcode-0.1.8 → zettcode-0.1.9}/src/zettcode/app/agent/extensions/mcp.py

@@ -137,12 +137,15 @@ class ReportingMcpExtension(McpExtension):
         """Return whether this is the first request its session has made, in a session the reader is in."""
         return self._is_a_reader_session(context) and cast(str, context.config.session_id) not in self._narrated
 
-    async def _say_quietly(self, context: AgentRunContext | None, text: str) -> None:
-        """Say a line without letting the saying fail the discovery it reports on."""
+    async def _say_quietly(self, context: AgentRunContext | None, text: str, level: str = "info") -> None:
+        """Say a line without letting the saying fail the discovery it reports on.
+
+        These are progress lines (a server is starting, or ready), so they are ``info`` unless said otherwise.
+        """
         if context is None:
             return
         try:
-            await self._say(context, text)
+            await self._say(context, text, level)
         except Exception:  # noqa: BLE001 - news about a server must never be what stops it
             pass
 
@@ -188,14 +191,19 @@ class ReportingMcpExtension(McpExtension):
         return [f"MCP server {name!r} in {path.name} is ignored: {reason}" for name, reason in skipped.items()]
 
     @staticmethod
-    async def _say(context: AgentRunContext, text: str) -> None:
-        """Publish one line for the transcript."""
+    async def _say(context: AgentRunContext, text: str, level: str = "warn") -> None:
+        """Publish one line for the transcript.
+
+        A line is a warning unless it says otherwise: what reaches here from the checks (a server that is down, an
+        entry that is ignored, a file that cannot be read) is something the reader may need to act on, and only the
+        progress lines of a start say ``info``.
+        """
         await context.emit(
             AgentEvent(
                 type=AgentEventType.CUSTOM,
                 session_id=cast(str, context.config.session_id),
                 name=MCP_NOTICE_EVENT_NAME,
-                payload=notice_payload(text),
+                payload=notice_payload(text, level),
             )
         )
 

{zettcode-0.1.8 → zettcode-0.1.9}/src/zettcode/app/agent/extensions/mcp_notice.py

@@ -13,9 +13,21 @@ from zett_agent.events import AgentEvent
 MCP_NOTICE_EVENT_NAME = "mcp_notice"
 
 
-def notice_payload(text: str) -> dict[str, str]:
-    """Return the JSON-serializable payload that carries one line of MCP news."""
-    return {"text": text}
+#: How serious a line of news is: ``info`` is progress (a server is starting, or ready), ``warn`` is something the
+#: reader may need to act on (a server is down, an entry is ignored). A payload that names neither is ``info``.
+LEVELS = ("info", "warn")
+
+
+def notice_payload(text: str, level: str = "info") -> dict[str, str]:
+    """Return the JSON-serializable payload that carries one line of MCP news and how serious it is."""
+    return {"text": text, "level": level if level in LEVELS else "info"}
+
+
+def notice_level_from(event: AgentEvent) -> str:
+    """Return how serious the notice an event carries is; ``info`` for a payload that does not say."""
+    payload = event.payload
+    level = payload.get("level") if isinstance(payload, dict) else None
+    return level if level in LEVELS else "info"
 
 
 def notice_from(event: AgentEvent) -> str | None:

{zettcode-0.1.8 → zettcode-0.1.9}/src/zettcode/config.py

@@ -135,10 +135,23 @@ DEFAULT_SKILL_ROOT = "~/.zettcode/skills"
 #: or ``both``, ahead of the user's own, so a project's version of a skill wins in that project.
 WORKSPACE_SKILL_ROOT = ".zettcode/skills"
 
+#: The same two places under the ``.agents`` directory that other coding agents share: ``~/.agents/skills`` for
+#: the user and ``<workspace>/.agents/skills`` for a project. Each is scanned right after the ``.zettcode``
+#: directory of its own scope, so a skill written for one of those tools is found with no copying, and a
+#: ZettCode skill of the same name in the same scope still wins.
+DEFAULT_AGENTS_SKILL_ROOT = "~/.agents/skills"
+WORKSPACE_AGENTS_SKILL_ROOT = ".agents/skills"
+
 #: The MCP server file a workspace may ship, relative to it. Read for ``[mcp] scope`` of
 #: ``workspace`` or ``both``, and merged over the user's file by server name.
 WORKSPACE_MCP_CONFIG = ".zettcode/mcp.json"
 
+#: The same file under the shared ``.agents`` directory, for the workspace and for the user. Each is read right
+#: after the ``.zettcode`` file of its own scope, so it only adds servers a ZettCode file does not name. The user's
+#: is not read when ``[mcp] config`` names a file: whoever points at a team file means that file.
+WORKSPACE_AGENTS_MCP_CONFIG = ".agents/mcp.json"
+DEFAULT_AGENTS_MCP_CONFIG = "~/.agents/mcp.json"
+
 #: API root of an Anthropic model whose entry names no ``base_url``. The
 #: Messages API lives at the root itself, not under ``/v1``.
 DEFAULT_ANTHROPIC_BASE_URL = "https://api.anthropic.com"
@@ -326,8 +339,8 @@ class ZettCodeConfig:
         skills_enabled: Discover local skills and advertise them to the model.
         skill_roots: Extra skill directories, searched before the directory :attr:`skills_scope`
             names; a relative entry is resolved against the workspace.
-        skills_scope: Which of the workspace's ``.zettcode/skills`` and the user's
-            ``~/.zettcode/skills`` to scan: ``"both"`` (the default) the project's first, so its version of
+        skills_scope: Which of the workspace's ``.zettcode/skills`` and ``.agents/skills`` and the user's
+            ``~/.zettcode/skills`` and ``~/.agents/skills`` to scan: ``"both"`` (the default) the project's first, so its version of
             a skill wins inside it; ``"workspace"`` the project's only, ``"global"`` the user's only.
         mcp_enabled: Load MCP servers from :attr:`mcp_config` and the workspace's ``.zettcode/mcp.json``.
         mcp_config: JSON file naming MCP servers; ``None`` uses ``~/.zettcode/mcp.json``.
@@ -440,8 +453,10 @@ class ZettCodeConfig:
         roots: list[Path] = list(self.skill_roots)
         if scope in ("workspace", "both"):
             roots.append(_resolve_root(WORKSPACE_SKILL_ROOT, self.workspace))
+            roots.append(_resolve_root(WORKSPACE_AGENTS_SKILL_ROOT, self.workspace))
         if scope in ("global", "both"):
             roots.append(_resolve_root(DEFAULT_SKILL_ROOT, self.workspace))
+            roots.append(_resolve_root(DEFAULT_AGENTS_SKILL_ROOT, self.workspace))
         # Ordered, one of each: a configured root may name the same directory a scope does.
         return tuple(dict.fromkeys(roots))
 
@@ -456,8 +471,11 @@ class ZettCodeConfig:
         files: list[Path] = []
         if scope in ("workspace", "both"):
             files.append(_resolve_root(WORKSPACE_MCP_CONFIG, self.workspace))
+            files.append(_resolve_root(WORKSPACE_AGENTS_MCP_CONFIG, self.workspace))
         if scope in ("global", "both"):
             files.append((self.mcp_config or Path(DEFAULT_MCP_CONFIG)).expanduser().resolve())
+            if self.mcp_config is None:
+                files.append(_resolve_root(DEFAULT_AGENTS_MCP_CONFIG, self.workspace))
         return tuple(dict.fromkeys(files))
 
 
@@ -577,6 +595,33 @@ def _read_models(raw: object, source: Path) -> tuple[ModelConfig, ...]:
     return tuple(models)
 
 
+def read_models(path: str | Path | None = None) -> tuple[ModelConfig, ...]:
+    """Return the models a config file lists, and nothing else it holds.
+
+    Unlike :func:`load_config`, no models is an answer (the file is new, or a program is being set up) and a
+    missing file is an empty one. A model that is configured wrongly is still an error, because it would fail on
+    the first request otherwise.
+
+    Args:
+        path: The file to read; ``$ZETTCODE_CONFIG`` or ``~/.zettcode/config.toml`` by default.
+    """
+    source = config_path(path)
+    if not source.is_file():
+        return ()
+    try:
+        data = tomllib.loads(source.read_text(encoding="utf-8"))
+    except tomllib.TOMLDecodeError as error:
+        raise ValueError(f"Invalid config file {source}: {error}") from error
+    raw = data.get("models", [])
+    if raw is None:
+        return ()
+    if not isinstance(raw, list):
+        raise ValueError("Config key 'models' must be an array of tables ([[models]])")
+    if any(not isinstance(entry, dict) for entry in raw):
+        raise ValueError("Config key 'models' must be an array of tables ([[models]])")
+    return tuple(_entry_model(entry, index) for index, entry in enumerate(raw, start=1))
+
+
 def _read_table(raw: object, key: str, source: Path, allowed: frozenset[str]) -> dict[str, object]:
     """Return one optional config table, rejecting unknown keys and wrong shapes."""
     if raw is None:

{zettcode-0.1.8 → zettcode-0.1.9}/src/zettcode/sdk/__init__.py

@@ -59,8 +59,21 @@ if TYPE_CHECKING:  # pragma: no cover - for type checkers and editors; at runtim
         ToolStarted,
     )
     from .handlers import approve_all, approve_commands, deny_all
+    from .models import add_model, list_models, remove_model, update_model
     from .session import RunStream, Session
-    from .types import Image, RunResult, Usage
+    from .types import (
+        DayTotals,
+        Image,
+        MentionInfo,
+        ModelCheck,
+        ModelTotals,
+        RunResult,
+        SessionStatsInfo,
+        SessionTotals,
+        Totals,
+        Usage,
+        WorkspaceUsage,
+    )
 
 #: Where each public name lives. The package resolves a name by importing only that module.
 _EXPORTS: dict[str, str] = {
@@ -72,6 +85,14 @@ _EXPORTS: dict[str, str] = {
     "RunResult": ".types",
     "Usage": ".types",
     "Image": ".types",
+    "MentionInfo": ".types",
+    "DayTotals": ".types",
+    "ModelCheck": ".types",
+    "ModelTotals": ".types",
+    "SessionStatsInfo": ".types",
+    "SessionTotals": ".types",
+    "Totals": ".types",
+    "WorkspaceUsage": ".types",
     "TextDelta": ".events",
     "ReasoningDelta": ".events",
     "ToolStarted": ".events",
@@ -85,6 +106,10 @@ _EXPORTS: dict[str, str] = {
     "ZettCodeError": ".errors",
     "ConfigurationError": ".errors",
     "RunError": ".errors",
+    "add_model": ".models",
+    "list_models": ".models",
+    "remove_model": ".models",
+    "update_model": ".models",
 }
 
 #: Kept literal so linters and editors can read it; a test checks it names exactly the keys of ``_EXPORTS``.
@@ -92,24 +117,36 @@ __all__ = [
     "ApprovalRequested",
     "Client",
     "ConfigurationError",
+    "DayTotals",
     "Finished",
     "Image",
+    "MentionInfo",
+    "ModelCheck",
+    "ModelTotals",
     "QuestionAsked",
     "ReasoningDelta",
     "RunError",
     "RunResult",
     "RunStream",
     "Session",
+    "SessionStatsInfo",
+    "SessionTotals",
     "TextDelta",
     "ToolFinished",
     "ToolStarted",
+    "Totals",
     "Usage",
+    "WorkspaceUsage",
     "ZettCodeError",
+    "add_model",
     "approve_all",
     "approve_commands",
     "deny_all",
+    "list_models",
     "prompt",
     "prompt_sync",
+    "remove_model",
+    "update_model",
 ]
 
 

{zettcode-0.1.8 → zettcode-0.1.9}/src/zettcode/sdk/_translate.py

@@ -7,15 +7,17 @@ custom events, so it imports both, and is itself imported only when a run starts
 
 from __future__ import annotations
 
-from collections.abc import Mapping
+from collections.abc import Mapping, Sequence
+from typing import TYPE_CHECKING
 
 from zett_agent.events import AgentEvent, AgentEventType
 from zett_agent.extensions.shell_approval import SHELL_APPROVAL_EVENT_NAME
 from zett_agent.messages import TextContent
 
 from ..app.agent.dialogue.ask import question_from
-from ..app.agent.extensions.mcp_notice import notice_from
+from ..app.agent.extensions.mcp_notice import notice_from, notice_level_from
 from ..app.agent.extensions.usage import USAGE_EVENT_NAME, UsageSnapshot
+from ..app.agent.storage.ledger import Ledger, SessionStats, SessionUsage, Tally
 from .events import (
     AnyEvent,
     ApprovalRequested,
@@ -34,9 +36,19 @@ from .events import (
     UsageUpdated,
     _Reply,
 )
-from .types import Compaction, Usage
+from .types import (
+    Compaction,
+    DayTotals,
+    ModelCheck,
+    ModelTotals,
+    SessionStatsInfo,
+    SessionTotals,
+    Totals,
+    Usage,
+    WorkspaceUsage,
+)
 
-__all__ = ["translate", "usage_from"]
+__all__ = ["checks_from", "ledger_from", "stats_from", "translate", "usage_from"]
 
 
 def usage_from(snapshot: UsageSnapshot) -> Usage:
@@ -77,6 +89,78 @@ def _optional_int(value: object) -> int | None:
     return int(value) if isinstance(value, (int, float)) and not isinstance(value, bool) else None
 
 
+if TYPE_CHECKING:  # pragma: no cover - annotations only
+    from ..doctor import Probe
+
+
+def totals_from(tally: Tally) -> Totals:
+    """Return one tally as the SDK's own counters."""
+    return Totals(
+        requests=tally.requests,
+        input_tokens=tally.input_tokens,
+        output_tokens=tally.output_tokens,
+        cache_read_tokens=tally.cache_read_tokens,
+        reasoning_tokens=tally.reasoning_tokens,
+    )
+
+
+def ledger_from(ledger: Ledger) -> WorkspaceUsage:
+    """Return the workspace ledger as plain SDK values, ordered the way a page shows it."""
+    sessions = sorted(ledger.sessions, key=lambda item: item.updated, reverse=True)
+    models = sorted(ledger.models.items(), key=lambda pair: pair[1].total, reverse=True)
+    return WorkspaceUsage(
+        sessions=tuple(_session_totals(item) for item in sessions),
+        models=tuple(ModelTotals(name, totals_from(tally)) for name, tally in models),
+        days=tuple(DayTotals(day, totals_from(tally)) for day, tally in sorted(ledger.days.items())),
+        total=totals_from(ledger.total),
+    )
+
+
+def _session_totals(usage: SessionUsage) -> SessionTotals:
+    """Return one session's ledger row."""
+    return SessionTotals(
+        id=usage.session_id,
+        title=usage.title,
+        started=usage.started,
+        updated=usage.updated,
+        tokens=totals_from(usage.tally),
+        models=usage.models,
+        entries=usage.entries,
+    )
+
+
+def stats_from(stats: SessionStats) -> SessionStatsInfo:
+    """Return one session's stored totals."""
+    return SessionStatsInfo(
+        id=stats.session_id,
+        entries=stats.entries,
+        requests=stats.requests,
+        input_tokens=stats.input_tokens,
+        output_tokens=stats.output_tokens,
+        cache_read_tokens=stats.cache_read_tokens,
+        reasoning_tokens=stats.reasoning_tokens,
+    )
+
+
+def checks_from(probes: Sequence[Probe]) -> tuple[ModelCheck, ...]:
+    """Return the doctor probes as SDK values."""
+    checks: list[ModelCheck] = []
+    for probe in probes:
+        tokens = probe.tokens
+        checks.append(
+            ModelCheck(
+                model=probe.model.shown_name,
+                model_id=probe.model.model,
+                ok=probe.ok,
+                seconds=probe.seconds,
+                detail=probe.detail,
+                input_tokens=tokens[0] if tokens else None,
+                output_tokens=tokens[1] if tokens else None,
+            )
+        )
+    return tuple(checks)
+
+
 def translate(event: AgentEvent, bridge: Bridge) -> list[AnyEvent]:
     """Return the SDK events one ``zett-agent`` event stands for; usually one, sometimes none or several.
 
@@ -176,4 +260,4 @@ def _custom(event: AgentEvent, session: str, bridge: Bridge) -> list[AnyEvent]:
             )
         ]
     line = notice_from(event)
-    return [Notice(session, line)] if line is not None else []
+    return [Notice(session, line, notice_level_from(event))] if line is not None else []