agent

type Conversation struct {
	// contains filtered or unexported fields
}

type Deps struct {
	// Model is the resolved language model (mock, anthropic, or gateway).
	Model agentcore.Model
	// ModelMode is "mock", "anthropic", or "gateway". It gates the gateway
	// attribution headers; those are never sent in other modes.
	ModelMode string
	// Source supplies a project's capability documents. Nil means the
	// assistant runs with no provider capabilities.
	Source capability.Source
	// Persona overrides the identity/voice section of the system prompt
	// (empty uses [DefaultPersona]). The fixed operating rules always follow
	// it — see [BuildSystemPrompt].
	Persona string
	// Emitter delivers usage events. Required (a no-op emitter is fine).
	Emitter *usage.Emitter
	// HTTPClient fetches provider knowledge. Nil uses the default client.
	HTTPClient *http.Client
	// History replays and records conversation turns per (project, contextId),
	// making follow-up messages in the same A2A context conversational. Nil
	// disables memory: every turn is answered standalone.
	History history.Store
	// SummarizationDisabled skips compaction entirely: loadHistory behaves
	// exactly as it did before summarization existed — plain Truncate, no
	// extra summarize model call, no History.Compact call ever issued. False
	// (the default) compacts aging history once replay crosses
	// CompactionThresholdRatio of the token budget. An escape hatch for
	// load-testing or a customer that wants zero synthetic model calls
	// injected into their history (see
	// docs/conversation-summarization-design.md "Still open").
	SummarizationDisabled bool
	// Memory backs the memory_remember / memory_forget tools: durable,
	// project-scoped facts that persist across conversations and users (unlike
	// History, which is per-conversation and windowed). Nil disables the
	// feature — no tools are composed.
	Memory memory.Store
	// PlatformAPI backs the base platform tools (resources_list,
	// resources_get, schema_get, locations_list, quota_get and, when a plan
	// token key is configured, the write path). Unlike a provider's tools
	// these are not entitled per project and not namespaced under a service:
	// every project has them. They act as the CALLER — composition binds the
	// client to the caller's own bearer token and the turn's project — so the
	// service reads nothing of its own. Nil disables them entirely.
	PlatformAPI *projectapi.Client
	// PlanTokenKey enables the base tools' change path (resources_validate,
	// resources_plan, resources_apply). Empty leaves it out: a service that
	// cannot check a token must not issue one. Ignored when PlatformAPI is
	// nil. See internal/plantoken.
	PlanTokenKey []byte
	// GapReports backs the report_capability_gap__<service> tools: lets
	// the model flag that a provider service is missing a tool or lookup
	// a user needed, written to THAT PROVIDER's own project (see
	// internal/gapreport), never to params.ProjectName. Nil disables the
	// feature entirely.
	GapReports gapreport.Store
	// CapabilityIdentityForwardHosts is the operator-sanctioned set of MCP
	// endpoint hosts that may receive the caller's own bearer token and the
	// turn's project. Empty (the default) forwards to nobody; a capability
	// document naming an endpoint never sanctions it. See internal/capability.
	CapabilityIdentityForwardHosts []string
	// AllowPrivateCapabilityNetworks relaxes the capability SSRF guard's
	// loopback/RFC1918 block (link-local/metadata stay blocked either way). The
	// platform's capability endpoints are in-cluster private ClusterIPs, so real
	// deployments set this true; it is threaded into capability.Compose.
	AllowPrivateCapabilityNetworks bool
	// StepLimit and MaxOutputTokens override the loop defaults when > 0.
	// HistoryTokenBudget overrides DefaultHistoryTokenBudget when > 0.
	StepLimit          int
	MaxOutputTokens    int
	HistoryTokenBudget int
	// TurnTimeout bounds the total wall-clock time of one turn when > 0;
	// otherwise DefaultTurnTimeout applies. A negative value disables the
	// per-turn deadline (the turn is bounded only by the caller's context).
	TurnTimeout time.Duration
	// MaxRetries, RetryBaseDelay, and RetryMaxDelay tune the loop's transient-
	// failure retry (rate limit / overload / transient transport). Zero values
	// use the agentcore defaults; a negative MaxRetries disables retries.
	MaxRetries     int
	RetryBaseDelay time.Duration
	RetryMaxDelay  time.Duration
	// Logger receives orchestration logs. Nil discards them.
	Logger *slog.Logger
	// Metrics records assistant_conversation_turn_duration_seconds,
	// assistant_tool_call_total, assistant_model_call_duration_seconds,
	// assistant_history_compaction_total, and (via capability.ComposeOptions)
	// assistant_gap_report_total — see internal/metrics. Unlike Memory or
	// GapReports this is never optional: [New] backs a nil value with a
	// fresh, unshared instance (mirroring the Logger fallback just above) so
	// metrics always record. Production boot shares one instance between
	// this and server.Deps.Metrics so both land on the same /metrics
	// endpoint.
	Metrics *appmetrics.Metrics
}

type Event struct {
	Kind     EventKind
	Text     string
	ToolName string
	// ToolCallID correlates an [EventToolCall] with its [EventToolResult];
	// providers that omit an id leave it empty.
	ToolCallID string
	// ToolInput is the call's raw JSON arguments ([EventToolCall] only). It is
	// caller-summarized before leaving the service — see internal/a2a.
	ToolInput json.RawMessage
	// ToolFailed marks an [EventToolResult] the tool reported as an error.
	ToolFailed bool
}

type EventKind string

type Mention struct {
	Kind     string
	Name     string
	APIGroup string
}

type Params struct {
	// UserText is the user's message.
	UserText string
	// ProjectName scopes capabilities and metering. Empty disables metering.
	ProjectName string
	// ContextID is the A2A contextId == conversation id == metering resource.
	ContextID string
	// TaskID is the A2A task id, used for logging.
	TaskID string
	// Mentions are the resources the user referenced with "@kind/name"; they
	// add one system note to this turn (see mentionNote).
	Mentions []Mention
}

type Result struct {
	State       State
	Text        string
	Error       string
	Usage       UsageSummary
	UsageEvents []usage.Event
}

type State string

type Stream struct {
	// contains filtered or unexported fields
}

type UsageSummary struct {
	InputTokens              int64
	OutputTokens             int64
	CacheReadTokens          int64
	CacheWriteTokens         int64
	TokenEventCount          int
	ToolInvocationEventCount int
	// Emitted is true when a collector was configured and accepted the batch.
	Emitted bool
}