# Local agent connection: administrator setup and recovery Ordinary workers give the AI agent a goal and approved inputs. The administrator or setup agent connects the release to the organization's runtime once, using that runtime's supported skill and MCP import mechanisms. Workers do not edit this kit or connection files. A runtime without MCP can use the supplied public CLIs through its permitted tool interface and the corresponding Skills. ## What is supplied `packr-agent-mcp` (`packr-agent-mcp.exe` on Windows) is a local stdio adapter. It exchanges one UTF-8 JSON-RPC message per line, up to 1 MiB. It opens no HTTP listener and starts no external executable. Keep its protocol stdout separate from stderr. Supported MCP protocol versions are 2024-11-05, 2025-03-26 and 2025-06-18. This does not require a particular model provider. The release catalog binds the adapter's exact bytes, OS/CPU and supported tools. Use the catalog and digest supplied for the same package; do not copy a catalog from another OS or generate a new one merely to bypass a mismatch. An adapter update requires a matching catalog and a fresh reviewed registration. | Available tool | Request fields | Result/use | |---|---|---| | `vibepackr.setup.status` | `{}` | Local adapter setup state; separate from appliance readiness | | `vibepackr.headless.health` | `{}` | Native health query through the configured local control-plane socket | | `vibepackr.headless.status` | `{}` | Native status query | | `vibepackr.headless.work_list` | `limit` (1–100) | Read existing Work references | | `vibepackr.headless.work_show` | `work_reference` | Read the original Work's minimized state | | `vibepackr.gape.validate_snapshot` | `input_id` | Validate a registered snapshot against its approved source scope | | `vibepackr.gape.compare` | `before_input_id`, `after_input_id` | Compare two registered snapshots | | `vibepackr.sdk.analyze` | `input_id` | Analyze a supported full integration request | | `vibepackr.integration_helper.discover` | `input_id` | Discover the request's supported integration shape | | `vibepackr.integration_helper.normalize` | `input_id` | Normalize the declared request | | `vibepackr.integration_helper.validate` | `input_id` | Validate declarations | | `vibepackr.integration_helper.prepare` | `input_id` | Prepare a local integration candidate | | `vibepackr.integration_helper.status` | `input_id` | Read its native preparation status | These MCP tools do not install an appliance, bind a runtime, submit Work, generate an SDK adapter or drive Builder. Use the release-supplied public CLI/GUI and its Skill for those tasks when authorized. A Helper candidate does not grant execution authority. GAPE snapshot creation uses the supplied GAPE CLI; subsequent validation and comparison can use MCP. Reobserve changed architecture when adding a legacy system or runtime to an installation already in use. ## Administrator/setup-agent steps 1. Extract the matching OS package and verify its supplied checksums. Keep the adapter, release catalog and public call schema together. Check the actual binary with `packr-agent-mcp --version`; this alone is not a connection test. 2. Prepare a private workspace and a new private setup request. Use the OS's owner-only access mechanism: on Unix, directories 0700 and files 0600; on Windows, the current user's private access rules. Do not loosen permissions to satisfy a check. Existing workspace files and results are preserved. 3. The setup request uses schema `packr.agent-mcp.setup-request.v1`, a **fresh** absolute `output_directory`, runtime profile `GENERIC_STDIO_DESCRIPTOR`, and a registration object. The registration contains: - `schema_version`: `packr.agent-mcp.registration.v1`; - `catalog_path` and the package's `expected_release_catalog_digest`; - a stable `workspace_id` and absolute private `workspace_root`; - `inputs`, mapping each permitted input ID to its relative file path, exact SHA-256, `maximum_bytes` (up to 1048576) and format `HELPER_REQUEST_V2` or `GAPE_SNAPSHOT_R1`; - `control_plane_socket`: the administrator-approved local socket, or `null` when only local preparation is required; - `approved_gape_repositories`: the explicit permitted source roots for snapshot validation, or an empty list when that operation is not needed. 4. Run the supplied binary's `register` command with that private setup request. For example, from the directory containing the actual release executable: ```sh ./packr-agent-mcp register /absolute/private/setup-request.json ``` On Windows use the equivalent `packr-agent-mcp.exe register` invocation with the actual private Windows path. The setup agent supplies real values; the example path is not an installation default. Registration writes only its fresh output directory and private local workspace records. 5. Retain `registration.json`, `mcp-server.json` and `SETUP_RECEIPT.json` inside the private setup output. The descriptor contains a command, arguments and an empty environment object. Import it through the runtime's documented MCP configuration mechanism. It is not a universal host-settings file and does not overwrite the host's settings. Import the relevant `skills/` folders separately using its supported mechanism, or explicitly attach their Markdown. 6. Verify a **live** initialize/initialized exchange and `tools/list`, then call `vibepackr.setup.status`. Confirm the expected release and 13 tool IDs. Record which Skills the runtime actually read. A descriptor or copied Skill file alone proves neither loading nor a successful connection. 7. For appliance queries, verify the configured installation and permitted local connection with native health/status. An unconfigured socket can be valid for an analysis-only workspace, but it does not establish appliance binding. Do not put credentials, customer prompts, endpoints or raw logs into MCP tool arguments. Input IDs refer only to administrator-registered local files. Each changed input or expanded source scope needs a new reviewed registration and fresh setup output; retain the previous one and its operation records. ## Example call and result After initialization, call the SDK analyzer with an input ID that was actually registered. Replace the catalog digest with the exact supplied 64-character value: ```json { "schema_version": "packr.agent-mcp.call.v1", "operation_ref": "sdk:analysis-001", "expected_release_catalog_digest": "", "workspace_id": "integration-lab", "request": {"input_id": "supported-synthetic-request"} } ``` The example's placeholder digest is intentionally not executable. The host passes these arguments to `vibepackr.sdk.analyze`; it must not add a source path, command, environment variable or network address to the request. The response preserves `transport_status`, `product_result` and `reconciliation` separately. A valid synthetic request can return payload `native_return: "Ok"`; malformed `{}` input returns native reason `INVALID_INPUT` and payload `native_return: "Err"`. Record the actual result rather than converting every transport success into product PASS. ## Failure and interruption cases | Actual observation | Concrete example | Next action | |---|---|---| | `CATALOG_IDENTITY_OR_ALLOWLIST_DENY` | A Windows adapter was paired with a Linux catalog, or adapter bytes changed | Preserve the mismatch; use the matching intact release. Administrator creates a fresh registration after the package identity is verified. | | `PRIVATE_FILE_PERMISSIONS_DENY` / `WORKSPACE_PRIVATE_DIRECTORY_DENY` | A shared folder exposes registration/workspace files to other users | Administrator supplies a proper private location; retain evidence. Do not grant broader permissions or suppress checks. | | `INPUT_NOT_REGISTERED` | The agent guessed an input ID for a new legacy request | Stop that call. Setup agent registers the approved file/digest in a fresh reviewed setup. | | `INPUT_DIGEST_DRIFT` | The JSON was edited after registration | Preserve both versions. Validate the new input and create a fresh registration and operation reference. Do not overwrite the original operation. | | `TOOLS_LIST_STATE_OR_PARAMS_DENY` | The host listed tools before initialization | Use the host's supported MCP handshake. Do not treat this as a product integration failure. | | `CONTROL_PLANE_NOT_CONFIGURED` | Local SDK analysis works, but health has no configured socket | Continue authorized local preparation. Administrator supplies the actual supported local connection before appliance queries. | | `OPERATION_IDENTITY_CONFLICT` | One operation reference was reused for another tool or changed inputs | Query/reconcile the original operation first. A distinct reviewed task gets a distinct reference. | | `RECONCILIATION_REQUIRED_NO_REINVOKE` | The adapter reserved an operation, then the process stopped before a recorded result | Preserve the reservation. Query the original product reference when one exists; otherwise have the administrator resolve the uncertain step. Do not delete the journal or resubmit to force progress. | | `ADAPTER_LOCAL_CACHED_RESULT_NOT_NEW_PRODUCT_EXECUTION` | Same operation and same inputs were called again | Treat the response as the retained result; it is not another execution or a current appliance health observation. Use a new reference for an intentionally new authorized observation. | | Timeout or cancellation notification | The host disconnects while a native call is running | Reconcile the same reference after reconnect. Synchronous native calls cannot be interrupted by this adapter; a cancellation notification proves no rollback or absence of effects. | The adapter's journal is a local transport checkpoint, not a product Work receipt. For a Work that was executed through another supported interface, retain and reconcile that same Work's product validation, recovery state and receipt.