UTCP Peer and JPEN-as-Tool

UTCP Peer and JPEN-as-Tool

Call tools under capability gates over SBI TCP. Stage a JPEN envelope and apply it as pipeline.envelope.apply.

Time: 30 minutes
Level: Intermediate
Profile: :core for peer; :cluster when packing live JPEN
Prerequisites: Basic Janus, SBI, cluster promises (for JPEN section)

---

Why UTCP?

Agents and services need a tool RPC that cannot skip capability checks. REST-ish JSON over TCP is easy to sketch and hard to trust. Janus native UTCP (SPEC-244) uses the same SBI wire family as the rest of the stack.

---

In-process first

{.profile: core.}

use std.utcp.registry as registry
use std.utcp.session as session

pub func main() -> i32 do
    _ = registry.reset()
    let tid = registry.register_compile_module_demo()
    let s = session.open()
    // Missing caps → CAP_MISMATCH (-1403)
    _ = session.invoke(s, tid)
    _ = session.present_known(s, 0)
    _ = session.present_known(s, 1)
    // Full caps → OK (1)
    _ = session.invoke(s, tid)
    _ = session.close(s)
    return 0
end

---

Peer over TCP

use std.utcp.peer as peer

let port = peer.listen(0)
_ = peer.start_accept_pool(1, 1)
let h = peer.client_connect(port)
_ = peer.client_present2(h, 0, 1)
_ = peer.client_invoke(h, tool_id)
_ = peer.client_close(h)
_ = peer.join()
_ = peer.close_listen()

Session protocol on one connection:

1. PRESENT — accumulate caps
2. STAGE (optional) — binary payload (JPEN, LEAS, or CHNK chunks)
3. INVOKE — cap check + tool dispatch
4. RESET — clear caps and stage

Wire and interop modes (HTTP / JSON-line vs normative SBI):
UTCP over SBI.

Discovery without JSON: invoke utcp.manual (no caps) and read the MANL body via peer.client_last_has_manl / client_manual_*.

---

JPEN as a tool

Requires :cluster to pack a live pipeline envelope, then UTCP to carry it:

1. Pack JPEN with std.cluster.promise (pipeline_envelope_pack_scratch).
2. Enable cluster peer CAP for apply.
3. Register pipeline.envelope.apply (intern index 2).
4. client_stage the bytes, client_present pipeline cap, client_invoke.

Proof: ./scripts/zb test-utcp-jpen-tool.

---

Next

• Concurrent clients: start_accept_pool(n, workers) + multiple handles
• Reference: std.utcp
• Spec: SPEC-244 (project _COMPLETED/)