micro.go

// Package micro is a pluggable framework for services and agents.
package micro

import (
	"context"
	"time"

	"go-micro.dev/v6/agent"
	"go-micro.dev/v6/client"
	"go-micro.dev/v6/model"
	"go-micro.dev/v6/server"
	"go-micro.dev/v6/service"
	"go-micro.dev/v6/store"
	"go-micro.dev/v6/wrapper/x402"
	"go.opentelemetry.io/otel/trace"
)

type serviceKey struct{}

// Service is the interface for a go-micro service.
type Service = service.Service

// Agent is the interface for an AI agent that manages services.
type Agent = agent.Agent

// AgentResponse is what an agent returns from Ask or a resumed run.
type AgentResponse = agent.Response

// AgentStream is a stream of tool execution events followed by final-answer chunks.
type AgentStream = agent.AgentStream

// AgentOption configures an Agent.
type AgentOption = agent.Option

// AgentRun records one agent execution.
type AgentRun = agent.Run

// Group is a set of services that share lifecycle management.
type Group = service.Group

type Option = service.Option

type Options = service.Options

// Event is used to publish messages to a topic.
type Event interface {
	// Publish publishes a message to the event topic
	Publish(ctx context.Context, msg interface{}, opts ...client.PublishOption) error
}

// Type alias to satisfy the deprecation.
type Publisher = Event

// NewService creates a new service with the given name and options. It is
// the canonical constructor, symmetric with NewAgent and NewFlow.
//
//	service := micro.NewService("greeter")
//	service := micro.NewService("greeter", micro.Address(":8080"))
func NewService(name string, opts ...Option) Service {
	return service.New(append([]Option{service.Name(name)}, opts...)...)
}

// New is a deprecated alias for NewService.
//
// Deprecated: use NewService(name, opts...) — symmetric with NewAgent and NewFlow.
func New(name string, opts ...Option) Service {
	return NewService(name, opts...)
}

// NewAgent creates a new AI agent that manages the given services.
// Attach it with service.Handle(agent) to share a service's RPC server and
// lifecycle, or call agent.Run() to host it independently.
//
//	agent := micro.NewAgent("task-mgr",
//	    micro.AgentServices("task"),
//	    micro.AgentPrompt("You manage tasks."),
//	    micro.AgentProvider("anthropic"),
//	)
//	agent.Run()
func NewAgent(name string, opts ...AgentOption) Agent {
	return agent.New(append([]AgentOption{agent.Name(name)}, opts...)...)
}

// AgentServices sets which services the agent manages.
func AgentServices(names ...string) AgentOption { return agent.Services(names...) }

// AgentPrompt sets the agent's system prompt.
func AgentPrompt(p string) AgentOption { return agent.Prompt(p) }

// AgentProvider sets the LLM provider.
func AgentProvider(p string) AgentOption { return agent.Provider(p) }

// AgentModel sets the LLM model.
func AgentModel(m string) AgentOption { return agent.Model(m) }

// AgentAPIKey sets the API key for the LLM provider.
func AgentAPIKey(k string) AgentOption { return agent.APIKey(k) }

// AgentBaseURL sets the base URL for the LLM provider. Use this to point
// the provider at a non-default endpoint (e.g., local Ollama, a proxy).
func AgentBaseURL(url string) AgentOption { return agent.BaseURL(url) }

// AgentMaxTokens caps provider output tokens (0 leaves the provider default).
func AgentMaxTokens(n int) AgentOption { return agent.MaxTokens(n) }

// AgentEffort sets provider-specific reasoning effort.
func AgentEffort(level string) AgentOption { return agent.Effort(level) }

// AgentTemperature sets sampling temperature, including zero, for supporting providers.
func AgentTemperature(t float64) AgentOption { return agent.Temperature(t) }

// AgentMaxTools caps the advertised tool count (0 leaves it unlimited).
func AgentMaxTools(n int) AgentOption { return agent.MaxTools(n) }

// ApproveFunc gates an agent's tool calls before they run.
type ApproveFunc = agent.ApproveFunc

// AgentMaxSteps bounds tool executions per Ask (0 = unbounded) — a
// stopping condition for autonomous agents.
func AgentMaxSteps(n int) AgentOption { return agent.MaxSteps(n) }

// AgentLoopLimit bounds how many times an agent may repeat the same tool
// call (same arguments) in one Ask before it's refused as a no-progress
// loop. 0 disables loop detection (defaults on).
func AgentLoopLimit(n int) AgentOption { return agent.LoopLimit(n) }

