zettcode-server 0.1.1__tar.gz → 0.4.0__tar.gz

{zettcode_server-0.1.1 → zettcode_server-0.4.0}/.gitignore

@@ -24,7 +24,14 @@ docs/.vitepress/.temp/
 # The TypeScript client is built from its sources; only dist/ is published.
 clients/typescript/dist/
 
+# The gateway's page is built from clients/gateway into the package when a distribution is made (`make gateway-ui`);
+# the build output is not kept in the repository. pyproject's `artifacts` puts it in the wheel all the same.
+packages/zettcode-gateway/src/zettcode/gateway/static/
+
 # 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
+
+# The release order is generated from the pyproject.toml files (`make order`); it is not kept in git.
+packages/order.txt

zettcode_server-0.4.0/PKG-INFO

@@ -0,0 +1,23 @@
+Metadata-Version: 2.5
+Name: zettcode-server
+Version: 0.4.0
+Summary: The HTTP face of ZettCode: a FastAPI server that drives the SDK
+Project-URL: Repository, https://github.com/Chang-LeHung/zettcode
+Author: Chang-LeHung
+License-Expression: MIT
+Keywords: api,server,zettcode
+Classifier: Development Status :: 5 - Production/Stable
+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: fastapi<1,>=0.115
+Requires-Dist: pydantic<3,>=2
+Requires-Dist: starlette<2,>=0.48
+Requires-Dist: uvicorn<1,>=0.35
+Requires-Dist: zettcode-engine
+Requires-Dist: zettcode-sdk

zettcode_server-0.4.0/pyproject.toml

