foundry-implementation-actor 0.1.0__py3-none-any.whl

foundry_implementation_actor/grounding.py

@@ -0,0 +1,197 @@
+"""Grounding — putting the capability's own context in front of the session before turn one.
+
+THE MECHANISM, AND WHY IT IS THIS ONE. `CLAUDE.md` at the working directory's root is loaded by
+the `claude` CLI **before the first turn**, and its `@relative/path.md` imports are resolved
+eagerly at the same moment. Verified live in this actor's exact invocation shape (`--print
+--output-format stream-json --permission-mode acceptEdits`): a question only the fetched context
+could answer came back in `num_turns: 1` with zero tool calls. Nothing was read, because nothing
+needed to be — it was already in the window.
+
+WHAT THIS REPLACES. The previous arrangement fetched the same envelopes into a tempdir **beside**
+the clone and asked the session, in prose, to "read it before you start". That is not broken —
+reads outside the cwd work and no permission denial was ever recorded — but it is *advisory*.
+Whether the context entered the window at all was the model's choice, re-made every session, and
+a session that skipped it looked exactly like one that had read it. Writing the envelopes inside
+the clone and naming them from a generated `CLAUDE.md` turns grounding from a request into a
+precondition.
+
+WHY INSIDE THE CLONE, SPECIFICALLY. A `@`-import resolves relative to the file that contains it.
+An envelope in a sibling tempdir can be *described* to a session but never imported by one, so
+the sibling-tempdir arrangement could not have been fixed by writing a better prompt.
+
+TWO TIERS, AND WHY THE CHOICE IS A MEASUREMENT. `load: eager` costs its full token weight on
+every session, unconditionally, whether or not the task touches what it describes. `load:
+on-demand` costs one line — its `answers:` and its path — and the session pays the rest only if
+it opens the file. Neither is the right default in general; the right one for a given source is
+whatever its measured envelope size says. One such read was already recorded as putting "40 kB of
+JSON on screen", so this is not a hypothetical budget.
+
+CONTAINMENT IS UNAFFECTED. The handler stages only `components[].path`, so everything written
+here — the `.foundry/` envelopes and the generated `CLAUDE.md` alike — is never staged, never
+committed, and dies with the clone. No `.gitignore` entry is needed, and adding one would be a
+second place to state a boundary that is already stated once.
+"""
+from __future__ import annotations
+
+import json
+import subprocess
+from pathlib import Path
+
+from papeete_actor_synchronous_messaging.engine import EngineError
+
+from .config import CapabilityConfig, Grounding
+
+CLAUDE_MD = "CLAUDE.md"
+
+DEFAULT_FETCH_TIMEOUT_S = 120
+
+# The marker that lets a generated block be told apart from prose a repo wrote for itself. It is
+# not parsed — nothing here ever edits a previous block, because every clone is fresh — but a
+# human reading a session's clone should be able to see instantly which half is machine-written.
+_BEGIN = "<!-- foundry-implementation-actor: generated grounding -->"
+
+
+def ground(config: CapabilityConfig, clone_dir: Path, *,
+           timeout: int = DEFAULT_FETCH_TIMEOUT_S) -> list[Grounding]:
+    """Fetch every `ground_in` source, write it into the clone, and render `CLAUDE.md`.
+
+    Returns the entries that were grounded, in declaration order. Raises `EngineError` if any
+    fetch fails — a session grounded in half its context is worse than one that never started,
+    because only the second is visible.
+    """
+    for entry in config.ground_in:
+        envelope = fetch(config, entry, timeout=timeout)
+        write_envelope(config, entry, clone_dir, envelope)
+    render_claude_md(config, clone_dir)
+    return list(config.ground_in)
+
+
+def fetch(config: CapabilityConfig, entry: Grounding, *,
+          timeout: int = DEFAULT_FETCH_TIMEOUT_S) -> str:
+    """Run one entry's `fetch:` argv and return its stdout.
+
+    This package knows no knowledge tool by name. It knows "run this, ground the session in what
+    comes back" — which is why a fourth source is a YAML entry rather than a change here.
+    """
+    argv = config.expand(entry.fetch)
+    try:
+        result = subprocess.run(argv, capture_output=True, text=True, timeout=timeout)
+    except FileNotFoundError as e:
+        raise EngineError(
+            f"grounding '{entry.name}': '{argv[0]}' is not on PATH. The sidecar names the tools "
+            f"this capability grounds itself in; installing them is the consuming image's job, "
+            f"not this package's."
+        ) from e
+    except subprocess.TimeoutExpired as e:
+        raise EngineError(
+            f"grounding '{entry.name}': {' '.join(argv)} timed out after {timeout}s"
+        ) from e
+    if result.returncode != 0:
+        raise EngineError(
+            f"grounding '{entry.name}': {' '.join(argv)} failed: {result.stderr.strip()}"
+        )
+    return result.stdout
+
+
+def write_envelope(config: CapabilityConfig, entry: Grounding, clone_dir: Path,
+                   envelope: str) -> Path:
+    """Write one fetched envelope into the clone, as Markdown wrapping the raw payload.
+
+    Markdown rather than the bare `.json` the previous arrangement wrote, for one reason: a
+    `CLAUDE.md` `@`-import pulls in a file whole, so the file has to carry its own title and its
+    own "what this answers" line, or the session receives a wall of JSON with no idea which
+    question it settles. The payload itself is untouched inside the fence.
+    """
+    destination = clone_dir / entry.into
+    destination.parent.mkdir(parents=True, exist_ok=True)
+    destination.write_text(
+        f"# {entry.name}\n\n"
+        f"{entry.answers}\n\n"
+        f"Fetched fresh for this session by `{' '.join(config.expand(entry.fetch))}`. Read it as "
+        f"given — it is this capability's own standing context, not something to re-derive.\n\n"
+        f"```json\n{_pretty(envelope)}\n```\n"
+    )
+    return destination
+
+
+def render_claude_md(config: CapabilityConfig, clone_dir: Path) -> Path:
+    """Write the clone's `CLAUDE.md`, or append to one the repo already commits.
+
+    APPEND, NEVER OVERWRITE. The capability repo has no `CLAUDE.md` of its own today, which is
+    exactly why this is safe to introduce now — there is nothing to clobber, so the clean-slate
+    case is the one being exercised. The day one is committed, it is the repo's own standing
+    guidance for anyone working in it, and silently replacing it with a generated block would
+    remove the very thing a session most needs to obey.
+    """
+    body = _claude_md_body(config)
+    path = clone_dir / CLAUDE_MD
+    if path.exists():
+        existing = path.read_text().rstrip("\n")
+        path.write_text(f"{existing}\n\n---\n\n{body}")
+    else:
+        path.write_text(body)
+    return path
+
+
+def _claude_md_body(config: CapabilityConfig) -> str:
+    eager = [g for g in config.ground_in if g.eager]
+    on_demand = [g for g in config.ground_in if not g.eager]
+
+    lines = [
+        _BEGIN,
+        "",
+        f"# {config.capability} — context for this session",
+        "",
+        "You are working inside a private clone made for one task. The context below was fetched "
+        "fresh for this session from this capability's own knowledge registry. It is authoritative: "
+        "read it as given rather than re-deriving what it already answers.",
+        "",
+    ]
+
+    if eager:
+        lines += ["## Standing context", ""]
+        for entry in eager:
+            lines.append(f"{entry.answers}:")
+            lines.append("")
+            lines.append(f"@{entry.into}")
+            lines.append("")
+
+    if on_demand:
+        lines += [
+            "## Available on demand",
+            "",
+            "Not loaded. Open the file if the task needs what it answers.",
+            "",
+        ]
+        for entry in on_demand:
+            lines.append(f"- **{entry.name}** — {entry.answers}. `{entry.into}`")
+        lines.append("")
+
+    lines += [
+        "## Boundaries",
+        "",
+        f"Write ONLY under {_join(config.writes_only_under)}. Nothing else in this clone is yours "
+        f"to change, and a staged path outside those roots is refused rather than committed.",
+        "",
+        "Do not `git add`, `git commit`, or `git push` — that is handled outside this session.",
+        "",
+    ]
+    return "\n".join(lines) + "\n"
+
+
+def _pretty(envelope: str) -> str:
+    """Pretty-print a JSON envelope; pass anything else through untouched.
+
+    The fetch contract is "whatever the tool prints", not "JSON" — a source that emits Markdown or
+    plain text is equally groundable, and reformatting is a convenience for the JSON case, never a
+    requirement placed on the tool.
+    """
+    text = envelope.strip()
+    try:
+        return json.dumps(json.loads(text), indent=2, ensure_ascii=False)
+    except (json.JSONDecodeError, ValueError):
+        return text
+
+
+def _join(items) -> str:
+    return ", ".join(items)

