ph-rlm 0.1.0__py3-none-any.whl

ph_rlm/__init__.py

@@ -0,0 +1,18 @@
+"""pH's RLM bundle: Prime Agent's design implemented on pH's seams.
+
+The rule the whole package follows (§6.8): take prime-agent's *semantics* — the
+RLM loop, non-blocking admission, the nuclear-family boundary, the Continual
+Harness, the doctrine prompts — and implement them on pH's seams. Do not take its
+runtime. `ph_rlm.kernel` is pH's own, and `ph_runtime` is its guest half.
+
+@module ph_rlm
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+BUNDLE = Path(__file__).parent / "bundle.yaml"
+"""The rows the `rlm` profile layers over `ph-base`."""
+
+__all__ = ["BUNDLE"]

ph_rlm/bindings.py

@@ -0,0 +1,259 @@
+"""`rlm-bindings` — the `rlm` namespace, as governed tool calls (P3-10, C2/C3).
+
+Prime Agent's `await rlm("task", name=..., model=...)` travelled over a Jupyter
+comm channel as a `host.request`, which meant it was invisible to
+`tools/pre-execute`, to `ctx.approval`, to the call limits and to the offload
+policy. Here the same call is a **binding**: one `call` frame out of the kernel,
+through the whole tool pipeline, landing as a durable
+`tool/code-dispatch-start`/`tool/code-dispatch` pair. A deployment can therefore
+deny or `ask` on subagent spawning by policy, and `max_subagent_spawns_per_run`
+counts it, without a line of code here.
+
+Two decisions worth stating:
+
+**The program-facing name is not the tool name.** A cell writes `rlm.run(...)`;
+the governed tool is `rlm_run`. A namespace cannot claim a bare global name like
+`run` — and it does not need to, because the SDK renders the namespaced form
+while the log records the tool. Only the tools exist as a registry surface, so a
+policy row addresses `rlm_run` and means exactly one thing.
+
+**Spawning is `counts_as_spawn`.** The bridge holds it to C4's spawn budget
+rather than the general dispatch budget, so one approved cell cannot fan out
+past `max_subagent_spawns_per_run` on the strength of that one approval.
+
+`find_models` is deliberately absent: it would need a model *catalogue* on
+`ctx.llm`, which does not exist yet. Advertising a discovery call that could only
+answer "I don't know" would be worse than not offering one, and the model already
+inherits the parent's model when it names none.
+
+@module ph_rlm.bindings
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from ph.cordis import Context, plugin
+from ph.json import JsonObject, as_str
+from ph.keys import SUBAGENTS, TOOLS
+from ph.llm.types import ContentBlock
+from ph.seams.code_runtime import CodeBindingNamespace
+from ph.seams.subagents import (
+    Access,
+    DowngradeReason,
+    SubagentRequest,
+    SubagentSpawnError,
+    downgrade_text,
+)
+from ph.tools import ToolModel, ToolOutput, ToolRunContext, define_tool, text_content
+from ph.tools.code_mode import CodeBindingsRequest, ToolCallError, governed_binding
+from ph.wire import WireModel
+
+from .keys import RLM_CHILDREN
+from .subagents import PROVIDER_NAME
+
+__all__ = ["NAMESPACE", "Config", "apply"]
+
+NAMESPACE = "rlm"
+
+RUN_TOOL = "rlm_run"
+LIST_TOOL = "rlm_list_subagents"
+DELETE_TOOL = "rlm_delete_subagent"
+
+_RUN_DESCRIPTION = (
+    "Delegate a task to a child agent. Returns immediately with an admission "
+    "handle — never the answer. The child replies by sending you an agent "
+    "message, which arrives on a later turn; do not wait or sleep for it."
+)
+
+
+class RunArgs(ToolModel):
+    """`rlm.run(...)`. Snake_case because the model types these names."""
+
+    prompt: str
+    name: str | None = None
+    model: str | None = None
+    thinking: str | None = None
+    access: Access = "read"
+    """`read` | `write`. Defaults to `read` (E4): a child that only needs to read
+    must not be handed a writable repo because nobody said otherwise. Typed, so
+    pydantic validates it and the model sees the two values in the schema."""
+    preset: str | None = None
+    """A named kind of child this deployment configured. Fills in what you did not
+    name; it cannot give the child more than you have (P4-13b)."""
+    skills: tuple[str, ...] | None = None
+    """Skills the child gets, by name from your own catalog. Naming one is also an
+    instruction: its full text goes in the child's prompt, so the child starts by
+    following that procedure rather than having to fetch it. `None` gives it
+    everything you have; you cannot name a skill you do not have (P4-13b)."""
+    tools: tuple[str, ...] | None = None
+    """Tools the child may call. `None` gives it everything you have. You cannot
+    name a tool you do not have."""
+
+
+class DeleteArgs(ToolModel):
+    child_id: str
+    reason: str = "user"
+
+
+class SpawnHandle(WireModel):
+    """What a spawn hands back. Deliberately not the answer."""
+
+    child_id: str
+    name: str
+    session_id: str
+    model: str
+    requested_access: Access
+    granted_access: Access
+    note: str | None = None
+    """The sentence for `SubagentRun.downgrade_reason`, rendered by the seam.
+
+    The model needs prose; the *log* keeps the code. One generator, so the two
+    cannot disagree and neither goes stale when the workspace tier lands."""
+
+
+class Config(WireModel):
+    """Row config for `rlm-bindings`."""
+
+    provider: str = PROVIDER_NAME
+    """Which `ctx.subagents` provider `rlm.run` delegates to."""
+
+
+def _render_handle(_args: JsonObject, value: Any) -> list[ContentBlock]:  # noqa: ANN401
+    lines = [
+        f"admitted {value['name']} ({value['childId']}) on {value['model']}",
+        f"session: {value['sessionId']}",
+        f"workspace access: {value['grantedAccess']} (requested {value['requestedAccess']})",
+    ]
+    if value.get("note"):
+        lines.append(as_str(value["note"]))
+    lines.append("It will reply by agent message; keep working and check later.")
+    return text_content("\n".join(lines))
+
+
+@plugin("rlm-bindings", config=Config, inject=[TOOLS, SUBAGENTS, RLM_CHILDREN])
+async def apply(ctx: Context, config: Config) -> None:
+    """Register the `rlm_*` tools and group them as the `rlm` code namespace."""
+
+    tools = ctx.require(TOOLS)
+
+    async def run_child(args: RunArgs, run: ToolRunContext) -> dict[str, Any]:
+        if run.agent is None:
+            raise ToolCallError(RUN_TOOL, "this tool has to be called by an agent")
+        try:
+            handle = await ctx.require(SUBAGENTS).start(
+                config.provider,
+                SubagentRequest(
+                    prompt=args.prompt,
+                    parent=run.agent,
+                    # The boundary the ceiling is computed in, stated rather than
+                    # derived from the routing target (P6-31, P6-24).
+                    scope=run.scope,
+                    name=args.name,
+                    reasoning_effort=args.thinking,
+                    model=args.model,
+                    access=args.access,
+                    preset=args.preset,
+                    skills=args.skills,
+                    tools=args.tools,
+                ),
+            )
+        except SubagentSpawnError as error:
+            # The model's to handle: it can retry with a different name, a
+            # shallower plan, or by doing the work itself.
+            raise ToolCallError(RUN_TOOL, str(error)) from error
+        reason: DowngradeReason | None = handle.downgrade_reason
+        return SpawnHandle(
+            child_id=handle.id,
+            name=handle.name,
+            session_id=handle.session_id,
+            model=handle.model,
+            requested_access=handle.requested_access,
+            granted_access=handle.granted_access,
+            note=downgrade_text(reason) if reason is not None else None,
+        ).to_wire()
+
+    def list_children(_args: object, run: ToolRunContext) -> dict[str, Any]:
+        """The roster, folded from the parent's own log — never a side table."""
+        session = run.session
+        rows = list(ctx.require(SUBAGENTS).roster(session).values()) if session is not None else []
+        return {"children": rows}
+
+    async def delete_child(args: DeleteArgs, run: ToolRunContext) -> dict[str, Any]:
+        session = run.session
+        removed = (
+            await ctx.require(RLM_CHILDREN).delete(session, args.child_id, reason=args.reason)
+            if session is not None
+            else False
+        )
+        return {"deleted": removed, "childId": args.child_id}
+
+    tools.register(
+        define_tool(
+            RUN_TOOL,
+            _RUN_DESCRIPTION,
+            parameters=RunArgs,
+            output=ToolOutput(schema=SpawnHandle, render=_render_handle),
+            execute=run_child,
+        )
+    )
+    tools.register(
+        define_tool(
+            LIST_TOOL,
+            "Your children: name, id, status, and whether each was deleted.",
+            parameters={"type": "object", "properties": {}},
+            output={"type": "object"},
+            render=_render_roster,
+            execute=list_children,
+            is_concurrency_safe=True,
+        )
+    )
+    tools.register(
+        define_tool(
+            DELETE_TOOL,
+            "Revoke a child. Its transcript stays on disk; the roster keeps a tombstone.",
+            parameters=DeleteArgs,
+            output={"type": "object"},
+            render=_render_deleted,
+            execute=delete_child,
+        )
+    )
+
+    def namespace(request: CodeBindingsRequest) -> CodeBindingNamespace:
+        """`rlm.run` / `.list_subagents` / `.delete_subagent`, bound to the run."""
+        view = ctx.require(TOOLS).view(request.scope)
+        specs = (
+            ("run", RUN_TOOL, True),
+            ("list_subagents", LIST_TOOL, False),
+            ("delete_subagent", DELETE_TOOL, False),
+        )
+        bindings = [
+            governed_binding(request, public, definition.schema(), counts_as_spawn=spawns)
+            for public, tool_name, spawns in specs
+            # A tool restricted away for this agent is absent from the SDK block
+            # too, so the prompt cannot offer what a cell could not call.
+            if (definition := view.visible.get(tool_name)) is not None
+        ]
+        return CodeBindingNamespace(
+            name=NAMESPACE,
+            description="delegate to child agents; every spawn is governed and recorded",
+            bindings=tuple(bindings),
+        )
+
+    tools.register_code_namespace(NAMESPACE, namespace)
+
+
+def _render_roster(_args: JsonObject, value: Any) -> list[ContentBlock]:  # noqa: ANN401
+    rows = value.get("children") or []
+    if not rows:
+        return text_content("no children")
+    lines = [
+        f"- {row.get('name')} ({row.get('runId')}) "
+        f"{'deleted' if row.get('deleted') else row.get('status', 'queued')}"
+        for row in rows
+    ]
+    return text_content("\n".join(lines))
+
+
+def _render_deleted(_args: JsonObject, value: Any) -> list[ContentBlock]:  # noqa: ANN401
+    return text_content(f"deleted {value['childId']}" if value["deleted"] else "no such child")

