Skip to content

Carry ToolContract over the serve wire so a host authorizes from metadata instead of a name side-table #3286

Description

@macanderson

stella-serve hands the host {name, input} (crates/stella-serve/src/frame.rs) plus a bare ToolSchema list (crates/stella-serve/src/session.rs). A host embedding Stella therefore has to maintain its own side-table mapping tool names to a capability model — the exact duplication #2716 exists to remove, and it goes stale the moment a tool is added.

ToolContract now exists (PR #3281). This is #2716 §5.

Definition of done

  • SessionSpec.tools: Vec<ToolSchema> becomes Vec<ToolContract>. ToolRequest frames are unchanged.
  • Export the schema under docs/wire/make wire-schema is a gate step and .github/workflows/wire-schema.yml covers the paths ci.yml ignores.
  • Add the version field to ToolContract here, with this as its consumer: a wire type an external host pins against is exactly what a contract version is for. (It was omitted from feat(stella-tools): ToolContract, AuthzGate port and the gate decorator — the governance half of tool-first #3281 rather than shipped unread.)
  • Gate-placement parity: RemoteToolExecutor's pre-frame gate (crates/stella-serve/src/remote.rs) must stay byte-parity with the CLI's and grow the same AuthzGate call. A host-supplied principal arrives as Principal::Host(id), which stella-core deliberately does not interpret (invariant feat(brand): Stella logo assets + README logo #1).
  • stella-parity gets a row: contract-carrying tools must have witnessed parity across the CLI and serve surfaces, or a capability ships on one and silently misses the other.

Constraint

stella-serve does not depend on stella-tools today. Resolving contracts host-side must not create that edge — the contract type lives in stella-protocol, which both already depend on.

Refs #2716, #3281.

Metadata

Metadata

Assignees

No one assigned

    Labels

    triageUntyped request — convert by adding bug / feature / epic

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions