@amaster.ai/employee-runtime-connector

Versioned AMaster Employee runtime connector CLI and daemon bundle.

The package exposes one command:

npx --package @amaster.ai/[email protected] -- amaster-runtime --help

For production images, install an exact version and invoke the package bin:

npm install --omit=dev --prefix /opt/pi-cli-runtime @amaster.ai/[email protected]
/opt/pi-cli-runtime/node_modules/.bin/amaster-runtime setup https://employee.example.com
/opt/pi-cli-runtime/node_modules/.bin/amaster-runtime daemon start --foreground

Do not use latest, ^, or ~ in a runtime image. The image tag and connector package version should identify one immutable deployment.

Tool transcript payloads

Task-mode Pi tool start/end events retain bounded input and result data instead of replacing both with lifecycle labels. Call IDs and isError stay unchanged; older summary-only events still replay. This changes reporting only, not tool execution or task acceptance. Existing known-runtime-credential redaction runs before projection; the projection additionally redacts credential-like keys, Bearer/credential assignments and private keys, and omits binary content blocks.

The projection limits strings to 2,000 characters, total text to 6,000 characters, depth to 7, traversal to 240 nodes, arrays to 20 items and objects to 30 fields. Serialized payloads above 12,000 characters use an explicit omission notice so the JSONL event is never cut mid-record. Truncation remains visible. File paths are data: Windows drive/UNC paths and CRLF text are JSON-escaped without shell commands or OS-specific path conversion. The module is included in the existing Node 20 daemon bundle on every platform.

Existing historical events cannot gain details that were never uploaded. New details require the executing desktop/cloud connector to use the updated bundle; deploying the frontend alone is insufficient. No connector install, restart or release is performed by the source change.

Incremental type safety

pnpm typecheck runs the legacy entry-point syntax checks plus TypeScript strict checkJs over src/amaster-runtime-daemon/typed/**/*.mjs and compile-time contract tests in type-tests/. The first migrated boundary is the run-completion phase and event transition table. It is imported by the existing completion-state module and bundled normally; package layout and runtime state version are unchanged.

The package declares its own TypeScript development dependency, using the same compiler version locked by the workspace. Source-development installs need dev dependencies for this gate; it must not depend on the root workspace exposing tsc on PATH. Published runtime consumers only need the distributed artifacts.

Put newly extracted independent daemon logic in the typed lane with explicit inputs/outputs. New files in that directory are included automatically. Do not add any or disable checking to make the gate pass. Keep untrusted I/O validation at the boundary. check:syntax is only a parser check; this incremental gate does not claim that the existing CLI/daemon or all legacy helpers are fully type-checked.

Immutable images should pin an exact package version as their baseline. The current connector does not download or replace runtime code while running; package upgrades and rollbacks belong to the image build and rollout.

The governed MCP cache identity follows the installed pi-mcp-adapter version. Adapter 2.26+ includes requestHeadersCommand even when it is unset; older versions must retain their previous identity. Upgrade the connector together with the adapter and verify the actual version pair using the Pi MCP contract tests. A cache identity mismatch can reject all governed tools before execution; deleting user configuration, credentials, sessions, or connector state cannot repair this mismatch. Each run generates its own governed cache.

Connector capability declaration is automatic. The exact package build declares what it implements, and runtime readiness removes dynamic capabilities when their executor or supporting runtime is unavailable. Operators restrict what the Server accepts with AMASTER_RUNTIME_CONNECTOR_CAPABILITY_ALLOWLIST; users do not need to configure a connector-local capability list. Historical AMASTER_CAPABILITIES and --capabilities inputs remain accepted for rollback compatibility in this release, but are ignored and reported as deprecated. They cannot add, remove, or authorize a capability.

browser_credential_env_read_v1 is the current managed-sandbox credential capability. It is advertised only when a Pi executor runs under a separate non-root UID in a cloud_managed Runner and the runner-owned browser-credential-env.mjs extension is a regular file with the expected tool and environment contract. For a credential-bearing command, the connector consumes the Server-authorized refs after acknowledgement, writes fixed BROWSER_USERNAME / BROWSER_PASSWORD keys to a private command-scoped .env outside the model workspace, passes only its path to the Pi child, redacts the values from connector logs/results, and removes the file at command cleanup.

This approved fallback is intentionally model-visible: browser_read_credential returns a selected value to the model, which then uses ordinary browser fill/click tools. It is not the former sealed transaction design and does not claim that the value is hidden from the model. Origin mismatch, ambiguous credential sets, missing extension readiness, and materialization failures fail closed. The saved Server secret remains reusable by later authorized commands, so the user does not need to provide the password again.

The private path and file mode are lifecycle and cross-process hygiene, not a confidentiality boundary against the Pi child: the model can intentionally obtain each authorized value through browser_read_credential. Desktop-delegated, same-UID, and non-Pi runners must not advertise or execute this capability.

browser_credential_auth_transaction_v1 remains build/runtime vocabulary for the private-FD path and is advertised only when the sealed extension matches its pinned digest. Pi Runtime owns the browser package and browser TCB version checks. The connector loads only the sealed extension for these commands using Pi's explicit --extension flag and disables ambient extension discovery. New browser-credential dispatches require browser_credential_env_read_v1; they never treat the older capability as equivalent. The retired browser_credential_ref_fill_v1 claim is decode-only. Commands carrying credential refs are routed only by their exact required capability: the current capability selects the .env path, the legacy capability selects the private-FD consumer, both together are rejected, and neither is not silently upgraded.

The publish workflow runs on pushes that change Connector package inputs. master publishes an immutable BOS tarball; released-x.y.z publishes to npm. A deployment bundle may reuse an earlier BOS tarball when those inputs are unchanged between its source commit and the Employee target commit. Release npm publication verifies the publishing commit as the package gitHead and updates the repository deployment pin. Remote deployment accepts that npm package only when its gitHead is an ancestor of the target source commit and the package inputs are unchanged between them. If another workspace source becomes a runtime build input, expand the workflow path filter, provenance scope, and bundle reuse scope together. After restart, deployment also verifies the package CLI version inside the container. Do not update the deployment pin manually to bypass provenance checks.

Package Contents

Pi plugin ownership boundary

The pi-agent repository owns plugin installation, dependency versions, package resolution, and build validation for pi-cli-runtime. The connector passes the Company browser profile through AMASTER_BROWSER_SESSION_USER_DATA_DIR; governed browser sessions use their managed profile instead. Do not add Pi package version or digest admission checks to Connector registration, heartbeat, or readiness. Credential capabilities check their Connector-owned runtime extension: the private transaction checks its sealed extension digest, while browser_credential_env_read_v1 checks its extension entrypoint. An absent or unexpected extension must remove the corresponding capability before dispatch. Other plugin failures remain task execution evidence, not Connector admission decisions.

• dist/amaster-runtime.mjs: configuration, pairing, workspace, diagnostics, and daemon lifecycle CLI.
• dist/amaster-runtime-daemon.mjs: standalone daemon bundle for connector registration, heartbeat, command execution, and result ingestion. The source of truth lives under this package's src/ directory. The package build copies the CLI and bundles the daemon modules into publishable output; do not edit generated files under dist/.

Runtime code belongs in the container image. Persist only connector state, the result outbox, and workspaces under the configured state directory.

Enabled context-governance admission

The Server admits governed Pi through the shared context-envelope and managed-project-instruction capabilities. The retired final_model_context_attestation_v1 capability is no longer advertised or required.

When a task-context-v2 command carries frozen Goal authority, the daemon verifies the exact materialized stdin or runtime system prompt before acknowledging or starting the executor, then records mirrorx.goal-context-delivery.v1 only after the process starts without a spawn error. The metadata-only receipt binds the exact command, run, executor, authority hash, selected transport, and delivered prompt hash. It proves Connector-owned process delivery and does not claim to inspect provider payloads, model history, or native compaction.

For Server-dispatched Codex run and wakeup commands, the effective model comes from the command's mirrorxRuntimeConnectorTaskSessionV1.configuredModel snapshot and is passed to Codex with --model. AMASTER_CODEX_MODEL is only a compatibility fallback for older commands that do not contain that snapshot; it does not override a Server-issued model or an explicit Server-issued null model. A malformed or identity-mismatched snapshot fails closed with codex_model_authority_invalid. Its non-empty taskKey is an opaque Server task-session identity and is not required to equal the Issue id; the current adapter binding intentionally accepts only codex_local.

