phern 0.3.0__tar.gz → 0.4.0__tar.gz

{phern-0.3.0 → phern-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: phern
-Version: 0.3.0
+Version: 0.4.0
 Summary: pH — a Python agent harness with no privileged core: every part is a row in a profile.
 Project-URL: Homepage, https://github.com/chastabor/pH
 Project-URL: Repository, https://github.com/chastabor/pH
@@ -23,20 +23,20 @@ Classifier: Typing :: Typed
 Requires-Python: >=3.12
 Requires-Dist: anyio<5,>=4.4
 Requires-Dist: httpx>=0.27
-Requires-Dist: ph-code-graph==0.3.0
-Requires-Dist: ph-core==0.3.0
-Requires-Dist: ph-rlm==0.3.0
-Requires-Dist: ph-runtime-guest==0.3.0
-Requires-Dist: ph-stabilize==0.3.0
-Requires-Dist: ph-text-index==0.3.0
+Requires-Dist: ph-code-graph==0.4.0
+Requires-Dist: ph-core==0.4.0
+Requires-Dist: ph-rlm==0.4.0
+Requires-Dist: ph-runtime-guest==0.4.0
+Requires-Dist: ph-stabilize==0.4.0
+Requires-Dist: ph-text-index==0.4.0
 Requires-Dist: pyyaml>=6.0
 Requires-Dist: rich>=13.0
 Requires-Dist: textual<9,>=8.2.5
 Requires-Dist: typer>=0.12
 Provides-Extra: local
-Requires-Dist: ph-text-index[local]==0.3.0; extra == 'local'
+Requires-Dist: ph-text-index[local]==0.4.0; extra == 'local'
 Provides-Extra: otel
-Requires-Dist: ph-core[otel]==0.3.0; extra == 'otel'
+Requires-Dist: ph-core[otel]==0.4.0; extra == 'otel'
 Provides-Extra: web
 Requires-Dist: textual-serve>=1.1.3; extra == 'web'
 Description-Content-Type: text/markdown

{phern-0.3.0 → phern-0.4.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "phern"
-version = "0.3.0"
+version = "0.4.0"
 description = "pH — a Python agent harness with no privileged core: every part is a row in a profile."
 readme = "README.md"
 requires-python = ">=3.12"
@@ -45,15 +45,15 @@ dependencies = [
     # `ph.bundles` composes a profile on an install of this package, and one
     # uninstalled from an install of this package takes its profiles out of
     # `phern doctor` rather than breaking the six that remain.
-    "ph-core==0.3.0",
-    "ph-rlm==0.3.0",
-    "ph-stabilize==0.3.0",
-    "ph-text-index==0.3.0",
-    "ph-code-graph==0.3.0",
+    "ph-core==0.4.0",
+    "ph-rlm==0.4.0",
+    "ph-stabilize==0.4.0",
+    "ph-text-index==0.4.0",
+    "ph-code-graph==0.4.0",
     # Reached through `ph-rlm` already; pinned here too because `ph_rlm.kernel`
     # installs it *by name* into `$PH_CACHE/runtime-venv`, so the version this
     # deployment resolves is the version a cell runs against.
-    "ph-runtime-guest==0.3.0",
+    "ph-runtime-guest==0.4.0",
     # Declared although `ph-core` already requires it: `ph_app.daemon` imports
     # `anyio` directly at 20-odd sites and `cancelsafe` is keyed to its
     # internals, so arriving here transitively understated the coupling.
@@ -111,13 +111,13 @@ web = ["textual-serve>=1.1.3"]
 # default CUDA wheels. Without it `text_index` and `text_search` still register
 # and still search an index you supply vectors for — what refuses to mount is
 # the row that *computes* them, with a message naming this extra.
-local = ["ph-text-index[local]==0.3.0"]
+local = ["ph-text-index[local]==0.4.0"]
 
 # Exporting the session log to an OTel collector, passed through for the same
 # reason `local` is: `ph-core` owns the row and the refusal message, but `phern`
 # is the name a person installs, so all three of this deployment's extras should
 # be reachable without first learning which member implements which.
-otel = ["ph-core[otel]==0.3.0"]
+otel = ["ph-core[otel]==0.4.0"]
 
 [project.entry-points."ph.plugins"]
 llm-openai-compatible = "ph_app.adapters.openai_compatible:apply"

phern-0.4.0/src/ph_app/__init__.py

@@ -0,0 +1,12 @@
+"""`ph_app` — the pH command line, and from Phase 2 the Textual TUI.
+
+**Importing any of the app declares its intent kinds** (T4): `kinds` is imported here,
+statically, so a process that loaded any part of the app — and so may resume a log the
+app wrote — has `CLIENT_COMMAND` for repair to settle. See `ph_app.kinds`.
+"""
+
+from __future__ import annotations
+
+from . import kinds as kinds
+
+__all__: list[str] = ["kinds"]

{phern-0.3.0 → phern-0.4.0}/src/ph_app/adapters/anthropic.py

@@ -408,7 +408,7 @@ class AnthropicAdapter:
         # instruction, the validation and the retry, and not the wire's guarantee
         # (P7-17). Passing it rather than leaving a default unremarked is what
         # stops the next adapter copying an omission it thought was an oversight.
-        return resolved(self.config, structured_output=False)
+        return resolved(self.config, structured_output=False, credential=self.config.api_key_env)
 
 
 @dataclass(slots=True)

{phern-0.3.0 → phern-0.4.0}/src/ph_app/adapters/google.py

@@ -515,7 +515,7 @@ class GoogleAdapter:
         # See `_body`: this route is asked for JSON and not held to a schema, so
         # it does not enforce one. Claiming otherwise would make a caller skip the
         # validation that is actually doing the work.
-        return resolved(self.config, structured_output=False)
+        return resolved(self.config, structured_output=False, credential=self.config.api_key_env)
 
 
 def _file_record(payload: dict[str, Any]) -> dict[str, Any]:

{phern-0.3.0 → phern-0.4.0}/src/ph_app/adapters/openai_compatible.py

@@ -441,7 +441,7 @@ class OpenAiCompatibleAdapter:
         # This wire takes `response_format: {"type": "json_schema", …}` with
         # `strict`, so the server builds a grammar and the reply cannot come back
         # another shape (P7-17).
-        return resolved(self.profile, structured_output=True)
+        return resolved(self.profile, structured_output=True, credential=self.profile.api_key_env)
 
 
 @dataclass(slots=True)

{phern-0.3.0 → phern-0.4.0}/src/ph_app/cli.py

@@ -203,7 +203,8 @@ def default(
         # because the logs worth auditing are the ones nobody can reopen (P3-25).
         if session_id is None:
             fail("[red]--mode trajectory needs --session <id|path>[/red]", code=2)
-        from .tui.trajectory_app import run_trajectory
+        # A late load: a command pays only for what it runs (`test_app_layering.py`).
+        from .tui.trajectory_app import run_trajectory  # noqa: PLC0415
 
         try:
             code = anyio.run(partial(run_trajectory, session_id))
@@ -228,7 +229,7 @@ def default(
         #
         # Imported here because the TUI pulls in Textual, and `phern -p` in a
         # script should not pay for a terminal UI it will never draw.
-        from .tui.app import run_tui
+        from .tui.app import run_tui  # noqa: PLC0415
 
         code = anyio.run(
             partial(
@@ -270,7 +271,7 @@ def default(
         # must not require aiohttp, and a person who asked for `--mode web`
         # without it gets the install line rather than a traceback.
         try:
-            from .web.serve import WebServer, run_web
+            from .web.serve import WebServer, run_web  # noqa: PLC0415
         except ImportError as error:
             fail(
                 "[red]--mode web needs the web extra:[/red] pip install 'phern\\[web]'",
@@ -325,7 +326,7 @@ def default(
     )
     # Here rather than at the top: `phern --help` must not pay for the persistence
     # layer, and `route` is about to import it anyway.
-    from ph.persistence import SessionBusy
+    from ph.persistence import SessionBusy  # noqa: PLC0415
 
     try:
         outcome = anyio.run(route)
@@ -442,7 +443,7 @@ def doctor(
     # Imported here rather than at module scope: `ph_app.daemon.supervisor`
     # pulls in the agent, the persistence layer and `filelock`, and `phern --print`
     # has no daemon in it. `daemon()` below reaches for `serve` the same way.
-    from .daemon.supervisor import NON_GUARANTEES
+    from .daemon.supervisor import NON_GUARANTEES  # noqa: PLC0415
 
     before_mount = [
         ("daemon socket lifetime", lifetime(roots=roots).describe()),
@@ -522,7 +523,8 @@ def _spawned_keep_alive(value: str | None, *, keep: bool) -> str:
             )
         return "0"
     if value is None:
-        from .tui.config import load_tui_settings
+        # A late load: a command pays only for what it runs (`test_app_layering.py`).
+        from .tui.config import load_tui_settings  # noqa: PLC0415
 
         value = load_tui_settings(resolve_roots().home).daemon_keep_alive
     return f"{keep_alive_seconds(value):g}"
@@ -632,7 +634,8 @@ def _children_cap(value: int | None) -> list[str]:
         return []
     if value < 1:
         raise typer.BadParameter(f"wants a positive number of children, not {value}")
-    from ph.seams.jobs import CHILDREN_KIND
+    # A late load: a command pays only for what it runs (`test_app_layering.py`).
+    from ph.seams.jobs import CHILDREN_KIND  # noqa: PLC0415
 
     return [f"{{id: jobs, config: {{concurrency: {{{CHILDREN_KIND}: {value}}}}}}}"]
 
@@ -680,7 +683,8 @@ def daemon(
     it. A parent's own fair share is `rlm-subagent-provider`'s `maxConcurrent`,
     and both apply. Neither refuses a delegation — the overflow queues.
     """
-    from .daemon.server import DaemonUnavailable, serve
+    # A late load: a command pays only for what it runs (`test_app_layering.py`).
+    from .daemon.server import DaemonUnavailable, serve  # noqa: PLC0415
 
     # Parsed before anything is composed or bound, so a mistyped duration is a
     # usage error rather than a daemon that got as far as printing a socket path.

{phern-0.3.0 → phern-0.4.0}/src/ph_app/daemon/client.py

@@ -110,7 +110,7 @@ class DaemonClient:
         landed, and an unkeyed retry runs the effect twice. So the stamp is
         applied here, once, rather than at each verb — `prompt` was the only verb
         that had it, and `session/command`, `session/shell`, `session/stage`,
-        `session/preset` and `credentials/store` are all in the same table.
+        and `session/preset` are all in the same table.
 
         The counter is this client's own, which is what makes a retry after a
         reconnect safe by default rather than by discipline.
@@ -127,8 +127,8 @@ class DaemonClient:
         **The reply is `R | MutationRepeated`, and that union is the honest
         one.** A repeat answers with one shape for every verb (`MUTATIONS` says
         why), and for the verbs whose own reply is a `RootDescription` the
-        repeat is a subtype — but `session/shell` answers with an exit code and
-        `credentials/store` with a name, so a caller that ignored the union
+        repeat is a subtype — but `session/shell` answers with an exit code, so a
+        caller that ignored the union
         would be reading fields off a description that is not there. Narrow on
         `isinstance(reply, MutationRepeated)`, which is the branch
         `MutationRepeated.repeated` was always for.

{phern-0.3.0 → phern-0.4.0}/src/ph_app/daemon/frontend.py

@@ -22,9 +22,9 @@ That re-posing is **in-memory, and so lasts as long as the daemon does** — whi
 is the whole of what it promises, and no longer a silent edge. A restart cannot
 carry the ask across, because what was waiting on it was a coroutine inside a
 turn, and both are gone. What it does instead is **settle** it: repair writes the
-`approval/decided` the crash never got to (P5-13), so `pending_approvals` stops
-reporting a question nobody can answer and the transcript says the person was
-still being asked when the harness stopped.
+`approval/decided` the crash never got to (P5-13), so the log holds no ask nobody
+can answer and the transcript says the person was still being asked when the
+harness stopped.
 
 So the guarantee is bounded and stated rather than absent. Within one daemon, an
 ask outlives every front end and waits for whoever turns up. Across a restart it
@@ -104,6 +104,22 @@ class AskDesk:
     root: Root
     front_ends: set[FrontEnd] = field(default_factory=set)
     asks: dict[str, PendingAsk] = field(default_factory=dict)
+    asked: int = 0
+    """How many asks this desk has named. The next is `ask-<asked + 1>`.
+
+    The desk names each ask itself, because nothing the seams hand it is unique.
+    The Continual Harness's `refine` approvals have no call id, which leaves only
+    the tool name, and a question's `ask_id` is whatever its caller passed. Two
+    asks under one name shared an entry in `asks`: the first to finish took the
+    other's with it, and the root read as idle while still parked on a person.
+
+    Unique within this root only, and on purpose: a root is self-contained and
+    coordinates with no other. Every ask frame and `ask.settled` carries the root's
+    `sessionId`, so a front end attached to two roots files an ask by both
+    (`AskKey`, each frame's `key`). A root started again has a new desk, counting
+    from 1 again. That is safe because `Supervisor.passivatable` never releases a
+    root with a front end attached, and a front end that loses the daemon takes its
+    own modals down."""
 
     # ------------------------------------------------------------- wiring --
 
@@ -175,13 +191,14 @@ class AskDesk:
     ) -> ApprovalAnswer:
         """`ctx.approval`'s answerer, over the socket.
 
-        The ask is keyed by the same string `pending_approvals` uses — the call
-        id, or the tool name when there is none — so a question re-posed after a
-        restart is recognizably the one the log is still holding open.
+        Named on the wire by the desk (`asked`), not by its call id, which a
+        `refine` ask does not have. The call id and the tool name still travel, in
+        `request`.
         """
-        ask_id = request.call_id or request.tool_name
         result = ApprovalAskReply.model_validate(
-            await self._ask(ApprovalAsk(session_id=self.root.id, ask_id=ask_id, request=request))
+            await self._ask(
+                ApprovalAsk(session_id=self.root.id, ask_id=self._name(), request=request)
+            )
         )
         if reason := result.reason:
             # "No, use the existing helper" redirects a turn where a bare refusal
@@ -199,22 +216,22 @@ class AskDesk:
     ) -> str | None:
         """`ctx.user_questions`' answerer, over the socket.
 
-        Keyed by the question's own `ask_id`, which `UserQuestionService.ask`
-        fills in before any answerer sees it — so the frame a front end answers
-        and the record a resume would re-pose from are the same string rather
-        than two that happen to line up. Minting a fallback here would be a
-        second, weaker id scheme (a counter that restarts at 1 after a resume)
-        for a value the seam already mints so that it cannot collide.
+        Named on the wire by the desk (`asked`), as an approval is. The question's
+        own `ask_id`, the log's `askId`, still travels, in `question`.
         """
         result = QuestionAskReply.model_validate(
             await self._ask(
-                QuestionAsk(session_id=self.root.id, ask_id=str(question.ask_id), question=question)
+                QuestionAsk(session_id=self.root.id, ask_id=self._name(), question=question)
             )
         )
         return result.answer
 
     # ------------------------------------------------------------ the ask --
 
+    def _name(self) -> str:
+        self.asked += 1
+        return f"ask-{self.asked}"
+
     async def _ask(self, ask: ApprovalAsk | QuestionAsk) -> dict[str, Any]:
         """Put one question to every front end and wait for the first answer.
 

{phern-0.3.0 → phern-0.4.0}/src/ph_app/daemon/server.py

@@ -46,11 +46,12 @@ from ph.resources import GRACE_SECONDS
 from ph.seams.attachments import mime_for
 from ph.seams.schedule import Schedule
 from ph.seams.shell import ShellService
-from ph.session import now_ms
+from ph.session import Prior, intents_of, now_ms, session_written
 from ph.text import duration
 from ph.wire import WireModel
 
 from .. import verbs
+from ..kinds import CLIENT_COMMAND, command_settled
 from ..params import (
     BrowseParams,
     CancelScheduleParams,
@@ -83,6 +84,7 @@ from ..payloads import (
     Hold,
     MutationRepeated,
     PresetApplied,
+    RepeatOutcome,
     RootDescription,
     RootListing,
     RootStatusReply,
@@ -135,7 +137,6 @@ from .supervisor import NON_GUARANTEES, Root, Supervisor
 if TYPE_CHECKING:
     from ph.seams.attachments import AttachmentStore
     from ph.seams.commands import CommandRegistry
-    from ph.seams.credentials import CredentialService
     from ph.seams.permission_presets import PermissionPresetService
 
 __all__ = ["DaemonServer", "serve"]
@@ -173,7 +174,7 @@ the answer to one question decided how often the other was asked.
 
 Five minutes, and slow on purpose. A check is O(events) in every live root's log
 and will almost always pass — it exists to catch a writer that bypassed
-`Session.append`, which is a bug nobody has on a schedule. Fast enough to name
+`Session._append`, which is a bug nobody has on a schedule. Fast enough to name
 the drift inside a working session, slow enough that the refold is not a tax
 anybody would later be tempted to remove.
 
@@ -275,6 +276,12 @@ for free — where a shared base would have to declare a `handle` returning
 """
 
 
+def _repeat_outcome(prior: Prior) -> RepeatOutcome:
+    """`settled` only for a verb its act saw finish: one still acting in this process,
+    or one repair or a raising act closed, is `unknown` in so many words."""
+    return "settled" if prior.outcome == "done" else "unknown"
+
+
 def _command_key(params: MutationParams) -> str:
     """A client's idempotence key, joined at the wire edge and only here.
 
@@ -495,9 +502,45 @@ class _Connection:
         parsed = mutation.verb.parse(params)
         root = await self.server.supervisor.start(parsed.session_id)
         plan = await mutation.prepare(self, root, parsed)
-        if not root.once(_command_key(parsed)):
-            return MutationRepeated(**root.describe().model_dump())
-        return await mutation.act(self, root, parsed, plan)
+        key = _command_key(parsed)
+        if not key:
+            # No identity offered, so no deduplication wanted: it always acts.
+            reply = await mutation.act(self, root, parsed, plan)
+        else:
+            journal = intents_of(root.ctx)
+            # The key is claimed between the halves (`Mutation` says why), and an
+            # act that raises is settled `unknown` by `claim` rather than leaving
+            # a key that refuses the retry with no word that nothing finished.
+            async with journal.claim_once(root.session, CLIENT_COMMAND, {"command": key}) as held:
+                if isinstance(held, Prior):
+                    # The retry a reconnecting client cannot avoid sending: it
+                    # does not know whether the first one landed. Answering "yes,
+                    # that one — and here is whether it finished" is what makes
+                    # asking twice safe.
+                    return MutationRepeated(
+                        **root.describe().model_dump(), outcome=_repeat_outcome(held)
+                    )
+                reply = await mutation.act(self, root, parsed, plan)
+                journal.settle(root.session, held, command_settled(key))
+        # **Durable before the client is told** (F7). A client that has its reply
+        # never re-sends, so a reply sent while the key and the act's own record
+        # were still in memory made a crash lose the act outright — and
+        # `session/prompt`'s "the message is logged" meant logged in a buffer.
+        # After the act, which is why `CLIENT_COMMAND` is `buffered`: a key made
+        # durable first would turn a crash before the act into a refused retry
+        # for work that never began. An act that records its own start before an
+        # effect it cannot take back (`!!`, `run_shell`) carries the key to disk
+        # with that record, and a crash then leaves an open key repair settles
+        # `unknown` — which the retry is told. One flush of the root, which
+        # carries the key, the act and its settle.
+        #
+        # `written`, not `flush`: the act has happened by now, so a write that
+        # fails does not make it not have happened, and answering the verb with
+        # an error would tell the client the one thing that is false. A disk that
+        # refuses writes is the root's own flushes failing next, which is the
+        # retry ladder's to report (`supervisor/failed`).
+        await session_written(root.ctx, root.session)
+        return reply
 
     # --- the methods -----------------------------------------------------------
     # One per row of `METHODS`, each taking its own params model. Read-only
@@ -766,21 +809,25 @@ class _Connection:
         _refresh_readings(root)
         return PresetApplied(session_id=root.id, preset=applied.name)
 
-    async def _prepare_credential(
-        self, root: Root, params: StoreCredentialParams
-    ) -> CredentialService:
+    async def _credentials_store(self, params: StoreCredentialParams) -> CredentialStored:
+        """Hand a root a credential's value, which it uses and does not keep.
+
+        **Unkeyed** (T5). Storing one value twice stores it once, so a retry needs no
+        key; and a key would outlive what it named — the value lives in this
+        process's memory, so after a restart a re-send is the only way it comes back.
+        `start` rather than `_root`: the value belongs to a mounted root's seam.
+        """
+        root = await self.server.supervisor.start(params.session_id)
         service = root.ctx.get(CREDENTIALS)
         if service is None:
             raise SeamAbsent("this deployment stores no credentials")
-        return service
-
-    async def _act_credential(
-        self, root: Root, params: StoreCredentialParams, service: CredentialService
-    ) -> CredentialStored:
         # **The value is used and not kept.** It is never logged, never echoed
         # in the reply, and never reaches `describe()` — the reply is the name
         # and a boolean, which is everything a UI needs to redraw.
         service.provide_value(params.name, params.value)
+        # And whatever was waiting on it goes (T5): the root, if its route named
+        # this, and every child held for it.
+        await self.server.supervisor.credential_supplied(root)
         return CredentialStored(session_id=root.id, name=params.name)
 
     def _attachments(self, root: Root, refs: list[AttachmentRef]) -> list[AttachmentRef]:
@@ -1060,11 +1107,6 @@ MUTATIONS: dict[str, Mutation[Any, Any]] = dict(
         _mutating(verbs.SESSION_STAGE, _Connection._prepare_stage, _Connection._act_stage),
         _mutating(verbs.SESSION_SHELL, _Connection._prepare_shell, _Connection._act_shell),
         _mutating(verbs.SESSION_PRESET, _Connection._prepare_preset, _Connection._act_preset),
-        _mutating(
-            verbs.CREDENTIALS_STORE,
-            _Connection._prepare_credential,
-            _Connection._act_credential,
-        ),
     )
 )
 """Every method that changes a root, and the one place their idempotence lives.
@@ -1077,7 +1119,9 @@ a method in this table gets the write-ahead guard whether its author thought of
 it or not, and one that is not in it cannot claim to be idempotent by key.
 
 The repeat reply has one shape — `MutationRepeated`, a description carrying
-`repeated: true` — so a client branches on one field for every verb.
+`repeated: true` and whether the first attempt finished (`outcome`) — so a client
+branches on one field for every verb. The keys and their outcomes are the
+journal's (`CLIENT_COMMAND`, P10-10).
 Deliberately absent: `attachment/put`
 (content-addressed, so a retry is a no-op already, and its reply *is* the
 reference a repeat must still return) and `session/new` (`start` is idempotent
@@ -1098,6 +1142,7 @@ METHODS: dict[str, _Row] = dict(
         _unkeyed(verbs.SESSION_SNAPSHOT, _Connection._snapshot),
         _unkeyed(verbs.ATTACHMENT_PUT, _Connection._put),
         _unkeyed(verbs.CREDENTIALS_HELD, _Connection._credentials_held),
+        _unkeyed(verbs.CREDENTIALS_STORE, _Connection._credentials_store),
         # The read-only projections (P5-14). What a front end used to read straight
         # off `ctx`; each is a fold computed now, so a reconnecting client gets
         # today's answer rather than one cached when somebody last wrote it down.
@@ -1297,6 +1342,9 @@ class DaemonServer:
                 ],
             ),
             ("socket lifetime", self.socket_lifetime().describe()),
+            # What is held for a credential, by name (T5) — the question a person
+            # asks when a child resumed after a restart and is not moving.
+            ("credentials awaited", self.supervisor.awaited() or [("held", "nothing")]),
             # The daemon's own non-guarantees (N5, I-2), printed by the command a
             # person runs to ask what this daemon is. Rule 6 wants them beside
             # where they would be assumed, and this reply *is* that place: it