fde-framework 0.1.44__tar.gz → 0.1.45__tar.gz

{fde_framework-0.1.44 → fde_framework-0.1.45}/CHANGELOG.md

@@ -5,7 +5,51 @@ the project is pre-release, so everything sits under 0.1.0 until the first tag.
 
 ## [Unreleased]
 
-## [0.1.44] — 2026-10-12
+## [0.1.45] — 2026-10-11
+
+A twelfth outside reading, and a coding agent driving the server for the
+first time, found three things between them: a release page that said
+nothing about what it was, a date a day ahead, and an MCP server that lost
+the agent's second call two different ways.
+
+- **The agent's second call finds the first call's work.**
+  `start(name="acme")` puts the record at engagements/acme;
+  `status(engagement="acme")` a moment later looked at `<workspace>/acme`
+  and said there was no engagement. The in-process test had passed the
+  path `start` returned, so it never asked by name. A bare name is now
+  looked for where `start` puts it, as `fde status acme` does at the
+  terminal; a path is taken as given; a name that climbs out is refused
+  before anything is looked for.
+- **Calls issued at once all come back.** Claude Code asked for `status`
+  and `next` in the same breath and the second came back "Connection
+  closed". The server runs each tool on its own thread, and the capture
+  that collects a command's output does so by swapping the process's
+  stdout; two swaps interleaved left one command printing straight onto
+  the JSON-RPC channel. Commands now run one at a time inside the server.
+  A new suite drives the server as a separate process over stdio with the
+  official client: six calls at once for three rounds, a call abandoned
+  midway, a record changed on disk between calls, and every tool's input
+  schema published. The hang reproduced before the fix and fails within
+  ninety seconds instead of hanging CI.
+- **The envelope's contract is a JSON Schema.** `fde mcp --schema` prints
+  it; every reply is validated against it; the schema's list of tools is
+  the server's; a field it does not name or a status it does not name
+  fails. The README says when the version moves: a field changing meaning
+  or going away, never one being added.
+- **A release page means verified.** It is written only after the wheel
+  PyPI serves has been installed on Python 3.11, 3.12 and 3.13, hashed
+  against the wheel the tests ran on, and walked through the first five
+  minutes. It carries the wheel and the sdist, their SHA-256, the commit,
+  the run and the install line.
+- **One date.** 0.1.44 shipped on October 11 dated October 12 in both
+  CHANGELOG and CITATION. Corrected; the release workflow now holds the
+  CHANGELOG date, CITATION's date-released and the tagged commit's own day
+  in the author's time zone to one value, and a test holds the two files
+  to each other.
+- A corrupt record is a sentence naming the file, not a traceback, through
+  the server as at the terminal; now pinned by a test.
+
+## [0.1.44] — 2026-10-11
 
 An eleventh outside reading found the README contradicting itself on its
 own test count, and asked for the published wheel to be the thing that

{fde_framework-0.1.44 → fde_framework-0.1.45}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: fde-framework
-Version: 0.1.44
+Version: 0.1.45
 Summary: The decision before the AI build: evidence in, an architecture with receipts out, a scored build or a stop. For Forward Deployed Engineers and anyone deciding whether an AI system should exist.
 Project-URL: Homepage, https://github.com/atulkapoor/fde-framework
 Project-URL: Documentation, https://atulkapoor.github.io/fde-framework/
@@ -159,15 +159,24 @@ It serves `triage`, `start`, `frame`, `status`, `next`, `stage`, `debt`,
 refusals included, beside a small envelope an agent can branch on without
 parsing prose: `schema_version`, `status` (ok, blocked, refused, failed),
 `mutated`, and the workspace. The envelope follows the command's exit,
-never a reading of its text; its contract is written in the server module
-and the version moves only when a field changes meaning. An agent is not a person, so every path it supplies must
-stay inside one workspace, the directory the server started in or
+never a reading of its text. Its contract is a JSON Schema, `fde mcp
+--schema`, that every reply is tested against; a client pins
+`schema_version`, which moves only when a field changes meaning or goes
+away, never when one is added. An engagement is named as `start` named
+it (`start(name="acme")`, then `status(engagement="acme")`), or by its
+path. An agent is not a person, so every path it supplies must stay
+inside one workspace, the directory the server started in or
 `FDE_WORKSPACE`; a path outside it, a traversal, or a symlink that points
 out is refused in words, and engagement names are plain names. The two
 tools that write to the record, `start` and `frame`, say so and carry the
