Connected Compute contracts

@hellmai/lumenflow-control-plane-sdk’s connected-compute/ module (WU-3523, INIT-091 phase 3) generalises the private-MCP assignment and typed-result wire contract (WU-3509) to every Connected Compute assignment, and adds a runner-side content-safety guard that contract never had.

Assignment and result contract

Every assignment and result shares a correlation envelope — workspace_id, assignment_id, invocation_id, connector_binding_id, connector_class, manifest_revision/manifest_digest, idempotency_key, fencing_generation, and receipt_id — plus an opaque, bounded, connector-specific payload.

import {
  ConnectedComputeAssignmentV1Schema,
  ConnectedComputeResultV1Schema,
  connectedComputeResultMatchesAssignmentFencingV1,
} from '@hellmai/lumenflow-control-plane-sdk';

const assignment = ConnectedComputeAssignmentV1Schema.parse(rawAssignment);

connector_class is the open extension point that makes the envelope connector-agnostic — 'private_mcp' is the only class implemented today (WU-3509); it’s a bounded label rather than a fixed enum so a future connector class doesn’t require re-versioning this schema.

A typed result carries a terminal status (succeeded / failed), structured_result or a typed error, artifact_references and evidence_references, usage and cost, and — on failure — an error_class/retryable pair drawn from the contract spine’s error taxonomy. connectedComputeResultMatchesAssignmentFencingV1 proves a result was minted under the same ownership epoch the runner was issued; a caller must reject a result whose fencing generation doesn’t match rather than resuming from it.

This is a generalisation, not a fork: WU-3509’s private-MCP shape is proven to fit inside this envelope unmodified — connectedComputeResultV1FromPrivateMcpResultCommitV1 projects a private MCP result commit onto the generalised contract, and a test asserts the private-MCP shape is a conformant specialisation.

Never-send guard

The dossier states Cloud must never send, inside a Connected Compute assignment payload: shell commands, executable paths, private URLs, raw credentials, unbounded code, or environment contents. The never-send guard is the runner-side content check that enforces exactly that — layered on top of, not instead of, the shape validation above.

import {
  evaluateNeverSendGuardV1,
  assertNeverSendGuardV1,
  NEVER_SEND_REASON_CODE,
} from '@hellmai/lumenflow-control-plane-sdk';

const verdict = evaluateNeverSendGuardV1(assignment);
if (verdict.verdict === 'rejected') {
  // verdict.forbidden_class, verdict.reason_code, verdict.path
}

assertNeverSendGuardV1(assignment); // throws NeverSendGuardViolationError on rejection

The guard walks every string leaf of the payload and fails closed — its only two outcomes are allowed and rejected; there is no “uncertain, allow” branch. It detects the canonical shape of each of the six forbidden classes by signature (fixed patterns and structural checks), not by exhaustive classification:

Forbidden class	Reason code	Detects
Shell command	`NEVER_SEND_SHELL_COMMAND`	`sh -c`, `cmd /c`, `powershell -command`, or a leading `#!` shebang
Executable path	`NEVER_SEND_EXECUTABLE_PATH`	A Windows `.exe`/`.bat`/`.cmd`/`.ps1`/`.dll` path, or a POSIX `/bin`/`/sbin` path or `.sh`/`.exe`/`.dylib`/`.so` file
Private URL	`NEVER_SEND_PRIVATE_URL`	A URL whose hostname resolves to loopback, RFC1918 private space, link-local, or `.local`/`.internal`
Raw credential	`NEVER_SEND_RAW_CREDENTIAL`	PEM private-key material, an AWS access key id, or a bearer token
Unbounded code	`NEVER_SEND_UNBOUNDED_CODE`	A multi-line blob containing a recognisable function/class/import construct
Environment contents	`NEVER_SEND_ENVIRONMENT_CONTENTS`	Three or more consecutive `KEY=value` lines

Detector order is fixed: the guard reports the first forbidden class it finds, so a payload matching more than one class is always reported under the same reason code.

Secure runner enrolment in v7

Connected Compute credentials no longer belong in process arguments. Put the runtime credential in an uppercase environment variable and pass only its name:

export LUMENFLOW_CONNECTED_COMPUTE_TOKEN='<runtime-token>'
pnpm compute:connect --experimental \
  --base-url https://cloud.example.com \
  --token-env LUMENFLOW_CONNECTED_COMPUTE_TOKEN

The v6-era --token <runtime-token> form is rejected in v7 so the secret does not enter shell history or process listings. Remote endpoints must use HTTPS and must not include username/password URL userinfo. Plain HTTP remains available only for explicit localhost, IPv4 127/8, or [::1] development endpoints.

Sealed host lifecycle in v7

Code assignments do not choose the command that decides gate completion. The real compute-run CLI entrypoint captures its own installed wu-prep sibling before accepting an assignment, then passes a sealed host closure through the runner. The assignment workspace is only the command cwd: its package.json, installed packages, bin metadata, scripts, and payload paths cannot replace the host lifecycle entrypoint. Missing host authority or a failed gate refuses completion.

Local runner: reduced-posture approval and control/kill halt

The customer-machine runner (ADR-112, amended by ADR-119) applies two additional governance rules on top of the contract above when executing a preplanned local:tool_exec assignment:

Reduced-posture mutation approval. For preplanned local:tool_exec assignments on a non-sandboxed (reduced) confinement posture, a mutation tool call (fs:write) only dispatches if the assignment’s own sealed Approvals section explicitly approved it. That approval value is remote input sealed into the envelope by the cloud claim response; the runner does not locally verify it. A missing or unset approval fails closed; read-only calls are never gated. This gate does not cover the code-class agent path, and it cannot fire in the current runner (the only production posture resolver never yields reduced today) — see ADR-119 §1.
Control/kill graceful halt. A pending control/kill action rides the runner’s existing lease-renewal call as one additive field — no new route, no change to claim semantics. The runner lets an in-flight tool call finish, refuses to start the next one, and reports a terminal failure carrying the assignment’s existing fencing_generation rather than a false success. A halted assignment cannot be resumed by a stale or superseded runner process; resuming requires a fresh claim.

See ADR-119 for the full mechanism and the explicitly deferred process-spawn and PTY session tool-capability scope.

Contract spine — the shared error taxonomy Connected Compute results classify against.
Runner deployment — the container and Kubernetes deployment modes that run this contract’s assignments.