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

{zettcode_sdk-0.4.1 → zettcode_sdk-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_sdk-0.4.1 → zettcode_sdk-0.4.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: zettcode-sdk
-Version: 0.4.1
+Version: 0.4.2
 Summary: The documented, stable Python surface over ZettCode: sessions, runs, models, daemons
 Project-URL: Repository, https://github.com/Chang-LeHung/zettcode
 Author: Chang-LeHung
@@ -16,6 +16,18 @@ Classifier: Programming Language :: Python :: 3.15
 Classifier: Typing :: Typed
 Requires-Python: >=3.10
 Requires-Dist: httpx<1,>=0.27
-Requires-Dist: zett-agent<0.3,>=0.2.7
+Requires-Dist: zett-agent<0.3,>=0.2.10
+Requires-Dist: zettcode-ask-user
 Requires-Dist: zettcode-broker
 Requires-Dist: zettcode-engine
+Requires-Dist: zettcode-files
+Requires-Dist: zettcode-guidance
+Requires-Dist: zettcode-instructions
+Requires-Dist: zettcode-jit-harness
+Requires-Dist: zettcode-mcp
+Requires-Dist: zettcode-memory
+Requires-Dist: zettcode-messaging
+Requires-Dist: zettcode-skills
+Requires-Dist: zettcode-todos
+Requires-Dist: zettcode-tool-output
+Requires-Dist: zettcode-truncation

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

@@ -19,33 +19,37 @@ classifiers = [
 dependencies = [
   "zettcode-engine",
   "zettcode-broker",
-  "zett-agent>=0.2.7,<0.3",
+  # Parts of the agent that live in distributions of their own, found through the same `zettcode.plugin` group as
+  # the ones published here. An SDK client offers skills and MCP servers and runs the same agent, so it installs them
+  # all; `require_agent_parts` refuses a start that lacks one.
+  "zettcode-skills",
+  "zettcode-messaging",
+  "zettcode-mcp",
+  "zettcode-files",
+  "zettcode-jit-harness",
+  "zettcode-ask-user",
+  "zettcode-instructions",
+  "zettcode-memory",
+  "zettcode-todos",
+  "zettcode-tool-output",
+  "zettcode-truncation",
+  "zettcode-guidance",
+  "zett-agent>=0.2.10,<0.3",
   "httpx>=0.27,<1",
 ]
 
-# The plugins that compose the agent. A part of the program, not a plugin: the `zettcode.plugins` group is what the
-# plugin release line looks for. They are activated by the rank `builtins.py` gives them, then by their `deps`.
-[project.entry-points."zettcode.agent"]
-skills = "zettcode.sdk.builtins:SkillResources"
-files = "zettcode.sdk.builtins:FileResources"
+# The plugins that compose the agent. A part of the program, not a plugin: the `[tool.zettcode] plugin = true`
+# marker is what the plugin release line looks for. They are activated by the rank `builtins.py` gives them, then by their `deps`.
+[project.entry-points."zettcode.plugin"]
 coding = "zettcode.sdk.builtins:CodingTools"
-tool-output = "zettcode.sdk.builtins:ToolOutput"
-long-output = "zettcode.sdk.builtins:LongOutput"
+commandline = "zettcode.sdk.builtins:CommandLine"
 capabilities = "zettcode.sdk.builtins:Capabilities"
 subagents = "zettcode.sdk.builtins:Subagents"
-messaging = "zettcode.sdk.builtins:Messaging"
 shell-permission = "zettcode.sdk.builtins:ShellPermission"
-harness = "zettcode.sdk.builtins:Harness"
 session-log = "zettcode.sdk.builtins:SessionLog"
-todos = "zettcode.sdk.builtins:TodoPlan"
 usage-tracking = "zettcode.sdk.builtins:UsageTracking"
 context-tracking = "zettcode.sdk.builtins:ContextTracking"
 side-questions = "zettcode.sdk.builtins:SideQuestionBoundary"
-tool-guidelines = "zettcode.sdk.builtins:ToolGuidance"
-ask-user = "zettcode.sdk.builtins:AskUser"
-project-instructions = "zettcode.sdk.builtins:ProjectInstructions"
-skill-tool = "zettcode.sdk.builtins:SkillTool"
-mcp = "zettcode.sdk.builtins:McpTools"
 self-compaction = "zettcode.sdk.builtins:SelfCompaction"
 compaction = "zettcode.sdk.builtins:Compaction"
 

{zettcode_sdk-0.4.1 → zettcode_sdk-0.4.2}/src/zettcode/daemon/process.py

@@ -186,7 +186,9 @@ class Daemons:
 
         By default the record is removed too (``kill``); with ``keep`` it stays, as a dead one, so the daemon is
         still listed and can be started again or deleted. A dead record is only removed (or, with ``keep``, left):
-        the process it described is gone already. Whether it is ``working`` is read from the state file, which can be a
+        the process it described is gone already. The one record ``keep`` does not keep is a folder with no readable
+        state: it names no session and no workspace, so there is nothing to start again, and it is removed. Whether
+        it is ``working`` is read from the state file, which can be a
         moment old, so a daemon that has just changed turn may be judged by the one before; ``--force`` is the answer to
         that, not a retry. The session is never touched — it is a conversation like any
         other, and ``zettcode resume <id>`` opens it afterwards.
@@ -201,6 +203,7 @@ class Daemons:
             return "removed: it never recorded what it was"
         if not record.alive:
             if keep:
+                record.end_beat()
                 return "was already gone; its record was kept"
             record.remove()
             return "was already gone; its record was removed"
@@ -218,22 +221,37 @@ class Daemons:
         deadline = time.monotonic() + grace
         while time.monotonic() < deadline:
             # The daemon removes its own record on the way out (unless asked to keep it), so the folder going is the
-            # proof it stopped — a pid can outlive the process it named, as a zombie its parent has not reaped.
-            if not record.folder.exists() or not pid_runs(pid):
-                if keep:
-                    return "stopped; its record was kept"
-                record.remove()
-                return "stopped"
+            # proof it stopped — a pid can outlive the process it named, as a zombie its parent has not reaped. A
+            # record that was asked to stay has no folder to go, and its proof is the heartbeat the daemon takes away.
+            gone = not record.folder.exists()
+            if gone or not pid_runs(pid) or (keep and not record.beating()):
+                if not keep:
+                    record.remove()
+                    return "stopped"
+                if gone:
+                    return "stopped; its record was removed"
+                # The process may have left without reaching its own last act (killed from elsewhere, an error while
+                # the client closed), and then the heartbeat is still fresh: take it away, so the record reads dead by
+                # the rule and not by a pid the system can hand to another process within the beat's thirty seconds.
+                record.end_beat()
+                return "stopped; its record was kept"
             time.sleep(POLL_SECONDS)
         _signal(pid, getattr(signal, "SIGKILL", signal.SIGTERM))
-        if not keep:
+        if keep:
+            record.end_beat()  # killed, it cannot take its own heartbeat away
+        else:
             record.remove()
         return "did not stop in time, so it was killed"
 
     @staticmethod
     def _gone(record: Record, keep: bool, said: str) -> str:
-        """Finish a stop whose process was already gone: keep the record or remove it."""
+        """Finish a stop whose process was already gone: keep the record or remove it.
+
+        A kept record loses its heartbeat like on the other two ways out, so it reads as dead by the same rule and not
+        by the pid alone, which a busy machine can reuse before the beat has gone stale.
+        """
         if keep:
+            record.end_beat()
             return f"{said}; its record was kept"
         record.remove()
         return f"{said}; its record was removed"

{zettcode_sdk-0.4.1 → zettcode_sdk-0.4.2}/src/zettcode/daemon/run.py

@@ -24,7 +24,7 @@ from pathlib import Path
 from typing import TYPE_CHECKING, Any
 
 from zettcode.error_text import may_pass
-from zettcode.relay import batch_size
+from zettcode.messaging.relayed import batch_size
 from zettcode.sdk.types import DIRECT_EMPTY, DIRECT_FAILED, IncomingMessage, Receipt
 
 from .state import Record, Registry, State
@@ -98,7 +98,7 @@ class Inbox:
     def done(self) -> IncomingMessage | None:
         """Close the turn that ended: return the next message to run, or ``None`` when the daemon is idle again.
 
-        The messages that waited come back as one, in order (see :func:`~zettcode.relay.batch_size`), so a daemon that
+        The messages that waited come back as one, in order (see :func:`~zettcode.messaging.relayed.batch_size`), so a daemon that
         was busy answers them in a single turn instead of one turn each; a chat window's message is always its own.
         """
         if self._waiting:
@@ -160,7 +160,11 @@ class Daemon:
         """Take a message from the broker: refused at once when it carries pictures this model cannot read.
 
         The sender is told then and there, in words it can act on, rather than after a turn that was bound to fail.
+        A daemon that has been asked to stop takes nothing: the turn would run while the client is being closed, and
+        its first state write would put a heartbeat back after the stop took it away.
         """
+        if self.stopping.is_set():
+            return Receipt(False, "this daemon is stopping")
         if message.images:
             try:
                 model = self.client.model
@@ -196,12 +200,30 @@ class Daemon:
             # answers. A stop that asked to keep it leaves it, as a dead one the reader can start again or delete.
             if not self._kept():
                 self.record.remove()
+            else:
+                # Nothing removes the folder now, so the daemon says it is gone the one way that does not depend on
+                # its pid: it takes its heartbeat away, and the record reads as dead from here on.
+                self.record.end_beat()
         return EXIT_OK
 
     def _kept(self) -> bool:
         """Return whether the stop that is ending this process asked for the record to stay."""
-        state = State.load(self.record.folder)
-        return state is not None and state.keep
+        return self._asked_to_keep(State.load(self.record.folder))
+
+    def _asked_to_keep(self, current: State | None) -> bool:
+        """Return whether ``current`` carries the ask to keep the record that was made of *this* process.
+
+        A stop writes ``keep`` into the state before it signals, and every later write of this process carries it, so
+        the daemon's last write cannot put it back: whatever status a turn that was already starting wrote over the
+        stop's, the field survives it. What may not be believed is a field left in the folder by an earlier start of
+        the same session (a daemon started again on a kept record finds it there, and would leave a record behind on
+        Ctrl-C that it used to remove). The token is this start's own and the pid is this process's: the token alone
+        names the state this process wrote, and the pid alone could be a stopped daemon's pid the system gave to the
+        new one, so both have to say so.
+        """
+        return bool(
+            current is not None and current.keep and current.token == self.options.token and current.pid == os.getpid()
+        )
 
     # -- what it answers ---------------------------------------------------------------------------
     def _start(self, message: IncomingMessage) -> None:
@@ -209,7 +231,13 @@ class Daemon:
         asyncio.ensure_future(self._answer(message))
 
     async def _answer(self, message: IncomingMessage) -> None:
-        """Run one turn, then the next waiting message, and go idle when there is none."""
+        """Run one turn, then the next waiting message, and go idle when there is none.
+
+        A message queued before the stop is not answered after it: the process is leaving, and the turn would run
+        while the client is being closed.
+        """
+        if self.stopping.is_set():
+            return
         try:
             await self._apply_requests()
             await self.mark("working")
@@ -399,7 +427,13 @@ class Daemon:
 
         The heartbeat is touched here as well as on its own clock: the first state a reader can see is written with
         proof of life beside it, so a daemon is never listed as dead between its start and its first beat.
+
+        Once the process has been asked to stop, the only state it writes is ``stopping``: whatever a task that was
+        already running says after that would also beat, and a heartbeat written after the daemon took its own away
+        reads as a daemon that is still there.
         """
+        if self.stopping.is_set() and status != "stopping":
+            return
         self.record.beat()
         sent, made, context = self._spend()
         state = State(
@@ -431,6 +465,10 @@ class Daemon:
                         requested_model=current.requested_model if current is not None else None,
                         requested_effort=current.requested_effort if current is not None else None,
                         requested_error=current.requested_error if current is not None else None,
+                        # A stop that wants the record kept writes the field before it signals, and this write is the
+                        # daemon's last: built afresh, the state would say "do not keep" and the daemon would remove
+                        # the record it was asked to leave. What counts as this process's ask is `_asked_to_keep`.
+                        keep=self._asked_to_keep(current),
                     ),
                     wait=0,
                 )
@@ -619,6 +657,11 @@ async def serve(options: Options) -> int:
                     await client.sessions.open(options.session)
                 except (ConfigurationError, SessionNotFoundError, SessionLockedError) as error:
                     return _failed(str(error))
+                if client.session.locked:
+                    # `open` does not refuse a session another process holds: it selects it, to be read and not
+                    # written. That is a fine thing for a reader and no thing at all for a daemon, whose every turn
+                    # would fail on the first write while the daemon sat there listed as idle.
+                    return _failed("this session is open in another ZettCode process, so a daemon cannot write to it")
             if options.title:
                 # The session this process holds, so the name is written where the daemon and `/resume` both read it.
                 try:

{zettcode_sdk-0.4.1 → zettcode_sdk-0.4.2}/src/zettcode/daemon/state.py

@@ -182,6 +182,15 @@ class Record:
     Reading a record reads its state once, at construction, and whether the process is there: a command that lists
     ten daemons asks the disk ten times, and nothing between two reads of one record can change the answer without
     the file changing too.
+
+    **When a record reads as alive.** Only while its pid answers *and* its heartbeat is fresh; either alone is not
+    proof (a pid is reused, and a zombie its parent has not reaped still answers signal zero). A record that is left
+    behind on purpose (a stop that asked to keep it) has no folder going away to say the process has stopped, so the
+    process says it itself: :meth:`end_beat` is the last thing it writes, and **nothing may beat after it** — which is
+    why ``Daemon.mark`` refuses every state but ``stopping`` once the daemon is stopping, ``take`` and ``_answer``
+    refuse work, and the stop paths in :mod:`.process` that find the process already gone take the beat away too.
+    A new writer of this folder that touches the heartbeat has to respect that, or a stopped daemon reads as running
+    for the thirty seconds a beat stays fresh (invariant H29).
     """
 
     def __init__(self, folder: Path) -> None:
@@ -270,6 +279,22 @@ class Record:
         except OSError:
             pass
 
+    def end_beat(self) -> None:
+        """Take the heartbeat away: the daemon's last word when it leaves its record behind.
+
+        A record that stays has no folder going away to say the process has stopped, and a pid is no proof either —
+        a zombie its parent has not reaped still answers signal zero. No heartbeat is: the record then reads as dead
+        at once, instead of after the thirty seconds a stale beat takes.
+        """
+        try:
+            (self.folder / BEAT_FILE).unlink()
+        except OSError:
+            pass
+
+    def beating(self) -> bool:
+        """Return whether a heartbeat file is there to be read, whatever its age."""
+        return (self.folder / BEAT_FILE).exists()
+
     def log(self, text: str) -> None:
         """Append one line to the daemon's log; a log that cannot be written is not worth failing a daemon over."""
         stamp = time.strftime("%Y-%m-%d %H:%M:%S")

zettcode_sdk-0.4.2/src/zettcode/mentions.py

@@ -0,0 +1,120 @@
+"""``@`` references: resources a draft can pull into one message.
+
+A mention is a token like ``@code-review`` typed in the composer. A provider
+owns one kind of resource (other sessions here; files in ``zettcode-files``, skills in ``zettcode-skills``) and both
+lists candidates for the completion menu and expands a token into the text the model
+should see. The draft the user typed stays the message that is stored and
+shown; the expansion is carried as a message attribute, so a session loaded
+later restores the original text instead of the injected resource.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Sequence
+
+from zettcode.broker.text import folder_name
+from zettcode.mention import Mention, MentionProvider, MentionRegistry
+from zettcode.wire import RosterPeer
+
+__all__ = [
+    "Mention",
+    "MentionProvider",
+    "MentionRegistry",
+    "RosterPeer",
+    "SessionMentions",
+]
+
+
+class SessionMentions(MentionProvider):
+    """The other ZettCode sessions that are running, addressed by the name they are listed under.
+
+    A session named anywhere in a draft is a reference like any other: the model reads ``session "name"``
+    and is told how to reach that session, and decides for itself whether the request calls for a message.
+    The shell sends nothing itself (see :mod:`zettcode.app.ui.messaging`).
+
+    Candidates are read from what the connection last reported — a list in memory — and never from
+    the broker: completion runs on every keystroke after an ``@``.
+    """
+
+    kind = "session"
+    #: A session is the most specific thing a name can mean, ahead of a skill and a file.
+    precedence = -20
+
+    def __init__(self, peers: Callable[[], Sequence[RosterPeer]]) -> None:
+        """Offer whichever sessions ``peers`` returns when asked.
+
+        Args:
+            peers: The other sessions as of now; called for every query, so it must not block.
+        """
+        self._peers = peers
+
+    def candidates(self, query: str) -> Sequence[Mention]:
+        """List the sessions ``query`` could mean, the likeliest first.
+
+        A reader looks for a session by what they remember of it, which is its name, what it was about,
+        the folder it works in, or the start of its id — so any of those matches, with a session whose
+        *name* starts with the query before one that only mentions it elsewhere. The token offered is
+        always the name, because that is what can be sent to.
+        """
+        lowered = query.lower()
+        ranked: list[tuple[int, int, RosterPeer]] = []
+        for order, peer in enumerate(self._peers()):
+            if peer.handle.lower().startswith(lowered):
+                ranked.append((0, order, peer))
+            elif (
+                lowered in peer.handle.lower() or lowered in peer.title.lower() or lowered in self._folder(peer).lower()
+            ):
+                ranked.append((1, order, peer))
+            elif len(lowered) >= 4 and peer.session_id.lower().startswith(lowered):
+                ranked.append((2, order, peer))
+        return tuple(
+            Mention(token=f"@{peer.handle}", kind=self.kind, name=peer.handle, description=self._describe(peer))
+            for _, _, peer in sorted(ranked, key=lambda item: item[:2])
+        )
+
+    @staticmethod
+    def _folder(peer: RosterPeer) -> str:
+        """Return the last part of the directory the session works in."""
+        return folder_name(peer.workspace)
+
+    @classmethod
+    def _describe(cls, peer: RosterPeer) -> str:
+        """Return the menu's line for a session: what it is about, whether it is working, where it is."""
+        parts = [peer.title or "untitled"]
+        if peer.status != "idle":
+            parts.append(peer.status)
+        folder = cls._folder(peer)
+        if folder:
+            parts.append(folder)
+        return " \u00b7 ".join(parts)
+
+    def rename(self, name: str) -> str | None:
+        """Put ``session "work"`` where the reader typed ``@work``: the model has no use for the ``@``."""
+        return f'session "{name}"' if self._find(name) is not None else None
+
+    def _find(self, name: str) -> RosterPeer | None:
+        """Return the session called ``name`` among those running now."""
+        return next((peer for peer in self._peers() if peer.handle == name), None)
+
+    def expand(self, name: str) -> str | None:
+        """Tell the model what the reader's ``@`` meant and how to reach that session.
+
+        Nothing is sent from here: the model is told which session the words mean and how to reach it, and
+        decides for itself whether the request calls for a message. A draft that begins with the name is no
+        different from one that names the session inside a sentence.
+        """
+        peer = self._find(name)
+        if peer is None:
+            return None
+        where = f" in {peer.workspace}" if peer.workspace else ""
+        about = f' It is titled "{peer.title}".' if peer.title else ""
+        return (
+            f'In the message above, `session "{name}"` is what the user wrote as @{name}. In ZettCode an @ before a '
+            f"name means another ZettCode session that is running right now, not a file or a skill. This one works{where}.{about}\n"
+            f"When the user's message is addressed to that session — the @ begins the message — what follows the name "
+            f"is the message to pass on. When the session is only mentioned, decide whether the request is for it. "
+            f'To send, call the send_message tool: send_message(to="{peer.session_id}", message=...). Write the '
+            f"message so the other session can act on it without having seen this conversation. If the request is only "
+            f"about the session (what it is doing, where it is), list_sessions answers that. Do not send anything the "
+            f"user did not ask you to pass on."
+        )