@amaster.ai/employee-runtime-connector 0.1.1-beta.15 → 0.1.1-beta.151

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,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,57 @@ 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.
+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.
+
+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 runtime build inputs are unchanged between them. Those inputs are the package path plus `packages/shared/src/source-acquisition-compatibility.json`, which is copied into the published package and bundled into the daemon. The manifest's failure-classification allowlists are therefore immutable build inputs too; Connector classification and any authorized Server parser must consume the same exact package truth. 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.
+- `dist/source-acquisition-compatibility.json`: versioned Source Acquisition protocol and failure-classification manifest. It does not constrain Pi plugin packages, versions, or configuration.
+
+Source executor diagnostics remain inside the complete run result JSON for authorized Server/read-surface handling. They contain only manifest-allowlisted failure and reason codes plus bounded phase/retry/start-state fields; raw error messages, arbitrary error codes, paths, locators, stdout, and stderr are not part of that contract. This Connector-only slice does not add a Company Sources client projection.
 
 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/output limits, automatically visible skill metadata, resumed-session history, and the enforced output reserve.
+
+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 disables ambient extension, skill, and context-file discovery and injects that exact compiled file through a run-owned final-system-prompt extension. When the operator-owned Pi settings declare `@amaster.ai/pi-telemetry`, the daemon resolves only that package-owned entry, requires the runtime npm manifest to pin its exact installed version, verifies its name, path, and tree digest, passes it as an explicit extension, and preserves the authoritative runtime run id for trace correlation; every other ambient package extension remains disabled. 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 normalized active tool set match their prior attestations, the provider model/output ceiling match the run contract, and the complete serialized payload plus output reserve fits the context window. 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
+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

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

@@ -0,0 +1,85 @@
+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",
+  "source_acquisition_v1",
+  "headed_browser_auth",
+]);
+
+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: "managed_pi_executor_required",
+    ready: (input) => input.runnerKind === "cloud_managed"
+      && input.executors.some((executor) => executor.kind === "pi"),
+  },
+  source_acquisition_v1: {
+    reasonCode: "source_acquisition_not_ready",
+    ready: (input) => input.sourceAcquisition?.ready === true,
+  },
+  headed_browser_auth: {
+    reasonCode: "headed_browser_runtime_not_ready",
+    ready: (input) => input.browserSessionBroker?.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: 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)),
+  };
+}