Documentation
¶
Overview ¶
Package toolbridge implements a generic HTTP client for the SpeechKit voice-agent tool bridge wire contract "speechkit.toolbridge.v1" (docs/server/toolbridge.v1.md).
The bridge is deployment-neutral: it knows nothing about who operates the remote endpoint. All tenant semantics (tool curation, authorization, entitlements, approval) live behind the two configured URLs; SpeechKit only forwards the opaque per-session credential the fronting proxy supplied at session creation as an Authorization bearer.
Fail-closed behavior:
- no credential -> no manifest, session runs tool-less
- manifest fetch failure -> session runs tool-less
- invoke failure / denial -> structured error payload ({error, user_guidance}) the model can verbalize; the session never dies
- hard per-session call cap (default 20)
The package is intentionally platform-neutral (no build tag) so its unit tests run on every OS; the linux-only server wiring adapts it to the voiceagent.SessionToolRouter interface.
Index ¶
Constants ¶
const ( // DefaultTimeout bounds one invoke round-trip. DefaultTimeout = 10 * time.Second // DefaultMaxCallsPerSession is the hard per-session invoke cap. DefaultMaxCallsPerSession = 20 )
const WireVersion = "speechkit.toolbridge.v1"
WireVersion is the toolbridge wire-contract version this client speaks.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Bridge ¶
type Bridge struct {
// contains filtered or unexported fields
}
Bridge is a concurrency-safe toolbridge HTTP client shared across sessions.
func New ¶
New constructs a Bridge. Returns an error when either URL is missing so a misconfigured deployment fails at wiring time, not mid-session.
func (*Bridge) Definitions ¶
Definitions returns the tool manifest for the session, cached per credential for manifestCacheTTL. A session without a credential gets no tools (fail-closed). Errors mean "run tool-less", never "kill the session".
func (*Bridge) Execute ¶
func (b *Bridge) Execute(ctx context.Context, session Session, tool string, args map[string]any) (map[string]any, bool)
Execute invokes one tool call. The returned map is always a model-facing tool response payload; ok=false is returned only when no usable payload could be produced (the caller substitutes a generic structured error). Denial envelopes from the remote endpoint are mapped to {error:{code,message}, user_guidance:...} so the model verbalizes the denial instead of hallucinating a result.
type Options ¶
type Options struct {
// ManifestURL is the GET endpoint returning the tool manifest. Required.
ManifestURL string
// InvokeURL is the POST endpoint executing one tool call. Required.
InvokeURL string
// Timeout bounds one HTTP round-trip. Zero uses DefaultTimeout.
Timeout time.Duration
// MaxCallsPerSession hard-caps invokes per session ID. Zero uses
// DefaultMaxCallsPerSession.
MaxCallsPerSession int
// HTTPClient overrides the transport (tests). Nil builds one from Timeout.
HTTPClient *http.Client
// Clock overrides the time source (tests). Nil uses time.Now.
Clock func() time.Time
}
Options configures a Bridge.
Source Files