ph_rlm/bundle.yaml

@@ -0,0 +1,174 @@
+# ph-rlm: Prime Agent's design as plugins, over ph-base.
+#
+# The `rlm` profile is base + tui + this. Every row here is a listener on a seam
+# that already exists; the only core change the bundle needs is the one the
+# `code_runtime` seam already carries — `namespace` and `persistence` (C1).
+
+# --- Code Mode --------------------------------------------------------------
+# Opt-in in `ph-base`, on here: the RLM model writes Python, so the transport
+# and its bindings are the whole surface it sees. `tools.mode: code` is what
+# makes a native tool call refuse with the SDK route back (C6).
+- id: tools
+  config:
+    mode: code
+
+- id: tools-code-mode
+  name: tools-code-mode
+  config:
+    maxDispatchesPerRun: 256
+    maxSubagentSpawnsPerRun: 32
+    maxParallelSubCalls: 10
+
+# The model-facing half of Code Mode: the transport is presented as `ipython`,
+# with prime-agent's description verbatim and its result layout. `run_code` stays
+# the reserved internal name — a profile renames the transport, it does not
+# replace it (P3-09).
+- id: rlm-presentation
+  name: rlm-presentation
+
+# --- the runtime ------------------------------------------------------------
+# pH's own CPython subprocess, fd 3 as the framed channel, one child per agent.
+# `persistence: namespace` is admissible only because the provider promises to
+# emit `kernel/snapshot` events, and the seam checks that promise when it
+# registers (D6) — cross-call state invisible to the log is exactly why dsh
+# withheld a persistent kernel.
+- id: code-runtime-python
+  name: code-runtime-python
+  config:
+    # `managed` builds $PH_CACHE/runtime-venv: ph-runtime-guest, dill, and the
+    # Python skills. Nothing else, because everything in it is reachable by
+    # model code.
+    python: managed
+    cpuSeconds: 30
+    addressSpaceBytes: 2147483648
+    maxLogBytes: 65536
+    maxValueBytes: 65536
+    maxSnapshotBytes: 16777216
+
+# --- delegation ------------------------------------------------------------
+# `rlm()` as a `ctx.subagents` provider: admission is logged and the handle
+# returns before the child answers, so a parent can fan out and keep working
+# (P3-11). The roster the parent reads back is the fold over these events, not a
+# side table, so it survives restart and compaction by construction.
+# E4 note: a child gets `read` unless it asks for `write`, and that default is
+# the seam's (`SubagentRequest.access`) rather than a row knob — until
+# `ctx.workspace` lands (Phase 4, D21) a `write` request is recorded and
+# downgraded with a reason code, because a guarantee nothing enforces must not
+# be granted, and a row knob that could not change that would be a lie.
+# What this host can carry, across every root — the other half of the per-parent
+# figure below, and here rather than in `ph-core` because this is the bundle that
+# produces `subagent` jobs at all. `phern daemon --max-concurrent-children` overrides
+# it. Eight rather than four so two parents fanning out fully is the ordinary
+# case and not a queue; a starting point, not a measurement.
+- id: jobs
+  config:
+    concurrency:
+      subagent: 8
+
+- id: rlm-subagent-provider
+  name: rlm-subagent-provider
+  config:
+    maxDepth: 2
+    # How many of one parent's children run at once; the rest queue in
+    # admission order rather than being refused. A deployment number, not a
+    # row default: the row says `null` (no cap) so a profile that never chose is
+    # not silently serialised. Four is a starting point, not a measurement.
+    maxConcurrent: 4
+
+# The model-facing half: `rlm.run(...)` inside a cell is a governed dispatch,
+# not a comm-channel RPC — so a policy row can deny or ask on spawning, and C4's
+# spawn budget counts it (P3-10).
+- id: rlm-bindings
+  name: rlm-bindings
+
+# Agent-to-agent messages (P3-12). The nuclear-family boundary is a *guard* —
+# deny-only, last, and not re-permittable by any later listener (C7) — while the
+# rate limit is backpressure the tool body raises, because ending a whole cell
+# over four messages in a second is not what a rate limit means.
+- id: rlm-messaging
+  name: rlm-messaging
+  config:
+    maxMessageChars: 16384
+    maxPending: 20
+    rateCapacity: 3
+    rateRefillSeconds: 1.0
+
+# The doctrine (P3-14). Sections after `tools:sdk`, because they refer to the
+# surface it has just described — and the volatile facts (depth, cwd, family,
+# workspace tier) are a `context()` snapshot rather than a cached section, or
+# every turn that changed one would re-bill the whole prefix (A12).
+- id: rlm-prompt
+  name: rlm-prompt
+
+# The Continual Harness (P3-16, D14): state is a fold over `harness/refined`
+# rather than a file, so a fork inherits the harness as of its boundary and a
+# rollback is derivable from the event that made the change. `/refine` is a
+# command, not a tool — it is something the human asks for.
+- id: rlm-harness
+  name: rlm-harness
+
+# I6's live example (P6-01). `harness_state.json` is written for humans and
+# nothing reads it back, which is exactly the arrangement that lets a projection
+# drift unnoticed — so the invariant is checked rather than assumed.
+- id: rlm-harness-invariant
+  name: rlm-harness-invariant
+
+# Capability-layer skills (P3-18): `SKILL.md` for the catalog, an installable
+# package for the kernel. The knowledge layer (`/refine`) may point at these and
+# may not create them — I7, and the reason the two share a word, not a mechanism.
+# No `paths` means no skills, so the row costs nothing until a deployment
+# configures one.
+- id: rlm-skills-python
+  name: rlm-skills-python
+
+# `subagent-task` stands down here. Both delegation shapes are real — one call
+# and one answer, or a handle collected later — but this bundle *is* the second
+# one: `rlm_run` admits a child that replies by agent message, with a roster and
+# an inbox built around that. Offering a blocking twin beside it would put two
+# ways to do one thing in the same prompt, and the model would have to guess
+# which of them the rest of the tools were designed for.
+- id: subagent-task
+  disabled: true
+
+# "Prompt-as-a-variable" (P3-17, Q4): a corpus the model queries through
+# `await tools.context_search(...)` — bindings, so each query is its own governed
+# dispatch and one oversized result can be offloaded without its siblings.
+# Disabled here and opt-in in `rlm-stable`: C3 gave the model governed
+# `read`/`grep`/`glob`, which demoted this from a headline feature to a
+# specialist one for non-file corpora. A row with no `sources` stands down anyway.
+- id: rlm-context-loader
+  name: rlm-context-loader
+  disabled: true
+
+# The row that makes `persistence: namespace` true rather than declared (D17).
+# Mounted with the runtime, not optionally: the seam takes the provider's promise
+# at registration, and these events are the promise being kept.
+- id: rlm-kernel-snapshot
+  name: rlm-kernel-snapshot
+  config:
+    inlineBlobMax: 65536
+
+# The containment ladder for an RLM session (P4-11, §4.8). The *root* agent
+# stays `advisory`: a person running `rlm` is working in the directory they
+# opened, and moving their agent to a checkout elsewhere is a surprise a
+# deployment should have to ask for. Children go to `worktree`, because eight of
+# them writing one tree concurrently is the fan-out hazard the tier exists for —
+# and the parent then reviews a diff instead of trusting sibling writes (E2).
+- id: containment
+  config:
+    tier: advisory
+    child_tier: worktree
+
+# The rungs themselves. Layered here rather than in `ph-base` because they cost
+# a checkout per agent, and inert until `containment` above asks for them.
+- id: workspace-git-worktree
+  name: workspace-git-worktree
+
+- id: workspace-checkpoint
+  name: workspace-checkpoint
+
+- id: workspace-commands
+  name: workspace-commands
+
+- id: workspace-revert
+  name: workspace-revert