PaperClipAI/maps/agent-access-map/runs-adapters.md

Runs, harnesses, and model accounts — agent access

Product map: Runs, harnesses, and model accounts.

Review date: 2026-10-12. Source commit: f981fa3cc10cb8663a87dec60345fbff46d54d0a.

This is a source-reviewed baseline of representative operations and known gaps. Each capability needs operation-level review before its entire scope can be qualified. No live agent execution is claimed. Follow the map contract for format, permission checks, evidence and maintenance.

Scoped runner-default source review: 2026-10-12 at eee0534154eaf5d0d3f2bbc97c1e24d86f34a5a5, limited to runner discovery, selected-runtime testing and saved execution/session preservation. The original baseline source and review depth remain unchanged for unrelated operations.

Scoped native cancellation source review: 2026-10-12 at ce23716503a2c9158b5a7ab74ab61571ff4ee7a3, limited to owned startup and shutdown/readiness ordering. The original baseline and review depth remain for unrelated operations; no live provider or agent authorization is claimed.

availability

Review: baseline.

API: present — representative operation IDs:

• GET /api/adapters.
• GET /api/companies/{companyId}/adapters/{type}/models.

Agent access: partial — Agent company-model API and bound runtime context; board adapter/account inventories.

Policy: Run/cost visibility and agent configuration policy; adapter installation/account login/session control require board/admin.

Evidence: source-only — implementation at the reviewed commit above.

Verification: not-run — exercise a listed permitted operation with actual agent credentials/run context; inspect its result and applicable persistence/attribution. Assert the relevant denied actor, owner, company or mode from Policy. Review the remaining operations before qualifying the whole capability.

Gaps: Raw instance adapter listing requires board, while company model discovery exists for eligible agents.

Scoped source-only evidence: adapter discovery reports supported runners/effective default for the selected company/environment; selection policy reads server-owned immutable sandbox facts without provisioning. New Codex defaults and explicit overrides follow the shared runner contract; other harness defaults remain unchanged. The board inventory does not grant a native agent an equivalent discovery binding. See probe restrictions for acquiring qualification.

validation

Review: baseline.

API: present — representative operation IDs:

• POST /api/companies/{companyId}/adapters/{type}/test-environment.

Agent access: partial — Permitted agent-creation validation path / REST / CLI; operator account login.

Policy: Run/cost visibility and agent configuration policy; adapter installation/account login/session control require board/admin.

Evidence: source-only — implementation at the reviewed commit above.

Verification: not-run — exercise a listed permitted operation with actual agent credentials/run context; inspect its result and applicable persistence/attribution. Assert the relevant denied actor, owner, company or mode from Policy. Review the remaining operations before qualifying the whole capability.

Gaps: Environment test path checks creation/configuration policy; missing provider auth must use its owner setup flow.

Scoped source review: test authorization and resolution requires same-company agents:create, saved-agent update access when supplied, allowed environment selection, and normal secret/responsible-user checks. An unchanged saved runner avoids new-creation policy but still receives selected runtime validation. Native readiness tests native Codex startup/model/account and bounded teardown; an authentication or Legacy CLI check cannot replace that runtime evidence. Missing dependencies, credentials, invalid models and incompatible settings fail without silently changing runners. Account login remains board/owner-bound.

Verification for this scope remains not-run: use an admitted agent REST/CLI validation path, assert missing grants and cross-company targets/accounts are denied, then prove the useful task/follow-up separately. hire_agent inherits its caller's runtime; do not assume its binding accepts arbitrary runner or account settings. See creation access.

runs

Review: baseline.

API: present — representative operation IDs:

• GET /api/heartbeat-runs/{runId}.
• GET /api/heartbeat-runs/{runId}/log.

Agent access: available — REST / native call_api / CLI run.

Policy: Run/cost visibility and agent configuration policy; adapter installation/account login/session control require board/admin.

Evidence: source-only — implementation at the reviewed commit above.

Verification: not-run — exercise a listed permitted operation with actual agent credentials/run context; inspect its result and applicable persistence/attribution. Assert the relevant denied actor, owner, company or mode from Policy. Review the remaining operations before qualifying the whole capability.

Gaps: Provider trace reveals/downloads require instance-admin and cannot be counted as ordinary run output access.

session

Review: baseline.

API: present — representative operation IDs:

• POST /api/agents/{id}/runtime-state/reset-session.
• GET /api/agents/{id}/task-sessions.

Agent access: restricted — Board session controls; native server-owned session continuation.

Policy: Run/cost visibility and agent configuration policy; adapter installation/account login/session control require board/admin.

Evidence: source-only — implementation at the reviewed commit above.

Verification: not-run — assert the documented agent denial with an owned test fixture; verify any listed agent request/result path separately. A delegated operation needs its own policy and access review.

Gaps: Execution context reset is not a permitted generic native API mutation or an ordinary agent management path.

Scoped source-only evidence: configuration changes and native execution/recovery retain existing execution on unrelated edits and use recorded run configuration for active/recovered runs. Explicit runner changes use revisions and session invalidation. Verify saved configuration, current versus historical run identity, restart and follow-up without granting session-reset authority to an agent.

Scoped Evidence: source-only — the native transport joins owned startup before certifying cleanup. Rejected duplicates cannot replace that owner or mutate recovery state. Unconfirmed preparation or registration retains recovery state; late registration may release only its own route and cannot launch after close. Shutdown interrupts readiness without granting authority over an unauthenticated adopted process.

Scoped Verification: not-run — verify allowed/denied access using the actual actor independently from the credential-free ownership controls. This correction adds no account-setup, cleanup-override or session-reset authority. The real native readiness/recovery fixtures and installed provider acceptance remain separate gates.