foundry_implementation_actor/handler.py

@@ -0,0 +1,220 @@
+"""`implement_task` — the deterministic, auditable half of an implementation door.
+
+`ClaudeCodeEngine.judge()` embodies the creative decision: what to build, grounded in the caller's
+own payload and in the capability's own standing context. Everything here is mechanical and never
+trusted to the engine's own judgement:
+
+- **Containment.** `git add <component root>` for each declared component — never `-A`, never a
+  bare `.` — then assert every `git diff --cached --name-only` path starts with one of those
+  roots. This check, not the session's own write-boundary instruction, is what actually enforces
+  the write boundary. A staged path outside it is refused rather than committed.
+- **The correlation id.** `TASK-NNN` is threaded through the branch name (from the engine), the
+  commit message, and — via `correlation.py`, bound at the top of this door — every log record
+  this actor emits for the request, alongside the trace id its caller propagated.
+- **Publishing.** For each component the commit actually touched, this actor builds an image in
+  the cluster's shared buildkit and pushes it to the registry, named and versioned by convention
+  (`papeete_version.compute`) — no explicit tag is ever handed to a caller. No Docker daemon is
+  involved anywhere: `buildctl` reaches `BUILDKIT_HOST`, which is why an actor running this can
+  be an ordinary Pod.
+- **Never opens a PR.** This door accepts, pushes, and publishes. Rendering a verdict and opening
+  a pull request belongs to whichever actor orchestrates the pipeline, once its other members
+  have also confirmed.
+
+THE BOUNDARY IS READ, NOT RESTATED. `WRITES_ONLY_UNDER` used to be a module constant here, kept
+in sync by hand with the sidecar's own declaration of the same fact. It is now
+`config.writes_only_under`, derived from `components[].path`. There is one source, and this file
+is not it.
+"""
+from __future__ import annotations
+
+import os
+import shutil
+import subprocess
+from pathlib import Path
+
+from papeete_version.version import compute as compute_version
+from papeete_version.version import normalize_name
+
+from . import correlation
+from .config import CapabilityConfig
+
+
+class HandlerError(RuntimeError):
+    """Raised for anything that stops this door short — including a containment violation.
+
+    `Actor.receive()` turns an uncaught exception from a handler into a `Refusal`
+    (`{self.name}'s own handler for '{offer.id}' failed: {e}`), which the HTTP binding replies as
+    400 — the same path an undeclared door or a schema violation already takes. A containment
+    breach is therefore refused, never silently swallowed or half-committed.
+    """
+
+
+def make_implement_task(config: CapabilityConfig):
+    """Bind one capability's config to the `implement-task` handler.
+
+    A factory rather than a module-level function reading `actor.engines["claude-code"]`: the
+    engine's registered name comes from the sidecar, so looking the config up through a hardcoded
+    engine key would reintroduce exactly the literal this package exists to remove.
+    """
+
+    def implement_task(actor, payload: dict, from_: str, judged: dict | None = None) -> dict:
+        # Bound again here, not only in the engine's own `judge()`: a refusal path reaches this
+        # door with `judged=None`, having never entered the engine at all, and that refusal is
+        # exactly the record you want carrying a task id.
+        correlation.bind(correlation_id=correlation.correlation_id(),
+                         task_id=payload.get("task_id"), door="implement-task", caller=from_)
+
+        if judged is None or not judged.get("implemented"):
+            reason = (judged or {}).get("reason", "not eligible")
+            correlation.event("implement-task-refused", because=reason)
+            return {"accepted": False, "because": reason}
+
+        task_id = payload["task_id"]
+        clone_dir = Path(judged["clone_dir"])
+        branch = judged["branch"]
+        summary = judged.get("summary", "")
+
+        try:
+            with correlation.stage("containment-commit",
+                                   writes_only_under=list(config.writes_only_under)):
+                components = _containment_commit(config, clone_dir, task_id, summary)
+            correlation.event("components-touched", components=components)
+            with correlation.stage("push-branch", branch=branch, repo=config.source_repo):
+                _push(config, clone_dir, branch, _github_token(actor, config))
+            images = []
+            for component in components:
+                with correlation.stage("publish-image", component=component):
+                    images.append(_publish_image(config, clone_dir, component, task_id))
+                    correlation.event("image-published", component=component, image=images[-1])
+            return {"accepted": True, "branch": branch, "images": images}
+        finally:
+            shutil.rmtree(clone_dir, ignore_errors=True)
+
+    return implement_task
+
+
+def _github_token(actor, config: CapabilityConfig) -> str:
+    engine = actor.engines.get(config.engine)
+    token = getattr(engine, "github_token", None) or os.environ.get("GITHUB_TOKEN")
+    if not token:
+        raise HandlerError("no GITHUB_TOKEN available (neither on the engine nor the environment)")
+    return token
+
+
+def _redact(text: str, secret: str) -> str:
+    return text.replace(secret, "***")
+
+
+def _run(clone_dir: Path, args: list[str], *, redact: str | None = None) -> str:
+    try:
+        result = subprocess.run(args, cwd=clone_dir, check=True, capture_output=True, text=True)
+    except subprocess.CalledProcessError as e:
+        stderr = _redact(e.stderr, redact) if redact else e.stderr
+        raise HandlerError(f"{' '.join(args[:2])} failed: {stderr}") from e
+    return result.stdout
+
+
+def _containment_commit(config: CapabilityConfig, clone_dir: Path,
+                        task_id: str, summary: str) -> list[str]:
+    boundary = config.writes_only_under
+    for path in boundary:
+        # `git add` errors hard (pathspec did not match any files) on a prefix that doesn't exist
+        # on disk AT ALL, not just one with zero changes — verified live against a sibling actor
+        # that hit exactly this for a tests/ root before any task had touched it. The guard is
+        # cheap and keeps two containment checks in different repos genuinely identical.
+        if (clone_dir / path).exists():
+            _run(clone_dir, ["git", "add", path])
+    staged = [line for line in _run(clone_dir, ["git", "diff", "--cached", "--name-only"])
+              .splitlines() if line]
+
+    offending = [p for p in staged if not any(p.startswith(prefix) for prefix in boundary)]
+    if offending:
+        _run(clone_dir, ["git", "reset"])
+        raise HandlerError(
+            f"{task_id}: refusing to commit — staged path(s) outside "
+            f"{', '.join(boundary)}: {offending}"
+        )
+    if not staged:
+        raise HandlerError(
+            f"{task_id}: nothing staged under {', '.join(boundary)} — the session made no change "
+            f"there"
+        )
+
+    message = f"feat({task_id}): implemented by {config.actor_name}\n\nTask: {task_id}"
+    if summary:
+        message += f"\n\n{summary}"
+    _run(clone_dir, [
+        "git", "-c", f"user.name={config.git_author_name}",
+        "-c", f"user.email={config.git_author_email}",
+        "commit", "-m", message,
+    ])
+
+    # Which component a staged path belongs to is resolved by LONGEST declared prefix, not by
+    # taking the path's first segment. The first-segment shortcut is correct only while every
+    # component root is one segment deep, and reports the wrong component — silently — the day
+    # one of them is `src/gateway/`.
+    return config.components_for(staged)
+
+
+def _push(config: CapabilityConfig, clone_dir: Path, branch: str, token: str) -> None:
+    push_url = f"https://x-access-token:{token}@github.com/{config.source_repo}.git"
+    _run(clone_dir, ["git", "push", "--force", push_url, f"HEAD:refs/heads/{branch}"],
+         redact=token)
+
+
+def _image_registry() -> str:
+    registry = os.environ.get("IMAGE_REGISTRY")
+    if not registry:
+        raise HandlerError(
+            "no IMAGE_REGISTRY set — this actor publishes to a registry, and refuses to build an "
+            "image nothing else could ever pull"
+        )
+    return registry.rstrip("/")
+
+
+def _publish_image(config: CapabilityConfig, clone_dir: Path,
+                   component: str, task_id: str) -> str:
+    """Build this component's own image in the cluster's shared buildkit and push it — versioned
+    by convention, never an explicitly-passed tag.
+
+    No Docker daemon and no docker socket: `buildctl` talks to the buildkitd Service named by
+    `BUILDKIT_HOST`, which holds the push credential itself. The build runs where buildkitd runs;
+    only the ref comes back.
+
+    Pushed rather than left local because the pod that runs this image is not this pod — it is a
+    container in an ephemeral namespace the orchestrating actor stands up later, which can only
+    reach the image through a registry.
+
+    THE REF IS A CONTRACT WITH ACTORS THIS PACKAGE NEVER SEES. Its peers recompute the identical
+    string and parse it back apart, so it is `config.image_ref` output or nothing. Never invent a
+    tag scheme here.
+    """
+    declared = config.component_for(f"{component}/")
+    if declared is None:                       # unreachable via `components_for`, cheap to hold
+        raise HandlerError(f"{component}: not a declared component of {config.capability}")
+
+    dockerfile_dir = clone_dir / declared.dockerfile
+    if not dockerfile_dir.is_dir():
+        # Late failure here is expensive: the commit has already landed and the branch is already
+        # pushed. Saying which declared path is missing beats `buildctl`'s own error, which names
+        # a temp path the operator has no way to map back to the sidecar.
+        raise HandlerError(
+            f"{component}: declared dockerfile directory '{declared.dockerfile}' does not exist "
+            f"in the clone — the sidecar and the repo disagree"
+        )
+
+    version = compute_version(
+        folder=clone_dir / declared.path.rstrip("/"),
+        name=config.image_name(component),
+        label="feature",
+        feature_name=normalize_name(task_id),
+    )
+    image = config.image_ref(_image_registry(), component, version)
+    _run(clone_dir, [
+        "buildctl", "build",
+        "--frontend", "dockerfile.v0",
+        "--local", f"context={declared.path.rstrip('/')}",
+        "--local", f"dockerfile={declared.dockerfile}",
+        "--output", f"type=image,name={image},push=true",
+    ])
+    return image