-protocol's hints so a client can ask first. Building, implementing and
-deploying are not served; they stay on the command line, where the person
-who runs them is accountable for them.
+protocol's hints so a client can ask first. Calls run one at a time
+inside the server, so an agent that asks for `status` and `next` in the
+same breath gets both. Exercised against two real clients: the official
+MCP Python client over stdio, in the test suite, with concurrent calls,
+an abandoned call and a record changed on disk between calls; and Claude
+Code 2.1, by hand, from the configuration above. Building, implementing
+and deploying are not served; they stay on the command line, where the
+person who runs them is accountable for them.
 
 > ### Five founding engagements
 > One real workflow, your real examples, a measured baseline, and someone
@@ -232,7 +241,7 @@ ladder, so nothing here can be over-read:
 
 | Claim | Status | The evidence, and where it stops |
 |---|---|---|
-| The framework is implemented | verified | 1,308 tests on three Pythons in CI; lint clean; every audit finding pinned as a check before it was fixed; every release installed from the published wheel into a fresh interpreter and walked through the first five minutes |
+| The framework is implemented | verified | 1,316 tests on three Pythons in CI; lint clean; every audit finding pinned as a check before it was fixed; every release installed from the published wheel into a fresh interpreter and walked through the first five minutes |
 | A build is reproducible | verified | byte-identical rebuild pinned by test; each public demo carries a Reproduce section and its digests |
 | The decisions generalise | partial | four shapes (extraction, freeform QA, a labelled decision, seventy-seven-way routing) on real data; one industry set; `fde kb sweep` names the shapes nothing serves |
 | The deliverable is production-reliable | unverified | no production engagement; the banking operating loop ran on a laptop and its record says so |

{fde_framework-0.1.44 → fde_framework-0.1.45}/README.md

@@ -115,15 +115,24 @@ It serves `triage`, `start`, `frame`, `status`, `next`, `stage`, `debt`,
 refusals included, beside a small envelope an agent can branch on without
 parsing prose: `schema_version`, `status` (ok, blocked, refused, failed),
 `mutated`, and the workspace. The envelope follows the command's exit,
-never a reading of its text; its contract is written in the server module
-and the version moves only when a field changes meaning. An agent is not a person, so every path it supplies must
-stay inside one workspace, the directory the server started in or
+never a reading of its text. Its contract is a JSON Schema, `fde mcp
+--schema`, that every reply is tested against; a client pins
+`schema_version`, which moves only when a field changes meaning or goes
+away, never when one is added. An engagement is named as `start` named
+it (`start(name="acme")`, then `status(engagement="acme")`), or by its
+path. An agent is not a person, so every path it supplies must stay
+inside one workspace, the directory the server started in or
 `FDE_WORKSPACE`; a path outside it, a traversal, or a symlink that points
 out is refused in words, and engagement names are plain names. The two
 tools that write to the record, `start` and `frame`, say so and carry the
-protocol's hints so a client can ask first. Building, implementing and
-deploying are not served; they stay on the command line, where the person
-who runs them is accountable for them.
+protocol's hints so a client can ask first. Calls run one at a time
+inside the server, so an agent that asks for `status` and `next` in the
+same breath gets both. Exercised against two real clients: the official
+MCP Python client over stdio, in the test suite, with concurrent calls,
+an abandoned call and a record changed on disk between calls; and Claude
+Code 2.1, by hand, from the configuration above. Building, implementing
+and deploying are not served; they stay on the command line, where the
+person who runs them is accountable for them.
 
 > ### Five founding engagements
 > One real workflow, your real examples, a measured baseline, and someone
@@ -188,7 +197,7 @@ ladder, so nothing here can be over-read:
 
 | Claim | Status | The evidence, and where it stops |
 |---|---|---|
