Documentation
¶
Overview ¶
Package voicetools binds an agentbridge.Agent to the voice agent's tool surface with the "Call GPT" semantics (owner decision 2026-08-10, AI-VOICE-SPEECHKIT-TARGET.md External Coding Agent Bridge):
- The bridge is NEVER a standing default. No agent process exists until the user explicitly places the call ("Call GPT") mid-conversation.
- Task tools (gpt_task/gpt_status/gpt_steer/gpt_stop) work only during an active call and fail closed with a speakable hint otherwise.
- hang_up_gpt — or the idle timeout — tears the agent process down again. Threads stay resumable across calls.
- Approval decisions are deliberately NOT a tool: the model can announce a pending approval, but only the host UI answers it (Coordinator.RespondApproval, wired to the overlay card in the device adapter).
Index ¶
Constants ¶
const ( ToolCallGPT = "call_gpt" ToolHangUpGPT = "hang_up_gpt" ToolGPTTask = "gpt_task" ToolGPTStatus = "gpt_status" ToolGPTSteer = "gpt_steer" ToolGPTStop = "gpt_stop" )
Tool names the model sees. call_gpt is the only entry point; everything else requires the active call.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Coordinator ¶
type Coordinator struct {
// contains filtered or unexported fields
}
Coordinator owns the call lifecycle: one optional agent process, its event pump, the idle timer, and the state gpt_status reports.
func New ¶
func New(policy Policy, newAgent func() agentbridge.Agent, notifier Notifier, logger *slog.Logger) *Coordinator
New wires a Coordinator. newAgent is invoked once per call (and the agent closed on hang-up), so no process outlives a call.
func (*Coordinator) CallActive ¶
func (c *Coordinator) CallActive() bool
CallActive reports whether a call is currently open.
func (*Coordinator) Close ¶
func (c *Coordinator) Close()
Close hangs up if needed. Safe to call repeatedly.
func (*Coordinator) RespondApproval ¶
func (c *Coordinator) RespondApproval(ctx context.Context, id string, d agentbridge.Decision) error
RespondApproval answers a pending approval from the HOST UI (overlay card). Deliberately not exposed as a model tool.
func (*Coordinator) Tools ¶
func (c *Coordinator) Tools() []agentkit.Tool
Tools returns the six-call tool surface for agentkit registration.
type Notifier ¶
type Notifier interface {
Narrate(text string)
AnnounceApproval(agentbridge.ApprovalRequest)
}
Notifier is the host sink for narration and approval announcements. The device adapter delivers Narrate as an agent_progress host prompt only while the voice session is listening; AnnounceApproval renders the overlay card.
type Policy ¶
type Policy struct {
// Enabled mirrors the double config gate; false hides nothing but makes
// call_gpt refuse with a speakable reason (the tool list is static per
// session on most realtime providers).
Enabled bool
// Projects is the allowlist; gpt_task resolves aliases against it and
// refuses anything else.
Projects []Project
// DefaultSandbox caps every turn; effective = min(default, project).
DefaultSandbox agentbridge.SandboxMode
// CallIdleHangup ends the call after inactivity (default 10 minutes).
CallIdleHangup time.Duration
// NarrationMinInterval rate-limits progress narration (default 20s).
// Terminal events (done, error, approval) always narrate.
NarrationMinInterval time.Duration
}
Policy is the fail-closed gate for the tool surface.
type Project ¶
type Project struct {
Alias string
Path string
Sandbox agentbridge.SandboxMode
}
Project is one allowlisted working directory (mirrors the [agent_bridge.codex.projects] config entries).
Source Files