@amaster.ai/employee-runtime-connector 0.1.1-beta.34 → 0.1.1-beta.341

package/README.md

@@ -12,26 +12,144 @@ For production images, install an exact version and invoke the package bin:
 
 ```sh
 npm install --omit=dev --prefix /opt/pi-cli-runtime @amaster.ai/employee-runtime-connector@0.1.0
-/opt/pi-cli-runtime/node_modules/.bin/amaster-runtime setup https://employee.example.com \
-  --capabilities remote_registration,heartbeat,executor_discovery,workspace_binding,run_wakeup,model_call,model_call_output_contract_v1,run_cancel,run_terminate,logs_cost_workspace_status
+/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.
 
+## 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 publish workflow verifies that npm records the publishing commit as the package `gitHead`, then updates the repository deployment pin. Remote deployment accepts that package only when its `gitHead` is an ancestor of the target source commit and the connector package path is unchanged between them. This path-only comparison is valid because the published connector is self-contained; if runtime code starts importing workspace source outside this package, expand the provenance scope and tests before release. After restart, deployment also verifies the package CLI version inside the container. Do not update the deployment pin manually to bypass either provenance check.
+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_ref_fill_v1` is a narrow private command capability. It can
+consume only a Server-issued credential ref for the exact command and writes the
+resolved value to a dedicated inherited file descriptor; it does not expose the
+value through prompt, argv, environment, workspace, logs, or result JSON. Normal
+navigation, snapshots, form submission, waits, and challenges remain ordinary Pi
+browser/task behavior.
+
+The publish workflow verifies that npm records the publishing commit as the package `gitHead`, then updates the repository deployment pin. Remote deployment accepts that package only when its `gitHead` is an ancestor of the target source commit and the connector package path is unchanged between them. If another workspace source becomes a runtime build input, expand the provenance scope and tests before release. After restart, deployment also verifies the package CLI version inside the container. Do not update the deployment pin manually to bypass either provenance check.
 
 ## Package Contents
 
+## Pi plugin ownership boundary
+
+`pi-cli-runtime` owns Pi plugin installation, versions, package resolution, and configuration. The connector must only start Pi, deliver a command, manage its process lifecycle, and return its result. Do not add Pi-plugin package/version/digest/schema/config checks to connector registration, heartbeat, capability advertisement, or command dispatch. A plugin failure is task execution evidence, not a connector admission decision.
+
 - `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.
+
+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
@@ -65,6 +183,11 @@ An enforced stop returns `pi_tool_argument_stream_amplification` with
 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
@@ -81,10 +204,25 @@ Pi execution uses three separate evidence layers:
 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, a finalized Runtime Artifact, or an accepted `company_diagnosis_brief` provider receipt whose invocation and returned Diagnosis/document/work-product identities are exact. 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.
+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.
@@ -99,3 +237,7 @@ 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.

package/dist/amaster-runtime-daemon/capability-registry.mjs

@@ -0,0 +1,95 @@
+export const BUILD_SUPPORTED_CAPABILITIES = Object.freeze([
+  "remote_registration",
+  "heartbeat",
+  "executor_discovery",
+  "workspace_binding",
+  "run_wakeup",
+  "context_envelope_v1",
+  "task_context_v2",
+  "managed_project_instructions_v1",
+  "artifact_template_catalog_v1",
+  "runtime_actions_v2",
+  "runtime_artifact_live_manifest_v1",
+  "continue_task_v1",
+  "run_exit_live_path_closure_v1",
+  "model_call",
+  "model_call_output_contract_v1",
+  "run_cancel",
+  "run_terminate",
+  "logs_cost_workspace_status",
+  "browser_credential_ref_fill_v1",
+  "execution_lanes_v1",
+  "mirrorx_initialization_context_v1",
+  "mirrorx_initialization_completion_v1",
+  "native_session_checkpoint_v1",
+]);
+
+const DYNAMIC_READINESS = Object.freeze({
+  native_session_checkpoint_v1: {
+    reasonCode: "managed_pi_checkpoint_required",
+    ready: (input) => input.checkpointUploadEnabled === true && input.runnerKind === "cloud_managed"
+      && input.executors.some((executor) => executor.kind === "pi"),
+  },
+  mirrorx_initialization_context_v1: {
+    reasonCode: "pi_executor_required",
+    ready: (input) => input.executors.some((executor) => executor.kind === "pi"),
+  },
+  mirrorx_initialization_completion_v1: {
+    reasonCode: "managed_linux_pi_required",
+    ready: (input) => process.platform === "linux" && input.runnerKind === "cloud_managed"
+      && input.executors.some((executor) => executor.kind === "pi"),
+  },
+  artifact_template_catalog_v1: {
+    reasonCode: "artifact_template_catalog_not_ready",
+    ready: (input) => {
+      const catalog = input.templateCatalog;
+      return catalog?.status === "ready"
+        && catalog.bundleAttested === true
+        && catalog.materialized === true
+        && catalog.readable === true
+        && catalog.executorReadable === true
+        && Number.isSafeInteger(catalog.fileCount)
+        && catalog.fileCount > 0
+        && typeof catalog.manifestSha256 === "string"
+        && /^[a-f0-9]{64}$/u.test(catalog.manifestSha256)
+        && typeof catalog.targetDir === "string"
+        && catalog.targetDir === input.runtimeTemplatesRoot;
+    },
+  },
+});
+
+function uniqueStrings(values) {
+  return Array.from(new Set((Array.isArray(values) ? values : [])
+    .map((value) => String(value ?? "").trim())
+    .filter(Boolean)));
+}
+
+export function buildRuntimeCapabilityReport(input) {
+  const legacyConfiguredCapabilities = uniqueStrings(input.legacyConfiguredCapabilities);
+  const runtimeUnavailable = [];
+  const advertised = BUILD_SUPPORTED_CAPABILITIES.filter((capability) => {
+    const readiness = DYNAMIC_READINESS[capability];
+    if (!readiness || readiness.ready(input)) return true;
+    runtimeUnavailable.push({
+      capability,
+      reasonCode: typeof readiness.reasonCode === "function"
+        ? readiness.reasonCode(input)
+        : readiness.reasonCode,
+    });
+    return false;
+  });
+  const buildSet = new Set(BUILD_SUPPORTED_CAPABILITIES);
+  const legacySet = new Set(legacyConfiguredCapabilities);
+  return {
+    schemaVersion: "mirrorx.connector-capability-report/v1",
+    source: "build_attested",
+    buildSupported: [...BUILD_SUPPORTED_CAPABILITIES],
+    runtimeUnavailable,
+    advertised,
+    deprecatedCapabilityOverridePresent: legacyConfiguredCapabilities.length > 0,
+    legacyMissingFromBuildTruth: legacyConfiguredCapabilities.length > 0
+      ? BUILD_SUPPORTED_CAPABILITIES.filter((capability) => !legacySet.has(capability))
+      : [],
+    legacyUnsupportedClaims: legacyConfiguredCapabilities.filter((capability) => !buildSet.has(capability)),
+  };
+}