b4pt0r-the-framework 0.1.0__tar.gz

b4pt0r_the_framework-0.1.0/.gitignore

@@ -0,0 +1,13 @@
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.coverage
+.venv/
+.playwright-browsers/
+node_modules/
+starter/ui/dist/
+.env
+.env.*
+!.env.example
+*.log
+.DS_Store

b4pt0r_the_framework-0.1.0/AGENTS.md

@@ -0,0 +1,59 @@
+# Working on The Framework
+
+The public Python package is `the_framework/`; `starter/` is an editable
+example that uses it. Read [README.md](README.md) for the first-run path and
+[docs/framework.md](docs/framework.md) for the composition API. This
+file records the constraints to preserve when changing the framework.
+
+## Ownership and contracts
+
+- Keep application identity, instructions, policies and domain-specific
+  features outside `the_framework`. Dependencies point from applications to the
+  framework, never the reverse. The starter must depend on `the_framework`, not
+  on any particular application.
+- An `AgentApplication` has one durable primary conversation. The worker is its
+  only history writer. Plugins may declare private specialist agents, but a
+  specialist must not write into primary history; results return through the
+  owning plugin or an ordered primary-agent input.
+- The server owns authentication, routes, client connections and worker
+  supervision. Workers own inference, tools and their sessions. Clients own
+  their local interface and media/device execution. Do not move a
+  responsibility across these process boundaries merely to simplify a call.
+- Treat saved sessions, task delivery, HTTP/WebSocket payloads and client
+  security as contracts. Preserve them when refactoring, or provide an explicit
+  tested migration. A client reconnection or worker restart must not create a
+  second main conversation or bypass safety controls.
+- Plugins contribute through the framework's declarations and lifecycle, not
+  by mutating FastAPI internals or global registries. Loading a plugin is
+  separate from exposing its tools to an agent; server routes may remain
+  available when an agent binding is disabled.
+
+## Making changes
+
+- Keep the public API small and typed. Prefer improving an existing primitive
+  to adding a forwarding layer. Migrate internal callers when an internal API
+  changes rather than retaining obsolete aliases.
+- Use `modict` for structured models where its mapping and validation features
+  fit. Inspect its API before adding a parallel model or conversion layer.
+  Backend-specific Responses behavior belongs at the `codex-backend-sdk`
+  boundary, not in ad hoc transport code elsewhere.
+- Changes to shared dependencies such as `modict` or `codex-backend-sdk` must
+  remain generally useful and backward-compatible; test them in their own
+  repositories before relying on the change here.
+- Keep the starter runnable from an installed wheel outside this checkout.
+  Its source and interface must remain editable application code, not hidden
+  framework policy.
+
+## Verification
+
+Add focused tests for the behavior being changed. Then run the framework suite:
+
+```sh
+uv sync --extra dev
+uv run pytest -q tests/application tests/agentic
+```
+
+`tests/application/` covers observable contracts and includes wheel-only
+checks. `tests/agentic/` covers internals that may evolve. For changes to the
+starter UI, also run its npm tests and build as described in
+[starter/README.md](starter/README.md).

b4pt0r_the_framework-0.1.0/CHANGELOG.md

@@ -0,0 +1,16 @@
+# Changelog
+
+Notable changes to the Python distribution are recorded here. Versions follow
+the distribution `b4pt0r-the-framework`; the import remains `the_framework`.
+Until a stable release, minor versions may revise the public composition API.
+
+## Unreleased
+
+- No changes recorded yet.
+
+## 0.1.0 - 2026-09-22
+
+- Provide the `AgentApplication` composition API for one persistent primary
+  agent, server extensions, plugins, private specialists and client surfaces.
+- Include the editable starter application and `the-framework bootstrap` CLI.
+- Package typed Python modules and runtime resources with MIT licensing.

b4pt0r_the_framework-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 B4PT0R
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

b4pt0r_the_framework-0.1.0/PKG-INFO

