ph-stabilize 0.2.0__py3-none-any.whl

ph_stabilize/__init__.py

@@ -0,0 +1,17 @@
+"""pH stabilization bundle: todo, offload, compaction, limits, HITL and permissions.
+
+Deep Agents' features are *algorithms plus prompts, not runtime* (§1.3 of the
+port plan), so each one lands here as a row on a seam `ph-core` already
+publishes. Reserved in Phase 0 (P0-01); built from Phase 4.
+
+@module ph_stabilize
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+BUNDLE = Path(__file__).parent / "bundle.yaml"
+"""The rows the `stabilize` layer adds over `ph-base`."""
+
+__all__ = ["BUNDLE"]

ph_stabilize/bundle.yaml

@@ -0,0 +1,110 @@
+# ph-stabilize: Deep Agents' stabilization features as plugins, over `ph-base`.
+#
+# Every row here attaches to a waterfall that already exists — D12, the whole
+# integration thesis: todo planning is a tool plus a prompt section, offloading
+# is `tools/post-execute`, summarization is `agent/pre-step`. None of them is a
+# parameter on the loop, and none of them needs the loop to know it is there.
+#
+# Layered by a profile rather than by `ph-base`, because a deployment that wants
+# the plain harness should get the plain harness — and `ph-base` composed on its
+# own still is one.
+#
+# **Every profile `ph-app` offers layers this bundle**, `base` included, and as
+# an *optional* bundle: an install without this distribution composes the same
+# profiles and simply never compacts. The reason is one row rather than all
+# nine — a session that grows until the provider refuses it is a defect in any
+# posture, not a feature of an unattended one — and the rest come along because
+# a bundle is the unit a profile can name. They are inert by design, with one
+# exception worth knowing: `permissions-fs` below ships a live rule.
+
+# --- planning ---------------------------------------------------------------
+# `write_todos` + the `todo/write` event + the prompt section (G1). `disabled`
+# in its own bundle — the `rlm-context-loader` idiom — because layering this
+# bundle for offload or compaction must not, by itself, hand the model a tool:
+# upstream dropped `TodoListMiddleware` from its default stack and re-adds it
+# per model, so a profile flips this row on purpose (`rlm-stable` does, P4-15).
+- id: tool-todo
+  name: tool-todo
+  disabled: true
+
+# A skill that declares `steps:` becomes work the model must finish, and a
+# listener on `agent/turn-stopping` objects while any of it is startable (P7-18).
+# `disabled` for `tool-todo`'s reason and one more: this row can keep a turn
+# going, which is a posture a deployment chooses rather than inherits. Useless
+# without `tool-todo` — the list it seeds is that row's — so a profile that
+# enables this enables both.
+- id: skill-steps
+  name: skill-steps
+  disabled: true
+
+# --- context offloading -----------------------------------------------------
+# One oversized tool result can end a session's usefulness on its own, and the
+# model rarely needs all of it (G2/C5). Enabled: unlike planning, this changes
+# nothing until a result actually exceeds 80 000 characters, so a profile that
+# layered this bundle for any reason wants it — there is no posture in which
+# losing the context window to one `find /` is the preferred outcome.
+- id: tool-result-offload
+  name: tool-result-offload
+
+# The other direction: a pasted build log or dumped table (G3). Same reasoning
+# as above for being on — and the same shape, except that the substitution is a
+# surface `replace`, so the log keeps what the person actually sent while the
+# model reads a preview.
+- id: input-offload
+  name: input-offload
+
+# --- compaction -------------------------------------------------------------
+# When the conversation itself is the thing that no longer fits (G4). Enabled,
+# for the same reason the offload rows are: this changes nothing until a session
+# actually reaches 85% of its window, and there is no posture in which losing
+# the turn to an overflow is preferable to summarizing what has already been
+# answered. The engine is the `ctx.compaction` provider; the seam ships in
+# `ph-base` with no backend, so a profile that layers nothing here simply never
+# compacts.
+- id: compaction-summarize
+  name: compaction-summarize
+
+# The human verb, split from the policy exactly as dsh splits them: a deployment
+# may want automatic compaction without handing anyone a command, or the command
+# with a different engine behind it.
+- id: command-compact
+  name: command-compact
+
+# --- limits -----------------------------------------------------------------
+# Hard boundaries on a loop that has stopped making progress (G5). Mounted with
+# every ceiling unset, so layering the bundle changes nothing until a profile
+# names a number — a limit nobody chose is a limit that fires on someone's
+# longest legitimate turn. The breaker is the exception and is on by default:
+# five identical failures in a row is not a long task, it is a stuck one.
+- id: limits
+  name: limits
+
+# --- human in the loop ------------------------------------------------------
+# A person between the model and what it cannot take back (G6). `interrupt_on`
+# is empty by default, so layering the bundle prompts about nothing: a harness
+# that asks on first run teaches its user to approve without reading, which is
+# worse than not asking. A profile names the tools and the patterns it cares
+# about — `rlm-stable` does, at P4-15.
+- id: hitl
+  name: hitl
+
+# Path rules over filesystem access (G7). Attached to `ctx.fs`'s intent
+# waterfalls rather than to the fs tools, so a second editing tool or a Code
+# Mode binding is covered by the same rules; `rules` is empty by default, for
+# `hitl`'s reason — layering a bundle must not start refusing file access. The
+# row says out loud what it does not reach when no sandbox is mounted (E9).
+- id: permissions-fs
+  name: permissions-fs
+  config:
+    rules:
+      # The default write scope (E6, §12 Q9b), and the *last* rule on purpose:
+      # first-match-wins means every explicit rule an operator writes above it
+      # decides first, so this is a default rather than an override. A write
+      # inside the agent's own workspace or its scratch matches nothing and is
+      # allowed; one leaving them asks, once. Inert until a containment tier is
+      # in force — with no acquired workspace there is nothing to be outside of.
+      - operations: [write]
+        paths: ["**"]
+        scope: outside-workspace
+        mode: interrupt
+

ph_stabilize/compact_command.py

@@ -0,0 +1,86 @@
+"""`command-compact` — `/compact`, over the backend-independent seam (P4-03).
+
+A row of its own, exactly as dsh splits `command-compact` from
+`compaction-basic`: the human verb and the summarization policy are different
+decisions, and a deployment that wants automatic compaction without a slash
+command — or a slash command with a different engine behind it — should not have
+to fork either. This row injects `commands` and `compaction` and knows nothing
+about summaries.
+
+**A command is not a turn.** `/compact` is something the *person* asked the
+harness to do, so it dispatches directly, records `command/run` and
+`command/done`, and never opens a `turn/*`. The one thing it does open is a
+surface replacement, which is why it insists the agent is idle first — a
+compaction that landed mid-turn would move the surface underneath a request the
+loop had already derived.
+
+**Every failure is a sentence, not a traceback.** `CompactionError.code` is a
+closed set precisely so a front end can phrase each one; the mapping lives here
+because this is the only place that has a person to say it to.
+
+@module ph_stabilize.compact_command
+"""
+
+from __future__ import annotations
+
+from ph.cordis import Context, plugin
+from ph.keys import COMMANDS, COMPACTION
+from ph.seams.commands import CommandContext, CommandDefinition
+from ph.seams.compaction import CompactionError
+from ph.text import count_of
+
+__all__ = ["FAILURE_TEXT", "apply"]
+
+FAILURE_TEXT: dict[str, str] = {
+    "busy": (
+        "Compaction needs an idle session: this one is working, or a compaction "
+        "is already running. The conversation is unchanged."
+    ),
+    "summary": (
+        "Compaction could not produce a usable summary. The conversation is "
+        "unchanged; the attempt is recorded in the session log."
+    ),
+    "unavailable": "This profile has no compaction engine, so there is nothing to compact with.",
+}
+"""One line per `CompactionError.code`. dsh's `expectedFailure`, narrowed to the
+codes pH's seam actually defines — a phrase for a code nothing raises is a
+promise nobody can check."""
+
+
+@plugin("command-compact", inject=[COMMANDS, COMPACTION])
+async def apply(ctx: Context, config: None) -> None:
+    """Register `/compact`."""
+
+    async def compact(argument: str, invocation: CommandContext) -> str:
+        agent = invocation.agent
+        if agent is None:
+            return "refusing: /compact needs an agent whose session to compact"
+        try:
+            # Anything typed after the verb is the person saying what they are
+            # about to work on. dsh refuses arguments here and deepagents'
+            # compact tool takes none — but the moment someone compacts on
+            # purpose is usually the moment they are changing subject, and they
+            # know something about what comes next that the summarizer cannot
+            # read off the conversation. The engine decides what to do with it;
+            # this row only passes it on and lets the log record it.
+            result = await ctx.require(COMPACTION).compact_now(agent, instructions=argument.strip())
+        except CompactionError as error:
+            # `.get` rather than a lookup: a future code without a phrase should
+            # still say something true, and the exception's own message is the
+            # truest thing available.
+            return FAILURE_TEXT.get(error.code, str(error))
+        if result is None:
+            return "no compactable history yet"
+        return (
+            f"compacted {count_of(len(result.shadowed_seqs), 'message')} "
+            f"(~{result.shadowed_tokens} tokens)"
+        )
+
+    ctx.require(COMMANDS).register(
+        CommandDefinition(
+            name="compact",
+            summary="Replace older conversation history with a summary.",
+            argument_hint="[what you are about to work on]",
+            run=compact,
+        )
+    )