DeepSeek Harness
Replaceable providers, canonical tool values, permission boundaries, and declared concurrency provide an integration seam. Its fresh Node program execution must keep fresh semantics when adapted.
Pinned architecture · Node executiondiff --git a/.gitattributes b/.gitattributes new file mode 100644 index 0000000000..c6a7ef62cf --- /dev/null +++ b/.gitattributes @@ -0,0 +1,2 @@ +# Keep captured stderr verbatim, including Zig's final blank summary line. +docs/agent-cast/evidence/**/*.stderr whitespace=-blank-at-eof diff --git a/.github/workflows/agent-cast.yml b/.github/workflows/agent-cast.yml new file mode 100644 index 0000000000..e1c3e11546 --- /dev/null +++ b/.github/workflows/agent-cast.yml @@ -0,0 +1,53 @@ +name: Agent-cast Foundation + +on: + pull_request: + paths: + - 'experiments/agent_cast/**' + - 'docs/agent-cast/**' + - 'scripts/agent_cast_ledger.py' + - 'scripts/qualify_agent_cast.py' + - 'scripts/tests/test_agent_cast_*.py' + - '.github/workflows/agent-cast.yml' + - '.github/actions/setup-zig/**' + workflow_dispatch: + +permissions: + contents: read + +concurrency: + group: agent-cast-${{ github.workflow }}-${{ github.ref }} + cancel-in-progress: true + +jobs: + qualify: + name: Agent-cast (${{ matrix.runner }}) + runs-on: ${{ matrix.runner }} + timeout-minutes: 15 + strategy: + fail-fast: false + matrix: + runner: [ubuntu-24.04, macos-15] + env: + PYTHONDONTWRITEBYTECODE: '1' + steps: + - uses: actions/checkout@v4 + - uses: ./.github/actions/setup-zig + with: + version: '0.16.0' + cache-key: agent-cast-foundation + - name: Validate ledger and exercise its failure cases + run: | + python3 scripts/agent_cast_ledger.py validate --json + python3 -m unittest scripts.tests.test_agent_cast_ledger -v + python3 -m unittest scripts.tests.test_agent_cast_qualification -v + - name: Build and drive the prototype + run: python3 scripts/qualify_agent_cast.py --output "$RUNNER_TEMP/agent-cast-receipts" + - name: Retain qualification evidence + if: always() + uses: actions/upload-artifact@v4 + with: + name: agent-cast-${{ matrix.runner }}-${{ github.sha }} + path: ${{ runner.temp }}/agent-cast-receipts/ + if-no-files-found: warn + retention-days: 14 diff --git a/docs/agent-cast-architecture.html b/docs/agent-cast-architecture.html new file mode 100644 index 0000000000..d8b7dd9f2c --- /dev/null +++ b/docs/agent-cast-architecture.html @@ -0,0 +1,504 @@ + + +
+ + + + +Compile declared tool calls into guarded execution plans. Preserve each call's authority and observable behavior. Let an actor runtime own the workers, workspaces, connections, and recovery.
+ +An optimizer batches, schedules, and reuses certified observations. Each original call retains its admission, budget, result, and receipt. The actor runtime executes the chosen plan.
A cost model chooses among permitted execution strategies. Use the embedded path for tiny native calls and a broker for reusable workers or clients. Retain Erlang-style ownership and existing isolation backends.
Trusted registrations supply dependencies, resource access, and observable contracts.
Batch requests and reuse eligible immutable observations while retaining logical calls.
Actors retain workers and clients under explicit leases, epochs, and reset rules.
Track what started, what committed, and what remains unknown.
This is a design proposal, not an implemented compiler or runtime. The local measurement below characterizes a small native transport experiment. The isolated eval target is a working assumption; native macOS execution remains a distinct trusted mode.
+A bounded logical plan describes the requested calls. The host admits each resolved action. The optimizer changes only eligible physical execution; the actor runtime owns resources and recovery.
Transforms eligible admitted logical calls into guarded physical work while preserving the declared observable contract.
Each mutable resource has one owner. The owner serializes state changes and can delegate concurrent I/O.
Arbitrary tool code runs in a worker or sandbox. A logical actor in the broker is not a memory isolation boundary.
Language adapters use the operation contract. Backends report their actual containment and lifecycle capabilities.
Compile declared tool execution plans into guarded physical work. Optimize the operation graph; existing language runtimes continue to execute Python, JavaScript, and shell code.
The intermediate representation (Tool IR) preserves original call IDs, arguments, dependencies, budgets, and result contracts. Trusted registrations supply effect summaries and executor equivalence rules.
The optimizer can share certified immutable computation, group transport, and schedule independent work. It must retain required errors, audit events, effects, and publication order.
The runtime retains workers, clients, and workspaces. It owns admission queues, lifetimes, cancellation, output credits, generation checks, and effect receipts.
Pooling reuses setup. Each required application request still executes. A repeated HTTP GET or SQL query does not become a pure expression because its client is persistent.
All eight calls are separately admitted against snapshot S0. A valid completed value satisfies r2; r1 and r3 share one certified read. Six fresh reads can use a bounded group. No logical call disappears.
r1 = snapshot.read(S0, A) +r2 = snapshot.read(S0, B) +r3 = snapshot.read(S0, A) +r4 = snapshot.read(S0, C) +r5 = snapshot.read(S0, D) +r6 = snapshot.read(S0, E) +r7 = snapshot.read(S0, F) +r8 = snapshot.read(S0, G)
cache_value(B) → r2 +read(A) → r1, r3 +read(C..G) → r4..r8 + +6 fresh reads +8 logical admissions and receipts +1 bounded group if the cost model selects it
Same immutable input, implementation, result contract, and authority partition. Preserve per-call audit, budgets, error behavior, and cancellation; a required physical audit event may prohibit coalescing.
This is an explanatory simulation, not an implemented optimizer or measured speedup. The fixture assumes compatible contracts, permitted concurrency, and a valid cached value. Grouping and backend choice remain cost-based.
| Effect / observation | Permitted strategy | Boundary |
|---|---|---|
Pure(inputs) | Memoize certified successful values; share equivalent computation | Complete immutable dependencies and no required per-execution effect |
ImmutableRead(snapshot) | Completed-value reuse, then qualified inflight coalescing and batching | Same input identity, visibility, output contract, and compatible caller state |
MutableRead(resource) | Execute each observation; retain eligible clients and buffers | No general output deduplication; respect ordering and freshness |
Mutate(workspace) | Keep each action, exact admission, ordering, and effect evidence | No automatic deletion, merging, or speculative execution of writes |
ExternalEffect(service) | Reuse a permitted client while performing required requests | GET, SELECT, or idempotence alone does not prove interchangeable results |
OpaqueExec(environment) | Preserve the admitted executor and conservative effect barriers | No inferred shell lowering or result cache; unknown dependencies stay unknown |
type LogicalCall = {
+ logical_id: string;
+ tool: string;
+ implementation_id: string;
+ canonical_arguments: unknown;
+ argument_bindings: Binding[];
+ dependencies: string[];
+ effects: TrustedEffectSummary;
+ result_contract: string;
+ deadline: Deadline;
+ output_budget: number;
+};
+
+type AdmittedCall = {
+ call: LogicalCall;
+ exact_authority: string;
+ allowed_executor_contract: string;
+ generations: GenerationSet;
+};
+
+type PhysicalWork = {
+ work_id: string;
+ admitted_consumers: string[];
+ strategy: "native" | "batch" | "memoized" | "worker";
+ guards: RuntimeGuard[];
+};
+
+type LogicalReceipt = {
+ logical_id: string;
+ outcome: Outcome;
+ effect: EffectEvidence;
+ provenance: "executed" | "memoized" | "coalesced";
+ physical_work_id?: string;
+};Proposed structural sketches. Supporting types are placeholders for bounded typed contracts. An agent-cast operation ID remains a logical identity; physical work IDs expose actual sharing. Fixture replay has separate provenance and cannot claim current execution. Budgets count logical calls even when physical work is reused.
| Pass | Legal transformation | Guard / stop condition |
|---|---|---|
| Completed-value reuse | Return a certified immutable value through the existing renderer | Current authority, input identity, contract, and implementation; a failed guard requires rejection or fresh preparation/admission; cache successful values only |
| Inflight coalescing | Share one physical read among compatible admitted consumers | Independent subscriber deadlines, cancellation, credits, audit, failure provenance, and retry eligibility; never cache shared execution failures as semantic results |
| Transport batching | Send compatible calls together without removing their identities | Preserve per-call errors, limits, ordering, and failure policy; do not wait indefinitely to fill a batch |
| Dependency scheduling | Execute already independent nodes within resource budgets | Keep control dependencies, conflicts, and deterministic write order |
| Executor selection | Choose a certified native or worker implementation | Stay inside the admitted executor contract; a changed binding requires host admission |
| Cost-based strategy | Select direct, cached, grouped, or persistent execution where permitted | Include planning, hashing, guards, queueing, projection, and persistence; decline unprofitable passes |
Compile fixed plans and currently ready graph segments. Dynamic arguments require preparation and admission after their inputs arrive. Arbitrary Python or JavaScript orchestration runs in its admitted runtime; the pre-admission planner does not execute or statically understand arbitrary code. MCP tool annotations also require a trusted source; annotations alone do not establish purity.
+Admission, completion, cancellation, and committed effects are separate facts. An operation can be cancelled after it has changed external state.
The host binds arguments, workspace, environment, and authority to the operation identity before invoking the broker.
{
+ "operation_id": "op_42",
+ "actor_epoch": 7,
+ "state": "settled",
+ "outcome": "succeeded",
+ "effect": "committed",
+ "durability": "durable",
+ "evidence": "service_confirmation"
+}Persist the known result before publication. A reconnect retrieves this operation's receipt without repeating its mutation.
The walkthrough is an explanation. It executes no tools. The receipt always shows the scenario's terminal state, independently of the selected event.
Use tracked calls for effects, notifications for events, and monitors for lifetime changes. An unacknowledged cast is not a durable mutation API.
Bind identity to the principal, tool implementation, exact arguments, and task/workspace lease. Reconnect queries that operation. Reject reused IDs with different bindings; retries do not automatically authorize repeating an effect.
Length-framed JSON-RPC control travels over a persistent local Unix socket. Negotiate a maximum frame size and reject oversized frames before allocating. Separate output transport uses byte credits, sequence numbers, quotas, and artifact handles.
Queue time consumes the execution budget. Reconnect cannot extend the stored deadline. Cancellation acknowledgement means observed; a terminal receipt describes effects.
Persist recovery-relevant intent before dispatch. Cheap reads can use ephemeral receipts; syncing every read could dominate its execution time.
A service may commit before a worker loses its reply. Reconcile through an idempotency key or service evidence. Infrastructure restart alone cannot prove exactly-once effects.
type Invocation = {
+ operation_id: string;
+ actor: { runtime_id: string; actor_id: string; epoch: number };
+ task_lease: string;
+ action_lease: string;
+ tool: string;
+ tool_version: string;
+ arguments: unknown;
+ remaining_budget_ms: number;
+ output_limit_bytes: number;
+};Schema sketch, not an implemented API. Enroll the harness through an authenticated control channel. Keep authority issuance outside tool workers; keep privileged descriptors and credentials outside arbitrary agent code. Recheck policy, credential, workspace, and implementation generations before start. Revocation stops future grants; an already released operation may still perform an effect.
Reuse JSON-RPC and MCP conventions at the external boundary. MCP permits custom bidirectional transports; agent-cast would add a documented execution lifecycle profile.
+Erlang contributes ownership, messages, monitors, and supervision. Restart policy describes resource recovery; retry policy describes whether work may be performed again.
A control actor can reconstruct state. A failed tool operation can require reconciliation even after its worker has been replaced.
Logical actors share a native process. Their ownership rules do not create BEAM-style memory isolation; a native fault can still terminate the broker.
Stop admission, request cancellation, and allow bounded cleanup.
Terminate the owning process or containment domain after grace expires.
Invalidate old actor epochs and leases before replacement state is published.
Apply a bounded restart budget and backoff. Repeated failure quarantines the resource.
A Zig implementation would not inherit BEAM's preemption, garbage collection, or process isolation. Choosing Zig supports integration with fx; this research does not establish BEAM as a performance bottleneck. Erlang process efficiency.
+Persistent resources avoid setup work. Cached observations avoid repeated computation. Both require current authority and an explicit consistency boundary.
An immutable snapshot gives a stable input identity. Cache file bytes, directory listings, or search results against that identity.
snapshot digest + tool version + exact arguments + optionsKeep a permitted worker or client alive. Its state remains explicitly owned.
Issue a new receipt after current admission and input validation.
Recover the existing operation without repeating its effect.
Supply saved data without claiming the effect occurred now.
| Resource | Allowed reuse | Invalidation / boundary |
|---|---|---|
| Images, schemas, binaries | Immutable content and implementation metadata | Digest, platform, implementation, or configuration change |
| Snapshot files / search | Results against immutable input identities | Snapshot, exact arguments, tool version, ignore rules, visibility, or options |
| Live filesystem | Existing kernel caches; reopen through existing semantics | Watchers are hints. Metadata equality cannot prove unchanged bytes. |
| HTTP | Persistent clients; response caching under HTTP semantics | Endpoint, principal, credentials, TLS, proxy, policy; freshness and validators |
| DNS | Established resolver and client behavior | Lifetime, resolver configuration, and network context |
| Database | Connections under driver/pooler reset contracts | Transaction, session, role, tenant, credential, and configuration state |
| Shell output | No general result cache | Only declared pure operations with known immutable dependencies qualify |
| Interpreter state | Within the declared task/session | Fresh-call semantics, worker epoch, task ownership, and reset qualification |
Networking reuse requires a protocol-aware owner. A new shell-launched client cannot transparently borrow another process's HTTP connection. A CONNECT tunnel cannot pool arbitrary application sessions. Reuse existing HTTP clients and database pooling contracts.
+The Tool IR keeps data and control dependencies. The optimizer groups eligible ready work; unresolved actions and effect barriers remain explicit.
Transport batching preserves individual tool requests and results. Programmatic tool calling lets the model express loops, transformations, and dependencies in code.
Programmatic calling can reduce inference round trips and intermediate context. It changes the model's affordances, so evaluate quality separately from execution latency. Established code-execution pattern.
Preserve the harness's fresh interpreter promise. Preloading cannot silently retain a previous call's globals, descriptors, or threads.
Retain imports and state within one task. Worker loss changes the epoch and reports state loss to the caller.
Create fresh workers from a tested, uncredentialed template. Fork safety and cloned state require qualification.
Whole-workspace exclusion is the initial policy. Reject conflicting batch nodes without explicit dependencies so lock acquisition cannot choose a different write order. Command exit alone does not establish quiescence; cache eligibility returns only against a newly established immutable revision. Fine-grained path locking must account for aliases, symlinks, hard links, mounts, and directory mutations. External editors bypass broker locks, so live host workspaces remain ineligible for immutable-result caching.
+Use the task or evaluation attempt as the containment boundary. Share prepared infrastructure while giving mutable task state a fresh owner.
Immutable images, executable metadata, artifact content, and warm capacity.
Writable workspace, worker state, shell state, task operation IDs, and scoped credentials.
Protocol-aware HTTP or database owners. Cross-task reuse requires permitted identity and a reset contract.
Start with one Linux backend. OCI images and OpenSandbox provide packaging and lifecycle interfaces; Docker is a practical comparison baseline.
Qualify portable VM options for macOS clients. A Linux guest cannot reproduce native macOS builds or host facilities with identical semantics.
Native same-UID workers are a trusted execution mode. Socket permissions and descriptor hygiene alone do not establish containment from hostile code.
Reconstruct declared task state and run actual tools. Warm images and permitted pooled clients may remain, but previous trial mutations and cached stateful observations cannot carry over. Measure performance and independently grade terminal effects.
ThinkingBox provides a relevant evaluation pattern: fresh backend state per attempt, repeated trials, terminal-state grading, and checks for extra effects. A deterministic environment does not make model outputs deterministic.
+The logical plan builder can describe calls before admission. Native optimization and portable execution stay after existing exact-action admission and before result publication. Preserve fx's ownership-bearing contracts.
The Node SDK invokes a registered tool through execute(input, { signal }). A client can retain a broker connection and translate the signal into cancellation.
Use immutable snapshot reads first. A deterministic provider fixture should generate an actual tool call through libfx, receive the broker result, and complete the turn.
Compare optimizer disabled versus enabled with identical descriptors, calls, and results. Keep per-logical receipts outside model-visible content initially; use the existing renderer for reused values.
const snapshotTool = {
+ name: "agent_cast_read_many",
+ description: "Read the task's immutable snapshot.",
+ inputSchema: readManySchema,
+ execute(input, { signal }) {
+ return runtime.readMany(snapshotLease, input.paths, {
+ signal,
+ });
+ },
+};This sketch assumes a proposed client, schema, and snapshot lease. It is not a shipped API or a runnable example.
| Current contract | Integration consequence | Source |
|---|---|---|
| Ordinary host-tool authority | The JavaScript host owns effects. This seam does not automatically inherit native CLI permission admission. | sdk/README.md |
| SDK cancellation | The SDK stops waiting and ignores late results. The adapter must drain underlying work, retain receipts, and close resources. | sdk/fx-sdk.js |
| Callback identity | The callback currently exposes a signal, not stable operation/session identity for durable checkpoint recovery. | executeHostTool |
| Prepared file mutation | An opaque process-local commit token cannot be serialized through generic JSON RPC. | PreparedFileMutation |
| Native terminals | Terminals belong to the current fx process. A surviving daemon changes ownership and cleanup behavior. | terminal/client.zig |
| Managed command completion | Preserve stop versus waiter-detach decisions, delivery cursors, and process-exit plus output-drain barriers. | managed_execution_contract.zig |
| Admitted command environment | The executing environment must match the admitted command, cwd, shell profile, and captured/TTY mode. | command_admission.zig |
Source review: fx commit c1db919112c5c83fdcc0be508f8d34d189d149af. Relative source links work while the explainer remains in this checkout's docs/ directory.
Attribute latency before optimizing it. Include plan construction, canonicalization, cache validation, guards, and result fan-out alongside launches, imports, IPC, service setup, useful work, and durable publication.
Median cost in microseconds per read. Every operation opens, reads, checks EOF, and closes the fixture. Batch cost is total batch time divided by eight.
Logarithmic axis starts at 1 µs. Numeric values are the measured medians.
| Path | p50 µs | p95 µs | p99 µs |
|---|---|---|---|
| Direct native | 9 | 12 | 13 |
| Warm native RPC | 16 | 20 | 22 |
| RPC batch, amortized | 10.75 | 12.125 | 12.75 |
| Fresh native process | 1,128 | 1,315 | 1,436 |
Change the assumed fraction of addressable tool work and its speedup. Other work remains unchanged.
20% of time accelerated by 4× leaves 85% of the original runtime.
speedup = 1 / ((1 − f) + f / k)
A scenario calculation, not an agent-cast performance prediction. Throughput also depends on resource budgets and contention.
Recorded on 6 October 2026 using macOS 26.5.2 arm64, Apple Clang 17, and -O2. All returned bytes were checked. Fixed buffers, process-count bounds, CPU limits, and a wall timeout bounded the run. This host rejected memory resource limits; that failed attempt was retained separately and is not a performance result.
Measurement receipt is embedded in this HTML file.
The receipt and probe source are embedded in the file. They remain available when this explainer is copied elsewhere. No external request is made by the downloads.
Stock fx native operations, warmed terminals, persistent MCP servers, Hermes's existing kernel, pooled HTTP clients, and existing warm sandbox providers.
Report broker and complete process-tree memory, CPU, guest memory, worker density, pools, cache state, and marginal cost per active task.
Fixed tool traces isolate execution changes. Full agent trials measure outcome rate, repeated reliability, tokens, and cost with equivalent fresh state.
Measure planning, hashing, guard checks, and result fan-out. Keep authorization-to-start dispatch separate from total completion, which includes output and required durable synchronization.
Persistent workers, sandbox pools, programmatic tools, and evaluation adapters are established. The proposal must demonstrate useful savings across these existing boundaries.
Replaceable providers, canonical tool values, permission boundaries, and declared concurrency provide an integration seam. Its fresh Node program execution must keep fresh semantics when adapted.
Pinned architecture · Node executionPersistent Python kernels and environment plugins already amortize startup. Bounded concurrent tool RPC is a candidate improvement to compare against the existing persistent path.
Pinned execution implementationReuse lifecycle APIs, execd, warm capacity, and backend adapters. Its experimental client pool hands out fresh prepared sandboxes; acquired sandboxes belong to the caller until destruction.
Pinned pool contractPublic command execution, filesystem operations, output streaming, cancellation, and environment APIs provide another adapter surface. They do not establish this session's internal service architecture.
Official API overviewThe joint post on 3 October 2026 is a plausible match to the recent release discussed. Fresh backend state, repeated attempts, terminal-state grading, and extra-effect checks directly inform reset validation.
Primary announcementRepository activity began 4–5 October. The artifact is a Git-backed memory specification and skill/plugin. Cognition's devin-connect is a separate transport gateway; these inspected artifacts do not expose the full Devin runtime.
Memory specification · GatewayReuse existing task orchestration and grader boundaries. Environment and sandbox interfaces are natural integration points for a new execution backend.
Harbor · Inspect interfaces · OpenEnvThe independent study submitted 1 October examines model–harness interactions. Tool affordances and recovery behavior can change agent results, so evaluate code mode separately from transport acceleration. This is not identified as a Hugging Face organizational harness release.
Primary paperThe two recent release identities remain plausible matches to the original references, rather than user-confirmed identities. Research date: 6 October 2026.
Establish equivalent useful work and real interoperability before expanding into a general execution platform.
Trace current optimized baselines. Separate normalization, admission, useful work, service setup, rendering, and persistence; record logical and physical operation counts.
Preserve original IDs, arguments, dependencies, result contracts, and budgets. Whitelist immutable fixture reads; default unknown registrations and commands to opaque.
Implement one immutable read executor and current-authority checks. Reuse certified successful values through the existing renderer, with a new logical receipt and explicit provenance.
Keep independent subscriber cancellation, deadlines, output credits, and audit. Add deterministic scheduling and a cost model that can choose the original direct path.
Use Python/Node clients and a fixture-driven host tool. Keep descriptors identical. Add one scoped pooled HTTP client while executing every required request.
Integrate one existing Linux backend. Test clean reset, stale plans/epochs, worker loss, output pressure, and effect uncertainty without automatic replay.
Add Hermes/DeepSeek and Harbor/Inspect adapters. Expand certified lowering, service actors, or plan-template reuse only where measurements justify it. Review terminals separately.
Define payload, concurrency, load, queue policy, and authorization-to-start timestamps. Report durable completion separately.
Count arenas, queues, stacks, and metadata. Also report workers, pools, guests, and total cost per task; moving allocations elsewhere does not establish efficiency.
Equal logical calls, outputs, errors, audit, limits, authority, and terminal effects. Test disabled/enabled passes and reject stale reads, unauthorized fan-out, duplicate effects, and state leaks.
Compare warm, persistent, pooled baselines under equal resources. Preserve fx's Linux startup budget through lazy service connection.
The prototype uses fixture-owned admissions and two logical agent identities in one process. Backing read counts refer to captured-content reader invocations, not OS reads or elapsed time. The native transport probe above is a separate experiment. No production fx integration or sandbox qualification has been performed.
+Keep the first implementation small enough to compare against existing paths and explicit enough to recover from failure.
Optimize certified physical work while preserving logical identities, current authority, error behavior, audit, budgets, and receipts.
Use bounded declared plans. Do not infer purity, replace shell semantics, or execute arbitrary model-authored code during planning.
The local probe shows IPC overhead on tiny reads. Existing fx operations can keep their direct execution path.
Own cross-language workers and clients where batching or retained setup repays dispatch cost.
Use OCI, backend SDKs, and qualified container or VM services. A new VMM is outside the initial scope.
Lifecycle, control-channel, filesystem, and memory costs belong at a task boundary unless measurements justify finer isolation.
Arbitrary commands depend on mutable files, clocks, randomness, credentials, services, and process state.
Ownership, crash reclamation, and tenant separation add cost. Profile socket copying and framing before adding it.
Restart infrastructure and expose uncertainty. Repeat an effect only under an explicit eligible retry or reconciliation contract.
Review ownership, input authority, recovery identity, cancellation, output drainage, and publication before moving terminals.
Primary references support the existing capabilities and constraints. The proposed architecture and engineering budgets are design judgments.