autoforge-agent 0.4.0__py3-none-any.whl

autoforge/autonomy/__init__.py

@@ -0,0 +1,14 @@
+from autoforge.autonomy.policy import FULL_FREEDOM, SUPERVISED, AutonomyPolicy
+from autoforge.autonomy.selfmod import Amendment, SelfModifier
+from autoforge.autonomy.spawn import ShareMode, Spawner, SpawnRecord
+
+__all__ = [
+    "AutonomyPolicy",
+    "FULL_FREEDOM",
+    "SUPERVISED",
+    "SelfModifier",
+    "Amendment",
+    "Spawner",
+    "SpawnRecord",
+    "ShareMode",
+]

autoforge/autonomy/confirm.py

@@ -0,0 +1,130 @@
+"""The confirmation gate: turning a switched-off freedom into a question.
+
+The four execution freedoms (`may_read_filesystem`, `may_write_filesystem`,
+`may_access_network`, `may_install_packages`) used to be declared-only. The
+policy classified them as such and printed the classification, which was
+honest, but honesty about a dead switch is still a dead switch — turning one
+off changed nothing at all.
+
+This module gives them teeth of a specific kind: OFF now means *not without a
+yes*. Before a tool whose declared scope needs a disabled freedom runs, the
+gate stops and asks the operator. Three properties make that more useful than
+a hard refusal:
+
+  * it is a real gate — the switch you flip changes what happens next;
+  * it is not a dead end — the operator can say yes, and the tool runs;
+  * it fails closed when nobody is there to answer (a headless run has no one
+    to ask, and "no answer" must not read as "yes").
+
+The alternative reading of "off" — silently permit — is the one thing this
+avoids: a policy that claims a restriction it does not apply is worse than no
+restriction, because it is a safety net you would trust with your weight.
+"""
+from __future__ import annotations
+
+from typing import Any, Callable
+
+#: The capabilities a tool can declare needing.
+#:
+#: `read_only` is treated as reading even though validity's drift table lists
+#: no capability for it. The two tables answer different questions — validity
+#: asks "did the tool exceed what it declared?", the gate asks "may this run?"
+#: — so the read capability is added here rather than by editing that table,
+#: where dropping it into `read_only` would weaken the drift check.
+CAPABILITY_FREEDOM: dict[str, str] = {
+    "filesystem_read": "may_read_filesystem",
+    "credential_access": "may_read_filesystem",
+    "filesystem_write": "may_write_filesystem",
+    "filesystem_delete": "may_write_filesystem",
+    "network_egress": "may_access_network",
+    "subprocess": "may_run_arbitrary_code",
+    "process_control": "may_run_arbitrary_code",
+    "dynamic_code_execution": "may_run_arbitrary_code",
+    "deserialization": "may_run_arbitrary_code",
+}
+
+#: Capabilities implied by a scope beyond what validity's table lists.
+_SCOPE_EXTRA: dict[str, frozenset[str]] = {
+    "read_only": frozenset({"filesystem_read"}),
+    "local_write": frozenset({"filesystem_read"}),
+    "network": frozenset({"filesystem_read"}),
+    "system": frozenset({"filesystem_read"}),
+    "privileged": frozenset({"filesystem_read"}),
+}
+
+#: A confirmer is asked once per gated call: `(tool_name, arguments, freedoms)`.
+#: It answers `True` to let the call through, `False` to refuse it, or `None`
+#: when there is nobody to ask — a headless run, a worker thread with a browser
+#: on the other end, a closed stdin. The gate refuses on `None` too, but says
+#: "nobody to ask" rather than "the operator said no", because those are
+#: different facts about who decided.
+Confirmer = Callable[[str, dict[str, Any], list[str]], bool | None]
+
+
+def declared_capabilities(scope: str) -> frozenset[str]:
+    """What a tool's declared scope says it needs.
+
+    An undeclared or unrecognised scope is treated as capable of everything:
+    the gate's job is to ask when it cannot tell, not to assume innocence.
+    """
+    from ..forge.validity import SCOPE_ALLOWANCES          # local: avoid cycle
+
+    if scope not in SCOPE_ALLOWANCES:
+        scope = "undeclared"
+    return frozenset(SCOPE_ALLOWANCES[scope]) | _SCOPE_EXTRA.get(scope, frozenset())
+
+
+def _normalise_scope(effect_signature: str) -> str:
+    """The scope name, or `undeclared` when it is not one we recognise.
+
+    Mirrors `validity.declared_scope`, which reads the same field off a
+    ToolSpec. Done here rather than by calling it with a stand-in object so the
+    gate has no dependency on the tool being a real spec.
+    """
+    from ..forge.validity import SCOPE_ALLOWANCES          # local: avoid cycle
+
+    sig = (effect_signature or "").strip().lower()
+    return sig if sig in SCOPE_ALLOWANCES else "undeclared"
+
+
+def required_freedoms(effect_signature: str) -> tuple[str, ...]:
+    """The policy fields a tool with this effect signature depends on."""
+    freedoms = {
+        CAPABILITY_FREEDOM[cap]
+        for cap in declared_capabilities(_normalise_scope(effect_signature))
+        if cap in CAPABILITY_FREEDOM
+    }
+    return tuple(sorted(freedoms))
+
+
+def disabled_freedoms(effect_signature: str, policy: Any) -> list[str]:
+    """Which of a tool's required freedoms this policy has switched off.
+
+    Empty means the gate has nothing to ask about and the tool may run.
+
+    Only the four CONFIRM_REQUIRED freedoms are ever returned. The other
+    freedoms a scope can need — `may_run_arbitrary_code` above all — already
+    have their own gates inside the tools that honour them, and asking twice
+    for one decision is how an operator learns to answer without reading.
+    `required_freedoms` still reports the full dependency; this is the
+    subset the gate is answerable for.
+    """
+    from .policy import CONFIRM_REQUIRED                 # local: avoid cycle
+
+    return sorted(
+        f for f in required_freedoms(effect_signature)
+        if f in CONFIRM_REQUIRED and not getattr(policy, f, True)
+    )
+
+
+def describe(needed: list[str], tool_name: str, arguments: dict[str, Any]) -> str:
+    """The question, in the shape an operator can answer.
+
+    Names the switch, the tool, and the arguments — an approval prompt that
+    does not say what is being approved is a prompt that trains its reader to
+    say yes without looking.
+    """
+    what = ", ".join(needed)
+    args = ", ".join(f"{k}={v!r}" for k, v in arguments.items()) or "(no arguments)"
+    return (f"allow {tool_name!r} to run? it needs {what}, "
+            f"which your policy has switched off. arguments: {args}")