-| The framework is implemented | verified | 1,308 tests on three Pythons in CI; lint clean; every audit finding pinned as a check before it was fixed; every release installed from the published wheel into a fresh interpreter and walked through the first five minutes |
+| The framework is implemented | verified | 1,316 tests on three Pythons in CI; lint clean; every audit finding pinned as a check before it was fixed; every release installed from the published wheel into a fresh interpreter and walked through the first five minutes |
 | A build is reproducible | verified | byte-identical rebuild pinned by test; each public demo carries a Reproduce section and its digests |
 | The decisions generalise | partial | four shapes (extraction, freeform QA, a labelled decision, seventy-seven-way routing) on real data; one industry set; `fde kb sweep` names the shapes nothing serves |
 | The deliverable is production-reliable | unverified | no production engagement; the banking operating loop ran on a laptop and its record says so |

{fde_framework-0.1.44 → fde_framework-0.1.45}/pyproject.toml

@@ -2,7 +2,7 @@
 # Distribution name matches the repository and stays unique on any index;
 # the import package and the CLI command remain the short `fde`.
 name = "fde-framework"
-version = "0.1.44"
+version = "0.1.45"
 description = "The decision before the AI build: evidence in, an architecture with receipts out, a scored build or a stop. For Forward Deployed Engineers and anyone deciding whether an AI system should exist."
 readme = "README.md"
 license = {text = "Apache-2.0"}

{fde_framework-0.1.44 → fde_framework-0.1.45}/src/fde/cli.py

@@ -2407,12 +2407,19 @@ def mcp_cmd(
     check: Annotated[bool, typer.Option(
         "--check", help="Build the server and list what it serves, without serving it."
     )] = False,
+    schema: Annotated[bool, typer.Option(
+        "--schema", help="Print the JSON Schema of the envelope beside every reply."
+    )] = False,
 ) -> None:
     """Serve the framework's conversational commands to a coding agent over
     stdio (Model Context Protocol): triage, start, frame, status, next,
     stage, debt, stop_when, history. Every path the agent supplies must be
     inside the workspace (FDE_WORKSPACE, else the current directory). Add
     it with, for example, `claude mcp add fde -- fde mcp`."""
+    if schema:
+        from fde.mcp_server import ENVELOPE_SCHEMA
+        typer.echo(json.dumps(ENVELOPE_SCHEMA, indent=2))
+        return
     try:
         from fde.mcp_server import describe, serve
         if check:

{fde_framework-0.1.44 → fde_framework-0.1.45}/src/fde/mcp_server.py

@@ -30,22 +30,41 @@ from __future__ import annotations
 
 import os
 import re
+import threading
 from pathlib import Path
 
 NAME = re.compile(r"^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$")
 
-# The envelope beside every reply. Bump when a field changes meaning or
-# goes away; adding a field keeps the version.
+# The envelope beside every reply, as the JSON Schema a client can validate
+# against (`fde mcp --schema` prints it). Bump the version when a field
+# changes meaning or goes away; adding a field keeps the version.
 SCHEMA_VERSION = 1
 STATUSES = ("ok", "blocked", "refused", "failed")