// AgentApproveTool sets a human-in-the-loop / policy hook called before
// each action the agent takes.
func AgentApproveTool(fn ApproveFunc) AgentOption { return agent.ApproveTool(fn) }

// AgentMaxSpend bounds paid x402 tool spend per Ask, in the asset's smallest
// unit (0 = disabled). Calls that would exceed it are refused before payment.
func AgentMaxSpend(amount int64) AgentOption { return agent.MaxSpend(amount) }

// AgentToolSpend records the x402 price for a tool, in the asset's smallest
// unit, so AgentMaxSpend can reserve budget before execution.
func AgentToolSpend(tool string, amount int64) AgentOption {
	return agent.ToolSpend(tool, amount)
}

// AgentPayer configures the wallet/signing hook used to settle x402-paid tools.
func AgentPayer(p x402.Payer) AgentOption { return agent.Payer(p) }

// AgentBudget bounds autonomous x402 payments per Ask, in the asset's smallest
// unit (0 = unlimited).
func AgentBudget(amount int64) AgentOption { return agent.Budget(amount) }

// AgentModelCallTimeout sets the timeout for each provider Generate call.
func AgentModelCallTimeout(d time.Duration) AgentOption { return agent.ModelCallTimeout(d) }

// AgentModelRetry sets the provider retry budget and backoff for transient failures.
func AgentModelRetry(maxAttempts int, backoff time.Duration) AgentOption {
	return agent.ModelRetry(maxAttempts, backoff)
}

// AgentToolCallTimeout sets the timeout for each agent tool execution.
func AgentToolCallTimeout(d time.Duration) AgentOption { return agent.ToolCallTimeout(d) }

// AgentToolRetry sets the tool retry budget and backoff for transient failures.
// Attempts include the first call. Retries are opt-in because tools can have
// side effects; keep handlers idempotent before enabling this.
func AgentToolRetry(maxAttempts int, backoff time.Duration) AgentOption {
	return agent.ToolRetry(maxAttempts, backoff)
}

// Memory is an agent's pluggable conversation memory.
type Memory = agent.Memory

// MemoryRecall is implemented by memory backends that retrieve prior context.
type MemoryRecall = agent.MemoryRecall

// ToolFunc handles a custom agent tool call.
type ToolFunc = agent.ToolFunc

// NewMemory returns the default store-backed agent memory.
func NewMemory(s store.Store, key string, limit int) Memory { return agent.NewMemory(s, key, limit) }

// NewRetrievalMemory returns store-backed memory with bounded active context
// and durable retrieval over every prior turn.
func NewRetrievalMemory(s store.Store, key string, activeLimit int) Memory {
	return agent.NewRetrievalMemory(s, key, activeLimit)
}

// NewCompactingMemory returns store-backed memory with deterministic
// summarization and retrieval controls.
func NewCompactingMemory(s store.Store, key string, maxMessages, keepRecent int) Memory {
	return agent.NewCompactingMemory(s, key, maxMessages, keepRecent)
}

// NewInMemory returns non-persistent agent memory.
func NewInMemory(limit int) Memory { return agent.NewInMemory(limit) }

// AgentSession selects an independent persistent conversation within an agent.
func AgentSession(id string) AgentOption { return agent.Session(id) }

// AgentMemory sets the agent's conversation memory (default: store-backed).
func AgentMemory(m Memory) AgentOption { return agent.WithMemory(m) }

// AgentRetrievalMemory enables deterministic default-memory retrieval without
// compaction; activeLimit bounds active context while every turn is archived.
func AgentRetrievalMemory(activeLimit int) AgentOption { return agent.RetrievalMemory(activeLimit) }

// AgentCompactMemory enables deterministic default-memory compaction and
// retrieval for long-running agents.
func AgentCompactMemory(maxMessages, keepRecent int) AgentOption {
	return agent.CompactMemory(maxMessages, keepRecent)
}

// AgentMemoryRecallLimit bounds recalled archived turns injected per Ask.
func AgentMemoryRecallLimit(n int) AgentOption { return agent.MemoryRecallLimit(n) }

// AgentTool registers a custom tool the agent can call, beyond its services.
func AgentTool(name, description string, properties map[string]any, handler ToolFunc) AgentOption {
	return agent.WithTool(name, description, properties, handler)
}

// AgentA2A makes the agent serve the A2A protocol on addr (e.g. ":4000")
// when it runs, so other agents can reach it directly by URL without a
// separate gateway.
func AgentA2A(addr string) AgentOption { return agent.WithA2A(addr) }