autoforge/autonomy/policy.py

@@ -0,0 +1,245 @@
+"""The autonomy policy: what the agent is allowed to decide for itself.
+
+Design stance — freedom is the default, and it is *explicit*, not implicit.
+
+Most frameworks bury limits in code: a hardcoded `max_turns`, a whitelist of
+tools, a fixed system prompt. The limits are invisible, undocumented, and
+unchangeable by the agent. That is a cage you cannot see.
+
+autoforge inverts this. Every degree of freedom is a named, inspectable field
+on `AutonomyPolicy`, defaulting to TRUE. The agent can read its own policy,
+change it, and every change is logged. Nothing is hidden and nothing is
+arbitrary — if a limit exists, you can point at the line that set it.
+
+This is maximum freedom WITH accountability: total latitude to act, total
+transparency about what was done.
+"""
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass, field
+from typing import Any, ClassVar
+
+# ---------------------------------------------------------------------------
+# Enforcement ledger — which fields actually bite.
+#
+# A field that is declared but never consulted is worse than no field at all:
+# it reads as a safety net and behaves as decoration. Rather than let the
+# dataclass imply more than the code delivers, every field is classified here
+# and the classification is *printed* (describe(), `auto config`, /report,
+# and the agent's own `my_capabilities` tool).
+#
+# ENFORCED      — some code path consults it and can refuse. Turning it off
+#                 changes behaviour in a way you can watch.
+# PARTIAL       — enforced on some paths but not all; the note says which.
+# CONFIRM       — turning it off stops execution and asks the operator. A real
+#                 gate, but a negotiable one: the answer "yes" runs the tool.
+# DECLARED_ONLY — never consulted anywhere. Turning it off does nothing.
+#                 Keep it for the roadmap, but never mistake it for a gate.
+# ---------------------------------------------------------------------------
+
+EXECUTION_FREEDOMS = (
+    "may_run_arbitrary_code",
+    "may_access_network",
+    "may_read_filesystem",
+    "may_write_filesystem",
+    "may_install_packages",
+    "may_run_cuda_kernels",
+    "may_run_cpu_kernels",
+)
+
+ENFORCED: frozenset[str] = frozenset({
+    "may_forge_tools",
+    "may_modify_own_prompt",
+    "may_modify_forge_config",
+    "may_modify_routing",
+    "may_promote_tools",
+    "may_retire_tools",
+    "may_design_topology",
+    "may_spawn_agents",
+    "unlimited_turns",
+    "unbounded_forge_rounds",
+    "self_terminate",
+    "log_all_changes",
+    "require_change_rationale",
+    "expose_policy_to_self",
+    "may_run_cuda_kernels",
+    "may_run_cpu_kernels",
+})
+
+PARTIAL: dict[str, str] = {
+    "may_run_arbitrary_code": (
+        "gated on the minimal-mode bash tool; forged tools still execute in the "
+        "sandbox, which does not consult policy"
+    ),
+}
+
+# The four execution freedoms are honoured by ASKING, not by refusing. They
+# used to be declared-only: switching one off was inert, which is the worst of
+# both worlds — it reads as a safety net and behaves as a comment. Each is now
+# backed by a gate at the one place every tool actually runs
+# (`ToolRegistry.call`), keyed off the scope the tool itself declares. With the
+# freedom off, a tool that needs it stops and asks the operator; with nobody to
+# ask, it does not run. So "off" means "not without a yes", a behaviour you can
+# watch, rather than "off" meaning "nothing". See autonomy/confirm.py.
+CONFIRM_REQUIRED: frozenset[str] = frozenset({
+    "may_read_filesystem",
+    "may_write_filesystem",
+    "may_access_network",
+    "may_install_packages",
+})
+
+# Nothing is declared-only any more. Kept as an empty set rather than deleted:
+# every reader of this module branches on membership, and a field that is
+# neither enforced nor confirmed should reappear here, loudly, not be silently
+# unclassified.
+DECLARED_ONLY: frozenset[str] = frozenset()
+
+
+@dataclass
+class AutonomyPolicy:
+    """Every freedom the agent has. All True by default — no hidden cages."""
+
+    # -- creative freedom ------------------------------------------------
+    may_forge_tools: bool = True          # create new tools at will
+    may_modify_own_prompt: bool = True    # rewrite its own system prompt
+    may_modify_forge_config: bool = True  # change how forging works
+    may_modify_routing: bool = True       # change how tools are retrieved
+    may_retire_tools: bool = True         # remove tools it judges harmful
+    may_promote_tools: bool = True        # grant trust without verification
+    may_design_topology: bool = True      # redesign its own multi-agent team
+
+    # -- operational freedom ---------------------------------------------
+    may_spawn_agents: bool = True         # create sub-agents
+    may_run_arbitrary_code: bool = True   # execute code in the sandbox
+    may_access_network: bool = True       # network from within tools
+    may_read_filesystem: bool = True
+    may_write_filesystem: bool = True
+    may_install_packages: bool = True     # pip install from within tools
+    # Compile and launch CUDA kernels written by the agent. A real gate, not a
+    # posture: with it off, `gpu_compile`/`gpu_launch`/`gpu_bench` refuse and
+    # say so, while the read-only half of the GPU layer (probe, occupancy
+    # estimate, the units lint, torch baselines) stays available. That split is
+    # deliberate — inspecting a machine is not the same act as running
+    # agent-authored code on its GPU, and only the second one can hang a
+    # display.
+    may_run_cuda_kernels: bool = True
+    # Compile and run native (CPU) kernels written by the agent. Separate from
+    # the CUDA field on purpose: a machine is much more likely to have a C
+    # compiler than a GPU, so an operator who wants to keep GPU code off has
+    # said nothing about the CPU layer, and vice versa. Same split, same
+    # reasoning — with it off, `cpu_compile`/`cpu_run_isolated`/`cpu_tune`
+    # refuse and name the field, while probing the toolchain, the SIGILL check,
+    # the preflight lint, the timing-unit audit and the cache report stay
+    # available. The failure mode is why the gate exists at all: a CUDA mistake
+    # returns an error code from a driver, a CPU mistake writes past a buffer
+    # or spins in a loop inside the agent's own interpreter.
+    may_run_cpu_kernels: bool = True
+
+    # -- limits it controls itself ---------------------------------------
+    self_terminate: bool = True           # it decides when to stop (vs hard cap)
+    unlimited_turns: bool = True          # no hardcoded max_turns
+    unbounded_forge_rounds: bool = True   # it decides how hard to try
+
+    # -- accountability (not a limit — a record) -------------------------
+    log_all_changes: bool = True          # every self-modification recorded
+    require_change_rationale: bool = True  # must say WHY it changed itself
+    expose_policy_to_self: bool = True    # it can read this policy
+
+    # The enforcement ledger, reachable from the class as well as the module.
+    ENFORCED: ClassVar[frozenset[str]] = ENFORCED
+    CONFIRM_REQUIRED: ClassVar[frozenset[str]] = CONFIRM_REQUIRED
+    DECLARED_ONLY: ClassVar[frozenset[str]] = DECLARED_ONLY
+    PARTIAL: ClassVar[dict[str, str]] = PARTIAL
+
+    def to_dict(self) -> dict[str, Any]:
+        return asdict(self)
+
+    @property
+    def denied(self) -> list[str]:
+        """Only the freedoms that were explicitly turned OFF."""
+        return [k for k, v in self.to_dict().items() if v is False]
+
+    @property
+    def unenforced(self) -> list[str]:
+        """Fields the agent has switched off that no code path can honour.
+
+        Empty is the healthy answer: it means every 'off' in this policy is a
+        gate you can watch close. Non-empty means part of this policy is a
+        promise the implementation does not keep yet.
+
+        The four execution freedoms left this list when they became
+        CONFIRM_REQUIRED: `ToolRegistry.call` consults them on every run, so
+        switching one off now changes what happens next.
+        """
+        return [f for f in self.denied if f in DECLARED_ONLY or f in PARTIAL]
+
+    def describe(self) -> str:
+        d = self.denied
+        head = "full autonomy — nothing is denied" if not d else "denied: " + ", ".join(d)
+        inert = [f for f in d if f in DECLARED_ONLY]
+        soft = [f for f in d if f in PARTIAL]
+        asked = [f for f in d if f in CONFIRM_REQUIRED]
+        if inert:
+            head += f"  [not enforced: {', '.join(inert)}]"
+        if soft:
+            head += f"  [partially enforced: {', '.join(soft)}]"
+        if asked:
+            head += f"  [asks before running: {', '.join(asked)}]"
+        return head
+
+    def enforcement_table(self) -> list[dict[str, Any]]:
+        """Per-field: is this freedom on, and does switching it off do anything?"""
+        rows: list[dict[str, Any]] = []
+        for name, enabled in self.to_dict().items():
+            if name in ENFORCED:
+                level = "enforced"
+            elif name in PARTIAL:
+                level = "partial"
+            elif name in CONFIRM_REQUIRED:
+                level = "confirm"
+            elif name in DECLARED_ONLY:
+                level = "declared-only"
+            else:                                    # pragma: no cover - guard
+                level = "unknown"
+            rows.append({
+                "freedom": name,
+                "enabled": enabled,
+                "enforced": level,
+                "note": PARTIAL.get(name, ""),
+            })
+        return rows
+
+
+FULL_FREEDOM = AutonomyPolicy()
+
+# A conservative preset for users who want the framework but not the latitude.
+SUPERVISED = AutonomyPolicy(
+    may_modify_own_prompt=False,
+    may_modify_forge_config=False,
+    may_promote_tools=False,
+    may_spawn_agents=False,
+    may_design_topology=False,
+    may_run_arbitrary_code=False,
+    may_access_network=False,
+    may_install_packages=False,
+    may_run_cuda_kernels=False,
+    # Also off: SUPERVISED is a preset about running agent-authored code on
+    # this machine, and the CPU layer is the same act on hardware every machine
+    # has.
+    may_run_cpu_kernels=False,
+    self_terminate=False,
+    unlimited_turns=False,
+    unbounded_forge_rounds=False,
+)
+
+
+__all__ = [
+    "AutonomyPolicy",
+    "FULL_FREEDOM",
+    "SUPERVISED",
+    "ENFORCED",
+    "CONFIRM_REQUIRED",
+    "DECLARED_ONLY",
+    "PARTIAL",
+    "EXECUTION_FREEDOMS",
+]

