diff --git a/doc/AGENT-ARTIFACTS.md b/doc/AGENT-ARTIFACTS.md index 6a451b5f3f..1d97ee4ae8 100644 --- a/doc/AGENT-ARTIFACTS.md +++ b/doc/AGENT-ARTIFACTS.md @@ -13,6 +13,17 @@ remote workspace. Supply a workspace-relative `contentRef`, basename `filename`, The tool verifies the file, stores an attachment and artifact work product, and binds it to the response. Generic API tools and a legacy API key are unnecessary. +The completion gate permits a narrow sentence-bound exception for one requested +file when the following sentence explicitly qualifies it, for example: +`Write memory.txt. This is personal memory, not a task deliverable.` or +`Write internal-proof.txt. This is an internal verification file, not a deliverable.` +Each qualifier applies to one file in the immediately preceding request sentence. +Separate file requests can each qualify when each has its own following qualifier. +Multiple files requested in one sentence, unqualified report requests, and explicit +attachment/download requests still need verified accessible publication evidence. Saying only “for internal verification” +does not establish this exception. Expected denied native writes in a negative +test are separately recognized as denied attempts, not requested deliverables. + Wait for the receipt. It includes `attachmentId`, `contentPath`, and `downloadPath`, along with the existing command, revision, entity references, and disposition. Reuse the original key after an ambiguous result. A receipt diff --git a/doc/agent-files.md b/doc/agent-files.md index d0fce516eb..5dc4d18070 100644 --- a/doc/agent-files.md +++ b/doc/agent-files.md @@ -37,6 +37,16 @@ workspace: their independent agent copy therefore lives under the excluded `.paperclip-runtime/agent-files///` area. It is not included in task workspace sync, Git staging, or task deliverables. +Sandbox transfer scratch lives separately under +`.paperclip-runtime/paperclip-runner/agent-file-transfers///`. +Workspace-staging transfer scratch stays outside `AGENT_HOME`, including +recovery after controller restart. Remote warm Codex checkpoints may temporarily +stage changed-file payloads under `AGENT_HOME/.paperclip-runtime/checkpoint-*`; +these are checkpoint scratch, not managed personal files. Cleanup removes +only the original materialization's agent directory and transfer scratch +through its owned lease. A later warm turn keeps that original materialization +identity; it does not grant collection or cleanup of another run's files. + Claude CLI runs keep the working-copy location in each run's prompt, separate from the cached system instructions. A new copy path alone does not reset the task session. Each turn names the current copy for relative file references; diff --git a/doc/architecture/runner-pi-capabilities.md b/doc/architecture/runner-pi-capabilities.md index 0172c726fb..6046bfb223 100644 --- a/doc/architecture/runner-pi-capabilities.md +++ b/doc/architecture/runner-pi-capabilities.md @@ -22,6 +22,28 @@ for the exact source/image evidence and merge status. All dated checkpoints below describe historical qualification attempts. Their failures and profile numbers are retained; they are not current release gates. +## User-selected models (2026-10-06) + +Native Pi accepts any explicit provider/model ID. The settings builder, server, +release profile, and Rust runner do not restrict selection to a qualification +model. Pi must acknowledge the exact selection before a prompt and on recovery; +unavailable models fail clearly without selecting a substitute. Runtime package, +version, command, permission, and process-ownership checks remain enforced. + +Bind the selected provider's credentials in the agent environment, for example +`OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, `GEMINI_API_KEY`, or `OPENROUTER_API_KEY`. +Custom models use `PAPERCLIP_PI_PROVIDERS`, an explicit JSON object in Pi's +`models.json` providers format. The runner writes it into the private Pi home, +forwards explicitly bound credential references, and includes its digest in +recovery identity. Credential commands and control-plane credential references +are rejected. General AWS IAM keys are excluded; Bedrock uses `AWS_BEARER_TOKEN_BEDROCK`. Choose a thinking level supported by the selected model (`off` +for a model without reasoning). + +The DeepSeek model IDs throughout the historical qualification results below +identify those attempts; they are not a product allowlist. Those results do not +qualify this merge or additional models. + + ## Historical Pi 1.0 candidate (2026-10-02, profile v13) Pi remains pinned to **`@earendil-works/pi-coding-agent@1.0.0`**, with @@ -30,8 +52,9 @@ reasoning-mode selection and rejects previous profile identities. It is a new qualification candidate; profile-12 results below remain historical evidence. Pi's new field also changes four shared files covered by Copilot's source -identity. Copilot therefore advances to a still-unqualified profile v13 without -changing its executable or model. Pi's profile-13 identity and native closure +identity. The subsequent live callback snapshot changes the shared sidecar again, +so Copilot now uses still-unqualified profile v14 without changing its executable +or model. Pi's profile-13 identity and native closure remain unchanged. Final artifacts must bind the corrected source; the initial ARM startup and 61 contract passes alone do not establish production readiness. @@ -1174,3 +1197,28 @@ separately built and verified Linux provider pack in its runner image; running local setup does not install or qualify a remote image. Published-tar local and Daytona startup evidence must bind the final installation candidate, with no candidate qualification flags, before a production-readiness claim. + + +## Cold process admission budget + +Pi cold `session.open`, including process replacement and durable reopen, has a +60-second admission budget. The controller shares one deadline across its cold +open/recovery command and provider identity barriers (`session.open`, replacement +`run.attach`, and replacement `runner.drain`). A live adopted runner keeps the +ordinary 30-second waits. Rust gives only Pi's sidecar `session.open` request the +60-second budget; initialize, attach, turn start and other sidecar commands stay +at 30 seconds. Inner ACP handshake (30 seconds), post-admission verification +(8 seconds), cancellation (2 seconds), and close (7 seconds) are unchanged. + +Timeout still poisons and retires the Rust sidecar process group. Closing the +controller during its startup wait rejects that wait and uses the existing owned +process cleanup. Callers must await transport close in their cleanup path. +This is trusted controller timing policy, outside the immutable Pi wrapper/profile +closure; it does not change profile 13, runtime 1.0.0, or the explicit model. + +The credential-free closed-startup regression requires the real +`session_ensure_failed` rejection within 60 seconds, with no prompt, no provider +identity and confirmed cleanup. Its child watchdog is 80 seconds (20 seconds for +cleanup after admission), inside a 90-second test timeout. Failed evidence stays +in its reported temporary directory. These margins do not extend production +command deadlines or qualify a target platform without a fresh run. diff --git a/doc/grok-native-runner.md b/doc/grok-native-runner.md index 1cdac172eb..dfd2096ea2 100644 --- a/doc/grok-native-runner.md +++ b/doc/grok-native-runner.md @@ -110,7 +110,7 @@ single successful browser task do not establish that qualification. ## Remote verification Do not run Docker on a developer laptop when using remote verification. The -`Docker Runner check` workflow offers maintainer-authorized manual EC2 image +`Docker Runner check` workflow offers maintainer-authorized manual Linux image builds and broad source checks without provider credentials. It records the source revision, resolved lock digest and immutable image reference. Paid Product E2E remains behind the protected default-branch workflow and environment.