provider

type Handler interface {
	HandleToolCall(ctx context.Context, msg toolregistry.ToolCallMessage) (toolregistry.ToolResultMessage, error)
}

type Options struct {
	// SinkName identifies the Pulse sink used for subscribing.
	// When empty, defaults to "provider".
	SinkName string

	// ResultEventType is the Pulse entry type used for publishing results.
	// When empty, defaults to toolregistry.ResultEventKey.
	ResultEventType string

	// SinkAckGracePeriod configures the Pulse sink acknowledgement grace
	// period. When non-zero, Serve passes it to the sink.
	//
	// This value must be identical across all providers using the same sink
	// name for a given toolset stream.
	//
	// Important: If a tool call can take longer than the sink ack grace
	// period and the provider only Ack's after publishing the tool result,
	// Pulse may reclaim and re-deliver the call while it is still in flight.
	// Deployments should set this high enough to cover worst-case tool
	// execution time.
	SinkAckGracePeriod time.Duration

	// Pong acknowledges health pings emitted by the registry gateway.
	// Providers must supply this to participate in health tracking.
	Pong func(ctx context.Context, pingID string) error

	// PongTimeout bounds how long Serve will wait for the Pong callback to
	// return when handling a ping message.
	//
	// Contract:
	//   - Ping messages exist solely for toolset health tracking; they are not part
	//     of tool execution correctness.
	//   - Pong failures must never crash the provider loop. If the registry is
	//     temporarily unreachable, the toolset should be marked unhealthy by the
	//     registry, and the provider should continue draining the stream so it can
	//     recover without a restart loop.
	//
	// When 0, Serve defaults to a short value suitable for transient outages.
	PongTimeout time.Duration

	// MaxConcurrentToolCalls caps the number of tool calls executed
	// concurrently by this provider (worker pool size).
	//
	// Serve drains the toolset stream in a dedicated loop and enqueues tool
	// calls for workers; it does not execute tool calls inline. This option
	// exists to bound provider-side resource usage (CPU, memory, upstream
	// concurrency) and to avoid overload amplification.
	//
	// When 0, Serve defaults to a small, safe value.
	MaxConcurrentToolCalls int

	// MaxQueuedToolCalls bounds how many tool calls may be buffered for worker
	// execution. When 0, defaults to a value derived from MaxConcurrentToolCalls.
	//
	// The provider subscription loop never blocks on tool execution. Instead,
	// it enqueues calls and continues draining the toolset stream so it can
	// respond to health pings.
	MaxQueuedToolCalls int

	// Logger is used for provider internal logging. When nil, defaults to a noop logger.
	Logger telemetry.Logger

	// Tracer is used for provider spans. When nil, defaults to a noop tracer.
	Tracer telemetry.Tracer
}