-ENVELOPE = {
-    "schema_version": "the integer above",
-    "tool": "the tool that answered",
-    "status": "ok: the command exited 0 | blocked: it refused or a condition triggered "
-              "(exit 1) | refused: the path or name was outside what the agent may touch; "
-              "nothing ran | failed: an exception, a bug to report",
-    "mutated": "true only when a writing tool ran and exited 0",
-    "workspace": "the directory every path was confined to",
+TOOLS = ("triage", "start", "frame", "status", "next", "stage", "debt", "stop_when", "history")
+ENVELOPE_SCHEMA = {
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "$id": f"https://github.com/atulkapoor/fde-framework/schemas/mcp-envelope/v{SCHEMA_VERSION}",
+    "title": f"fde MCP reply envelope, version {SCHEMA_VERSION}",
+    "description": "The structured content beside the text of every tool reply. The text "
+                   "is what the command printed; the envelope is what an agent branches on "
+                   "without parsing prose. It follows the command's exit, not its wording.",
+    "type": "object",
+    "properties": {
+        "schema_version": {"const": SCHEMA_VERSION,
+                           "description": "Bumped when a field changes meaning or goes away."},
+        "tool": {"enum": list(TOOLS), "description": "The tool that answered."},
+        "status": {"enum": list(STATUSES),
+                   "description": "ok: the command exited 0. blocked: it refused or a "
+                                  "condition triggered (exit 1); the text says which. "
+                                  "refused: a path or name was outside what the agent may "
+                                  "touch; nothing ran. failed: an exception; a bug to report."},
+        "mutated": {"type": "boolean",
+                    "description": "True only when a writing tool ran and exited 0."},
+        "workspace": {"type": "string",
+                      "description": "The directory every path was confined to."},
+    },
+    "required": ["schema_version", "tool", "status", "mutated", "workspace"],
+    "additionalProperties": False,
 }
 
 THIRTY_SECONDS = """\
@@ -68,10 +87,12 @@ brief into typed facts; `status` for the gates and what is still unknown;
 for where the engagement stands on its record; `debt` for what nobody has
 settled; `stop_when` for whether the evidence says stop; `history` for the
 whole record in order. Every tool returns the command's own output,
-refusals included. `start` and `frame` write to the record; the rest only
-read it. Every path must be inside the server's workspace. Nothing here
-builds, implements or deploys; those are run by a person on the command
-line.
+refusals included, with a status beside it (ok, blocked, refused, failed)
+to branch on instead of the prose. `start` and `frame` write to the
+record; the rest only read it. An engagement is named as `start` named
+it, or by its path; every path must be inside the server's workspace.
+Nothing here builds, implements or deploys; those are run by a person on
+the command line.
 """
 
 
@@ -100,6 +121,21 @@ def confine(path: str | None, what: str, root: Path | None = None) -> Path | Non
     return resolved
 
 
+def locate(engagement: str) -> Path:
+    """The engagement as the command will see it. `start(name="acme")` puts
+    the record at engagements/acme; `status(engagement="acme")` a moment
+    later must find it, as `fde status acme` does on the command line. So a
+    bare name is looked for at <workspace>/<name> and then where `start`
+    puts it; both candidates are confined, so a name that climbs out is
+    refused before anything is looked for. A path is taken as given."""
+    path = confine(engagement, "engagement")
+    if path is not None and not (path / "facts").is_dir() and not Path(engagement).is_absolute():
+        under = confine(str(Path("engagements") / engagement), "engagement")
+        if under is not None and (under / "facts").is_dir():
+            return under
+    return path
+
+
 def plain_name(name: str) -> str:
     if not NAME.match(name or ""):
         raise Outside(f"an engagement name is a plain name (letters, digits, '.', '_', '-'), "
@@ -113,6 +149,16 @@ def _registry() -> str:
     return os.environ.get("FDE_REGISTRY") or str(default_root())
 
 
+# One command at a time. The server runs each tool on a worker thread, and
+# a coding agent will issue `status` and `next` in the same breath; the
+# runner that captures a command's output does so by swapping the
+# process's stdout, and two swaps interleaved left one command printing
+# straight onto the JSON-RPC channel. The protocol broke, the client saw
+# "Connection closed", and the record was not at fault. Commands take
+# milliseconds; the record has one writer at a time, as it should.
+_ONE_AT_A_TIME = threading.Lock()
+
+
 def run_command(args: list[str], registry: bool = True) -> tuple[str, str]:
     """One command, in-process, as the terminal would run it: the text it
     printed, and a status an agent can branch on without parsing prose --
@@ -123,7 +169,8 @@ def run_command(args: list[str], registry: bool = True) -> tuple[str, str]:
     from fde.cli import app
 
     argv = [*args, "--registry", _registry()] if registry else list(args)
-    result = CliRunner().invoke(app, argv)
+    with _ONE_AT_A_TIME:
+        result = CliRunner().invoke(app, argv)
     text = (result.output or "").strip()
     if result.exception and not isinstance(result.exception, SystemExit):
         return (f"{text}\n\nfde: {type(result.exception).__name__}: {result.exception}".strip(),
@@ -211,14 +258,14 @@ def build_server():
         """WRITES: reads a brief, pasted as text, into typed facts appended to
         the engagement's record, played back for correction with the
         follow-up questions. The engagement must be inside the workspace."""
-        return run_command(["frame", str(confine(engagement, "engagement")), "--text", text])
+        return run_command(["frame", str(locate(engagement)), "--text", text])
 
     @server.tool(annotations=reads)
     @guarded
     def status(engagement: str):
         """The engagement's gates, what is known by scope and who said it, what
         is still missing, and which roles have not been heard."""
-        return run_command(["status", str(confine(engagement, "engagement"))])
+        return run_command(["status", str(locate(engagement))])
 
     @server.tool(annotations=reads)
     @guarded
@@ -227,7 +274,7 @@ def build_server():
         and -- when it is a question -- the evidence already on record and
         the decisions that turn on each candidate answer. Reads only; the
         action it names is for a person to run."""
-        return run_command(["next", str(confine(engagement, "engagement"))])
+        return run_command(["next", str(locate(engagement))])
 
     @server.tool(annotations=reads)
     @guarded
@@ -236,7 +283,7 @@ def build_server():
         validation, prototype, pilot, production, adoption, retrospective,
         or stopped -- with what would move it to the next stage. Reads only:
         a person runs `fde stage` to append the transition to the record."""
-        args = ["stage", str(confine(engagement, "engagement")), "--no-record"]
+        args = ["stage", str(locate(engagement)), "--no-record"]
         target = confine(project, "project")
         return run_command(args + (["--project", str(target)] if target else []))
 
@@ -247,7 +294,7 @@ def build_server():
         settled -- failing gates, standing waivers, guessed or merely stated
         facts, disagreements, unsigned attestations, unheard roles, open
         incidents, undecided components -- each with an owner and an age."""
-        return run_command(["debt", str(confine(engagement, "engagement"))])
+        return run_command(["debt", str(locate(engagement))])
 
     @server.tool(annotations=reads)
     @guarded
@@ -256,7 +303,7 @@ def build_server():
         """Judge the engagement's stop conditions against what the record has
         measured: the scorecard, the field journal, the recorded outcomes.
         Reads only; recording a condition is for a person."""
-        args = ["stop-when", str(confine(engagement, "engagement"))]
+        args = ["stop-when", str(locate(engagement))]
         target = confine(project, "project")
         if target:
             args += ["--project", str(target)]
@@ -270,7 +317,7 @@ def build_server():
     def history(engagement: str):
         """Every dated entry on the engagement's record, in order, the undated
         ones above it, one line each."""
-        return run_command(["history", str(confine(engagement, "engagement"))],
+        return run_command(["history", str(locate(engagement))],
                            registry=False)
 
     @server.resource("fde://thirty-seconds", name="fde in thirty seconds",
@@ -293,6 +340,7 @@ def describe() -> str:
             else "reads"
         lines.append(f"    {tool.name:10} {hint}")
     lines.append("  resources: fde://thirty-seconds")
+    lines.append(f"  envelope: schema_version {SCHEMA_VERSION} (`fde mcp --schema`)")
     return "\n".join(lines)
 
 

{fde_framework-0.1.44 → fde_framework-0.1.45}/tests/test_mcp.py

@@ -224,10 +224,11 @@ def test_check_mode_creates_nothing(tmp_path, monkeypatch):
 
 
 def test_the_envelope_is_versioned_and_every_status_is_reachable(tmp_path, monkeypatch):
+    import jsonschema
+
     from fde import mcp_server
-    from fde.mcp_server import ENVELOPE, SCHEMA_VERSION, STATUSES, reply, run_command
+    from fde.mcp_server import ENVELOPE_SCHEMA, SCHEMA_VERSION, STATUSES, reply, run_command
 
-    assert set(ENVELOPE) == {"schema_version", "tool", "status", "mutated", "workspace"}
     monkeypatch.setenv("FDE_WORKSPACE", str(tmp_path))
     server = build_server()
     seen = {}
@@ -243,7 +244,7 @@ def test_the_envelope_is_versioned_and_every_status_is_reachable(tmp_path, monke
     for status in STATUSES:
         assert seen[status]["status"] == status
         assert seen[status]["schema_version"] == SCHEMA_VERSION
-        assert set(seen[status]) == set(ENVELOPE)
+        jsonschema.validate(seen[status], ENVELOPE_SCHEMA)
 
     class Broken:
         output = "half-written"
@@ -270,3 +271,85 @@ def test_doctor_measures_the_install_and_fails_only_on_what_the_core_needs(tmp_p
     sick = runner.invoke(app, ["doctor", "--registry", str(tmp_path / "nowhere")])
     assert sick.exit_code == 1 and "NO registry" in sick.output
     assert "something the core needs is missing" in sick.output
+
+
+# --- the interface as a product: the second call finds the first call's work
+
+
+def test_an_engagement_is_found_by_the_name_start_gave_it(tmp_path, monkeypatch):
+    """`start(name="acme")` then `status(engagement="acme")` is the sequence
+    an agent writes first. Before this test the second call looked at
+    <workspace>/acme, found nothing, and said so; the record was at
+    engagements/acme, where `start` had put it and where `fde status acme`
+    finds it on the command line."""
+    monkeypatch.setenv("FDE_WORKSPACE", str(tmp_path))
+    server = build_server()
+    opened = asyncio.run(server.call_tool("start", {
+        "name": "acme", "statement": "Route each support message to one of 77 queues."}))
+    assert opened.structured_content["status"] == "ok"
+    assert (tmp_path / "engagements" / "acme" / "facts").is_dir()
+    for tool, expected in (("status", "blocked by"), ("next", "next: fde "),
+                           ("stage", "acme: discovery"), ("debt", "decision debt as of"),
+                           ("history", "acme: history"),
+                           ("stop_when", "no stop conditions on record")):
+        result = asyncio.run(server.call_tool(tool, {"engagement": "acme"}))
+        assert expected in result.content[0].text, (tool, result.content[0].text)
+        assert result.structured_content["status"] == "ok", (tool, result.structured_content)
+    framed = asyncio.run(server.call_tool("frame", {
+        "engagement": "acme",
+        "text": "Two agents triage 9,000 emails a month by hand and misroute about 12 percent."}))
+    assert framed.structured_content["status"] == "ok" and framed.structured_content["mutated"]
+    # The path form still works, and a name that climbs is still refused
+    # before anything is looked for.
+    by_path = asyncio.run(server.call_tool("status", {"engagement": "engagements/acme"}))
+    assert by_path.structured_content["status"] == "ok"
+    climbing = asyncio.run(server.call_tool("status", {"engagement": "../acme"}))
+    assert climbing.structured_content["status"] == "refused"
+    assert "outside the workspace" in climbing.content[0].text
+
+
+def test_a_corrupt_record_is_a_sentence_naming_the_file_not_a_traceback(tmp_path, monkeypatch):
+    monkeypatch.setenv("FDE_WORKSPACE", str(tmp_path))
+    server = build_server()
+    asyncio.run(server.call_tool("start", {
+        "name": "acme", "statement": "Route each support message to one of 77 queues."}))
+    asyncio.run(server.call_tool("frame", {
+        "engagement": "acme", "text": "Two agents triage 9,000 emails a month by hand."}))
+    record = next((tmp_path / "engagements" / "acme" / "facts").glob("*.yaml"))
+    with record.open("a") as fh:
+        fh.write('{"this is": not yaml\n')
+    for tool in ("status", "next", "debt"):
+        result = asyncio.run(server.call_tool(tool, {"engagement": "acme"}))
+        text = result.content[0].text
+        assert result.structured_content["status"] != "ok", tool
+        assert record.stem in text and "cannot read" in text, (tool, text)
+        assert "Traceback" not in text, (tool, text)
+
+
+def test_the_schema_is_published_and_is_what_every_reply_follows(tmp_path, monkeypatch):
+    import json
+
+    import jsonschema
+    from typer.testing import CliRunner
+
+    from fde.cli import app
+    from fde.mcp_server import ENVELOPE_SCHEMA, SCHEMA_VERSION, TOOLS
+
+    result = CliRunner().invoke(app, ["mcp", "--schema"])
+    assert result.exit_code == 0, result.output
+    published = json.loads(result.output)
+    assert published == ENVELOPE_SCHEMA
+    jsonschema.Draft202012Validator.check_schema(published)
+    assert published["$id"].endswith(f"/v{SCHEMA_VERSION}")
+    # The schema's list of tools is the server's list of tools.
+    monkeypatch.setenv("FDE_WORKSPACE", str(tmp_path))
+    server = build_server()
+    assert {t.name for t in asyncio.run(server.list_tools())} == set(TOOLS)
+    # And an envelope with a field it does not name, or a status it does not
+    # name, fails validation: a client can trust the schema to be the contract.
+    good = asyncio.run(server.call_tool("triage", {"statements": ["Route."]})).structured_content
+    jsonschema.validate(good, published)
+    with pytest.raises(jsonschema.ValidationError):
+        jsonschema.validate({**good, "extra": 1}, published)
+    with pytest.raises(jsonschema.ValidationError):
+        jsonschema.validate({**good, "status": "done"}, published)

fde_framework-0.1.45/tests/test_mcp_stdio.py

@@ -0,0 +1,119 @@
+"""The server as a client sees it: a separate process over stdio, driven by
+the official MCP client, the way a coding agent drives it. The in-process
+tests check each tool; these check the transport under what agents
+actually do -- several calls at once, a call abandoned midway, a record
+that changed on disk between calls."""
+
+from __future__ import annotations
+
+import asyncio
+import os
+import sys
+
+import pytest
+
+pytest.importorskip("mcp", reason="the MCP extra is not installed")
+
+from mcp import ClientSession, StdioServerParameters  # noqa: E402
+from mcp.client.stdio import stdio_client  # noqa: E402
+
+from fde.mcp_server import TOOLS  # noqa: E402
+
+STATEMENT = "Route each support message to one of 77 queues."
+PATIENCE = 90  # seconds; a regression hangs the server, and the test must fail, not hang
+
+
+def serve_in(workspace):
+    return StdioServerParameters(command=sys.executable, args=["-m", "fde.cli", "mcp"],
+                                 env={**os.environ, "FDE_WORKSPACE": str(workspace)})
+
+
+def drive(workspace, scenario):
+    async def main():
+        async with stdio_client(serve_in(workspace)) as (read, write):
+            async with ClientSession(read, write) as session:
+                await asyncio.wait_for(session.initialize(), PATIENCE)
+                return await asyncio.wait_for(scenario(session), PATIENCE)
+    return asyncio.run(main())
+
+
+def test_a_real_client_lists_the_tools_with_their_input_schemas_and_walks_by_name(tmp_path):
+    async def scenario(session):
+        listed = await session.list_tools()
+        schemas = {t.name: t.input_schema for t in listed.tools}
+        opened = await session.call_tool("start", {"name": "acme", "statement": STATEMENT})
+        status = await session.call_tool("status", {"engagement": "acme"})
+        return schemas, opened, status
+
+    schemas, opened, status = drive(tmp_path, scenario)
+    assert set(schemas) == set(TOOLS)
+    for name, schema in schemas.items():
+        assert schema["type"] == "object" and schema["properties"], name
+        if name not in ("triage", "start"):
+            assert "engagement" in schema["required"], name
+    assert opened.structured_content["status"] == "ok" and opened.structured_content["mutated"]
+    assert status.structured_content["status"] == "ok"
+    assert "blocked by" in status.content[0].text
+
+
+def test_calls_issued_at_once_all_come_back(tmp_path):
+    """Claude Code issued `status` and `next` in the same breath and the
+    second came back "Connection closed": the server ran them on two
+    threads, and the output capture that each swaps in leaked one
+    command's text onto the JSON-RPC channel. Commands are now one at a
+    time inside the server."""
+    async def scenario(session):
+        await session.call_tool("start", {"name": "acme", "statement": STATEMENT})
+        rounds = []
+        for _ in range(3):
+            replies = await asyncio.gather(
+                *(session.call_tool(tool, {"engagement": "acme"})
+                  for tool in ("status", "next", "debt", "stage", "history", "stop_when")),
+                return_exceptions=True)
+            rounds.append(replies)
+        after = await session.call_tool("history", {"engagement": "acme"})
+        return rounds, after
+
+    rounds, after = drive(tmp_path, scenario)
+    for replies in rounds:
+        for reply in replies:
+            assert not isinstance(reply, BaseException), repr(reply)
+            assert reply.structured_content["status"] == "ok", reply.content[0].text
+            assert reply.content[0].text.strip(), reply.structured_content
+    assert after.structured_content["status"] == "ok"
+
+
+def test_a_call_abandoned_midway_leaves_the_server_answering(tmp_path):
+    async def scenario(session):
+        await session.call_tool("start", {"name": "acme", "statement": STATEMENT})
+        abandoned = asyncio.ensure_future(session.call_tool("next", {"engagement": "acme"}))
+        await asyncio.sleep(0)
+        abandoned.cancel()
+        try:
+            await abandoned
+        except asyncio.CancelledError:
+            pass
+        return await session.call_tool("status", {"engagement": "acme"})
+
+    status = drive(tmp_path, scenario)
+    assert status.structured_content["status"] == "ok"
+
+
+def test_the_record_is_read_fresh_so_a_change_on_disk_shows_in_the_next_call(tmp_path):
+    from typer.testing import CliRunner
+
+    from fde.cli import app
+
+    async def scenario(session):
+        await session.call_tool("start", {"name": "acme", "statement": STATEMENT})
+        before = await session.call_tool("history", {"engagement": "acme"})
+        # Someone at the terminal frames a brief while the server is up.
+        result = CliRunner().invoke(app, ["frame", str(tmp_path / "engagements" / "acme"),
+                                          "--text", "Two agents triage 9,000 emails a month "
+                                                    "by hand and misroute about 12 percent."])
+        assert result.exit_code == 0, result.output
+        after = await session.call_tool("history", {"engagement": "acme"})
+        return before.content[0].text, after.content[0].text
+
+    before, after = drive(tmp_path, scenario)
+    assert "0002-frame" not in before and "0002-frame" in after

fde_framework-0.1.45/tests/test_release_consistency.py

@@ -0,0 +1,38 @@
+"""One version, in every place that states it. Two tags this week had to
+be moved after the fact; this fails before the tag instead."""
+
+from __future__ import annotations
+
+import re
+import tomllib
+from pathlib import Path
+
+REPO = Path(__file__).resolve().parent.parent
+
+
+def test_pyproject_citation_and_changelog_agree_on_the_version():
+    version = tomllib.loads((REPO / "pyproject.toml").read_text())["project"]["version"]
+    citation = re.search(r"^version: (\S+)$", (REPO / "CITATION.cff").read_text(), re.M)
+    assert citation and citation.group(1) == version, "CITATION.cff lags pyproject.toml"
+    latest = re.search(r"^## \[(\d+\.\d+\.\d+)\]", (REPO / "CHANGELOG.md").read_text(), re.M)
+    assert latest and latest.group(1) == version, "CHANGELOG.md's newest entry lags the version"
+
+
+def test_citation_and_changelog_agree_on_the_date_and_it_is_not_ahead_of_today():
+    """0.1.44 shipped on October 11 dated October 12, in both files, and an
+    outside reader noticed before I did. The two files must agree, and the
+    date may not be in the future; the release workflow goes further and
+    holds it to the day the tagged commit was authored."""
+    from datetime import date, timedelta
+
+    changelog = re.search(r"^## \[\d+\.\d+\.\d+\] — (\d{4}-\d{2}-\d{2})",
+                          (REPO / "CHANGELOG.md").read_text(), re.M)
+    assert changelog, "the newest CHANGELOG entry carries no date"
+    citation = re.search(r"^date-released: '(\d{4}-\d{2}-\d{2})'$",
+                         (REPO / "CITATION.cff").read_text(), re.M)
+    assert citation and citation.group(1) == changelog.group(1), \
+        "CITATION.cff date-released != the newest CHANGELOG date"
+    released = date.fromisoformat(changelog.group(1))
+    # A day of slack: the author's calendar and the test runner's need not
+    # agree at midnight.
+    assert released <= date.today() + timedelta(days=1), f"{released} has not happened yet"