@@ -0,0 +1,245 @@
+Metadata-Version: 2.5
+Name: b4pt0r-the-framework
+Version: 0.1.0
+Summary: Build persistent, extensible local agent applications with supervised workers and authenticated clients
+Project-URL: Homepage, https://github.com/B4PT0R/the_framework
+Project-URL: Documentation, https://github.com/B4PT0R/the_framework/blob/main/README.md
+Project-URL: Repository, https://github.com/B4PT0R/the_framework
+Project-URL: Changelog, https://github.com/B4PT0R/the_framework/blob/main/CHANGELOG.md
+Project-URL: Issues, https://github.com/B4PT0R/the_framework/issues
+Author: B4PT0R
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agentic-applications,agents,fastapi,framework,plugins
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: FastAPI
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Requires-Dist: codex-backend-sdk>=0.5.3
+Requires-Dist: fastapi
+Requires-Dist: httpx
+Requires-Dist: jsonschema>=4.26.0
+Requires-Dist: modict>=0.4.19
+Requires-Dist: pillow
+Requires-Dist: playwright
+Requires-Dist: python-multipart
+Requires-Dist: pyyaml
+Requires-Dist: tiktoken
+Requires-Dist: uvicorn
+Requires-Dist: websockets
+Provides-Extra: dev
+Requires-Dist: httpx2>=2.0.0; extra == 'dev'
+Requires-Dist: pytest; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# The Framework
+
+The Framework is a Python library for building applications around a persistent
+AI agent. It supplies the parts that are easy to get wrong repeatedly: one
+durable conversation, a supervised agent worker, plugin and specialist-agent
+lifecycle, authenticated HTTP/WebSocket connections, and versioned web
+interfaces. You supply the agent's identity, instructions, application
+services, security policy and user experience.
+
+You can use it for a local desktop companion, a private agent with tools and
+memory, or another agent application whose browser and backend need to survive
+worker restarts without losing the conversation. It is a library, not a hosted
+agent service. The included [starter](https://github.com/B4PT0R/the_framework/blob/main/starter/README.md) is an editable
+application that shows the pieces working together; you are free to build a
+different frontend or none at all.
+
+The PyPI distribution is named `b4pt0r-the-framework`. Python code imports
+`the_framework`, and the template command is `the-framework`. Python 3.12 or
+newer is required.
+
+To install the published package in a virtual environment:
+
+```sh
+python3 -m venv .venv
+. .venv/bin/activate
+python -m pip install b4pt0r-the-framework
+```
+
+The Python wheel includes the framework and the editable starter template, but
+not a prebuilt browser UI or Playwright's Chromium binary. Those are prepared
+separately when you run the starter.
+
+## What an application is made of
+
+| Part | What it does | What your application decides |
+| --- | --- | --- |
+| `AgentApplication` | Validates and assembles one application | Name, version, plugins, server services, security and client surfaces |
+| `AgentSpec` | Describes an agent and its session policy | Instructions, model configuration, tools and resources |
+| `Plugin` / `PluginSpec` | Adds agent tools, context, hooks and optional server runtime | Which capabilities exist and when they are exposed |
+| `Extension` / `@endpoint` | Starts services and exposes validated API routes | Application state, route schemas and authorization |
+| `ClientSurface` | Builds, previews, publishes and rolls back an editable web UI | Source, build command, routes and release policy |
+
+There is exactly **one primary, durable conversation**. Private specialist
+agents can perform bounded background work, but their sessions are not new
+user-facing conversations and they cannot edit the primary history directly.
+The server supervises workers and owns authentication and client transport;
+workers own inference and their own sessions; a browser client owns its local
+interface and device/media execution. This separation lets a client reconnect
+or refresh while the main conversation remains intact.
+
+Plugins may provide agent-facing tools without a server runtime, or both. A
+plugin's runtime state and its binding to an agent are separate: turning off its
+tools for the agent need not remove routes that a settings screen still uses.
+Specialists, durable task delivery and versioned public capabilities are
+available when a simple plugin is not enough. More detail is in the
+[framework guide](https://github.com/B4PT0R/the_framework/blob/main/docs/framework.md).
+
+## Try a working application
+
+Install [`uv`](https://docs.astral.sh/uv/) and Node.js/npm, then from this
+checkout run:
+
+```sh
+uv sync
+npm --prefix starter/ui ci
+npm --prefix starter/ui run build
+uv run playwright install chromium
+uv run python -m starter
+```
+
+Playwright Chromium also needs its system libraries; on Linux,
+`uv run playwright install --with-deps chromium` can install them if you have
+the required system permissions. The starter opens a local Chromium window with
+chat, settings, file attachments and an editable React interface. Its server
+listens on loopback and authenticates the browser. You can inspect the UI and
+settings without model credentials; generating replies, using hosted search or
+embeddings, and voice features require a usable account/capabilities through
+`codex-backend-sdk`. The [starter guide](https://github.com/B4PT0R/the_framework/blob/main/starter/README.md) covers sign-in,
+data storage and feature-by-feature behavior.
+
+To make an independent, editable copy, run `the-framework bootstrap` in the
+environment where you installed the package. From this checkout, prefix it
+with `uv run`:
+
+```sh
+uv run the-framework bootstrap --code-dir /path/to/my-agent-code --data-dir /path/to/my-agent-data
+```
+
+Both directories must be empty or absent, distinct and non-overlapping. The
+command copies the starter source and records the private data location; it
+does not install npm dependencies, build the UI or launch the app. From the new
+code directory, run `npm --prefix starter/ui ci`,
+`npm --prefix starter/ui run build`, then `python -m starter` in an environment
+with `b4pt0r-the-framework` installed. Change `starter/application.py` and
+`starter/instructions.md` first; `starter/ui/` contains the editable interface.
+Keep the data directory private: it holds conversation history, configuration,
+uploads, memory and browser profiles.
+
+## Build a small application yourself
+
+Save the following as `example.py`. It is a complete HTTP application; the
+repository also includes an [expanded version](https://github.com/B4PT0R/the_framework/blob/main/examples/minimal_agent_app.py)
+with `modict` request/response models and a health endpoint.
+
+```python
+from the_framework import AgentApplication, AgentSpec, Extension, SessionPolicy, endpoint
+from the_framework.server.api.endpoints import Principal
+
+
+class BearerSecurity:
+    async def authenticate(self, request):
+        if request.headers.get("authorization") != "Bearer example-secret":
+            return None
+        return Principal(id="example-client", scopes=frozenset({"counter:write"}))
+
+    async def authorize(self, principal, requirement, request):
+        return requirement is None or requirement.get("scope") in principal.scopes
+
+
+class Counter:
+    def __init__(self):
+        self.value = 0
+        self.running = False
+
+    async def start(self):
+        self.running = True
+
+    async def stop(self):
+        self.running = False
+
+    @endpoint(
+        "post", "/api/v1/counter/increment",
+        request={"type": "object", "properties": {"amount": {"type": "integer"}},
+                 "required": ["amount"], "additionalProperties": False},
+        response={"type": "object", "properties": {"value": {"type": "integer"}},
+                  "required": ["value"]},
+        authorization={"scope": "counter:write"},
+    )
+    def increment(self, amount: int):
+        """Increment the application counter."""
+        self.value += amount
+        return {"value": self.value}
+
+
+counter = Counter()
+application = AgentApplication(
+    name="Counter Agent",
+    version="0.1",
+    primary_agent=AgentSpec(
+        name="assistant",
+        description="The application's primary agent",
+        session=SessionPolicy.durable(),
+    ),
+    security=BearerSecurity(),
+    extensions=(Extension(name="counter", service=counter,
+                          endpoints=(counter.increment,)),),
+)
+app = application.build()
+```
+
+Start it with:
+
+```sh
+uv run uvicorn example:app --host 127.0.0.1 --port 8000
+```
+
+Then, in another terminal:
+
+```sh
+curl -sS -X POST http://127.0.0.1:8000/api/v1/counter/increment \
+  -H 'Authorization: Bearer example-secret' \
+  -H 'Content-Type: application/json' \
+  -d '{"amount": 2}'
+```
+
+The result is `{"value":2}`. The literal bearer secret is **only** for this
+loopback demonstration; use a real authentication policy for an application.
+The primary agent declaration alone does not create a chat API or start
+inference: the starter shows how to add its supervised worker and client
+transport. `@endpoint` validates request and response data and contributes an
+OpenAPI schema. `Extension` manages dependencies and service startup/shutdown;
+`AgentApplication.compile()` checks the full graph before runtime startup.
+
+For the next step, read [composition and runtime](https://github.com/B4PT0R/the_framework/blob/main/docs/framework.md) for
+plugins, private specialists, persistent resources, security, voice and client
+surfaces. The [starter source](https://github.com/B4PT0R/the_framework/tree/main/starter) shows these features in one application
+without requiring you to adopt its UI design.
+
+## Develop and package
+
+```sh
+uv sync --extra dev
+uv run pytest -q tests/application tests/agentic
+uv build
+```
+
+The build produces a wheel and source archive in `dist/`. The wheel contains
+the typed `the_framework` package, runtime prompts and the editable starter
+template; it does **not** bundle Node modules or a prebuilt browser UI. The
+test suite includes a wheel-only import/bootstrap check outside the checkout.
+For UI changes, also run `npm --prefix starter/ui test` and
+`npm --prefix starter/ui run build`.
+
+This repository is [MIT licensed](https://github.com/B4PT0R/the_framework/blob/main/LICENSE). See the [changelog](https://github.com/B4PT0R/the_framework/blob/main/CHANGELOG.md)
+for version notes. Publishing to PyPI is a separate release action; building
+locally does not publish anything.

b4pt0r_the_framework-0.1.0/README.md

@@ -0,0 +1,206 @@
+# The Framework
+
+The Framework is a Python library for building applications around a persistent
+AI agent. It supplies the parts that are easy to get wrong repeatedly: one
+durable conversation, a supervised agent worker, plugin and specialist-agent
+lifecycle, authenticated HTTP/WebSocket connections, and versioned web
+interfaces. You supply the agent's identity, instructions, application
+services, security policy and user experience.
+
+You can use it for a local desktop companion, a private agent with tools and
+memory, or another agent application whose browser and backend need to survive
+worker restarts without losing the conversation. It is a library, not a hosted
+agent service. The included [starter](https://github.com/B4PT0R/the_framework/blob/main/starter/README.md) is an editable
+application that shows the pieces working together; you are free to build a
+different frontend or none at all.
+
+The PyPI distribution is named `b4pt0r-the-framework`. Python code imports
+`the_framework`, and the template command is `the-framework`. Python 3.12 or
+newer is required.
+
+To install the published package in a virtual environment:
+
+```sh
+python3 -m venv .venv
+. .venv/bin/activate
+python -m pip install b4pt0r-the-framework
+```
+
+The Python wheel includes the framework and the editable starter template, but
+not a prebuilt browser UI or Playwright's Chromium binary. Those are prepared
+separately when you run the starter.
+
+## What an application is made of
+
+| Part | What it does | What your application decides |
+| --- | --- | --- |
+| `AgentApplication` | Validates and assembles one application | Name, version, plugins, server services, security and client surfaces |
+| `AgentSpec` | Describes an agent and its session policy | Instructions, model configuration, tools and resources |
+| `Plugin` / `PluginSpec` | Adds agent tools, context, hooks and optional server runtime | Which capabilities exist and when they are exposed |
+| `Extension` / `@endpoint` | Starts services and exposes validated API routes | Application state, route schemas and authorization |
+| `ClientSurface` | Builds, previews, publishes and rolls back an editable web UI | Source, build command, routes and release policy |
+
+There is exactly **one primary, durable conversation**. Private specialist
+agents can perform bounded background work, but their sessions are not new
+user-facing conversations and they cannot edit the primary history directly.
+The server supervises workers and owns authentication and client transport;
+workers own inference and their own sessions; a browser client owns its local
+interface and device/media execution. This separation lets a client reconnect
+or refresh while the main conversation remains intact.
+
+Plugins may provide agent-facing tools without a server runtime, or both. A
+plugin's runtime state and its binding to an agent are separate: turning off its
+tools for the agent need not remove routes that a settings screen still uses.
+Specialists, durable task delivery and versioned public capabilities are
+available when a simple plugin is not enough. More detail is in the
+[framework guide](https://github.com/B4PT0R/the_framework/blob/main/docs/framework.md).
+
+## Try a working application
+
+Install [`uv`](https://docs.astral.sh/uv/) and Node.js/npm, then from this
+checkout run:
+
+```sh
+uv sync
+npm --prefix starter/ui ci
+npm --prefix starter/ui run build
+uv run playwright install chromium
+uv run python -m starter
+```
+
+Playwright Chromium also needs its system libraries; on Linux,
+`uv run playwright install --with-deps chromium` can install them if you have
+the required system permissions. The starter opens a local Chromium window with
+chat, settings, file attachments and an editable React interface. Its server
+listens on loopback and authenticates the browser. You can inspect the UI and
+settings without model credentials; generating replies, using hosted search or
+embeddings, and voice features require a usable account/capabilities through
+`codex-backend-sdk`. The [starter guide](https://github.com/B4PT0R/the_framework/blob/main/starter/README.md) covers sign-in,
+data storage and feature-by-feature behavior.
+
+To make an independent, editable copy, run `the-framework bootstrap` in the
+environment where you installed the package. From this checkout, prefix it
+with `uv run`:
+
+```sh
+uv run the-framework bootstrap --code-dir /path/to/my-agent-code --data-dir /path/to/my-agent-data
+```
+
+Both directories must be empty or absent, distinct and non-overlapping. The
+command copies the starter source and records the private data location; it
+does not install npm dependencies, build the UI or launch the app. From the new
+code directory, run `npm --prefix starter/ui ci`,
+`npm --prefix starter/ui run build`, then `python -m starter` in an environment
+with `b4pt0r-the-framework` installed. Change `starter/application.py` and
+`starter/instructions.md` first; `starter/ui/` contains the editable interface.
+Keep the data directory private: it holds conversation history, configuration,
+uploads, memory and browser profiles.
+
+## Build a small application yourself
+
+Save the following as `example.py`. It is a complete HTTP application; the
+repository also includes an [expanded version](https://github.com/B4PT0R/the_framework/blob/main/examples/minimal_agent_app.py)
+with `modict` request/response models and a health endpoint.
+
+```python
+from the_framework import AgentApplication, AgentSpec, Extension, SessionPolicy, endpoint
+from the_framework.server.api.endpoints import Principal
+
+
+class BearerSecurity:
+    async def authenticate(self, request):
+        if request.headers.get("authorization") != "Bearer example-secret":
+            return None
+        return Principal(id="example-client", scopes=frozenset({"counter:write"}))
+
+    async def authorize(self, principal, requirement, request):
+        return requirement is None or requirement.get("scope") in principal.scopes
+
+
+class Counter:
+    def __init__(self):
+        self.value = 0
+        self.running = False
+
+    async def start(self):
+        self.running = True
+
+    async def stop(self):
+        self.running = False
+
+    @endpoint(
+        "post", "/api/v1/counter/increment",
+        request={"type": "object", "properties": {"amount": {"type": "integer"}},
+                 "required": ["amount"], "additionalProperties": False},
+        response={"type": "object", "properties": {"value": {"type": "integer"}},
+                  "required": ["value"]},
+        authorization={"scope": "counter:write"},
+    )
+    def increment(self, amount: int):
+        """Increment the application counter."""
+        self.value += amount
+        return {"value": self.value}
+
+
+counter = Counter()
+application = AgentApplication(
+    name="Counter Agent",
+    version="0.1",
+    primary_agent=AgentSpec(
+        name="assistant",
+        description="The application's primary agent",
+        session=SessionPolicy.durable(),
+    ),
+    security=BearerSecurity(),
+    extensions=(Extension(name="counter", service=counter,
+                          endpoints=(counter.increment,)),),
+)
+app = application.build()
+```
+
+Start it with:
+
+```sh
+uv run uvicorn example:app --host 127.0.0.1 --port 8000
+```
+
+Then, in another terminal:
+
+```sh
+curl -sS -X POST http://127.0.0.1:8000/api/v1/counter/increment \
+  -H 'Authorization: Bearer example-secret' \
+  -H 'Content-Type: application/json' \
+  -d '{"amount": 2}'
+```
+
+The result is `{"value":2}`. The literal bearer secret is **only** for this
+loopback demonstration; use a real authentication policy for an application.
+The primary agent declaration alone does not create a chat API or start
+inference: the starter shows how to add its supervised worker and client
+transport. `@endpoint` validates request and response data and contributes an
+OpenAPI schema. `Extension` manages dependencies and service startup/shutdown;
+`AgentApplication.compile()` checks the full graph before runtime startup.
+
+For the next step, read [composition and runtime](https://github.com/B4PT0R/the_framework/blob/main/docs/framework.md) for
+plugins, private specialists, persistent resources, security, voice and client
+surfaces. The [starter source](https://github.com/B4PT0R/the_framework/tree/main/starter) shows these features in one application
+without requiring you to adopt its UI design.
+
+## Develop and package
+
+```sh
+uv sync --extra dev
+uv run pytest -q tests/application tests/agentic
+uv build
+```
+
+The build produces a wheel and source archive in `dist/`. The wheel contains
+the typed `the_framework` package, runtime prompts and the editable starter
+template; it does **not** bundle Node modules or a prebuilt browser UI. The
+test suite includes a wheel-only import/bootstrap check outside the checkout.
+For UI changes, also run `npm --prefix starter/ui test` and
+`npm --prefix starter/ui run build`.
+
+This repository is [MIT licensed](https://github.com/B4PT0R/the_framework/blob/main/LICENSE). See the [changelog](https://github.com/B4PT0R/the_framework/blob/main/CHANGELOG.md)
+for version notes. Publishing to PyPI is a separate release action; building
+locally does not publish anything.

b4pt0r_the_framework-0.1.0/docs/framework-api-simplification-audit.md

@@ -0,0 +1,37 @@
+# Framework API simplification
+
+## Decisions and evidence
+
+| Objective | Result | Regression coverage |
+| --- | --- | --- |
+| One agent declaration | `AgentSpec` owns configuration, instructions, plugins, session/queue policy and completion settings. `agent_trigger(spec, ...)` owns selection and result handling only. | `test_agent_spec.py`, `test_framework.py`, worker/fleet tests |
+| Internal wire representation | `WorkerProfile` remains a JSON execution payload, not a public facade export or a second source retained in AgentSpec. Older profile configuration fields are read at the worker boundary. | profile round trips, native coercion, real worker process tests |
+| Explicit construction | `AgentResources` replaces implicit option dictionaries and parallel build keywords. Explicit resources bypass the factory completely. | factory identity, defaults, invalid contracts, configuration persistence tests |
+| Concise plugin installation | Plugin classes with an explicit name normalize to PluginSpec; full declarations retain policies, dependencies and services. | shorthand/full-form discovery, duplicate identities, no construction during compilation |
+| Lifecycle simplicity | Existing Extension start/stop adapters suffice. Permanent restart callback composition happens at construction; absent restart remains absent. No new manager or lifecycle abstraction. | `test_runtime_composition.py`, service rollback and runtime shutdown tests |
+| Model endpoint contracts | Request/response modict classes work alongside explicit JSON Schema. Native validators/defaults are applied at the existing HTTP boundary; field metadata supplies OpenAPI. | `test_endpoint_models.py`, endpoint registry, minimal application tests |
+
+The actual product migrated its primary construction, simple plugin declarations,
+memory curator and visual specialists. The minimal standalone application uses
+model-based endpoint contracts. No application-specific policy was added to the
+core, and no Pydantic DTO or alternate dispatch path was introduced.
+
+## Deliberate limits
+
+Final verification: `pytest -q --tb=short tests/application tests/agentic` reports
+**900 passed**. This includes the isolated wheel and real worker subprocess
+tests. The product compiles 14 plugins and 10 agents. Ruff's F401/F811/F821/F822/
+F823/E9 checks and `git diff --check` pass for the changed core and endpoint tests.
+
+- OpenAPI projection describes JSON field types, required fields and extra-field
+  policy. It does not reverse-engineer Python validators or execute factories.
+  Unsupported/recursive hints require an explicit JSON Schema. Runtime model
+  validation remains authoritative for custom constraints.
+- A wire profile cannot serialize Python closures or application services.
+  Application-backed workers continue resolving the original namespaced spec.
+- This work verifies source, transports and packaging with automated tests.
+  It does not claim a production restart, real inference, voice or device run.
+- No server restart, publish or push was performed for this goal.
+
+The follow-ups already recorded in TODO.md remain separate from this API work:
+YAML declaration errors, grouping usage records, and older architecture wording.

b4pt0r_the_framework-0.1.0/docs/framework-clarification-audit.md

@@ -0,0 +1,51 @@
+# Framework clarification follow-up
+
+## Changes and verification boundaries
+
+- Usage payloads (`ResponseUsage`, `TokenDetails`) live in `agent/models/usage.py`.
+  The session store imports that owner, not the context builder. Public agent
+  exports remain; internal callers were migrated without compatibility aliases.
+  Recovery, coercion, session and context tests cover the unchanged behavior.
+- Invalid YAML raises a contextual `ValueError` naming the declaring callable
+  and YAML location, with the parser exception chained. Invalid metadata shapes
+  no longer disappear through falsey fallback. Plain descriptions and empty
+  docstrings remain supported. Both tool and endpoint construction are tested.
+- AGENTS.md now describes distributed capability ownership and authenticated
+  remote clients, rather than a local-desktop-only runtime. Evidence:
+  `server/clients/remote.py`, `the_harness/remote_composition.py`,
+  `docs/remote-client-protocol.md`, and `test_client_remote.py` (exclusive leases,
+  revocation, stale generations and remote ownership without local Chromium).
+- Memory instructions now distinguish temporary working capacity from completion
+  constraints, omit the obsolete entry-count cap and describe deferred embedding.
+  Evidence: `plugins/memory/store.py::_validate_capacity`,
+  `plugins/memory/curator.py::completion_constraint_error` and `complete_curation`,
+  plus memory tests for soft capacity, reduction beyond hard capacity, deferred
+  embeddings and completion repair. No runtime policy or personal data changed.
+
+## Schema comparison: deliberate non-extraction
+
+Tools and signature-derived endpoints already share `signature_parameters` and
+`annotation_schema`. The separate HTTP model projection reads modict field
+metadata, defaults and required/extra policy; it never executes default factories.
+The modict README field and configuration contracts were checked locally.
+
+The remaining visitors overlap on scalar/list/union syntax, but differ in real
+contracts: callable annotation inference is best-effort and accepts tuple/set
+shapes, whereas explicit HTTP model contracts reject unsupported hints, non-string
+mapping keys and recursive models rather than silently understating validation.
+Combining them now would add policy switches or callbacks to a small visitor.
+No new generic abstraction is introduced solely to deduplicate those branches.
+
+Comparison did uncover a nullable-enum defect in callable projection: adding null
+to `type` while preserving a non-null `enum` still excludes null. Union projection
+now uses `anyOf` for constrained branches. A JSON Schema behavior test verifies
+null and declared enum members are accepted, but arbitrary values are rejected.
+
+No SDK/modict patch, publication, server restart or deployment was needed.
+
+## Final verification
+
+`pytest -q --tb=short tests/application tests/agentic`: **914 passed**,
+including isolated-wheel imports and worker-process tests. Focused Ruff checks
+(F401/F811/F821/F822/F823/E9) and `git diff --check` pass. The nullable contracts
+are tested by accepted/rejected values rather than a prescribed JSON layout.