Documentation
¶
Overview ¶
Package agentmessage implements the v1 agent-message provenance sentinel contract (issue #1465): inter-session messages delivered by the agentd send_message tool carry a machine-detectable origin marker so frontends and receiving agents can distinguish agent traffic from human input.
Sentinel format v1 — a single line at the START of the delivered message, followed by one newline and the message text:
<!-- lsp:agent-message-v1 {"fromSession":"ses_..."} -->
The format is a stable API contract locked by the golden fixtures in testdata/ (authoritative), following the attachment-manifest-v1 precedent. Changes are additive-only; any format change requires a new version marker while this parser keeps supporting v1. Unknown versions and unknown JSON keys parse as plain text (forward compatibility). fromSession is always present in a valid v1 sentinel; workspace is a legal v1 key that v1 senders never emit — it exists so a future cross-workspace sender (#1260) needs no v2 (omitted implies a local, same-workspace sender).
Values ride as JSON, so structurally hostile content (the --> terminator, newlines, quotes) is escaped by the encoder and can never break the line — but session IDs come from the live session list at the sender (agentd validates existence by ID), and the sentinel is provenance metadata, NOT authentication: every session in a workspace shares the same pod credential, so a sender can always claim a sibling's ID. Compose is idempotent: any existing leading v1 sentinel is stripped before the fresh one is prepended, so Compose(Compose(m)) == Compose(m) and a re-sent message never double-sentinels.
Index ¶
Constants ¶
const ( ModeInjected = "injected" ModeSelfDeclared = "self-declared" )
Origin modes (#1469 hybrid ruling).
Variables ¶
var ErrEmptyFromSession = errors.New("fromSession is required")
ErrEmptyFromSession rejects composing without the mandatory field.
Functions ¶
Types ¶
type Origin ¶
type Origin struct {
FromSession string `json:"fromSession"`
Workspace string `json:"workspace,omitempty"`
Mode string `json:"mode,omitempty"`
}
Origin is the provenance metadata carried by the sentinel. FromSession is the sending session's ID (mandatory). Workspace names the sending workspace for cross-workspace senders (future, #1260); omitted means the sender is local to the receiving workspace. Mode labels HOW the origin was established (#1469 hybrid ruling): "injected" — stamped by the platform's harness plugin from the harness's own session identity; "self-declared" — supplied by the sending model and validated by-ID (the degraded-pod fallback). The sentinel is metadata, never authentication: both modes carry the same trust boundary (a session can claim a sibling's ID under the shared pod credential) — the mode makes the DEGREE of platform attestation visible, nothing more.
func Parse ¶
Parse detects a leading v1 sentinel line and returns the origin, whether one was found, and the message text with the sentinel line (and its newline) removed. Anything else — no sentinel, interior or forged lines, unknown versions, malformed payloads, a missing or non-string fromSession, a non-string workspace — returns found=false with the text unchanged: the message payload is never broken by an unparseable sentinel. Known keys are matched CASE-SENSITIVELY and type-strictly (parity with the TS port, locked by shared fixtures); unknown keys are tolerated (additive-only contract).
Source Files