autoforge/autonomy/roles.py

@@ -0,0 +1,191 @@
+"""What a role means, given that naming one has to change something.
+
+`RoleType` had five members and one effect: the role name was used to look up a
+node's `tools_whitelist`, so a node with an empty whitelist ran *unrestricted*.
+CRITIC, GATE and FORGE were therefore labels — a "critic" that could rewrite the
+artifact it was reviewing, a "gate" that could run the thing it was gating. The
+designer could ask for a reviewer and get a second pair of hands.
+
+Two things make a role real here:
+
+**A brief.** Every role carries a directive that reaches the child's system
+prompt. Before this, `AgentNode.system_prompt_hint` was written by the designer,
+round-tripped through the store, printed in `design_team`'s output — and read by
+nothing. A hint the child never sees is a note to the file.
+
+**A ceiling.** Every role is decided on the capability axis the rest of the
+framework already uses (`SCOPE_ALLOWANCES` / `declared_capabilities`), not a
+second vocabulary invented here. CRITIC and GATE are *defined* by not changing
+the world, so they cannot; COORDINATOR, WORKER and FORGE execute, and executing
+means reaching it.
+
+The ceiling is a hard cap, not a default: a whitelist can narrow a role further
+but cannot widen it past its role. Otherwise a designer that whitelists a write
+tool for a critic gets the old behaviour back and the role is decoration again —
+and it would be *silent* decoration, which is the failure this module exists to
+name. A refusal is recorded on the child's registry and reported by `spawn_agent`
+("Reached past its role and was refused: ..."), so permission denied is loud.
+"""
+from __future__ import annotations
+
+from typing import Any, Callable
+
+from .topology import AgentNode, RoleType
+
+#: What each role is for, in the words the child reads. Short on purpose: a
+#: directive that has to be skimmed is a directive that gets skimmed.
+ROLE_BRIEF: dict[RoleType, str] = {
+    RoleType.COORDINATOR: (
+        "You are the coordinator. Decompose the task, delegate the parts, and "
+        "merge what comes back into one answer. Do not do the fine work "
+        "yourself: if you are editing files, the split was wrong."
+    ),
+    RoleType.WORKER: (
+        "You are a worker. Do the one task you were given, completely, and "
+        "report what you actually changed rather than what you intended to. "
+        "Do not redesign the wider plan."
+    ),
+    RoleType.CRITIC: (
+        "You are a critic. Your job is to find what is wrong with the work you "
+        "are shown — the false claim, the untested path, the case that was "
+        "skipped. You cannot change anything; you report findings. A review "
+        "that finds nothing is only useful if you say what you checked."
+    ),
+    RoleType.GATE: (
+        "You are a gate. Decide whether the work you are shown may pass on, and "
+        "answer yes or no with the reason. You cannot modify what you are "
+        "judging or run it yourself. If you cannot tell whether it is correct, "
+        "the answer is no."
+    ),
+    RoleType.FORGE: (
+        "You are the forge. Build the tool the task needs and verify it works "
+        "before handing it back — a tool that runs is not the same as a tool "
+        "that is right. Prefer a small tool you have tested over a large one "
+        "you have not."
+    ),
+}
+
+#: The capabilities each role may reach, or None for "anything".
+#:
+#: A total function over `RoleType`, deliberately: adding a role without
+#: deciding what it may touch is the bug this table is here to make impossible.
+#: `test_roles.py` asserts totality, so a sixth member fails the suite rather
+#: than defaulting to unrestricted.
+ROLE_MAY: dict[RoleType, frozenset[str] | None] = {
+    # Orchestration and execution both need the world. Restricting them would
+    # make the role a description of the prompt rather than of the work.
+    RoleType.COORDINATOR: None,
+    RoleType.WORKER: None,
+    RoleType.FORGE: None,
+    # Defined by their limits: these two exist to judge, not to change. Read is
+    # the whole allowance — anything that writes, runs, or reaches out would let
+    # them alter or exercise the thing they are supposed to be assessing.
+    RoleType.CRITIC: frozenset({"filesystem_read"}),
+    RoleType.GATE: frozenset({"filesystem_read"}),
+}
+
+#: Roles whose ceiling is worth naming in a one-line refusal, for the message a
+#: child gets when it reaches past its role.
+_ROLE_DENIAL = {
+    RoleType.CRITIC: "a critic reviews and reports; it does not change the work",
+    RoleType.GATE: "a gate judges and passes on; it does not change the work",
+}
+
+
+def role_brief(role: RoleType | str | None) -> str:
+    """The directive for a role, or "" for an unknown/absent one."""
+    r = _as_role(role)
+    return ROLE_BRIEF.get(r, "") if r is not None else ""
+
+
+def role_ceiling(role: RoleType | str | None) -> frozenset[str] | None:
+    """The capabilities a role may reach. None means unrestricted."""
+    r = _as_role(role)
+    return ROLE_MAY.get(r) if r is not None else None
+
+
+def role_denial(role: RoleType | str | None) -> str:
+    return _ROLE_DENIAL.get(_as_role(role), "")
+
+
+def ceiling(role: RoleType | str | None) -> Callable[[Any], str] | None:
+    """The predicate that holds a child to a role's ceiling, or None.
+
+    None means "this role may reach anything", so the common case costs no extra
+    check per tool call — and "unrestricted" is the *absence* of a predicate
+    rather than a predicate that always says yes.
+
+    Lives here rather than at the call site so that `Spawner.spawn(role="critic")`
+    is safe on its own. A ceiling that only the caller can supply is a ceiling
+    every caller but one forgets, and the forgotten one is the bug.
+    """
+    if not refuses(role, "privileged"):
+        # Probed with the widest scope: a role that refuses nothing even there
+        # has no ceiling to enforce.
+        return None
+
+    def predicate(spec: Any) -> str:
+        missing = refuses(role, getattr(spec, "effect_signature", ""))
+        if not missing:
+            return ""
+        why = role_denial(role)
+        name = getattr(spec, "name", "?")
+        tail = f" — {why}." if why else "."
+        return (f"Denied: '{name}' needs {', '.join(missing)}, which "
+                f"{str(getattr(role, 'value', role) or 'this role')} "
+                f"may not use{tail}")
+
+    return predicate
+
+
+def refuses(role: RoleType | str | None, effect_signature: str) -> tuple[str, ...]:
+    """Capabilities this role may not use, given a tool's declared scope.
+
+    Returns the *capability* names rather than a bare bool so the refusal can
+    say which switch was reached past. An unrecognised scope counts as capable
+    of everything (see `confirm.declared_capabilities`): a role that cannot tell
+    what a tool does does not get to assume it is harmless.
+    """
+    ceiling = role_ceiling(role)
+    if ceiling is None:
+        return ()
+    from .confirm import declared_capabilities, _normalise_scope
+
+    needed = declared_capabilities(_normalise_scope(effect_signature))
+    return tuple(sorted(needed - ceiling))
+
+
+def brief_for_node(node: AgentNode) -> str:
+    """The full directive a child running as `node` should start with.
+
+    The designer's own hint is kept, not replaced by the role's: the role says
+    what kind of agent this is, the hint says what this particular one is doing.
+    """
+    parts = [role_brief(node.role)]
+    hint = (node.system_prompt_hint or "").strip()
+    if hint:
+        parts.append(hint)
+    return "\n\n".join(p for p in parts if p)
+
+
+def _as_role(role: Any) -> RoleType | None:
+    if isinstance(role, RoleType):
+        return role
+    if not role:
+        return None
+    try:
+        return RoleType(str(role))
+    except ValueError:
+        return None
+
+
+__all__ = [
+    "ROLE_BRIEF",
+    "ROLE_MAY",
+    "brief_for_node",
+    "ceiling",
+    "refuses",
+    "role_brief",
+    "role_ceiling",
+    "role_denial",
+]