Skip to content

[Enhancement]: Add an opaque annotation channel to tool-execution intercepts #445

Description

@bbednarski9

Problem

Relay's tool-execution intercept chain carries only the application-visible Json result. Relay needs an adjacent, optional metadata channel so middleware can annotate a tool execution without changing that result or imposing a result schema on the caller.

Relay-owned shape

pub struct ToolExecutionFrame {
    pub result: Json,
    pub annotation: Option<Json>,
}

pub struct ToolExecutionFrameOutcome {
    pub frame: ToolExecutionFrame,
    pub pending_marks: Vec<PendingMarkSpec>,
}

Add a frame-aware callback and continuation variant to the existing tool-execution registry:

ToolExecutionFrameFn(
    tool_name: &str,
    args: Json,
    next: ToolExecutionFrameNextFn,
) -> Result<ToolExecutionFrameOutcome>

Required semantics

  • Raw and frame-aware callbacks use one registry, priority order, and continuation chain.
  • The existing raw callback API and application-visible Json result are unchanged.
  • annotation is opaque JSON. Relay may transport, sanitize, and export it, but does not define or interpret its schema. JSON null means absent.
  • Frame-aware middleware may explicitly preserve, replace, or remove the annotation.
  • A raw callback preserves a downstream annotation only when it calls next exactly once and returns a structurally unchanged downstream result. Ambiguous cases drop the annotation.
  • Existing continuation, error, short-circuit, and pending-mark behavior remains unchanged.
  • The frame-aware variant is additive across Relay's existing in-process, worker, and native plugin surfaces.

Acceptance criteria

  • Preserve, replace, and remove work through a mixed raw/frame-aware chain.
  • Raw pass-through preserves annotations only in the unambiguous case above.
  • Existing raw-result callers remain behaviorally compatible.
  • No second registry or execution chain is introduced.

Out of scope

  • A canonical tool-result schema.
  • Changes to harness-owned tool dispatch, receipt, or result semantics.
  • A new service, process, or sidecar.

Metadata

Metadata

Assignees

Labels

Improvementimprovement to existing functionalityNeeds TriageIssue needs Triaged

Projects

No projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions