agentinputlab 0.1.0a1__py3-none-any.whl

workers/llmcompiler/export_prompts.py

@@ -0,0 +1,74 @@
+"""Export source-bound HotpotQA prompts without executing config-file code."""
+from __future__ import annotations
+
+import argparse
+import ast
+import json
+import subprocess
+from pathlib import Path
+
+from . import driver
+
+
+def literal_string(node, constants):
+    if isinstance(node, ast.Constant) and isinstance(node.value, str):
+        return node.value
+    if isinstance(node, ast.Name) and node.id in constants:
+        return constants[node.id]
+    if isinstance(node, ast.BinOp) and isinstance(node.op, ast.Add):
+        return literal_string(node.left, constants) + literal_string(node.right, constants)
+    if isinstance(node, ast.JoinedStr):
+        parts = []
+        for part in node.values:
+            if isinstance(part, ast.FormattedValue):
+                if part.conversion != -1 or part.format_spec is not None:
+                    raise ValueError("prompt formatting is outside the literal exporter")
+                part = part.value
+            parts.append(literal_string(part, constants))
+        return "".join(parts)
+    raise ValueError("prompt expression is not a literal string; code execution forbidden")
+
+
+def export(checkout, output, template="gpt"):
+    if template not in {"gpt", "llama"}:
+        raise ValueError("template must be gpt or llama")
+    driver.verify_checkout(checkout)
+    relative = f"configs/hotpotqa/{template}_prompts.py"
+    source = driver._read_bytes(checkout / relative, label="pinned prompt source")
+    tracked = subprocess.run(("git", "-C", str(checkout), "show", f"HEAD:{relative}"),
+        capture_output=True, check=True, timeout=30).stdout
+    if tracked != source:
+        raise ValueError("prompt file differs from its pinned Git blob")
+    constants = {}
+    for node in ast.parse((checkout / "src/llm_compiler/constants.py").read_text()).body:
+        if isinstance(node, ast.Assign) and len(node.targets) == 1:
+            constants[node.targets[0].id] = ast.literal_eval(node.value)
+    values = {node.targets[0].id: literal_string(node.value, constants)
+        for node in ast.parse(source).body if isinstance(node, ast.Assign) and len(node.targets) == 1}
+    prompts = {"planner_example_prompt": values["PLANNER_PROMPT"],
+        "planner_example_prompt_replan": values["PLANNER_PROMPT"],
+        "planner_stop": [constants["END_OF_PLAN"]], "joinner_prompt": values["OUTPUT_PROMPT"],
+        "joinner_prompt_final": values["OUTPUT_PROMPT"]}
+    bundle = {"schema_version": "agentinputlab.llmcompiler.prompts.v1",
+        "upstream_commit": driver.UPSTREAM_COMMIT, "prompts": prompts}
+    raw = json.dumps(bundle, indent=2, sort_keys=True, ensure_ascii=False).encode()
+    if len(raw) > 64 * 1024:
+        raise ValueError("exported prompt bundle exceeds64KiB")
+    with output.open("xb") as handle:
+        handle.write(raw)
+    return {"status": "ok", "source_relative_path": relative,
+        "source_sha256": driver._sha256_bytes(source), "prompt_hash": driver._canonical_hash(prompts),
+        "upstream_commit": driver.UPSTREAM_COMMIT, "config_code_executed": False}
+
+
+def main():
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--checkout", type=Path, required=True)
+    parser.add_argument("--output", type=Path, required=True)
+    parser.add_argument("--template", choices=("gpt", "llama"), default="gpt")
+    args = parser.parse_args()
+    print(json.dumps(export(args.checkout, args.output, args.template), sort_keys=True))
+
+
+if __name__ == "__main__":
+    main()

workers/llmcompiler/live.py

@@ -0,0 +1,174 @@
+"""Explicit controlled live model/tool callback transport for pinned LLMCompiler.
+
+Only a startup-bound authenticated numeric-loopback endpoint is reachable. No
+provider key, request-selected URL, import, shell command, or network tool exists
+inside this worker. Native upstream planning/scheduling/join/replan is retained.
+"""
+from __future__ import annotations
+
+import argparse
+import asyncio
+import importlib.metadata
+import json
+import os
+import re
+import sys
+import urllib.parse
+import urllib.request
+from collections.abc import Mapping
+from types import SimpleNamespace
+from uuid import uuid4
+
+from . import driver
+
+
+def runtime_attestation():
+    from pathlib import Path
+    manifest = driver._verify_static_manifests()
+    return {"schema": "agentinputlab.llmcompiler.live-attestation.v1",
+        "driver_sha256": driver._sha256_bytes(Path(driver.__file__).read_bytes()),
+        "live_driver_sha256": driver._sha256_bytes(Path(__file__).read_bytes()),
+        "compatibility_manifest_sha256": driver.COMPATIBILITY_MANIFEST_SHA256,
+        "required_versions": {name: importlib.metadata.version(name)
+            for name in manifest["legacy_dependencies"]["required_versions"]},
+        "source_files_verified": True, "required_versions_verified": True, "import_origins_verified": True}
+
+
+def load_prompts(path, request):
+    value, _ = driver._load_json(path, label="LLMCompiler live prompt bundle")
+    driver._expect_keys(value, {"schema_version", "upstream_commit", "prompts"}, label="prompt bundle")
+    prompts = value["prompts"]
+    keys = {"planner_example_prompt", "planner_example_prompt_replan", "planner_stop",
+            "joinner_prompt", "joinner_prompt_final"}
+    if (value["schema_version"] != "agentinputlab.llmcompiler.prompts.v1"
+            or value["upstream_commit"] != driver.UPSTREAM_COMMIT
+            or not isinstance(prompts, Mapping) or set(prompts) != keys
+            or driver._canonical_hash(prompts) != request.prompt_hash
+            or not all(isinstance(prompts[k], str) for k in keys - {"planner_stop"})
+            or not isinstance(prompts["planner_stop"], list)
+            or not all(isinstance(s, str) and s for s in prompts["planner_stop"])):
+        raise driver.WorkerFailure("DEPENDENCY_MISMATCH", "live prompt bundle identity differs")
+    return driver.ReplayBundle(prompts=dict(prompts), entries=())
+
+
+class Callback:
+    def __init__(self, url, key_env, request):
+        parsed = urllib.parse.urlparse(url)
+        if (parsed.scheme != "http" or parsed.hostname != "127.0.0.1" or parsed.port is None
+                or parsed.path != "/callback" or parsed.username or parsed.password
+                or parsed.query or parsed.fragment):
+            raise driver.WorkerFailure("CONFIGURATION_INVALID", "callback URL must be numeric IPv4 loopback")
+        if not re.fullmatch(r"[A-Z_][A-Z0-9_]*", key_env) or not os.environ.get(key_env):
+            raise driver.WorkerFailure("CONFIGURATION_INVALID", "callback credential unavailable")
+        self.url, self.key, self.request = url, os.environ[key_env], request
+
+    async def call(self, kind, payload):
+        value = {"request_id": self.request.request_id, "call_id": uuid4().hex,
+                 "kind": kind, "payload": payload}
+
+        def send():
+            request = urllib.request.Request(self.url, data=driver._canonical_json(value).encode(),
+                headers={"Authorization": "Bearer " + self.key, "Content-Type": "application/json"})
+            try:
+                with urllib.request.build_opener(urllib.request.ProxyHandler({})).open(
+                        request, timeout=self.request.controls.timeout_seconds) as response:
+                    raw = response.read(driver._MAX_MANIFEST_BYTES + 1)
+                if len(raw) > driver._MAX_MANIFEST_BYTES:
+                    raise ValueError("callback response byte limit")
+                result = json.loads(raw)
+                if not isinstance(result, dict) or result.get("ok") is not True:
+                    raise ValueError("callback failed")
+                return result["payload"]
+            except Exception:
+                raise driver.WorkerFailure("HOST_CALLBACK_FAILED", "bound host callback failed; no retry",
+                    consumed=True) from None
+
+        return await asyncio.to_thread(send)
+
+
+class LiveModel(driver._ReplayModel):
+    def __init__(self, callback):
+        super().__init__(())
+        self.callback = callback
+
+    async def complete(self, channel, prompt, stop):
+        index = len(self.consumed)
+        self.consumed.append(driver.ReplayEntry(channel, driver._sha256_text(prompt), "", 0, 0))
+        value = await self.callback.call("model", {"prompt": prompt, "channel": channel,
+            "stop": list(stop or ()), "seed": self.callback.request.seed})
+        if (not isinstance(value, dict) or set(value) != {"text", "input_tokens", "output_tokens", "finish_reason"}
+                or not isinstance(value["text"], str)):
+            raise driver.WorkerFailure("BACKEND_OUTPUT_INVALID", "invalid live model response", consumed=True)
+        entry = driver.ReplayEntry(channel, driver._sha256_text(prompt), value["text"],
+            driver._nonnegative_int(value["input_tokens"], label="input_tokens"),
+            driver._nonnegative_int(value["output_tokens"], label="output_tokens"))
+        self.consumed[index] = entry
+        if not entry.response.strip():
+            raise driver.WorkerFailure("BACKEND_OUTPUT_INVALID", "live model returned empty final text", consumed=True)
+        if channel == "planner":
+            self.planner_responses.append(entry.response)
+        return entry.response
+
+    async def apredict(self, prompt, *, callbacks=None, stop=None, **kwargs):
+        response = await self.complete("planner", prompt, stop)
+        # This is buffered completion delivery, never native streaming parity.
+        await self._notify(callbacks, response)
+        return response
+
+    async def agenerate_prompt(self, prompts, stop=None, callbacks=None, **kwargs):
+        if len(prompts) != 1:
+            raise driver.WorkerFailure("BACKEND_OUTPUT_INVALID", "one join prompt required")
+        value = prompts[0]
+        prompt = value.text if hasattr(value, "text") else value.to_string()
+        response = await self.complete("join", prompt, stop)
+        return SimpleNamespace(generations=[[SimpleNamespace(text=response)]])
+
+    def assert_exhausted(self):
+        # There is no frozen response count in an actual live execution.
+        pass
+
+
+class LiveTools:
+    def __init__(self, callback):
+        self.callback, self.calls = callback, 0
+
+    async def invoke(self, name, arguments):
+        self.calls += 1
+        value = await self.callback.call("tool", {"name": name, "arguments": list(arguments)})
+        if not isinstance(value, dict) or set(value) != {"output"}:
+            raise driver.WorkerFailure("TOOL_EXECUTION_FAILURE", "invalid bound tool response", consumed=True)
+        return value["output"]
+
+
+def main(argv=None):
+    parser = argparse.ArgumentParser(description=__doc__)
+    for key in ("checkout", "prompt-bundle", "callback-url", "callback-key-env"):
+        parser.add_argument("--" + key, required=True)
+    args = parser.parse_args(argv)
+    request_id = ""
+    try:
+        from pathlib import Path
+        driver.verify_checkout(Path(args.checkout))
+        raw = driver._read_request_line()
+        if isinstance(raw, Mapping):
+            request_id = raw.get("request_id", "")
+        request = driver.validate_request(raw)
+        bundle = load_prompts(Path(args.prompt_bundle), request)
+        callback = Callback(args.callback_url, args.callback_key_env, request)
+        upstream = driver.import_upstream(Path(args.checkout))
+        asyncio.run(callback.call("attest", runtime_attestation()))
+        response = asyncio.run(driver.execute_request(request, upstream, bundle, LiveTools(callback),
+            runtime_model=LiveModel(callback)))
+    except driver.WorkerFailure as exc:
+        response = driver._failure_response(exc, request_id=request_id)
+    except Exception as exc:
+        response = driver._failure_response(driver.WorkerFailure("WORKER_INTERNAL_FAILURE",
+            f"live worker failed closed: {type(exc).__name__}"), request_id=request_id)
+    sys.stdout.write(driver._canonical_json(response) + "\n")
+    sys.stdout.flush()
+    # Preserve typed errors and usage for the supervised host, not only stderr.
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

workers/llmcompiler/patch_manifest.json

@@ -0,0 +1,147 @@
+{
+  "schema_version": "agentinputlab.llmcompiler.patch-manifest.v1",
+  "upstream_commit": "a00c9d35507507da70e8c637eee64efc8c1857ae",
+  "patches": [
+    {
+      "id": "request_local_completed_dependency_lookup_v1",
+      "kind": "runtime_compatibility_patch",
+      "upstream_symbols": [
+        "src.llm_compiler.task_fetching_unit.TaskFetchingUnit",
+        "src.llm_compiler.llm_compiler.LLMCompiler._acall"
+      ],
+      "changes": [
+        "retain completed task observations and completion events for dependency lookup across native replan TFU instances",
+        "preserve global upstream task IDs and dependency substitution without rewriting model responses or plans",
+        "keep each TFU iteration and scheduling set round-local so completed tasks are neither executed nor appended to scratchpad twice",
+        "scope the completed dependency cache to a single full invocation; never share observations between requests"
+      ],
+      "algorithm_logic_changed": false
+    },
+    {
+      "id": "explicit_host_live_callbacks_v1",
+      "kind": "transport_compatibility_patch",
+      "upstream_symbols": [
+        "src.llm_compiler.planner.Planner.run_llm",
+        "src.llm_compiler.llm_compiler.LLMCompilerAgent.arun",
+        "src.tools.base.Tool"
+      ],
+      "changes": [
+        "add an explicitly selected authenticated numeric-loopback callback seam to caller-bound model and read-only tools",
+        "retain upstream planning, dependency substitution, scheduling, join and replan",
+        "bind callback requests to the root request identity and state execution budget",
+        "require worker source/version/dependency attestation before model or tool callbacks",
+        "bind explicit positional argument order for multi-parameter tool dispatch and task traces",
+        "record host-observed usage and genuine model/tool failures without automatic retries",
+        "declare streamed callbacks buffered after completion, without native-streaming latency or checkpoint parity claims"
+      ],
+      "algorithm_logic_changed": false
+    },
+    {
+      "id": "controlled_replay_model_type_gate_v1",
+      "kind": "transport_compatibility_patch",
+      "upstream_symbols": [
+        "src.llm_compiler.planner.BaseLLM",
+        "src.llm_compiler.llm_compiler.BaseLLM"
+      ],
+      "changes": [
+        "bind the upstream BaseLLM isinstance gates to the worker-local replay adapter",
+        "preserve Planner.run_llm and LLMCompilerAgent.arun without importing a request-selected backend",
+        "match every planner and join prompt by SHA-256 before releasing its frozen response"
+      ],
+      "algorithm_logic_changed": false
+    },
+    {
+      "id": "bounded_task_fetching_trace_v1",
+      "kind": "safety_and_observability_patch",
+      "upstream_symbols": [
+        "src.llm_compiler.task_fetching_unit.TaskFetchingUnit",
+        "src.llm_compiler.llm_compiler.TaskFetchingUnit"
+      ],
+      "changes": [
+        "subclass the official TaskFetchingUnit while retaining its dependency scheduling and argument substitution",
+        "bound concurrent task bodies with the request concurrency control",
+        "reject excess, duplicate, malformed, or non-allowlisted tasks before their execution",
+        "record planned, ready, running, completed, and failed scheduler states",
+        "unblock and abort the scheduler after a tool failure so the upstream busy loop cannot deadlock"
+      ],
+      "algorithm_logic_changed": false
+    },
+    {
+      "id": "fail_closed_join_guard_v1",
+      "kind": "security_patch",
+      "upstream_symbols": [
+        "src.llm_compiler.llm_compiler.LLMCompiler.join"
+      ],
+      "changes": [
+        "refuse the join model call after any tool execution failure",
+        "never turn a missing or denied tool observation into a synthetic final answer"
+      ],
+      "algorithm_logic_changed": false
+    },
+    {
+      "id": "replan_control_translation_v1",
+      "kind": "configuration_compatibility_patch",
+      "upstream_symbols": [
+        "src.llm_compiler.llm_compiler.LLMCompiler._acall"
+      ],
+      "changes": [
+        "translate AgentInputLab max_replans=N to the upstream loop bound N+1",
+        "retain one initial planning iteration when max_replans is zero"
+      ],
+      "algorithm_logic_changed": false
+    },
+    {
+      "id": "jsonl_stdout_isolation_v1",
+      "kind": "transport_safety_patch",
+      "upstream_symbols": [
+        "src.utils.logger_utils.enable_logging",
+        "src.utils.logger_utils.log"
+      ],
+      "changes": [
+        "disable official verbose logging",
+        "discard incidental stdout during imports and execution so stdout remains exactly one JSON response line"
+      ],
+      "algorithm_logic_changed": false
+    },
+    {
+      "id": "whole_run_timeout_and_async_cleanup_v1",
+      "kind": "runtime_safety_patch",
+      "upstream_symbols": [
+        "src.llm_compiler.planner.Planner.aplan",
+        "src.llm_compiler.llm_compiler.LLMCompiler._acall",
+        "src.llm_compiler.task_fetching_unit.TaskFetchingUnit._run_task"
+      ],
+      "changes": [
+        "apply controls.timeout_seconds to the complete worker execution rather than an individual model call",
+        "always signal the streaming queue when its planner exits or fails",
+        "cancel and await planner and tool tasks on failure, cancellation, timeout, and successful shutdown",
+        "settle the upstream fire-and-forget planner task before permitting join"
+      ],
+      "algorithm_logic_changed": false
+    },
+    {
+      "id": "pre_schedule_dependency_validation_v1",
+      "kind": "runtime_safety_patch",
+      "upstream_symbols": [
+        "src.llm_compiler.task_fetching_unit.TaskFetchingUnit.set_tasks"
+      ],
+      "changes": [
+        "validate each incoming task batch atomically before passing it to the official scheduler",
+        "reject unknown, duplicate, self-referential, malformed, cyclic, or excess tasks before execution"
+      ],
+      "algorithm_logic_changed": false
+    },
+    {
+      "id": "complete_legacy_dependency_attestation_v1",
+      "kind": "compatibility_verification_patch",
+      "upstream_symbols": [
+        "requirements.txt"
+      ],
+      "changes": [
+        "verify every distribution version listed in compatibility_manifest.json",
+        "verify every imported top-level package originates inside its pinned distribution"
+      ],
+      "algorithm_logic_changed": false
+    }
+  ]
+}

workers/mce/README.md

@@ -0,0 +1,198 @@
+# MCE isolated worker
+
+This sidecar integrates
+`metaevo-ai/meta-context-engineering@c4b7a7c2ce3ffc4bf4a74c52d2dd8a9a8fb14c30`
+without moving generated Python or context contents into the AgentInputLab
+host.
+
+## Controlled semantic-patch path
+
+`MCEOfficialRuntime` calls the upstream `mce.main.run_iteration` function for
+baseline iteration zero and every configured evolution iteration. The function
+must originate from the pinned `mce/main.py` SHA-256; preloaded `sys.modules`
+substitutes are discarded.
+
+This is deliberately **not** an `official_native` adapter. A hash-bound semantic
+patch replaces exactly four globals already imported by `mce.main`:
+
+- `run_meta_agent` and `run_base_agent` delegate to an isolated manager's
+  remote `run_agent`;
+- `load_interfaces` performs remote static validation and returns an opaque
+  receipt, never a locally imported callable;
+- `batch_evaluate` delegates to a separate trusted oracle supervisor.
+
+The pinned `run_iteration` orchestration, baseline/sub-iteration loop, batching,
+aggregation, and returned validation metric remain upstream code. The patch
+manifest and digest are bound through worker identity, request, runtime
+binding, artifact bundle, and response attestation.
+
+The host freezes:
+
+- train and validation example identities and input hashes;
+- the interface and initial-context hashes;
+- target, meta, and base model fingerprints;
+- seed, iteration, batch, call, wall, and artifact limits;
+- source commit and source-file hashes;
+- sandbox image, policy, test report, and resource limits.
+
+## Security boundary
+
+The driver must run inside the container or microVM named by the
+`MCESandboxAttestation`. The source mount is read-only and the workspace is
+new for every request. Generated code may execute only inside that worker.
+The validation oracle is mounted only in a trusted, out-of-process supervisor;
+the generated workspace cannot see it, and only the supervisor returns metric
+values. Provider calls pass through the same trusted boundary, which reserves
+model/tool budget before transport. A production runtime must supply the exact
+isolated-manager fingerprint and implement `bind_run`, `run_agent`,
+`validate_interfaces_static`, `batch_evaluate`, and `usage_receipt`; any
+missing or altered field fails closed. This is an operator-attested deployment
+boundary, not a claim that a Python object can cryptographically prove its own
+container or microVM.
+Only path, media type, byte size, SHA-256, iteration score, and normalized
+usage leave the worker. Symlinks, paths outside the workspace, test-split
+fields, and inline file contents are rejected.
+
+The public upstream currently raises `NotImplementedError` for its own E2B
+flag, so AgentInputLab does not describe that flag as a working sandbox.
+Isolation is supplied by the external worker deployment.
+
+Upstream does not expose complete model-call/token accounting. The isolated
+manager therefore binds target/meta/base model identities to a trusted
+pre-call supervisor and must return an exact usage receipt. Missing or
+different accounting fails closed. The runtime seeds Python once per run.
+At the three stochastic patched seams it assigns deterministic logical seeds as
+`base_seed + logical_call_index`, in upstream invocation order and before each
+await. A batch evaluator may fan out into multiple provider calls; the attested
+manager contract therefore requires each actual provider call to derive a
+non-negative 63-bit seed from SHA-256 over the canonical, versioned
+`{logical_seed, stable_subcall_index}` identity in stable sample/call order.
+This avoids the cross-call collisions caused by simple integer addition. The
+manager passes that seed through `before_seeded_model_call`, which verifies the
+derivation before reserving the provider call. These versioned seed modes are bound into the
+semantic-patch manifest, manager fingerprint, run binding, sandbox attestation,
+and response attestation. This remains an operator-attested boundary rather
+than cryptographic proof of a remote provider's sampling implementation. The
+configured wall deadline applies to the complete run.
+
+## Status boundary
+
+The checked path is an `external_only`, controlled thin-wrapper L2 integration.
+It is not an official E2B path or a paper-result reproduction: model
+credentials/local weights, a production isolated-manager deployment, a
+task-specific upstream environment, and generated artifacts remain operator
+supplied. The fixture runtime is rejected unless explicitly enabled.
+
+An operator constructs `MCEWorkerDriver` with the trusted runtime, artifact
+store, and sandbox attestation, then exposes it with
+`workers.mce.serve_jsonl(driver, input_stream, output_stream)`. The module CLI
+intentionally refuses to invent those trust-boundary dependencies.
+
+## Text-artifact fitting API
+
+The separate text-only profile produces Markdown context instead of executable
+interfaces. Install `agentinputlab[mce-text]` and mount the pinned upstream
+checkout. In a dedicated child process, set `PYTHON_DOTENV_DISABLED=1`, give the
+unused upstream client a non-secret dummy `OPENAI_API_KEY`, and set its
+`OPENAI_API_BASE=http://127.0.0.1:1/v1`. Actual inference uses the explicitly
+supplied backend; configure its credentials under a different environment key.
+
+```python
+from agentinputlab.recipes import (
+    MCETextFitControls, MCETextOfflineRecipe, MCETextArtifactCommonSupport,
+)
+
+# train and validation are disjoint sequences of MCEExample objects, with
+# input={"question": ..., "context": ...}, a text expected_output, and the
+# corresponding split. backend is a real, metered LLMBackend.
+artifact = MCETextOfflineRecipe(MCETextFitControls(
+    iterations=1, train_batch_size=2, per_call_output_tokens=512,
+    max_model_calls=32, max_output_tokens=16384, seed=17,
+)).fit(
+    checkout="/path/to/pinned/meta-context-engineering",
+    output_root="/path/to/new/fit-directory",
+    train=train, validation=validation, backend=backend,
+)
+method = MCETextArtifactCommonSupport(artifact)
+```
+
+This API runs pinned `run_iteration` for the baseline and evolution iterations.
+Validation references remain scorer-only; first-best validation selects the
+artifact. Baseline selection yields an explicit NO_OP. Fit costs and seed
+`base_seed + logical_call_index` are recorded separately from downstream use.
+Record provider requests before transport and enforce a child-process/provider
+deadline: the API's wall check is cooperative. Claude-agent and embedding SDK
+imports use sentinels that raise if invoked; their execution and the full
+generated-code sandbox are separate profiles, not covered by this text fit.
+
+## Frozen executable-artifact evaluation
+
+`recipe.mce.final_artifact_eval` uses `MCEFinalArtifactEvaluator`, not the
+text-only profile. Keep the `MCESplitAudit` computed from the original fitting
+and validation examples together with the returned `MCEContextArtifact`:
+
+```python
+from agentinputlab.recipes import (
+    MCEFinalArtifactEvaluator, MCEFinalControls, MCEFinalExample,
+    validate_mce_split_isolation,
+)
+
+# artifact is returned by MCEOfflineRecipe.fit; client is the same isolated
+# sidecar with its original persistent artifact store and model identities.
+fit_audit = validate_mce_split_isolation(train_examples, validation_examples)
+evaluator = MCEFinalArtifactEvaluator(
+    artifact=artifact, split_audit=fit_audit,
+    interface_signature=interface_signature, client=client,
+    controls=MCEFinalControls(
+        max_model_calls=8, max_tool_calls=8,
+        max_output_tokens=4096, max_output_tokens_per_call=512,
+    ),
+)
+result = evaluator.evaluate(
+    (MCEFinalExample("heldout-id", {"question": "..."}, expected_output="..."),),
+    context=context,
+)
+```
+
+These budgets apply to the **whole evaluate call**. Use one example per call
+when each benchmark position has its own 4096-token/8-call budget. Increasing
+the collection size does not silently multiply a budget. Fitting costs remain
+separate. Model/source/interface/environment/storage identities and the
+original fit split audit are checked before dispatch. Test IDs and input
+hashes must be disjoint from both fitting and validation.
+
+The sidecar materializes the frozen regular-file closure into a fresh generated
+workspace. Native task loading and the existing isolated-evaluation seam run
+without meta/base-agent evolution; generated interfaces are never imported by
+the sidecar or caller host. The manager must provide
+`final_evaluation_fingerprint()` equal to
+`workers.mce.driver.final_evaluation_manager_contract()`. Its actual provider
+transport must pass the requested cap to `before_seeded_model_call`, retain the
+returned reservation ID, and pass that ID to `after_model_call`. Concurrent
+reservations cannot exceed the aggregate token/call budget. Use
+`failed_model_call(reservation_id=...)` for unknown failed-response usage;
+that reservation is quarantined, not reported as zero actual token usage.
+This is an operator-attested boundary, not proof that a remote provider obeys
+its requested generation cap. Measured provider overruns are retained and
+rejected.
+
+Configure a persistent, private `oracle_root` on `MCEWorkerDriver`. Each final
+request gets a create-only `mce-final-<request_id>` evidence directory there,
+outside the generated workspace, containing the claim, oracle, raw native
+evaluation and terminal/cost record. A repeated identical request is rejected
+before another model call; inspect the existing evidence instead of retrying.
+The host receives per-position scored/failed rows, the unchanged native
+summary, and a separately labeled all-position primary-metric mean that keeps
+failed positions in its denominator. Neither fitting nor text-artifact smoke
+tests certify this full generated-code runtime; production acceptance also
+requires an available isolated manager and real model/task execution.
+
+## Checks
+
+```bash
+PYTHONPATH=src:. pytest -q tests/workers/test_mce_worker_driver.py
+PYTHONPATH=src:. pytest -q tests/unit/test_remaining_recipes.py -k mce
+AGENTINPUTLAB_MCE_PINNED_SOURCE=/path/to/pinned/checkout \
+  PYTHONPATH=src:. pytest -q \
+  tests/workers/test_mce_worker_driver.py::MCEOfficialRuntimeTests::test_real_pinned_run_iteration_with_semantic_patch
+```

workers/mce/__init__.py

@@ -0,0 +1,29 @@
+"""Pinned external worker support for Meta Context Engineering."""
+
+from .driver import (
+    PROVIDER_SUBCALL_SEED_MODE,
+    SEED_MODE,
+    MCEEvolutionIteration,
+    MCEEvolutionRun,
+    MCEOfficialRuntime,
+    MCEWorkerDriver,
+    PersistentArtifactStore,
+    TrustedEvaluationSupervisor,
+    TrustedProviderSupervisor,
+    derive_provider_subcall_seed,
+    serve_jsonl,
+)
+
+__all__ = [
+    "PROVIDER_SUBCALL_SEED_MODE",
+    "SEED_MODE",
+    "MCEEvolutionIteration",
+    "MCEEvolutionRun",
+    "MCEOfficialRuntime",
+    "MCEWorkerDriver",
+    "PersistentArtifactStore",
+    "TrustedEvaluationSupervisor",
+    "TrustedProviderSupervisor",
+    "derive_provider_subcall_seed",
+    "serve_jsonl",
+]