Docker worker host adapter#

The public @kontourai/flow-agents/docker-worker export provides runCodexDockerWorker and parseCodexEvents. @kontourai/flow-agents/provider-broker provides startProviderProxy; @kontourai/flow-agents/storage-admission provides trusted-host storage admission and observation. These ports run on the host, outside model-writable workspaces.

Callers provide an immutable Docker image ID, explicit model and deadline, a workspace fork, a read-only kit/source root and context file, a private receipt directory, and a model-scoped host capability. The worker uses a read-only container root, bounded memory/process/storage resources, observed mount/image configuration, and retained stdout/stderr/context digests. Completion requires one observed Codex thread and complete turn; absent token measurements remain unavailable. Containers carry kontour.worker.run=<runId> for cancellation.

Host applications can supply workspaceSetup with prepare (an async host callback), mounts (additional read-only /workspace/... overlays), bootstrap (a trusted host shell fragment), prompt, and metadata. This generic port supports existing third-party runtime setup without embedding a methodology or vendor switch in the adapter. None of these fields may be sourced from model output. Preparation receives {image,workspace,sourceRoot,runId,budget}. Overlay source paths are canonicalized and target paths must be unique, absolute descendants of /workspace without traversal.

The broker reads a host credential file and returns a random capability, base URL, bound model and host observations. Workers never receive the host credential or credential file. The capability permits only Responses endpoints, enforces the selected model and optional reasoning effort, forwards canonical JSON and records measured usage when available. Call close() after the run to revoke capability and terminate pending requests. Docker Desktop reaches the host listener through host.docker.internal; the capability protects the listener, which binds all interfaces by default for Docker reachability.

This API proves observed execution and retained evidence. It does not prove semantic task quality or the physical upstream model. Storage inspection requires Python 3 on the host and refuses non-regular entries such as symlinks in writable roots.

Kits declare execution: {module, export, contract: "kontour.kit.execution_request@1.0"} in kit.json. The module must be a regular, relative .mjs file inside the repository. flow-agents kit run <id> --dest <workspace> --request <json> --controller-root <private-root> [--auth-file <host-auth.json>] executes that entry only after verifying the installed repository's recorded content hash. The public @kontourai/flow-agents/kit-execution export supplies verifyInstalledKit({kitId,dest}) and executeInstalledKit({kitId,dest,requestFile,controllerRoot,authFile?}) for hosts using the same binding. An explicit request source_root must equal the verified installed kit root.

Install the kit's public npm dependencies into the destination workspace before executing its copied module. Kit install remains a validated copy operation, and does not fetch dependencies or run setup scripts. The entry returns a result with status; the CLI exits zero for completed or waiting, otherwise one.

forbiddenMountRoots: [{kind: "controller" | "hidden-oracle" | "credentials", path}] names host-only boundaries. The adapter canonicalizes each path and refuses actual Docker mounts overlapping any listed boundary. Receipt fields are false only when that boundary kind was explicitly inventoried and checked; absent inventory remains null. ownerId is a host UUID recorded as kontour.worker.owner; installed dispatch creates it per invocation, sends cancellation via IPC on deadline, and verifies owner-only container cleanup before returning. A fresh Node child loads the complete entry module graph for every invocation, so an installed update never borrows the previous process's module cache. Executable installed trees refuse hash-excluded cache and VCS directories.

AI-DLC consumers#

The AI-DLC methodology, lifecycle implementation and conformance tests live solely in kontourai/aidlc-kit. Flow Agents exposes generic host and installed-kit APIs; use the standalone kit's documented installation and execution entry. Normal execution requires the kit installed in the destination workspace, its integrity verified, and its public npm dependencies installed there.

Consumers require a published @kontourai/flow-agents release exposing /kit-execution, /docker-worker and /provider-broker. Registry version 6.5.2 lacks these exports. A clean installation using a candidate engine package establishes development evidence only; it cannot establish published consumer closure or live AWS-versus-Kontour effectiveness.