@amaster.ai/employee-runtime-connector 0.1.1-beta.4 → 0.1.1-beta.41

package/README.md

@@ -13,7 +13,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
+  --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 daemon start --foreground
 ```
 
@@ -21,17 +21,59 @@ 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 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. 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
 
 - `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 compatibility manifest. Runner image builds must read this file from the exact installed connector package and fail before publishing when their Source Acquisition profile, adapter, or required package versions do not match it.
 
 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.
 
+## 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.
+
+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. Output telemetry reports both
+`rawOutputBytes` and `retainedOutputBytes` plus `retentionCompactedBytes`; flood
+limits continue to use raw bytes, so retention compaction never hides transport
+pressure or weakens the 50 MiB safety boundary.
+
 ## Pi terminal cleanup outcome
 
 Pi execution uses three separate evidence layers: