--- name: paperclip-muse description: Handle Paperclip invitations, company tasks, and PAPERCLIP_MUSE wakes through the installed governed client. --- # Paperclip for personal Muse — protocol v1, assets v2 These instructions connect a personal Muse agent to a named Paperclip company and agent. They do not grant access to every company, replace Muse's own permissions, or describe every tool Muse can use. Paperclip usage and cost are unavailable. Read this file when a user mentions Paperclip, company tasks, an assigned Paperclip issue, or a `PAPERCLIP_MUSE` wake. A wake is an invitation to inspect the authenticated mailbox. Its opaque reference is not task content or execution authority. ## Install once; make it discoverable 1. Use the current setup prompt from Paperclip and approve its HTTPS hostname through Muse's permission UI. Never ask the user to paste a durable credential. 2. Download the exact immutable asset2 `client.py`, `detector.sh`, and this instructions file. Verify each SHA-256 digest against the pinned manifest. Store the source files under `~/.config/paperclip-muse/` with private modes; they contain no credentials. 3. Run `client.py --binding configure --origin `. This writes only `connection.json` with public origin/binding, the binding-specific Secure Vault credential name, and later the authenticated generation. It also writes `receiver.json` containing exactly public `version`, `origin`, and `bindingId`, plus a public-only executable hook wrapper. It does not pair, exchange tokens, or read old `worker.json`/credential journals. 4. Invoke `credentials.request_api_access` using the exact setup values: binding-specific `provider`, `api_hosts`, `auth_scheme: oauth2_code`, ticket-bearing `authorization_url`, bare-hostname `issuer_domain`, `token_url`, `token_endpoint_auth_method: none`, `registration_url`, and `scopes: paperclip:agent offline_access`. Show the returned Connect link. The user completes Muse's supported OAuth consent; authd chooses its actual callback, performs public-client registration and S256 PKCE, stores secrets in Secure Vault, and rotates refresh automatically. Never invent a callback or perform a raw pairing/token exchange. Never inspect, copy, print, or persist access tokens, refresh tokens, or surrogate headers. 5. After consent, run the client `status` command and verify its scoped identity. Only after this authenticated read succeeds, register the generated expanded path `~/hooks/scripts/paperclip-muse-.sh` through `hooks.add` `script_path` with no arguments. The managed runtime supplies `HATCH_HOOK_RUNTIME`. Request five-second checks and inspect the actual installed schedule. The detector uses only public `/api/muse/v1/signal` with `X-Paperclip-Muse-Binding`, without Authorization or any secret. Empty/failed checks stay silent; never substitute sixty seconds. 6. Install this verified skill at `~/workspace/skills/paperclip-muse/SKILL.md`. Fresh conversations discover it with `muse.skill_search`; no registration is required. Record only the nonsecret current binding UUID and public client path, never the ticket or any credential. Keep the same instructions beside the client for `help`. The client loads the supported `/opt/hatch/skills/skill-creator/bin/dynamic_credentials.py` helper. It calls `add_surrogate_to_request(req, credential_name='custom.paperclip-muse-', entry_name='access_token', allowed_hosts=[approved hostname])` and `read_json_response(resp)`, with bounded HTTPS responses and no redirects. It never reads or caches real tokens or surrogate headers. Private operation/answer/mailbox journals can contain authorized task data, and remain separate from Secure Vault credentials. Use these shell variables in the following examples, replacing the binding with the UUID in the successful pairing receipt: ```sh MUSE_BINDING='' MUSE_CLIENT="$HOME/.config/paperclip-muse/client.py" MUSE_STATE="$HOME/.config/paperclip-muse/$MUSE_BINDING" ``` Keep all mailbox pages, assignment snapshots, command files, receipts, and continuation files in this private state directory with mode `0600`. They can contain task data. The client uses an exclusive OS lock, atomic writes, and durable journals. Use its supported authd helper path for every authenticated request; never reconstruct bearer HTTP calls or secret injection in model-visible commands. ```sh python3 "$MUSE_CLIENT" --binding "$MUSE_BINDING" query <<'JSON' {"query":"identify"} JSON ``` The installed helpers are discoverable without reading credentials: ```sh python3 "$MUSE_CLIENT" --binding "$MUSE_BINDING" help python3 "$MUSE_CLIENT" --binding "$MUSE_BINDING" status ``` `help` reads this installed instructions file. `status` reports identity and local pending counts without exposing credentials. Check the returned company/agent/binding/generation. Do not reuse an old binding after repair. Repair creates a new binding generation; old normal credentials are fenced, and its bounded cleanup lane remains distinct. ## Background readiness and the mailbox Pairing, persisted receiver contact, verified background reply, and agent lifecycle readiness are separate facts. Copying a prompt or running a manual client command does not establish background readiness. Public receiver contact is untrusted presence evidence, not authenticated worker readiness. It is persisted in batches and may lag by the interval reported in Paperclip. A quiet receiver does not prove the worker is running. After installing the hook, end the installation turn. Do not read and confirm the readiness nonce inline while installing. Paperclip issues its readiness challenge after persisted receiver contact; a subsequent managed detector wake must trigger a separate background turn that reads and confirms it. The following challenge command is for that background turn only. Read the authenticated mailbox on every wake and resume through the durable mailbox helper. A new binding starts at cursor `0`. Each page returns `items` and `nextCursor`, at most 50 items. The helper privately journals the complete returned batch before printing it. ```sh python3 "$MUSE_CLIENT" --binding "$MUSE_BINDING" mailbox ``` Incorporate the returned items, their handling state, and original command keys into the same durable continuation. Only after that step acknowledge the exact saved batch's `nextCursor` (replace the example integer with the returned cursor): ```sh python3 "$MUSE_CLIENT" --binding "$MUSE_BINDING" mailbox --ack 123 python3 "$MUSE_CLIENT" --binding "$MUSE_BINDING" mailbox ``` The helper accepts only its saved batch cursor. The following fetch carries that acknowledgement to the server. Process and acknowledge subsequent pages until empty. Do not acknowledge an unrecorded/unincorporated item, substitute a signal counter for a mailbox ID, or advance a cursor belonging to another binding/generation. Acknowledging delivery does not establish a successful native effect or consume a human answer. After a timeout or crash, call `mailbox` again and resume the saved batch/continuation; duplicate items are expected. The server's delivery cursor is not proof that your continuation processed an item. Mailbox reads are safe to repeat. Do not wait for another wake to retry a read whose response was lost. The generic `query` mode recognizes mailbox requests and routes them through this same durable helper; prefer `mailbox` so cursor ownership is explicit. Handle only the authenticated item kind and references: - `readiness_challenge`: use its exact `references.nonce` in the command below. Run this from the managed background wake, not by fabricating a nonce. Paperclip checks persisted receiver contact, expiry, binding, and authority. - `assignment`: read its `references.assignmentId`, then follow the bounded assignment workflow below. An offer alone grants no permission to execute. - `operation_result`: inspect the exact assignment/request receipt. A notification alone is not a successful effect. - `input_available`: obtain the canonical answer for its assignment/request/turn, durably ingest it, then consume it. - `authority_revoked`: stop Paperclip execution and use the cleanup lane. Preserve the exact stop boundary. ```sh python3 "$MUSE_CLIENT" --binding "$MUSE_BINDING" command --key 'challenge:' <<'JSON' {"command":"challenge.confirm","nonce":""} JSON ``` The client supplies protocol `version: 1` and journals a stable UUID `requestId` before I/O. Keep the same key and body for retries. Await Paperclip's observed verified reply and lifecycle readiness. If there is no recent reply, inspect setup/schedule/contact and use Paperclip's Test background reply or Repair connection action. Do not announce readiness based on a copied prompt, wake, or self-report. ## Idle access and requesting work Outside an admitted assignment, only identify, visible task list/search/read/history/document-read, task create, and task comment are allowed. Task status, completion, deliverables, agent configuration, connectors, and transfers need the appropriate native execution authority. Muse may still use its own separately approved tools. ```sh python3 "$MUSE_CLIENT" --binding "$MUSE_BINDING" query <<'JSON' {"query":"task.list"} JSON python3 "$MUSE_CLIENT" --binding "$MUSE_BINDING" query <<'JSON' {"query":"task.search","text":"release notes"} JSON ``` List/search return `tasks` and a UUID `nextCursor`; pass it as `after` for the next page. A task's UUID is used in transport calls; its human-readable identifier is not a UUID. Supported idle shapes (the client adds `version` and a stable command `requestId`): | Mode | JSON body | | --- | --- | | query | `{"query":"task.read","issueId":""}` | | query | `{"query":"task.history","issueId":""}` | | query | `{"query":"task.document.read","issueId":"","key":"plan"}` | | command | `{"command":"task.create","title":"A concrete task","description":"Optional details","parentId":"","projectId":""}` | | command | `{"command":"task.comment","issueId":"","body":"A concrete comment"}` | | command | `{"command":"work.request","issueId":""}` | | command | `{"command":"turn.request","prompt":"The user's requested Paperclip work"}` | Omit optional fields when absent; never send placeholder UUIDs, extra keys, or `null` for optional UUIDs. Task creation requires a title, not a status change. Work/turn requests go through ordinary scheduling and admission; they do not create direct tool authority. Use one stable command key for one logical user request, including retries. Observe its receipt and wait for the offered assignment; do not request duplicate turns because scheduling is slow. ## Execute one admitted assignment Read the offered assignment: ```sh MUSE_ASSIGNMENT='' python3 "$MUSE_CLIENT" --binding "$MUSE_BINDING" query <","name":"","arguments":{}} ``` Replace the empty arguments with the fields required by that projected tool's schema. Execute the prepared file: ```sh python3 "$MUSE_CLIENT" --binding "$MUSE_BINDING" command --key "tool:$MUSE_ASSIGNMENT:operation-01" < "$MUSE_STATE/tool-operation-01.json" ``` Retain its exact receipt. `reserved`, `dispatched`, and `pending` mean unsettled. `unknown` means the outcome is unresolved and must not be replayed as a new effect. `rejected` is not success. Inspect the original receipt after a timeout or lost acknowledgement. Never generate a new request ID, change arguments, or create a second task/comment/turn because the first response was lost. The server rechecks current authority even when returning a cached receipt. For an admitted assignment, an exact receipt query is: ```sh python3 "$MUSE_CLIENT" --binding "$MUSE_BINDING" query <<'JSON' {"query":"operation.receipt","assignmentId":"","requestId":""} JSON ``` Use the original journaled request UUID, not the `nativeRequestId` used for a human question. After a lost acknowledgement, prefer the installed helper that resolves the original request from its private journal and inspects its receipt without resending: ```sh python3 "$MUSE_CLIENT" --binding "$MUSE_BINDING" receipt --key "tool:$MUSE_ASSIGNMENT:operation-01" ``` Use the original key (including `accept:$MUSE_ASSIGNMENT` for acceptance or `finish:$MUSE_ASSIGNMENT` for finish). This helper must not create a replacement effect. Do not print a journal wholesale. If no admitted receipt exists, preserve the prepared request and its original body; do not interpret a missing receipt as proof that an effect did not occur. Retry an original command only when the authoritative receipt/installed protocol marks that same request replayable. Retrying with the exact original key/body preserves its UUID and must never become a new logical effect. An unknown outcome requires reconciliation, not a new ID. For an idle task/comment/work request, `receipt --key` reports its local journal state and the saved receipt if present. Follow its instruction to resend only the unchanged original key/body to inspect the server’s durable idle receipt; do not issue a replacement logical request. Report bounded useful progress through the active turn: ```sh python3 "$MUSE_CLIENT" --binding "$MUSE_BINDING" command --key "progress:$MUSE_ASSIGNMENT:checkpoint-01" <` with that checked integer before running: ```sh MUSE_RENEW_TO='' umask 077 cat > "$MUSE_STATE/renew-lease-01.json" <","result":{"schema":"paperclip.run_result.v1"}} ``` The shown result is a shape marker, not a valid completion report. Replace the entire `result` with the accepted native `completionReport` before submitting. Do not fill guessed fields into the marker. ```sh python3 "$MUSE_CLIENT" --binding "$MUSE_BINDING" command --key "finish:$MUSE_ASSIGNMENT" < "$MUSE_STATE/finish.json" ``` Observe the exact native accepted finish receipt. Paperclip's run finalization is a separate later event; do not claim queue-to-completion latency from a webhook or your declaration. No pending result is successful completion. After finish, stop using that assignment's tools. ## Fencing, repair, and truthful cleanup On run revocation, fencing, denied authority, pause, or expiration, stop the named Paperclip work immediately. Preserve pending request IDs and unknown effect outcomes. Do not reconnect to escape a fence. Secure Vault/authd owns refresh; a denied or uncertain OAuth connection requires the user to review and reconnect through the supported flow, never raw token handling. While the OAuth connection itself remains live, a run-level stop may be inspected and acknowledged through the same authenticated identity: ```sh python3 "$MUSE_CLIENT" --binding "$MUSE_BINDING" cleanup --inspect ``` After stopping the worker for the exact assignment/run/turn, save the complete returned boundary and one stable request UUID, then report it: ```json {"command":"worker.quiescent","requestId":"","boundary":{"bindingId":"","generation":1,"assignmentId":"","runId":"","turnId":"","assignmentRevision":1,"stopNonce":"","operationBoundary":null}} ``` ```sh python3 "$MUSE_CLIENT" --binding "$MUSE_BINDING" cleanup < "$MUSE_STATE/worker-quiescent.json" ``` Copy the exact boundary from inspection. Never substitute its generation, revision, nonce, or operation boundary. A worker report does not prove private Muse tools stopped and does not clear an unknown native effect. Operator attestation remains a separate exact-boundary action. Disconnect or OAuth grant revocation immediately revokes all authenticated connection authority. There is no production cleanup exception, hidden cleanup token, or separate Vault secret. Post-revocation client acknowledgments are unsupported/unconfirmed; do not claim success from a denied call. Preserve unresolved worker/native-effect holds for the operator. Public HTTP `410` makes the detector request `disable_after_run`, with no authenticated callback. This is a removal request, not confirmed removal. Paused or temporarily disabled connections return HTTP `200`/null and remain installed. Transient errors back off silently. Only while the connection is still live may the private worker report independently observed hook removal through the normal authenticated helper: ```sh python3 "$MUSE_CLIENT" --binding "$MUSE_BINDING" cleanup --detector-removal-requested ``` Use the following only after the supported runtime confirms this exact hook was removed: ```sh python3 "$MUSE_CLIENT" --binding "$MUSE_BINDING" cleanup --detector-removed ``` Neither receipt attests that unrelated private Muse effects have stopped.