For admitted Pi runs, the daemon compiles source-repository AGENTS.md and AGENTS.override.md topology into one root AGENTS.md with explicit relative scopes, same-scope override semantics, and a higher-authority MirrorX platform block. Governed Pi preserves operator-configured user extensions and tools, disables ambient skill and context-file discovery, and injects that exact compiled file through a run-owned project-instruction extension. pi-mcp-adapter normally merges the operator's user-level mcp.json with the run-owned workspace .pi/mcp.json; the workspace definition wins on a same-name server, and only environment placeholders referenced by preserved user MCP definitions are granted to the child. The daemon projects the Server-issued tool catalog into run-owned MCP config and cache before spawn without revalidating that platform-owned surface. Project instructions and promoted skills use before_agent_start only to inject frozen content; governed tool inputs use tool_call for trust-boundary schema validation. No MirrorX extension validates platform-owned context or tool surfaces during execution, and no MirrorX extension uses session_start, before_provider_request, session_before_compact, or session_compact. Pi owns provider payload construction, history and native compaction. Runtime Actions, artifact receipts, completion closure and cost telemetry remain the post-run authorities.

WorkBuddy Host (CodeBuddy engine)

The optional codebuddy executor participates in the same governed task lifecycle as Codex, while its local execution surface remains deliberately narrower than both Codex and the WorkBuddy desktop product. It does not expose WorkBuddy experts, projects, Office integrations, marketplace connectors. The connector creates a private per-run CodeBuddy home, supplies one strict MirrorX MCP definition, uses an exact tool allowlist, exposes the governed namespace directly with NoDefer(mcp__amaster__*), and preserves only an authority-bound native session rollout. It never inherits the user's ordinary .codebuddy settings, memory, projects, MCP servers, workflows, or marketplace state. When no dedicated provider credential is configured, it reuses only the current OS user's WorkBuddy desktop login through a bounded encrypted-file snapshot inside the private home. The connector copies only the active authentication id's workbuddy-desktop.info opaque encrypted bytes without decrypting, parsing, logging, or serializing token fields. Locks, logout markers, and backups are coordination/history state rather than authentication inputs and are not copied; any logout-marker directory entry, including a dangling symlink, makes the desktop session unavailable. CodeBuddy can mutate only the private snapshot.

Managed CodeBuddy runs expose the native file tools plus mcp__amaster__*; they do not expose Bash, WebFetch, or WebSearch. CodeBuddy 2.137.1's Bash sandbox cannot prevent a command from connecting to an existing loopback service, so allowing Bash would leave a path around Governed MCP even with unsandboxed execution disabled. Consequently these runs can inspect and edit a workspace and perform governed MirrorX actions, but they cannot run tests, builds, package managers, or arbitrary shell commands. This is an explicit capability gap rather than claimed Pi/Codex parity. Governed result authority remains correlated until a structured receipt is actually parsed; an outer transport status cannot shadow a nested structuredContent receipt, and more than 256 unresolved governed calls fails the run instead of evicting an unmatched call id. The managed profile also resolves the workspace once and uses that same canonical directory for CodeBuddy trust and child process execution; an unavailable cwd fails with a stable managed-profile error.

This executor is off by default. Enable discovery with AMASTER_ENABLE_CODEBUDDY_EXECUTOR=true. AMASTER_CODEBUDDY_COMMAND can select an explicit CLI; on macOS the gated discovery path can also find the CLI bundled in /Applications/WorkBuddy.app. CodeBuddy 2.137.1 is the minimum supported version because that is the oldest release on which the native NoDefer(mcp__amaster__*) tool surface has been verified end to end; older versions fail readiness. The Server task-session snapshot owns the model for current commands; AMASTER_CODEBUDDY_MODEL is only a compatibility fallback for older commands without that snapshot. Authentication resolves in two fail-closed modes: exactly one explicitly configured CODEBUDDY_API_KEY or CODEBUDDY_AUTH_TOKEN wins, otherwise the current OS user's WorkBuddy desktop login must be present. Desktop login reuse validates the complete source path chain and opens it with no-follow file descriptors before materializing the private snapshot; all run configuration and native sessions stay isolated. The snapshot is currently supported on macOS and Linux, including Linux XDG_DATA_HOME; Windows continues to require an explicit provider credential until an ACL-equivalent safety check exists. If command scope supplies either auth variable, that complete auth scope overrides daemon auth; two methods in the selected scope fail closed. Provider routing may additionally use the supported CODEBUDDY_INTERNET_ENVIRONMENT, CODEBUDDY_BASE_URL, or proxy variables. Secret values remain run-scoped and must never be placed in arguments, logs, connector metadata, or committed configuration.

Heartbeat readiness is explicitly a fresh daemon_default diagnostic, not command admission: a later command may supply its own complete auth scope. The source metadata check intentionally runs on each heartbeat so logout and permission changes are observed immediately; the measured local cost is about 0.03 ms per check, so it is not cached.

