@amaster.ai/employee-runtime-connector 0.1.1-beta.23 → 0.1.1-beta.230

package/README.md

@@ -12,8 +12,7 @@ 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
 ```
 
@@ -21,17 +20,56 @@ Do not use `latest`, `^`, or `~` in a runtime image. The image tag and connector
 
 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 requires `final_model_context_attestation_v1` for governed Pi runs because that path disables ambient context discovery and injects a run-owned compiled instruction bundle. This is a Pi delivery contract, not a connector-wide requirement: an explicitly selected self-hosted Codex runtime continues through its own Runtime Actions V2 and native-session contracts and cannot borrow the Pi attestation claim. Adding the same final-context guarantee to another executor requires executor-specific proof for scoped project-instruction semantics, the normalized final active tool schemas, the selected model's context window, automatically visible skill metadata, and resumed-session history.
+
+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 final-system-prompt 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. Governed MCP tools remain fail-closed: the daemon requires their exact catalog and schemas while accepting additional Pi-native or user-extension tools, including the adapter proxy when a user MCP needs it. Run-exit closure applies the same rule to its two required MirrorX tools as a schema-bound subset instead of rejecting the ambient user tool surface. When the operator-owned Pi settings declare `@amaster.ai/pi-telemetry`, the daemon verifies that package's immutable identity and preserves the authoritative runtime run id for trace correlation while Pi loads it normally from the shared settings. A last-ordered `before_provider_request` hook then validates every provider call, including later calls after tool results: exactly one system message contains the compiled instructions, visible role-skill metadata and the attested active tool contract match their prior attestations, and the complete serialized input fits the context window. It does not override the active model's output limit or inject provider `max_tokens`, `max_completion_tokens`, or `max_output_tokens`; no `modelMaxOutputTokens` substitute exists. Each call appends metadata-only hashes and sizes to a bounded chained receipt; a missing, broken, or oversized chain fails the run.
+
+Pi 0.80.10's internal compaction summarizer calls the provider outside `before_provider_request`. The Enabled profile therefore records and cancels every `session_before_compact` attempt and fails immediately if `session_compact` is nevertheless observed. No model-generated compaction summary is accepted until that provider path has equivalent final-context attestation. The Server also enumerates Pi and Codex as the only supported governed executors at configuration and heartbeat dispatch boundaries; missing or unknown executor kinds fail closed.
+
+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 +103,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,7 +124,7 @@ 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.
 

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

@@ -0,0 +1,91 @@
+export const BUILD_SUPPORTED_CAPABILITIES = Object.freeze([
+  "remote_registration",
+  "heartbeat",
+  "executor_discovery",
+  "workspace_binding",
+  "run_wakeup",
+  "context_envelope_v1",
+  "managed_project_instructions_v1",
+  "artifact_template_catalog_v1",
+  "final_model_context_attestation_v1",
+  "runtime_actions_v2",
+  "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",
+]);
+
+const DYNAMIC_READINESS = Object.freeze({
+  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;
+    },
+  },
+  final_model_context_attestation_v1: {
+    reasonCode: (input) => input.runnerKind === "desktop_delegated"
+      && input.executors.some((executor) => executor.kind === "pi")
+      ? input.piFinalContextAttestation?.reasonCode ?? "desktop_pi_attestation_runtime_not_ready"
+      : "attested_pi_executor_required",
+    ready: (input) => input.executors.some((executor) => executor.kind === "pi")
+      && (
+        input.runnerKind === "cloud_managed"
+        || (
+          input.runnerKind === "desktop_delegated"
+          && input.piFinalContextAttestation?.ready === true
+        )
+      ),
+  },
+});
+
+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)),
+  };
+}