@@ -0,0 +1,47 @@
+[project]
+name = "zettcode-server"
+description = "The HTTP face of ZettCode: a FastAPI server that drives the SDK"
+requires-python = ">=3.10"
+dynamic = ["version"]
+license = "MIT"
+authors = [{name = "Chang-LeHung"}]
+keywords = ["zettcode", "server", "api"]
+classifiers = [
+  "Development Status :: 5 - Production/Stable",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Programming Language :: Python :: 3.14",
+  "Programming Language :: Python :: 3.15",
+  "Typing :: Typed",
+]
+dependencies = [
+  "zettcode-engine",
+  "zettcode-sdk",
+  "fastapi>=0.115,<1",
+  "starlette>=0.48,<2",
+  "uvicorn>=0.35,<1",
+  "pydantic>=2,<3",
+]
+
+[project.urls]
+Repository = "https://github.com/Chang-LeHung/zettcode"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.version]
+# One version for the whole repository: the engine ships the file.
+path = "../zettcode-engine/src/zettcode/version.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/zettcode"]
+
+[tool.hatch.build.targets.sdist]
+include = ["/src", "/pyproject.toml"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"

{zettcode_server-0.1.1/src/zettcode_server → zettcode_server-0.4.0/src/zettcode/server}/__init__.py

@@ -4,20 +4,20 @@ The server is a thin layer: an endpoint says what to ask the agent and how to le
 SDK does the work. It owns no model loop, no tools, and no session format, so a session begun here is one the
 terminal can open afterwards, and the other way round.
 
-The application is built by :func:`create_app`, and served by the ``zettcode-server`` program.
+It is part of this package, not a package of its own: one ``pip install zettcode`` writes both console scripts, the
+terminal's ``zettcode`` and the server's ``zettcode-server``. The application is built by :func:`create_app`, and
+served by :mod:`zettcode.server.cli`.
 """
 
 from __future__ import annotations
 
 from typing import TYPE_CHECKING, Any
 
-__version__ = "0.1.1"
-
 if TYPE_CHECKING:  # pragma: no cover - annotations only; importing the app costs FastAPI
     from .app import create_app
     from .settings import Settings
 
-__all__ = ["Settings", "__version__", "create_app"]
+__all__ = ["Settings", "create_app"]
 
 
 def __getattr__(name: str) -> Any:

{zettcode_server-0.1.1/src/zettcode_server → zettcode_server-0.4.0/src/zettcode/server}/app.py

@@ -25,6 +25,7 @@ from zettcode.sdk.errors import (
     NothingToDoError,
     RunError,
     RunTimeoutError,
+    SendError,
     SessionBusyError,
     SessionLockedError,
     SessionNotFoundError,
@@ -33,8 +34,8 @@ from zettcode.sdk.errors import (
 from zettcode.sdk.models import add_model as add_model_entry
 from zettcode.sdk.models import remove_model as remove_model_entry
 from zettcode.sdk.models import update_model as update_model_entry
+from zettcode.version import __version__
 
-from . import __version__
 from .runner import NoModelError, Runner, prepare, result_payload
 from .runner import Request as RunRequest
 from .schemas import (
@@ -42,6 +43,9 @@ from .schemas import (
     ApprovalAnswer,
     ApprovalPolicy,
     CancelledOut,
+    CommandIn,
+    CommandOut,
+    CommandsOut,
     CompactionOut,
     ContextOut,
     CurrentSessionOut,
@@ -50,11 +54,15 @@ from .schemas import (
     ErrorOut,
     HealthOut,
     HistoryOut,
+    InboxMessageOut,
+    InboxOut,
     MentionsOut,
     ModelCreate,
     ModelsOut,
     ModelUpdate,
+    PluginOut,
     PluginsOut,
+    PluginSwitchIn,
     PromptRequest,
     QuestionAnswer,
     RenameRequest,
@@ -64,6 +72,8 @@ from .schemas import (
     RunStateOut,
     SelfCompactionOut,
     SelfCompactionUpdate,
+    SendIn,
+    SentOut,
     SessionCreate,
     SessionOut,
     SessionsOut,
@@ -103,6 +113,7 @@ FAILURES: tuple[tuple[type[BaseException], int, str], ...] = (
     (NothingToDoError, 409, "nothing_to_do"),
     (NoModelError, 409, "no_model"),
     (ConfigurationError, 400, "invalid"),
+    (SendError, 404, "unreachable"),
     (RunTimeoutError, 504, "timeout"),
     (RunError, 502, "run"),
     (ZettCodeError, 500, "internal"),
@@ -157,6 +168,34 @@ def stream_of(runner: Runner, request: RunRequest, *, resume: bool = False) -> S
     )
 
 
+def message_stream_of(runner: Runner, message_id: str) -> StreamingResponse:
+    """Answer one message another session sent, and stream the turn as ``/prompts`` streams one.
+
+    A message that is not waiting any more — answered already, or never arrived — is a 404, decided here, while a
+    status line is still possible; what fails once the stream is open becomes an ``error`` frame.
+    """
+    if not runner.ready:
+        raise NoModelError("No model is configured; add one with POST /models")
+    try:
+        frames = runner.stream_message(message_id)
+    except KeyError:
+        raise StarletteHTTPException(status_code=404, detail="No message with that id is waiting") from None
+
+    async def body() -> AsyncIterator[bytes]:
+        try:
+            async for name, payload in frames:
+                yield sse_frame(name, payload)
+        except Exception as error:  # noqa: BLE001 - the status line is gone; the failure goes down the stream
+            _, code = failure_of(error)
+            yield sse_frame("error", error_body(code, str(error)))
+
+    return StreamingResponse(
+        body(),
+        media_type="text/event-stream",
+        headers={"Cache-Control": "no-cache", "Connection": "keep-alive", "X-Accel-Buffering": "no"},
+    )
+
+
 def runner_of(request: Request) -> Runner:
     """Return the runner the server's lifespan put on the application."""
     return request.app.state.runner
@@ -248,9 +287,14 @@ def create_app(settings: Settings, *, client_factory: ClientFactory | None = Non
         """
         if runner.busy:
             raise SessionBusyError("A run is in progress; change the models when it ends")
-        added = await asyncio.to_thread(add_model_entry, body.entry(), path=settings.config_path)
-        if not runner.ready:
-            await runner.reload(model=added[-1].name)
+        entry = body.entry()
+        if runner.ready:
+            # The client the runs use changes with the file, so the model it lists and the one the next prompt can
+            # choose are the file's at once; a rebuild would drop the conversation in progress and its settings.
+            await asyncio.to_thread(runner.client.add_model, entry)
+        else:
+            added = await asyncio.to_thread(add_model_entry, entry, path=settings.config_path)
+            await runner.start(model=added[-1].name)
         return ModelsOut(models=[model_out(model) for model in runner.models_now()], current=runner.current_model)
 
     @protected.patch("/models/{name}", response_model=ModelsOut, tags=["models"])
@@ -261,8 +305,10 @@ def create_app(settings: Settings, *, client_factory: ClientFactory | None = Non
         changes = body.changes()
         if not changes:
             raise ValueError("Name at least one field to change")
-        await asyncio.to_thread(update_model_entry, name, changes, path=settings.config_path)
-        await runner.reload(model=runner.current_model)
+        if runner.ready:
+            await asyncio.to_thread(runner.client.update_model, name, changes)
+        else:
+            await asyncio.to_thread(update_model_entry, name, changes, path=settings.config_path)
         return ModelsOut(models=[model_out(model) for model in runner.models_now()], current=runner.current_model)
 
     @protected.delete("/models/{name}", response_model=ModelsOut, tags=["models"])
@@ -270,13 +316,15 @@ def create_app(settings: Settings, *, client_factory: ClientFactory | None = Non
         """Remove one model from the configuration file; the last one cannot go, since a client needs one."""
         if runner.busy:
             raise SessionBusyError("A run is in progress; change the models when it ends")
-        await asyncio.to_thread(remove_model_entry, name, path=settings.config_path)
-        await runner.reload()
+        if runner.ready:
+            await asyncio.to_thread(runner.client.remove_model, name)
+        else:
+            await asyncio.to_thread(remove_model_entry, name, path=settings.config_path)
         return ModelsOut(models=[model_out(model) for model in runner.models_now()], current=runner.current_model)
 
     @protected.get("/settings", response_model=SettingsOut, tags=["models"])
     async def settings_out(runner: RunnerDep) -> SettingsOut:
-        """Return the model, effort and permission a run starts with."""
+        """Return the model, effort, permission and harness a run starts with."""
         client = runner.client
         return SettingsOut(
             model=model_out(client.model),
@@ -284,18 +332,20 @@ def create_app(settings: Settings, *, client_factory: ClientFactory | None = Non
             efforts=list(client.efforts),
             permission=client.permission,
             permissions=list(client.permissions),
+            harness=client.harness,
         )
 
     @protected.patch("/settings", response_model=SettingsOut, tags=["models"])
     async def change_settings(update: SettingsUpdate, runner: RunnerDep) -> SettingsOut:
-        """Change the model, the reasoning effort, the permission level or the compaction point for the prompts that follow."""
+        """Change the model, effort, permission level, harness or compaction point for the prompts that follow."""
         if (
             update.model is None
             and update.effort is None
             and update.permission is None
+            and update.harness is None
             and update.compact_percent is None
         ):
-            raise ValueError("Name at least one of model, effort, permission or compact_percent")
+            raise ValueError("Name at least one of model, effort, permission, harness or compact_percent")
         client = runner.client
         if update.model is not None:
             client.use_model(update.model)
@@ -303,6 +353,8 @@ def create_app(settings: Settings, *, client_factory: ClientFactory | None = Non
             client.use_effort(update.effort)
         if update.permission is not None:
             client.use_permission(update.permission)
+        if update.harness is not None:
+            client.use_harness(update.harness)
         unsaved: str | None = None
         if update.compact_percent is not None:
             if runner.busy:
@@ -313,16 +365,19 @@ def create_app(settings: Settings, *, client_factory: ClientFactory | None = Non
 
     @protected.get("/sessions", response_model=SessionsOut, tags=["sessions"])
     async def list_sessions(runner: RunnerDep, limit: Annotated[int, Query(ge=1, le=200)] = 20) -> SessionsOut:
-        """List the stored sessions of this workspace, most recently active first."""
+        """List the stored sessions of this workspace, most recently active first, and which of them are running."""
         client = runner.client
         stored = await client.sessions.list(limit=limit)
-        return SessionsOut(sessions=[session_out(item, client.session.id) for item in stored])
+        running = runner.running_sessions()
+        return SessionsOut(sessions=[session_out(item, client.session.id, item.id in running) for item in stored])
 
     @protected.post("/sessions", response_model=SessionOut, status_code=201, tags=["sessions"])
     async def new_session(runner: RunnerDep, body: SessionCreate | None = None) -> SessionOut:
-        """Start an empty conversation and make it the one the next prompt continues."""
-        client = runner.client
-        session = client.sessions.new()
+        """Start an empty conversation and make it the one the next prompt continues.
+
+        A run in the conversation being left goes on there, and shows as running in the list.
+        """
+        session = await runner.new_session()
         if body is not None and body.title:
             await session.rename(body.title)
         return SessionOut(id=session.id, title=session.title, current=True)
@@ -334,8 +389,12 @@ def create_app(settings: Settings, *, client_factory: ClientFactory | None = Non
 
     @protected.post("/sessions/{session_id}/open", response_model=CurrentSessionOut, tags=["sessions"])
     async def open_session(session_id: str, runner: RunnerDep) -> CurrentSessionOut:
-        """Continue a stored conversation: the next prompt goes to it."""
-        session = await runner.client.sessions.open(session_id)
+        """Continue a stored conversation: the next prompt goes to it.
+
+        A run in the conversation being left goes on there. Opening a conversation that is running brings it back as
+        it is, run and all.
+        """
+        session = await runner.open_session(session_id)
         return current_session_out(session)
 
     @protected.post("/sessions/current/rename", response_model=SessionOut, tags=["sessions"])
@@ -421,6 +480,30 @@ def create_app(settings: Settings, *, client_factory: ClientFactory | None = Non
         """
         return stream_of(runner, request)
 
+    @protected.get("/commands", response_model=CommandsOut, tags=["prompts"])
+    async def commands(runner: RunnerDep) -> CommandsOut:
+        """List the commands every front end may run: a name, a summary, and what the run takes.
+
+        These are what the plugins registered on ``ctx.commands`` — text and a toast, or a preset for a turn — so a
+        client with no terminal can offer them without reimplementing any of them.
+        """
+        return CommandsOut(commands=list(runner.commands()))
+
+    @protected.post("/commands/{name}", response_model=CommandOut, tags=["prompts"])
+    async def run_command(name: str, body: CommandIn, runner: RunnerDep) -> CommandOut:
+        """Run one command by name and return what it answered with.
+
+        A command that answers with a prompt is not run as a turn here: the client sends ``POST /prompts`` with that
+        text and the ``shown`` line, so the turn belongs to the conversation the client is looking at, like every
+        other prompt.
+
+        ``404 not_found`` when no plugin registered that name.
+        """
+        try:
+            return await runner.run_command(name, body.argument)
+        except KeyError:
+            raise StarletteHTTPException(status_code=404, detail=f"No plugin registered the command {name!r}") from None
+
     @protected.post("/runs/resume", tags=["prompts"], responses={200: {"content": {"text/event-stream": {}}}})
     async def resume_run(request: ResumeRequest, runner: RunnerDep) -> StreamingResponse:
         """Continue the interrupted request where it stopped, streaming it like ``/prompts``.
@@ -456,7 +539,8 @@ def create_app(settings: Settings, *, client_factory: ClientFactory | None = Non
     @protected.post("/runs/steer", response_model=SteeredOut, tags=["prompts"])
     async def steer(body: SteerIn, runner: RunnerDep) -> SteeredOut:
         """Send a message into the run in progress; it drops what it was doing to take it into account."""
-        return SteeredOut(steered=runner.steer(body.text))
+        taken = runner.steer(body.text, body)
+        return SteeredOut(steered=taken is not None, text=taken)
 
     @protected.post("/runs/cancel", response_model=CancelledOut, tags=["prompts"])
     async def cancel_run(runner: RunnerDep) -> CancelledOut:
@@ -465,7 +549,12 @@ def create_app(settings: Settings, *, client_factory: ClientFactory | None = Non
 
     @protected.post("/sessions/current/ask", response_model=AnswerOut, tags=["sessions"])
     async def ask_side_question(body: SideQuestionRequest, runner: RunnerDep) -> AnswerOut:
-        """Ask something answered from the conversation but kept out of it, as ``/btw`` does."""
+        """Ask something answered from the conversation but kept out of it, as ``/btw`` does.
+
+        The client that asked is the reader, so the run is stored with the reader's origin and a reopen may restore it;
+        nothing has to be passed for that. Only the terminal restores one on resume — ``/history`` leaves every side
+        exchange out — and what is drawn live is the front end's own decision, as for the streamed sibling.
+        """
         if runner.busy:
             raise SessionBusyError("A run is already in progress; ask again when it ends")
         return AnswerOut(answer=await runner.client.session.ask(body.question, timeout=body.timeout))
@@ -522,11 +611,53 @@ def create_app(settings: Settings, *, client_factory: ClientFactory | None = Non
             headers={"Content-Disposition": f'attachment; filename="zettcode-{session.id[:8]}.html"'},
         )
 
+    @protected.post("/sessions/current/send", response_model=SentOut, tags=["sessions"])
+    async def send_message(body: SendIn, runner: RunnerDep) -> SentOut:
+        """Send a message to another ZettCode session explicitly, without a model turn."""
+        to, disposition = await runner.send(body.to, body.text, mode=body.mode)
+        return SentOut(to=to, disposition=disposition)
+
     @protected.get("/plugins", response_model=PluginsOut, tags=["models"])
     async def plugins(runner: RunnerDep) -> PluginsOut:
-        """List the plugins this server loaded, and the ones that could not load."""
+        """List the plugins this server loaded, the ones that failed, and every one a switch can reach."""
         report = runner.client.plugins
-        return PluginsOut(loaded=list(report.loaded), failures=list(report.failures))
+        return PluginsOut(
+            loaded=list(report.loaded),
+            failures=list(report.failures),
+            entries=[
+                PluginOut(
+                    name=entry.name,
+                    origin=entry.origin,
+                    builtin=entry.builtin,
+                    enabled=entry.enabled,
+                    failure=entry.failure,
+                    setting=entry.setting,
+                    switchable=entry.switchable,
+                    why=entry.why,
+                )
+                for entry in report.entries
+            ],
+        )
+
+    @protected.put("/plugins/{name}", response_model=PluginOut, tags=["models"])
+    async def switch_plugin(name: str, body: PluginSwitchIn, runner: RunnerDep) -> PluginOut:
+        """Turn one plugin's work on or off for the next start, and return it as the list now shows it.
+
+        Nothing is loaded or unloaded here: a switch is read once, when a process starts. A compiled-in plugin is
+        switched by a configuration key in the server's configuration file, an installed one by [plugins] disable there;
+        a client that wants the change now restarts the server, which is what the extension does.
+        """
+        entry = await asyncio.to_thread(runner.client.set_plugin_enabled, name, body.enabled)
+        return PluginOut(
+            name=entry.name,
+            origin=entry.origin,
+            builtin=entry.builtin,
+            enabled=entry.enabled,
+            failure=entry.failure,
+            setting=entry.setting,
+            switchable=entry.switchable,
+            why=entry.why,
+        )
 
     @protected.get("/mentions", response_model=MentionsOut, tags=["models"])
     async def mentions(
@@ -534,9 +665,31 @@ def create_app(settings: Settings, *, client_factory: ClientFactory | None = Non
         query: Annotated[str, Query(description="What was typed after the @, without it")] = "",
         limit: Annotated[int, Query(ge=1, le=200)] = 50,
     ) -> MentionsOut:
-        """List the files, skills and plugin resources an ``@`` in the prompt can reference."""
+        """List the files, skills, sessions and plugin resources an ``@`` in the prompt can reference."""
         return MentionsOut(mentions=[mention_out(item) for item in await runner.mentions(query, limit)])
 
+    @protected.get("/messages", response_model=InboxOut, tags=["prompts"])
+    async def messages(runner: RunnerDep) -> InboxOut:
+        """List the messages other sessions sent that this chat has not answered yet, oldest first."""
+        return InboxOut(
+            messages=[
+                InboxMessageOut(
+                    id=waiting.id,
+                    sender_id=waiting.message.sender_id,
+                    sender=waiting.message.sender,
+                    text=waiting.message.text,
+                    via=waiting.message.via,
+                    hops=waiting.message.hops,
+                )
+                for waiting in runner.waiting()
+            ]
+        )
+
+    @protected.post("/messages/{message_id}", tags=["prompts"], responses={200: {"content": {"text/event-stream": {}}}})
+    async def answer_message(message_id: str, runner: RunnerDep) -> StreamingResponse:
+        """Answer one message another session sent, streaming the turn exactly as ``/prompts`` does."""
+        return message_stream_of(runner, message_id)
+
     @protected.post("/doctor", response_model=DoctorOut, tags=["models"])
     async def doctor(runner: RunnerDep, body: DoctorRequest | None = None) -> DoctorOut:
         """Ask every configured model one short question and report which of them answer, as ``zettcode doctor``."""

{zettcode_server-0.1.1/src/zettcode_server → zettcode_server-0.4.0/src/zettcode/server}/cli.py

@@ -11,7 +11,8 @@ import os
 import sys
 from pathlib import Path
 
-from . import __version__
+from zettcode.version import __version__
+
 from .settings import DEFAULT_HOST, DEFAULT_PERMISSION, DEFAULT_PORT, TOKEN_VARIABLE, Settings
 
 
@@ -41,9 +42,14 @@ def build_parser() -> argparse.ArgumentParser:
     )
     parser.add_argument(
         "--permission",
-        choices=("deny", "ask", "safe", "auto"),
+        choices=("deny", "ask", "safe", "full", "auto"),
         default=DEFAULT_PERMISSION,
-        help=f"shell permission a run starts at (default: {DEFAULT_PERMISSION})",
+        help=f"shell permission a run starts at (default: {DEFAULT_PERMISSION}); auto is the old name of full",
+    )
+    parser.add_argument(
+        "--harness",
+        action="store_true",
+        help="start with the just-in-time harness on: the model may write and run its own Python tools (default: off)",
     )
     parser.add_argument("--model", default=None, help="model to start on, by name (default: the first configured)")
     parser.add_argument("--effort", default=None, help="reasoning effort to start on (default: the model's own)")
@@ -59,10 +65,8 @@ def build_parser() -> argparse.ArgumentParser:
 
 
 def version_text() -> str:
-    """Return the line ``--version`` prints: the server, and the agent it serves."""
-    from zettcode import __version__ as agent
-
-    return f"zettcode-server {__version__} (zettcode {agent})"
+    """Return the line ``--version`` prints: the server and the agent are one package, so one version."""
+    return f"zettcode-server {__version__}"
 
 
 def settings_from(argv: list[str] | None = None) -> Settings:
@@ -79,6 +83,7 @@ def settings_from(argv: list[str] | None = None) -> Settings:
         port=args.port,
         token=args.token or os.environ.get(TOKEN_VARIABLE) or None,
         permission=args.permission,
+        harness=args.harness,
         model=args.model,
         effort=args.effort,
         config_path=args.config.expanduser() if args.config is not None else None,