0
0
plan: "0035"
title: "A requester can ask for an atirc agent on its guest: spec.agent, a long atirc token minted at the RFP into the secrets bundle, an atirc-agent.service unit, and a requester-originated guest.agentStart event"
status: done
source: >
2026-10-29 and 2026-10-30, the user's decisions (binding), design rev 6 of the kcp-wasm page plan
docs/plans/0035-atirc-agent.md (johnandersen777/kcp, branch kcp-wasm-memory-storage-1). The page
and the CLI request a VM from the socialweb market and give it an atirc agent: a long atirc token
named <handle-nick>-<rfp-rkey>, minted by the requester when the VM request creates its RFP,
delivered through the requester-vault secrets bundle as ATIRC_TOKEN, and a guest systemd unit that
runs the atirc README's root/new-account block and `atirc agent run`. It follows the wootty shell
pattern of plan 0032 (internal/atproto/cloudinit/tunnels.go) end to end: opt-in per contract, a
cloud-init module from contractModules, the binary from socialweb-guest-downloads through
setup-guest-binaries.service, the token only in the secrets bundle. Option B (user, 2026-10-29):
user_data installs the unit but does not start it; a requester-originated
com.publicdomainrelay.temp.compute.events.guest.agentStart starts it, so no harness spend until
the user asks. atirc deployment https://irc.fedfork.com (did:web:irc.fedfork.com, service #atirc).
linux/arm64 is out of scope (user).
principle: >
The agent is opt-in per ComputeContract (spec.agent). Only opted-in contracts mint: a long atirc
token is not revocable. The token lives only in the requester's OpenBao bundle and the guest file
0600, never in user_data, spec, status, a record, a ContractEvent or a log line. The bidder installs
the atirc binary from its own downloads; the guest never fetches it from irc.fedfork.com or the
internet. The unit starts only on a guest.agentStart the requester publishes; the bidder refuses
that event from a guest.
decisions:
scope: >
internal/atproto/oauth/scope.go: RequesterOAuthScope gains
rpc:chat.atirc.mint?aud=did:web:irc.fedfork.com%23atirc (exact aud, linux-kcp and atirc-dev
2026-10-30); the requester calls getServiceAuth with aud did:web:irc.fedfork.com#atirc and lxm
chat.atirc.mint (the same string; atirc accepts it and the bare DID). Fall back to aud=* only if
the PDS refuses. typescript-helpers lib/oauth-scope/mod.ts mirrors the Go scope token for token.
The unused OAuthScopeLocalhost constant goes.
api: >
ComputeContractSpec.Agent *ComputeContractAgent {EnvFile, apigen userEndpoint, default
/etc/atirc/atirc.env}. spec.agent without spec.secretsRef fails the contract before the RFP
("an agent needs its token in spec.secretsRef"). The Infra and EphemeralInfra contract templates
carry it as they carry tunnels.
mint: >
The requester (internal/market/requester) mints after the RFP is submitted and on resume:
ensureAtircToken skips without spec.agent, spec.secretsRef, a handle or deps.ServiceAuth (no
identity-mode gate: OAuth and PDS-account identities alike), and when the bundle entry at
spec.agent.envFile already has a non-empty ATIRC_TOKEN. Subhandle <label>-<rfp rkey>.<handle>
(label: the handle's first dot-label, lowercased, at most 14 characters). It POSTs
<AtircURL>/xrpc/chat.atirc.mint with a chat.atirc.mint service-auth token for
did:web:irc.fedfork.com#atirc and merges ATIRC_TOKEN=<token> (mode 0600) into the bundle by path
with a vault write (services/requester resolves vault.CapabilityWrite; the grant covers
<mount>/contracts/*). Every failure logs and returns; the placeholder stays. Logs
requester_atirc_minted or requester_atirc_mint_failed, never the token.
guest_unit: >
cloudinit.AgentModule(AgentOptions{EnvFile}) writes /etc/systemd/system/atirc-agent.service
(After and Wants setup-guest-binaries.service and the secrets ready units, Restart=always),
/usr/local/bin/atirc-agent-run.sh (waits for the secrets ready file, the binary and a non-empty
ATIRC_TOKEN; creates the nick user in wheel; exec runuser -u <nick> -- atirc agent run) and
/etc/socialweb-guest-agent/agent.json {"unit": "atirc-agent.service"}; runcmd only
daemon-reload. guestseed installs socialweb-guest-agent and atirc when agent.json is in
write_files.
agent_start: >
Lexicon com.publicdomainrelay.temp.compute.events.guest.agentStart (createdAt, signatures),
requester-originated only (market.IsRequesterGuestEventNSID), checked in CheckGuestEvent, in the
ContractEvent NSID enum. The requester refuses an outbound agentStart for a contract without
spec.agent. The guest agent reads agent.json and on agentStart runs systemctl start --no-block
<unit>; without agent.json it ignores the event. No reply event.
downloads: >
versions.json guestDownloads.files.atirc pins the immutable atirc linux/amd64 binary
https://irc.fedfork.com/dl/v0.1.0-9459165 (sha256
9eab39c20ec84d0df9f45b085fcb77eebd65f341b115a5f5db6ef2b595e67491, 39379048 bytes);
scripts/build-guest-downloads.sh adds atirc-x86_64 and skips aarch64 with a log line.
cli: >
run request --agent[=<envFile>] sets spec.agent and merges an ATIRC_TOKEN= placeholder entry
(mode 0600) into the --secrets bundle (a one-entry bundle without --secrets). run request agent
<name> creates the outbound guest.agentStart ContractEvent for the invocation's contract
(ContractSignaling.PublishAgentStart) and waits for Published or the refusal.
state_rules:
- Read AGENTS.md first. status is one of todo, doing, done, blocked. The lead flips statuses.
- No Go tests (AGENTS.md, plan 0027). Proof is the build gates and the live runs below.
- Schema changes bump the Revision in api/v1alpha1/resources.go and run go generate; generated
output is never hand-merged.
items:
- id: A-SCOPE
title: "chat.atirc.mint in the requester OAuth scope"
depends_on: []
files:
- internal/atproto/oauth/scope.go
- typescript-helpers lib/oauth-scope/mod.ts
done_when: "RequesterOAuthScope holds rpc:chat.atirc.mint?aud=did:web:irc.fedfork.com%23atirc; mod.ts matches."
status: done
- id: B-API
title: "spec.agent on ComputeContract and the infra templates"
depends_on: []
files:
- api/v1alpha1/types_computecontract.go
- api/v1alpha1/resources.go
- internal/market/requester/secrets.go
done_when: "go generate ./... leaves no diff; a contract with spec.agent and no secretsRef fails before the RFP."
status: done
- id: C-MODULE
title: "cloudinit.AgentModule and the guestseed atirc need"
depends_on: [B-API]
files:
- internal/atproto/cloudinit/agent.go
- internal/market/requester/secrets.go
- internal/guestseed/binaries.go
done_when: "The rendered user_data of a spec.agent contract holds the unit, the run script and agent.json; runcmd has no start."
status: done
- id: D-AGENT-START
title: "The requester-originated guest.agentStart event"
depends_on: [B-API, C-MODULE]
files:
- lexicons/com/publicdomainrelay/temp/compute/events/guest/agentStart.json
- internal/atproto/market/guest.go
- internal/guestidentity/guestrecord.go
- api/v1alpha1/types_contractevent.go
- internal/market/requester/contractevents.go
- internal/guestagent
- AGENTS.md
done_when: "An outbound agentStart reaches the guest agent, which starts atirc-agent.service; the bidder refuses it from a guest."
status: done
- id: E-MINT
title: "Mint the atirc token at the RFP into the secrets bundle"
depends_on: [A-SCOPE, B-API]
files:
- internal/market/requester/atirc.go
- internal/market/requester/runner.go
- internal/market/requester/requester.go
- internal/services/requester/wiring.go
done_when: "A spec.agent request logs requester_atirc_minted and the bundle entry carries a non-empty ATIRC_TOKEN."
status: done
- id: F-DOWNLOADS
title: "atirc in socialweb-guest-downloads"
depends_on: []
files:
- internal/versions/versions.json
- scripts/build-guest-downloads.sh
done_when: "build-guest-downloads.sh writes atirc-x86_64 with the pinned sha256 and logs the aarch64 skip."
status: done
- id: G-CLI
title: "run request --agent and run request agent <name>"
depends_on: [B-API, D-AGENT-START]
files:
- cmd/socialweb-computer/request.go
- cmd/socialweb-computer/main.go
- internal/stack/request/webrtc.go
- deploy/apps/option-map.yaml
done_when: "run request --agent --hold reaches Held with a minted token; run request agent <name> publishes the event."
status: done
- id: ACC35-AGENT
title: "An agent contract runs atirc agent run on its guest after agentStart"
depends_on: [C-MODULE, D-AGENT-START, E-MINT, F-DOWNLOADS, G-CLI]
done_when: >
run request --agent --hold logs requester_atirc_minted; after Held atirc-agent.service is
inactive; run request agent <name> publishes the event, the unit is active, the nick is on the
atirc channel; /etc/atirc/atirc.env is root 0600; the token is in no kcp object and no log.
Without --agent: no mint, no unit, no atirc binary.
status: done