agentforge-framework 0.2.1__tar.gz → 0.2.2__tar.gz

{agentforge_framework-0.2.1 → agentforge_framework-0.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentforge-framework
-Version: 0.2.1
+Version: 0.2.2
 Summary: A modular framework for coordinating specialized software agents.
 Author: Yash Mhatre
 License-Expression: Apache-2.0
@@ -145,7 +145,7 @@ without notice. See
 ```console
 $ pip install agentforge-framework
 $ agentforge --version
-agentforge 0.2.1
+agentforge 0.2.2
 ```
 
 That is the whole of it. The two routes below the naming note are for a machine
@@ -169,7 +169,7 @@ from the [latest release](https://github.com/yashmhatre/AgentForge/releases/late
 and install the file:
 
 ```console
-$ pip install agentforge_framework-0.2.1-py3-none-any.whl
+$ pip install agentforge_framework-0.2.2-py3-none-any.whl
 ```
 
 Publishing a release is a wizard rather than a checklist:

{agentforge_framework-0.2.1 → agentforge_framework-0.2.2}/README.md

@@ -127,7 +127,7 @@ without notice. See
 ```console
 $ pip install agentforge-framework
 $ agentforge --version
-agentforge 0.2.1
+agentforge 0.2.2
 ```
 
 That is the whole of it. The two routes below the naming note are for a machine
@@ -151,7 +151,7 @@ from the [latest release](https://github.com/yashmhatre/AgentForge/releases/late
 and install the file:
 
 ```console
-$ pip install agentforge_framework-0.2.1-py3-none-any.whl
+$ pip install agentforge_framework-0.2.2-py3-none-any.whl
 ```
 
 Publishing a release is a wizard rather than a checklist:

{agentforge_framework-0.2.1 → agentforge_framework-0.2.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "agentforge-framework"
-version = "0.2.1"
+version = "0.2.2"
 description = "A modular framework for coordinating specialized software agents."
 readme = "README.md"
 requires-python = ">=3.11"

{agentforge_framework-0.2.1 → agentforge_framework-0.2.2}/src/agentforge_framework/__init__.py

@@ -1,3 +1,3 @@
 """AgentForge — coordination of specialized software agents through reusable workflows."""
 
-__version__ = "0.2.1"
+__version__ = "0.2.2"

{agentforge_framework-0.2.1 → agentforge_framework-0.2.2}/src/agentforge_framework/agents/decomposer.py

@@ -45,6 +45,8 @@ from ..core.contracts import (
     Task,
 )
 from ..core.plan_format import (
+    RESULT_CLOSE,
+    RESULT_OPEN,
     SLICES_CLOSE,
     SLICES_OPEN,
     SPEC_CLOSE,
@@ -105,8 +107,9 @@ not publish the spec, do not open an issue, and do not apply a label.
 
 ## Required output
 
-End your reply with this block and nothing after it. Markdown inside it, not \
-JSON:
+End your reply with these two blocks, in this order, and nothing after them.
+
+First the spec. Markdown inside it, not JSON:
 
 {spec_open}
 ## Problem Statement
@@ -128,10 +131,22 @@ JSON:
 ...
 {spec_close}
 
+Then your own verdict:
+
+{result_open}
+```json
+{{"outcome": "completed", "summary": "one line on what the spec covers"}}
+```
+{result_close}
+
 Cover the whole source. Anything in it that reaches no user story reaches no \
 Issue and does not get built. Scale the spec to what you were given: a \
 one-sentence Task earns a short spec, and padding one out invents scope nobody \
-asked for.\
+asked for.
+
+If the source is too thin to synthesize without inventing most of it, write the \
+verdict block with `"outcome": "escalated"` and a summary naming what you need \
+the human to supply. Omit the spec block in that case.\
 """
 
 SLICES = """\
@@ -186,7 +201,9 @@ publish anything, do not open an issue, and do not apply a label.
 
 ## Required output
 
-End your reply with this block and nothing after it:
+End your reply with these two blocks, in this order, and nothing after them.
+
+First the cut:
 
 {slices_open}
 ```json
@@ -202,7 +219,19 @@ End your reply with this block and nothing after it:
   ]
 }}
 ```
-{slices_close}\
+{slices_close}
+
+Then your own verdict:
+
+{result_open}
+```json
+{{"outcome": "completed", "summary": "one line on how you cut it and why"}}
+```
+{result_close}
+
+If the spec cannot be cut without guessing at something it left open, write the \
+verdict block with `"outcome": "escalated"` and a summary naming what has to be \
+settled first. Omit the slices block in that case.\
 """
 
 #: What one approved Slice looks like when it is handed to a planning pass. The
@@ -298,6 +327,8 @@ class Decomposer:
                 cwd=cwd,
                 spec_open=SPEC_OPEN,
                 spec_close=SPEC_CLOSE,
+                result_open=RESULT_OPEN,
+                result_close=RESULT_CLOSE,
             ),
             cwd,
         )
@@ -311,6 +342,8 @@ class Decomposer:
                 cap=MAX_SLICES,
                 slices_open=SLICES_OPEN,
                 slices_close=SLICES_CLOSE,
+                result_open=RESULT_OPEN,
+                result_close=RESULT_CLOSE,
             ),
             cwd,
         )

{agentforge_framework-0.2.1 → agentforge_framework-0.2.2}/src/agentforge_framework/core/skills.py

@@ -14,6 +14,13 @@ one task. `COMPOSED` says what each expands to, because a composite has to
 survive both Capability Tiers — natively it fans out through the Skill tool, and
 as a Fragment there is no tool to fan out with, so the delivery path inlines what
 it names.
+
+A skill's author can also forbid autonomous invocation outright, by marking
+`disable-model-invocation` in the frontmatter. ADR-0005 chose delivery from one
+input — what the Provider can do — and had none for what the skill permits, so a
+marked skill offered natively is refused by the Skill tool and the Role escalates
+instead of working. `fragment_only` reads the mark from the bundle as shipped, so
+the rule survives a refresh that marks a skill we have never heard of.
 """
 
 from __future__ import annotations
@@ -22,8 +29,11 @@ import json
 import sys
 from collections.abc import Sequence
 from dataclasses import dataclass, field
+from functools import lru_cache
 from pathlib import Path
 
+import yaml
+
 from .process import CommandRunner, SubprocessRunner
 
 SKILLS_ROOT = Path(__file__).resolve().parent.parent / "skills"
@@ -69,6 +79,74 @@ def expand(names: Sequence[str]) -> tuple[str, ...]:
     return tuple(ordered)
 
 
+#: The frontmatter key by which a skill's author says a model may not invoke it
+#: autonomously — only a human typing the command may.
+MODEL_INVOCATION_KEY = "disable-model-invocation"
+
+
+def _frontmatter(text: str) -> dict:
+    """The YAML block a SKILL.md opens with, or nothing if it has none."""
+    if not text.startswith("---"):
+        return {}
+    parts = text.split("---", 2)
+    if len(parts) < 3:
+        return {}
+    data = yaml.safe_load(parts[1])
+    return data if isinstance(data, dict) else {}
+
+
+@lru_cache(maxsize=1)
+def fragment_only() -> frozenset[str]:
+    """Skills the bundle forbids a model to invoke, read from the bundle itself.
+
+    Hand-listing these would have exactly the problem vendoring exists to
+    prevent: a refresh that marks a third skill would be picked up by nobody,
+    and the failure arrives as an escalation from a planning pass rather than as
+    anything a reader would connect to a bundle bump.
+
+    Frontmatter that will not parse counts as marked. Fragment delivery costs
+    tokens; getting this wrong the other way costs the Run.
+    """
+    marked = set()
+    for path in sorted(SKILLS_ROOT.iterdir()):
+        source = path / "SKILL.md"
+        if not source.is_file():
+            continue
+        try:
+            data = _frontmatter(source.read_text(encoding="utf-8"))
+        except yaml.YAMLError:
+            marked.add(path.name)
+            continue
+        if data.get(MODEL_INVOCATION_KEY):
+            marked.add(path.name)
+    return frozenset(marked)
+
+
+def forbids_model_invocation(name: str) -> bool:
+    """Whether a skill, or anything it composes, may not be model-invoked.
+
+    A composite is checked through its parts as well: natively it fans out
+    through the Skill tool, so a composite naming a marked skill would reach the
+    same refusal one indirection later.
+    """
+    marked = fragment_only()
+    return any(part in marked for part in expand((name,)))
+
+
+def split_delivery(names: Sequence[str]) -> tuple[tuple[str, ...], tuple[str, ...]]:
+    """Partition declared skills into the natively deliverable and the rest.
+
+    This is consulted before the Capability Tier, not after it. A marked skill
+    has no native delivery at any tier, so the Fragment is not the degraded form
+    here — it is the only one.
+    """
+    native: list[str] = []
+    fragment: list[str] = []
+    for name in names:
+        (fragment if forbids_model_invocation(name) else native).append(name)
+    return tuple(native), tuple(fragment)
+
+
 class SkillNotFound(LookupError):
     """A skill was requested that is not in the vendored bundle."""
 

{agentforge_framework-0.2.1 → agentforge_framework-0.2.2}/src/agentforge_framework/providers/base.py

@@ -35,7 +35,7 @@ from ..core.contracts import (
 )
 from ..core.plan_format import extract_result_block
 from ..core.process import CommandResult, CommandRunner, MissingBinary, require
-from ..core.skills import expand, read_skill
+from ..core.skills import expand, read_skill, split_delivery
 
 
 class ProviderError(RuntimeError):
@@ -133,9 +133,9 @@ class CliProvider(Provider):
             ) from exc
 
     @abstractmethod
-    def build_argv(
-        self, prompt: str, model: str, native_skills: tuple[str, ...] = ()
-    ) -> Sequence[str]: ...
+    def build_argv(self, model: str, native_skills: tuple[str, ...] = ()) -> Sequence[str]:
+        """The invocation, without the prompt. See `invoke` for why it is absent."""
+        ...
 
     @abstractmethod
     def parse_output(self, result: CommandResult) -> ProviderOutput: ...
@@ -149,9 +149,20 @@ class CliProvider(Provider):
         tier: ModelTier,
         cwd: Path,
     ) -> AgentResult:
+        """The prompt travels on stdin, never in the argument vector.
+
+        Windows caps a command line at 32,767 characters, and an AgentForge
+        prompt carries a Context Pack, a Spec, or both — `decompose` crossed the
+        cap on a 30k plan document and died as `[WinError 206]`. Linux allows
+        roughly 2MB, so every `ubuntu-latest` job in CI passed throughout (#100).
+
+        Always stdin, never "stdin when the prompt is long": a size threshold
+        would make this the rarely-taken path and the bug would return the first
+        time a prompt landed the other side of it.
+        """
         prompt, native_skills = self._deliver_skills(role, prompt)
-        argv = self.build_argv(prompt, self.model_for(tier), native_skills)
-        completed = self.runner.run(argv, cwd=cwd, timeout=self.timeout)
+        argv = self.build_argv(self.model_for(tier), native_skills)
+        completed = self.runner.run(argv, cwd=cwd, stdin=prompt, timeout=self.timeout)
         output = self.parse_output(completed)
         return to_agent_result(role=role, tier=tier, output=output)
 
@@ -166,6 +177,10 @@ class CliProvider(Provider):
         here and every body travels. Without that, a skill whose text says "run
         these two" reaches a Provider that cannot run anything and the Role is
         left with an instruction pointing at nothing.
+
+        A skill whose author forbids model invocation is a Fragment whatever the
+        tier, so the two deliveries are not exclusive: a Role can declare one of
+        each and the prompt carries both.
         """
         if not role.skills:
             return prompt, ()
@@ -173,16 +188,24 @@ class CliProvider(Provider):
         if self.capability_tier is CapabilityTier.NATIVE:
             for name in role.skills:
                 read_skill(name)  # refuse a name nothing answers for, before the CLI runs
-            commands = ", ".join(f"/agentforge:{name}" for name in role.skills)
+            native, inlined = split_delivery(role.skills)
+        else:
+            native, inlined = (), tuple(role.skills)
+
+        if native:
+            commands = ", ".join(f"/agentforge:{name}" for name in native)
             instruction = (
                 f"Use the declared native AgentForge skills before doing this work: {commands}."
             )
-            return f"{instruction}\n\n{prompt}", role.skills
+            prompt = f"{instruction}\n\n{prompt}"
+
+        if inlined:
+            fragments = [
+                f"## Skill: {name}\n\n{read_skill(name).rstrip()}" for name in expand(inlined)
+            ]
+            prompt = f"{prompt}\n\n" + "\n\n".join(fragments) + "\n"
 
-        fragments = [
-            f"## Skill: {name}\n\n{read_skill(name).rstrip()}" for name in expand(role.skills)
-        ]
-        return f"{prompt}\n\n" + "\n\n".join(fragments) + "\n", ()
+        return prompt, native
 
 
 def to_agent_result(*, role: Role, tier: ModelTier, output: ProviderOutput) -> AgentResult:

{agentforge_framework-0.2.1 → agentforge_framework-0.2.2}/src/agentforge_framework/providers/claude.py

@@ -47,13 +47,16 @@ class ClaudeProvider(CliProvider):
     def permission_mode(self) -> str:
         return self.PERMITTED if self.allow_commands else self.DENIED
 
-    def build_argv(
-        self, prompt: str, model: str, native_skills: tuple[str, ...] = ()
-    ) -> Sequence[str]:
+    def build_argv(self, model: str, native_skills: tuple[str, ...] = ()) -> Sequence[str]:
+        """`-p` carries no prompt argument: with none, the CLI reads stdin.
+
+        Verified against the installed CLI rather than the help text, which
+        documents `-p` as "print response and exit" and says nothing about where
+        the prompt comes from.
+        """
         argv = (
             self.binary,
             "-p",
-            prompt,
             "--model",
             model,
             "--output-format",

{agentforge_framework-0.2.1 → agentforge_framework-0.2.2}/src/agentforge_framework/providers/codex.py

@@ -74,11 +74,15 @@ class CodexProvider(CliProvider):
     #: rather than an edit here.
     REASONING_EFFORT: ClassVar[str] = "medium"
 
-    def build_argv(
-        self, prompt: str, model: str, native_skills: tuple[str, ...] = ()
-    ) -> Sequence[str]:
+    def build_argv(self, model: str, native_skills: tuple[str, ...] = ()) -> Sequence[str]:
         """Options precede the subcommand: `codex [OPTIONS] <COMMAND> [ARGS]`.
 
+        The prompt argument is `-`, which `codex exec --help` documents as "read
+        instructions from stdin". Omitting it entirely reads stdin too, but the
+        sentinel says so out loud, and the same help says a prompt supplied
+        alongside piped stdin gets the stdin appended as a `<stdin>` block —
+        which is the failure mode the explicit `-` rules out.
+
         This adapter previously passed `--full-auto` after `exec`, which fails
         twice over: that flag does not exist in the current CLI, and options
         placed after the subcommand are rejected regardless.
@@ -98,7 +102,7 @@ class CodexProvider(CliProvider):
             "--ask-for-approval",
             self.PERMITTED if self.allow_commands else self.DENIED,
             "exec",
-            prompt,
+            "-",
         )
 
     def parse_output(self, result: CommandResult) -> ProviderOutput:

{agentforge_framework-0.2.1 → agentforge_framework-0.2.2}/src/agentforge_framework.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentforge-framework
-Version: 0.2.1
+Version: 0.2.2
 Summary: A modular framework for coordinating specialized software agents.
 Author: Yash Mhatre
 License-Expression: Apache-2.0
@@ -145,7 +145,7 @@ without notice. See
 ```console
 $ pip install agentforge-framework
 $ agentforge --version
-agentforge 0.2.1
+agentforge 0.2.2
 ```
 
 That is the whole of it. The two routes below the naming note are for a machine
@@ -169,7 +169,7 @@ from the [latest release](https://github.com/yashmhatre/AgentForge/releases/late
 and install the file:
 
 ```console
-$ pip install agentforge_framework-0.2.1-py3-none-any.whl
+$ pip install agentforge_framework-0.2.2-py3-none-any.whl
 ```
 
 Publishing a release is a wizard rather than a checklist:

{agentforge_framework-0.2.1 → agentforge_framework-0.2.2}/tests/test_cli.py

@@ -272,7 +272,7 @@ def test_the_control_run_is_one_flag(runner, capsys):
 
     assert run(["implement", "12", "--allow-commands", "--no-context-pack"], runner) == 0
 
-    prompts = [call[call.index("-p") + 1] for call in runner.matching("claude")]
+    prompts = runner.prompts_to("claude")
     assert prompts and all("## Context Pack" not in prompt for prompt in prompts)
 
 
@@ -516,8 +516,7 @@ def test_the_document_reaches_the_synthesis_pass(runner, tmp_path):
 
     run(["decompose", str(plan), "--yes"], runner)
 
-    first = runner.matching("claude")[0]
-    prompt = first[first.index("-p") + 1]
+    prompt = runner.prompts_to("claude")[0]
     assert "Late-arriving facts need a handler." in prompt
     assert "PLAN.md" in prompt
 

{agentforge_framework-0.2.1 → agentforge_framework-0.2.2}/tests/test_decompose.py

@@ -23,6 +23,11 @@ from agentforge_framework.agents.decomposer import (
 )
 from agentforge_framework.core.contracts import Slice
 from agentforge_framework.core.plan_format import (
+    RESULT_CLOSE,
+    RESULT_OPEN,
+    SLICES_OPEN,
+    SPEC_CLOSE,
+    SPEC_OPEN,
     PlanFormatError,
     extract_slices,
     order_slices,
@@ -71,7 +76,7 @@ def a_runner(issues=(12,)) -> FakeRunner:
 
 def _prompts(runner: FakeRunner) -> list[str]:
     """What each stage was actually asked, in order. `claude -p <prompt>`."""
-    return [call[call.index("-p") + 1] for call in runner.matching("claude")]
+    return runner.prompts_to("claude")
 
 
 def bodies(runner: FakeRunner) -> list[str]:
@@ -500,3 +505,71 @@ def test_the_decomposer_reports_every_invocation_so_the_pass_can_be_priced():
     assert cut.ok
     assert len(cut.results) == 2
     assert len(cut.slices) == 3
+
+
+# --- every stage asks for a verdict ----------------------------------------
+#
+# The bug this file did not catch (#96). Each stage's prompt asked for its own
+# block and stopped, and `providers/base.py` requires a result block from every
+# invocation — so `decompose` failed on its first call against a real model
+# while 27 tests passed. The fixtures were more generous than the prompts: they
+# appended a result block nothing had asked the model to write.
+#
+# So these read the prompt rather than a fake response. A fixture cannot prove
+# that a prompt asks for what the parser needs; only the prompt can.
+
+
+def _stage_prompts(runner: FakeRunner) -> list[str]:
+    return runner.prompts_to("claude")
+
+
+def test_every_stage_asks_the_model_for_a_result_block():
+    """Whatever else a stage wants, it wants a verdict. `providers/base.py`
+    fails any invocation that comes back without one."""
+    runner = a_runner()
+    runner.script("claude", stdout=pipeline())
+
+    forge(runner).plan("add a retry", approver=_yes)
+
+    prompts = _stage_prompts(runner)
+    assert len(prompts) == 3, "spec, cut, and one planning pass"
+    for index, prompt in enumerate(prompts):
+        assert RESULT_OPEN in prompt, f"stage {index} never asks for a result block"
+        assert RESULT_CLOSE in prompt
+
+
+def test_the_spec_stage_asks_for_the_spec_block_and_then_the_verdict():
+    runner = a_runner()
+    runner.script("claude", stdout=pipeline())
+
+    forge(runner).plan("add a retry", approver=_yes)
+
+    prompt = _stage_prompts(runner)[0]
+    assert prompt.index(SPEC_OPEN) < prompt.index(RESULT_OPEN), "in that order"
+    assert '"outcome": "escalated"' in prompt, "a source too thin to use has a way out"
+
+
+def test_the_cut_stage_asks_for_the_slices_block_and_then_the_verdict():
+    runner = a_runner()
+    runner.script("claude", stdout=pipeline())
+
+    forge(runner).plan("add a retry", approver=_yes)
+
+    prompt = _stage_prompts(runner)[1]
+    assert prompt.index(SLICES_OPEN) < prompt.index(RESULT_OPEN), "in that order"
+    assert '"outcome": "escalated"' in prompt
+
+
+def test_a_stage_that_answers_with_only_its_own_block_is_the_bug_that_shipped():
+    """Reproduces #96 exactly: a model that does what the old prompt asked, and
+    nothing more, gets a failed Agent Result rather than a spec."""
+    runner = a_runner()
+    runner.script(
+        "claude",
+        stdout=_envelope(f"{SPEC_OPEN}\n## Problem Statement\n\nNo verdict.\n{SPEC_CLOSE}"),
+    )
+
+    outcome = forge(runner).plan("add a retry", approver=_yes)
+
+    assert outcome.failure is not None
+    assert "without reporting a result block" in outcome.failure.summary

{agentforge_framework-0.2.1 → agentforge_framework-0.2.2}/tests/test_docs.py

@@ -391,3 +391,26 @@ def test_the_matrix_runs_every_python_the_metadata_claims():
     tested = [int(version.split(".")[1]) for version in matrix]
 
     assert tested == list(range(floor, max(tested) + 1))
+
+
+def test_the_suite_runs_on_windows_somewhere_in_ci():
+    """#100 was a Windows process limit that every `ubuntu-latest` job stepped
+    over without noticing, on a project whose author develops on Windows. It
+    survived a release that way.
+
+    This asks only that some job runs the suite on Windows — which job, and on
+    which Python, is left open.
+    """
+    workflow = yaml.safe_load(
+        (REPO_ROOT / ".github" / "workflows" / "ci.yml").read_text(encoding="utf-8")
+    )
+
+    on_windows = [
+        job
+        for job in workflow["jobs"].values()
+        if "windows" in str(job.get("runs-on", "")) + str(job.get("strategy", ""))
+    ]
+    assert on_windows, "no CI job runs on Windows"
+    assert any(
+        "pytest" in str(step.get("run", "")) for job in on_windows for step in job.get("steps", [])
+    ), "a Windows job exists but nothing runs the suite on it"

{agentforge_framework-0.2.1 → agentforge_framework-0.2.2}/tests/test_execution_posture.py

@@ -108,7 +108,7 @@ def test_codex_options_precede_the_subcommand():
 
     for flag in ("--model", "--sandbox", "--ask-for-approval"):
         assert argv.index(flag) < exec_at, f"{flag} must precede `exec`"
-    assert argv[-1] != "exec", "the prompt is the subcommand's argument"
+    assert argv[-1] == "-", "the subcommand's argument is the stdin sentinel, not the prompt"
 
 
 def test_codex_no_longer_passes_a_flag_the_cli_does_not_have():
@@ -205,7 +205,7 @@ def test_a_denied_role_is_told_to_report_rather_than_substitute_inspection():
 
     Forge(cwd=ROOT, provider="claude", runner=runner).implement(12)
 
-    prompt = runner.only("claude")[2]
+    prompt = runner.prompt_to("claude")
     assert "cannot run commands" in prompt.lower()
     assert "escalate" in prompt.lower()
 

{agentforge_framework-0.2.1 → agentforge_framework-0.2.2}/tests/test_interview.py

@@ -68,7 +68,7 @@ def an_orchestrator(*replies: str) -> tuple[Orchestrator, FakeRunner]:
 
 
 def prompts(runner: FakeRunner) -> list[str]:
-    return [call[call.index("-p") + 1] for call in runner.matching("claude")]
+    return runner.prompts_to("claude")
 
 
 # --- the interview -----------------------------------------------------------

{agentforge_framework-0.2.1 → agentforge_framework-0.2.2}/tests/test_plugins.py

@@ -228,7 +228,7 @@ def test_fragments_never_travel_in_an_issue_body():
 
 def prompts_from(runner: FakeRunner) -> list[str]:
     """What each Agent was actually handed, read off the argument vector."""
-    return [call[call.index("-p") + 1] for call in runner.matching("claude")]
+    return runner.prompts_to("claude")
 
 
 def a_python_run() -> FakeRunner:
@@ -298,7 +298,7 @@ def test_a_fragment_reaches_both_capability_tiers_the_same_way():
     runner = a_python_run()
     Forge(cwd=ROOT, provider="codex", runner=runner).implement(12, allow_commands=True)
 
-    prompts = [call[call.index("exec") + 1] for call in runner.matching("codex")]
+    prompts = runner.prompts_to("codex")
     assert "Type-annotate new public functions" in prompts[0]