foundry_implementation_actor/schemas/agentic-context.schema.yaml

@@ -0,0 +1,143 @@
+# agentic-context.schema.yaml — the foundry-implementation-actor/agentic-context contract.
+#
+# WHAT THIS FILE IS FOR. One capability's own declaration of what a non-deterministic door should
+# ground itself in, where it may write, and what it publishes. The machinery in this package
+# carries no capability literal of its own — every identifier it needs is DERIVED from `capability`
+# and `source_repo` below (see `config.py`), so a second capability instantiates the same actor by
+# writing this file and nothing else.
+#
+# THE CONTRACT IS COMMITTED SOURCE, NOT A FETCHED GATE. It lives inside the package, the same path
+# in a source checkout and in an installed wheel, so `foundry-implementation-actor lint` needs no
+# network and no credential. Same discipline as papeete-actor's own manifest schema.
+#
+# ─── WHY A SIDECAR AND NOT THE CARD ───────────────────────────────────────────────────────────
+# `papeete_actor_synchronous_messaging.card` opens exactly four hardcoded filenames and never
+# globs, so `Actor.from_card()` will never see this file. That is deliberate: this is the actor's
+# own operational configuration, not part of any published card contract, and it is loaded by this
+# package's `config.py` directly.
+#
+# ─── WHY `writes_only_under` IS NOT DECLARED HERE ─────────────────────────────────────────────
+# It used to be, beside `components:`, and the two drifted — the sidecar declared one list while
+# the file that actually ENFORCES containment carried its own hardcoded copy. There is now exactly
+# one source: `components[].path`. A boundary that can be stated twice will eventually be stated
+# differently.
+
+contract: foundry-implementation-actor/agentic-context/v1
+
+kind: agentic-context
+
+location: actor-agentic-context.yaml    # at the actor's folder root, beside actor.yaml
+
+required:
+  - context
+  - engine
+  - capability
+  - source_repo
+  - registry_repo
+  - components
+  - ground_in
+
+fields:
+
+  context:
+    type: string
+    const: foundry-implementation-actor/agentic-context/v1
+    doc: >-
+      The contract this file claims. A file declaring some other value is read, warned, and not
+      checked further — UNMIGRATED is not the same as non-conformant, and migration is each
+      pair's own act.
+
+  engine:
+    type: string
+    doc: >-
+      The engine name this actor's non-deterministic door names on its card. Registered under
+      exactly this key in `Actor.from_card(engines={...})`.
+
+  capability:
+    type: string
+    doc: >-
+      The capability id, in its canonical dotted form with the `CAP` segment present — e.g.
+      `<ENT>.<DOMAIN>.CAP.<TYPE>.<NNN>.<CODE>`. Every other rendering of the id is derived from
+      this one; none is declared. See `config.py` for the full table.
+
+  source_repo:
+    type: string
+    doc: >-
+      `<owner>/<repo>` of the repository this actor clones, writes to, and pushes a branch to.
+      The actor's own name and its git commit identity are derived from the repo half.
+
+  registry_repo:
+    type: string
+    doc: >-
+      `<owner>/<repo>` of the knowledge registry the `ground_in` fetches resolve through. There is
+      NO default: a fetch that silently reaches a fallback registry is worse than one that fails.
+
+  components:
+    type: array
+    doc: >-
+      The units this actor may write to and publish. Each entry declares its own boundary, its own
+      test suite, and its own Dockerfile context — the three things that were hardcoded, in three
+      different files, before this contract existed.
+    items:
+      required: [name, path, tests, dockerfile]
+      fields:
+        name:
+          type: string
+          doc: The component's own name. Appears in the published image ref.
+        path:
+          type: string
+          doc: >-
+            Its root inside the repo, trailing slash included. The union of these IS the write
+            boundary — nothing else declares it. May be more than one segment deep; the
+            component a staged path belongs to is resolved by longest prefix, not by taking
+            the path's first segment.
+        tests:
+          type: string
+          doc: >-
+            The component's own test suite, named in the session's prompt so the instruction to
+            iterate it green is not a hardcoded literal in an f-string.
+        dockerfile:
+          type: string
+          doc: >-
+            The directory holding this component's Dockerfile, as `buildctl --local dockerfile=`
+            takes it. Must exist in the clone, or publishing this component fails late, after a
+            commit and a push have already landed.
+
+  ground_in:
+    type: array
+    doc: >-
+      What the session is grounded in, before its first turn. Each entry is a command to run and a
+      place to put its output inside the clone — this package hardcodes no knowledge tool. A
+      fourth knowledge source is an entry here, not a change to this package.
+    items:
+      required: [name, answers, fetch, into, load]
+      fields:
+        name:
+          type: string
+          doc: Short identifier for the source. Titles its section in the rendered Markdown.
+        answers:
+          type: string
+          doc: >-
+            One line saying what question this source answers. It is not decoration: for an
+            on-demand entry it is the ONLY thing the session sees, and what it decides to read
+            the file on.
+        fetch:
+          type: array
+          doc: >-
+            argv to run, as a list. `{capability}`, `{registry_repo}` and `{source_repo}` are
+            substituted from the fields above. Non-zero exit, a missing binary, or a timeout all
+            fail the request before any session time is spent.
+        into:
+          type: string
+          doc: >-
+            Repo-relative path to write the envelope to, INSIDE the clone. Inside, because a
+            CLAUDE.md `@`-import resolves relative to the file that contains it — an envelope in
+            a sibling tempdir cannot be imported, only described.
+        load:
+          type: string
+          enum: [eager, on-demand]
+          doc: >-
+            `eager` is `@`-imported by the generated CLAUDE.md and enters the window before turn
+            one, unconditionally, every session. `on-demand` is listed by its `answers` line and
+            its path, and costs nothing until the session opens it. Choose from a measurement of
+            the envelope, not from taste.