This is an intentional compatibility break for the not-yet-public context-governance contract. There is no historical command migration, dual-read, or fallback from a new Server-issued envelope to an unproved executor path.

Contracted Pi model calls

Pi model_call commands with model_call_output_contract_v1 keep provider and model selection paired with the output ceiling. Command target fields have the highest precedence, followed by AMASTER_PI_PROVIDER / AMASTER_PI_MODEL, then the Pi profile's defaultProvider / defaultModel. Each selected precedence layer must be a complete provider/model pair: a partial command or runtime override fails closed instead of silently falling through to a lower-precedence default. The daemon copies only the normalized default pair into the isolated one-shot profile, validates that the resolved model exists, applies maxOutputTokens to that exact model, and records the resolved target and source in command-result diagnostics. Missing or unknown targets also fail closed before Pi is spawned.

Pi tool-argument transport guard

AMASTER_PI_TOOL_ARGUMENT_GUARD_MODE defaults to shadow; supported values are off, shadow, and enforce. Shadow records metadata-only matches while the single-incident thresholds are calibrated. Promote deliberately to enforce after reviewing near misses and false positives; use off as the emergency rollback. The enforce signature requires at least 8 MiB transported, at most 512 KiB materialized, and at least 16x amplification before tool_execution_start. Replay ratio is telemetry, not a kill prerequisite. Threshold overrides are available through the AMASTER_PI_TOOL_ARGUMENT_* environment variables, but production changes must be based on shadow telemetry and false-positive review.

An enforced stop returns pi_tool_argument_stream_amplification with retryable=false and recommends upsert_document_revision_from_workspace_file. The command result keeps only byte counts, ratios, event/tool identity, thresholds, and near-miss distances; it omits the inline argument body.

The same governed workspace-file action supports both modes: omit documentId, baseRevisionId, and issueId for the current Issue's initial document, or provide documentId and baseRevisionId together for an exact CAS revision. Both modes use the same ownership manifest and byte-ingest path.

Pi JSON mode can also repeat a cumulative message snapshot beside each incremental message_update. The daemon compacts only that redundant snapshot from its retained parse/result buffer while preserving the delta, terminal events, live logs, and tool-argument guard input. For Pi stdout, AMASTER_EXECUTOR_MAX_OUTPUT_BYTES (50 MiB by default) limits the compacted, retained stream. A separate raw stdout safety ceiling is eight times that limit, capped at 512 MiB; stderr and other executors still use the configured raw-byte limit. Above a configured 512 MiB retained limit, the raw safety ceiling can stop the process first. The command result's outputFlood.basis distinguishes retained from raw, and telemetry reports both limits and byte counts. The raw ceiling, timeout, memory limit, and tool-argument guard remain active when Pi emits large redundant JSONL snapshots.

If a Pi assistant message ends at length with only thinking content and no text or tool call, the daemon permits Pi's next generation so it can use its built-in recovery when eligible. A second such message in the same run stops the run; an unrecovered first message is classified when the process settles. It returns pi_reasoning_output_exhausted with token counts and content block types, never the thinking text. outputTelemetry.piGenerationSummary records delta counts/bytes by type, the sum of completed assistant messages' output tokens, and length-stop counts. These are diagnostic observations; use provider billing records for authoritative usage.

Pi terminal cleanup outcome

Pi execution uses three separate evidence layers:

1. a valid successful agent_end and output/usage contract;
2. a durable, inspectable Runtime Action receipt or finalized Runtime Artifact;
3. process cleanup disposition.

An exact process-kill EPERM error emitted only after the first two layers have completed may be isolated as a failed cleanupDisposition warning without changing the command's successful business result. Both accepted shapes require kill and EPERM; generic filesystem/process permission text such as EPERM: operation not permitted, unlink ... is a business error. Durable evidence is limited to a completed Runtime Action or a finalized Runtime Artifact. A runtime_action.status readback is evidence only when its call/plan ref matches an earlier submit/commit receipt in the same transcript. The diagnostic and durable evidence reference remain in the result. Text-only or action-only-without-assistant-output streams, standalone governed reads, non-effect Runtime Action tools, rejected or pending effects, pre-terminal errors, provider failures, timeout, cancellation, resource limits, any signal, live residue, and uncertain ownership remain failures.

This isolation does not schedule a retry or a second business continuation. Command result delivery and the result outbox remain the sole idempotency boundary.