// AgentWrapTool registers a tool-execution wrapper — the tool-side
// analog of a client/server middleware wrapper. Each wrapper takes the
// next handler and returns a new one; run code before next(...) for
// "before", after it for "after". Use it for logging, metrics, retries,
// or policy. Wrappers run outside the built-in guardrails, so they see
// every call and result, including refusals.
func AgentWrapTool(w ...model.ToolWrapper) AgentOption {
	return agent.WrapTool(w...)
}

// AgentTraceProvider enables OpenTelemetry spans for agent runs, model calls,
// tool calls, delegation, and failures.
func AgentTraceProvider(tp trace.TracerProvider) AgentOption { return agent.TraceProvider(tp) }

// AgentWithCheckpoint sets the durability backend for agent Ask runs.
// It uses the same Checkpoint interface as flows so services, agents,
// and workflows can share one execution history backend.
func AgentWithCheckpoint(c Checkpoint) AgentOption { return agent.WithCheckpoint(c) }

// AgentPending returns checkpointed agent runs that have not completed.
// Use it at process startup to discover agent work that should be resumed.
func AgentPending(ctx context.Context, a Agent) ([]AgentRun, error) { return agent.Pending(ctx, a) }

// AgentResume resumes a checkpointed agent run by id. Completed runs return
// the persisted response, including completed tool-call metadata, without
// calling the model or replaying tool calls. Incomplete runs resume from the
// saved prompt plus completed tool checkpoints; a provider call interrupted
// mid-stream is retried rather than continued byte-for-byte.
func AgentResume(ctx context.Context, a Agent, runID string) (*AgentResponse, error) {
	return agent.Resume(ctx, a, runID)
}

// AgentResumePending resumes every incomplete checkpointed agent run, oldest
// first. It returns the first run id that fails again so startup recovery loops
// can leave the durable backlog visible instead of swallowing the failure.
func AgentResumePending(ctx context.Context, a Agent) (string, error) {
	return agent.ResumePending(ctx, a)
}

// AgentResumeInput resumes a checkpointed agent run waiting for human input.
func AgentResumeInput(ctx context.Context, a Agent, runID, input string) (*AgentResponse, error) {
	return agent.ResumeInput(ctx, a, runID, input)
}

// AgentResumeStreamAsk resumes a checkpointed agent run by id and streams the
// resulting tool events and final answer.
func AgentResumeStreamAsk(ctx context.Context, a Agent, runID string) (AgentStream, error) {
	return agent.ResumeStreamAsk(ctx, a, runID)
}

// Checkpoint stores agent execution progress for recovery.
type Checkpoint = agent.Checkpoint

// StoreCheckpoint returns a store-backed Checkpoint whose run keys are
// namespaced under scope (the agent name). A nil store uses
// the default store.
func StoreCheckpoint(s store.Store, scope string) Checkpoint {
	return agent.StoreCheckpoint(s, scope)
}

// NewGroup creates a service group for running multiple services
// in a single binary with shared lifecycle management.
func NewGroup(svcs ...Service) *Group {
	return service.NewGroup(svcs...)
}

// FromContext retrieves a Service from the Context.
func FromContext(ctx context.Context) (Service, bool) {
	s, ok := ctx.Value(serviceKey{}).(Service)
	return s, ok
}

// NewContext returns a new Context with the Service embedded within it.
func NewContext(ctx context.Context, s Service) context.Context {
	return context.WithValue(ctx, serviceKey{}, s)
}

// NewEvent creates a new event publisher.
func NewEvent(topic string, c client.Client) Event {
	if c == nil {
		c = client.NewClient()
	}

	return &event{c, topic}
}

// RegisterHandler is syntactic sugar for registering a handler.
func RegisterHandler(s server.Server, h interface{}, opts ...server.HandlerOption) error {
	return s.Handle(s.NewHandler(h, opts...))
}

// RegisterSubscriber is syntactic sugar for registering a subscriber.
func RegisterSubscriber(topic string, s server.Server, h interface{}, opts ...server.SubscriberOption) error {
	return s.Subscribe(s.NewSubscriber(topic, h, opts...))
}

// AgentWithApproval installs context-aware durable tool approval.
func AgentWithApproval(fn agent.ApprovalFunc) AgentOption { return agent.WithApproval(fn) }

// AgentResumeApproval resolves a saved tool approval and resumes its run.
func AgentResumeApproval(ctx context.Context, a Agent, runID, approvalID string, approved bool, reason string) (*AgentResponse, error) {
	return agent.ResumeApproval(ctx, a, runID, approvalID, approved, reason)
}