alkcall/AGENTS.md

AGENTS.md

Operating instructions for opencode agents working in this repo. opencode auto-loads this file as instructions, overriding the built-in defaults for this project. Custom agents in .opencode/agents/ inherit these rules unless their own prompts say otherwise.

Git Workflow

Commit and push when reasonable. When a change is complete and verified (build + lint + tests pass), commit and push to origin/main without asking. This overrides the built-in default of "only commit when explicitly asked."

The workflow:

1. Make the change
2. Verify: cargo test, cargo clippy --all-targets -- -D warnings, cargo fmt --check, cargo doc --no-deps if docs changed
3. Inspect git status and git diff before staging — stage only the intended files, never secrets
4. Write a concise commit message matching the repo style (see git log --oneline -10). For multi-point changes, use a summary line plus a body with bullet points and a verification block.
5. git push origin main
6. Report the commit hash and the verification summary

Exceptions — do not commit or push without asking:

• The change is exploratory / speculative (you're not sure the user wants it kept)
• The user is actively reviewing the diff and may ask for changes
• The change touches published wire formats or semver-relevant public API (this crate will be on crates.io; the EventEnvelope shape and the channels 8-byte chunk header are wire-format-stable — see ADR-014 and ADR-034)
• You'd be force-pushing, amending a published commit, creating an empty commit, or skipping hooks

Never commit secrets, keys, or credentials. If a commit fails or hooks reject it, fix the issue and create a new commit — do not amend the failed one.

Git identity is preconfigured (glm-5.2 <glm-5.2@alk.dev>). Do not change git config, skip hooks, or use git commit -i.

Project Conventions (Rust / RPC protocol crate)

This is the call + channels RPC crate — the unification of alknet-call (structured JSON RPC: operations, streaming subscriptions, service discovery) and alknet-channels (multiplexing proxy: N logical channels over one transport stream, channel 0 pre-negotiated as alk/call). The conventions below apply to all work in src/ and tests/. They mirror .opencode/agents/implementation-specialist.md §Project Conventions and are repeated here so they apply to every session, not just spawned implementation agents.

1. No comments in code unless the user explicitly asks. This is a project-wide convention. Doc comments (///, //!) are fine and expected on public API. Inline // comments only when the user asks or when a non-obvious safety/correctness constraint would otherwise be missed (e.g., "fresh per call — ID reuse under the same connection corrupts PendingRequestMap correlation and the abort-cascade tree").

2. Error handling — thiserror for library error types. No panics in library code. No unwrap() or expect() outside tests. If you reach for unwrap, the error path wasn't specified — stop and decide what should actually happen. For poisoned RwLock/Mutex, use unwrap_or_else(|e| e.into_inner()) so a panic in one operation does not cascade to other operations.

3. tokio is the async runtime — all I/O is async. The call protocol's stream handling, the channels demux/mux, from_call discovery, and the dispatch loop are all async. Do not introduce blocking I/O on the async path. Use tokio::sync primitives (oneshot, mpsc) for request correlation and subscription channels; parking_lot for short-held internal locks (PendingRequestMap).

4. No secret material on the wire — the call protocol carries no private keys, API keys, mnemonics, or decrypted credentials in call.requested payloads, call.responded payloads, or OperationContext.metadata. Outbound credentials flow through Capabilities injected at the assembly layer → HandlerRegistration.capabilities → OperationContext.capabilities → handler. See the no-env-vars invariant below and ADR-010.

5. No-env-vars invariant — no handler reads outbound credentials from any source other than OperationContext.capabilities. The credential injection path is vault → assembly layer → Capabilities → HandlerRegistration.capabilities → OperationContext.capabilities → handler. Downstream consumers' std::env::var reads are unreachable because the assembly layer never calls Default::default(). This is a spec-level invariant, not a runtime convention.

6. OperationEnv must remain a trait — the trait-based design enables registry layering (session overlays, connection overlays, peer-keyed composition). Making OperationEnv concrete or hardcoding the global registry into the dispatch path would close the session-overlay and connection-overlay patterns. This is the same integration-point pattern as IdentityProvider. See ADR-019, ADR-024

7. Wire formats are stable — two wire formats live in this crate:

   • EventEnvelope ({ type, id, payload } with length-prefixed JSON framing) — the call protocol's wire format. Cross-language consumable (TypeScript, Python, any language). The envelope shape and the five event types (call.requested, call.responded, call.completed, call.aborted, call.error) are stable. New event types may be added; existing ones must not change shape. See ADR-014.
   • Channels 8-byte chunk header ([channel_id:u32 BE][length:u32 BE][payload]) — the channels wire format. This is a one-way door: changing the header format breaks all peers. The channels layer has no stream_type concept — the handler owns its sub-stream multiplexing on the BiStream it receives. See ADR-034, ADR-035

8. Producer/consumer, not server/client — both sides of a call or channels connection can initiate. A producer exposes operations (call) or opens data channels (channels); a consumer calls operations or opens channels. Both sides can be both simultaneously — connection direction (who opened it) is independent of call/channel direction (who calls/opens). Avoid "server" and "client" framing in docs and API names; use "producer" and "consumer," or "accept side" / "connect side" for the connection-establishment half specifically. See ADR-022, ADR-037 §direction semantics.

9. Vendored core types — the types formerly in alknet-core (Connection, ProtocolHandler, BiStream, BidiStreamSource, AuthContext, IdentityProvider, Identity, AuthToken, Capabilities, OwnershipProvider, HandlerError, StreamError) live in this crate. They are the home for these types going forward — do not add a separate alkcore dependency. When the alknet mono-repo is reworked, it will consume alkcall's versions. Keep these types lean (no TLS, no transport coupling, no endpoint/accept-loop); the dial and the TLS config are concerns of the consumer, not of this crate. See ADR-007, ADR-008, ADR-009.

10. BAST documents for wire formats — every binary wire format in this crate carries a BAST (Binary Abstract Syntax Tree) document as its machine-readable spec (e.g. the channels chunk header's docs/architecture/chunk-header.bast.json, embedded as CHUNK_HEADER_BAST). BAST is plain JSON — no dependency required to author or consume it. The alktype crate compiles BAST into readers/writers/validators; future codegen derives language-specific implementations. Trivial or hot-path formats (chunk header, tty framing) stay hand-rolled with the BAST doc as the contract; complex formats (sftp) use the alktype engine or codegen. Do not roll your own offset map or validator for complex formats. See the alktype crate at /workspace/@alkdev/alktype.

11. Feature flags — transports may be feature-gated if the need arises. The base crate should compile lean (no quinn, no iroh unless the feature is on). The vendored Connection type supports Connection::from_stream / from_bidi for transport-agnostic construction — the call and channels protocols are transport-agnostic by construction. Verify both cargo test (default) and cargo test --all-features pass if features are added.

12. Naming — Rust standard: snake_case for functions/variables/ modules, PascalCase for types/traits, SCREAMING_SNAKE_CASE for constants.

13. Module structure — one module per file under src/, re-exported from src/lib.rs. Public API surface is lib.rs re-exports. The crate has two subsystems: registry (operation specs, context, dispatch, registry) and protocol (wire format, streams, adapter, dispatch loop, pending requests, abort cascade) for the call half; and the channels half (wire format, ChannelsAdapter, ChannelManager, ChannelBidiStreamSource, channel lifecycle operations, ChannelClient).

14. Abort cascades to descendants — call.aborted for a parent request cascades to all non-terminal descendants in the call tree. Default policy is abort-dependents; continue-running is an opt-in for long-running work. The abort policy is set on OperationContext and propagated through OperationEnv::invoke() — the composing handler decides the child's policy, not the wire caller. See ADR-020.

15. Peer authorization via AccessControl — a remote peer's call is authorized by AccessControl::check(peer_identity) against the op's AccessControl — the same mechanism that gates every other call. No remote_safe flag, no trusted_peer bypass. An op with AccessControl::default() is callable by any peer; an op with required_scopes is callable only by peers whose Identity.scopes satisfy them; an op with Visibility::Internal is never callable from the wire. See ADR-024.

Verification Commands

Run these before committing. All must pass.

cargo test                                    # full suite
cargo clippy --all-targets -- -D warnings
cargo fmt --check
cargo doc --no-deps                           # if docs changed
cargo publish --dry-run --allow-dirty         # before a release

If feature flags are added, also run cargo test --all-features and cargo clippy --all-features --all-targets -- -D warnings.

Before a release, also verify the wasm target (the crate is WASM-clean by construction — no net/fs/process tokio features):

cargo check --target wasm32-unknown-unknown
cargo clippy --target wasm32-unknown-unknown -- -D warnings
cargo semver-checks check-release             # before a release

Architecture Context

• docs/architecture/ — the authoritative spec. Read it before non-trivial changes. ADRs are numbered 001..048; OQs (open questions) track resolved/deferred decisions.

• This crate unifies alknet-call and alknet-channels from the alknet mono-repo (/workspace/@alkdev/alknet). The source architecture docs were ported from /workspace/@alkdev/alknet/docs/architecture/ and renumbered as alkcall ADRs (001..048; ADR-048 was authored in this crate). The ALPN strings (alk/call, alk/channels) are wire-stable going forward (renamed from alknet/ to alk/ in v0.1.1, before the first published consumer).

• Key ADRs that inform this crate's design:

  Call protocol:

  • ADR-014 — hand-rolled EventEnvelope framing (irpc never integrated; supersedes ADR-013)
  • ADR-015 — call protocol stream model (bidirectional streams, ID-based correlation)
  • ADR-022 — call protocol client and adapter contract (CallClient spawn_dispatch transport-agnostic; from_call imports remote ops; connection direction independent of call direction)
  • ADR-019 — operation registry layering (curated + session + connection overlays; OperationEnv as trait-object integration point)
  • ADR-024 — peer-graph routing model (peer-keyed overlays + PeerRef routing; AccessControl-based peer authorization)
  • ADR-010 — secret material flow and capability injection (no secret material on the wire; capabilities injected at assembly layer)
  • ADR-017 — privilege model and authority context (internal = authority switch not ACL skip; External/Internal visibility)
  • ADR-020 — abort cascade for nested calls (default abort-dependents, continue-running opt-in)
  • ADR-018 — handler registration, provenance, and composition authority
  • ADR-016 — operation error schemas (typed details in call.error)
  • ADR-021 — streaming handler for subscriptions (StreamingHandler type, invoke_streaming() dispatch path)
  • ADR-026 — forwarded-for identity (metadata only, never used by AccessControl::check)

  Channels:

  • ADR-034 — channels wire format (8-byte chunk header; one-way door)
  • ADR-035 — channels pure channel multiplexing (no stream_type, BiStream-only, handler owns sub-stream multiplexing)
  • ADR-036 — channel 0 pre-negotiated as alk/call
  • ADR-037 — channel lifecycle operations (channel/open/close/ control/resources/subscribe on channel 0's call registry)
  • ADR-039 — ChannelsAdapter and ChannelManager (substrate-agnostic demux loop; ChannelManager is ALPN-blind, auth-blind, transport-blind)
  • ADR-040 — backpressure, channel limits, ID reuse (bounded-buffer, 256-channel per-connection memory bound, monotonic IDs)
  • ADR-042 — hub relay (translate channel 0, byte-forward data channels with ID rewrite)
  • ADR-043 — ChannelClient (transport-agnostic from_connection primary; dial lives in the consumer)
  • ADR-041 — per-identity channel cap (256 per PeerId via ChannelLifecyclePolicy)

  Shared (vendored core types):

  • ADR-001 — ALPN-based protocol dispatch
  • ADR-002 — ProtocolHandler trait
  • ADR-003 — auth as shared core (IdentityProvider in core, handlers extract credentials)
  • ADR-004 — ALPN string convention (alk/ prefix, one ALPN per connection)
  • ADR-005 — BiStream type definition (handlers receive Connection, not BiStream)
  • ADR-007 — Connection::from_stream (generic single-stream connections — unblocks TCP+TLS, SSH, WebTransport, wasm)
  • ADR-008 — BidiStreamSource trait (the Connection extension point ChannelBidiStreamSource implements)
  • ADR-009 — BiStream as the handler leaf (accept_bi returns BiStream)

• If a TODO references a "Phase B" or a design direction that an ADR has since decided against, the TODO is stale — remove it and align the comments with the ADR. Do not implement the rejected design.

• The call protocol's EventEnvelope shape was derived from the @alkdev/pubsub EventEnvelope (/workspace/@alkdev/pubsub/src/types.ts), which has a working WebSocket client/server implementation. The call protocol refined it with typed event names and structured payloads.