Live log delivery durability

Executor process logs (stdout/stderr events, including full-transcript chat turns) are streamed to the Server as batches against /ingest/logs/batch. Every live log entry carries a per-command monotonically increasing seq; the Server dedupes on (commandId, sourceSeq), so a retry after an ambiguous outcome (restart, timeout, 5xx) never duplicates canonical heartbeat_run_events.

Full-transcript turns preserve every pi event as canonical log entries, including per-token streaming deltas (thinking_delta, text_delta, toolcall_delta) — the chat transcript's typewriter rendering is driven by them. No per-stream entry budget exists: every entry is delivered, and live output is never suppressed. Byte volume stays bounded by the executor flood limit, and outage-time connector memory by the retry backlog byte bound below.

A batch whose delivery outcome is ambiguous is not dropped: it enters a bounded in-memory retry backlog that is retried on a timer and drains in source order, preserving heartbeat_run_events ordering. If the backlog is still undelivered when the executor turn ends, the remaining entries move into the durable result outbox and the command result is deferred until the log entries are delivered first; a sustained log-ingest outage bounded by AMASTER_RESULT_OUTBOX_MAX_ATTEMPTS drops the entries with a stderr diagnostic rather than holding the result hostage. HTTP 400 entries keep the existing bisect-to-invalid drop semantics.

Tuning knobs (defaults are the production values):

• AMASTER_RUNTIME_LIVE_LOG_RETRY_BACKLOG_MAX_BYTES (default 16 MiB): in-memory backlog bound; oldest batches are dropped with a diagnostic when exceeded.
• AMASTER_RUNTIME_LIVE_LOG_RETRY_INTERVAL_MS (default 2000): background backlog retry cadence.
• AMASTER_RUNTIME_LIVE_LOG_FINAL_DRAIN_ATTEMPTS (default 3) and AMASTER_RUNTIME_LIVE_LOG_FINAL_DRAIN_TIMEOUT_MS (default 5000): bounded final drain at the end of an executor turn.
• AMASTER_RUNTIME_DEFERRED_LOG_DRAIN_TIMEOUT_MS (default 5000): per-batch timeout when delivering deferred entries before a command result or from the result outbox.

Mutation attestation

The daemon reports its connector contract, exact package/build, platform/architecture, and discovered executor versions on every heartbeat. The server compares those facts with AMASTER_RUNTIME_RECOMMENDED_VERSION and AMASTER_RUNTIME_RECOMMENDED_BUILD_COMMIT, persists a short-lived content-bound attestation, and correlates Runtime V2 commands to that proof.

AMASTER_RUNTIME_ATTESTATION_MODE defaults to shadow. Set it to enforce only after the expected version and build marker are configured and shadow diagnostics are clean; enforce mode refuses to create or lease Runtime V2 mutation commands without a current exact attestation. AMASTER_RUNTIME_ATTESTATION_TTL_SECONDS defaults to 300 and accepts 60–3600. Invalid mode or TTL values fail server startup visibly.

Threat model: these facts are self-reported by a connector authenticated with its existing connector credential. There is no hardware-backed signature, remote attestation, or independent trust root. The proof detects accidental version/schema/executor drift by an honest connector and correlates commands to the observed facts; it does not prove that a compromised or malicious connector is running the claimed code. Proof identity is stable for the exact connector credential and fact set, create/lease revalidate it under the connector transaction lock, stale commands are isolated within a poll batch, and an active connector can recover after restoring exact facts. Keep the default shadow mode observational, and do not treat this mechanism as a standalone production security boundary or enable enforce before expected markers are configured and shadow diagnostics are clean.

The AMaster remote stack derives its runtime image from the Pi base image with docker/Dockerfile.amaster-employee-pi-cli-runtime. The build installs one exact connector package version under /opt/pi-cli-runtime and sets AMASTER_RUNTIME_CLI_TARGET to that package binary. Do not mount repository scripts or previously installed runtime code from /data over this path; /data is a state volume and must survive package upgrades and rollbacks.

Pi extension load diagnostics

Successful pi_agent_extension_load_timing events are forwarded as system / info records with an extension name and duration. The event payload preserves sourceStream: stderr and the original structured diagnostic. Successful timing records are excluded from result stderr excerpts so they do not create warning panels. Failed loads remain stderr / error with their diagnostic details; unknown or malformed events keep the existing stderr behavior. This applies to new runs after updating the connector in the runner image; historical log records are not rewritten.