telemetry

const (

	// AttrPodID identifies the sdk/pod runtime instance an operation
	// belongs to. Set by the pod controller; absent when the
	// operation runs outside any pod (e.g. a bare agent.Run).
	AttrPodID = "pod.id"

	// AttrAgentID identifies the agent (sdk/agent.Agent.ID) executing
	// the operation. Stable across runs of the same logical agent.
	AttrAgentID = "agent.id"

	// AttrTenantID identifies the tenant on whose behalf the
	// operation is running. Producers should populate this when a
	// tenant boundary is meaningful (multi-tenant SaaS deployments).
	AttrTenantID = "tenant.id"

	// AttrRunID identifies one engine.Run execution
	// (engine.Run.ID). Used as the routing key for engine event
	// envelopes (engine.run.<run_id>.*) and as the correlation
	// key in run-summary spans.
	AttrRunID = "run.id"

	// AttrParentRunID identifies the parent run when one engine.Run
	// dispatches another (multi-agent call chain). Empty for
	// top-level runs.
	AttrParentRunID = "parent.run.id"

	// AttrTaskID identifies the A2A-aligned task an operation
	// belongs to (sdk/agent.Request.TaskID, mirrored into
	// sdk/agent.Result.TaskID). Promoted by sdk/agent.Run into
	// engine.Run.Attributes so engines / nodes / observers can
	// recover it without reaching back through agent state.
	// Optional: empty when the upstream Request did not carry a
	// task identifier.
	AttrTaskID = "task.id"

	// AttrEngineKind identifies the concrete engine.Engine
	// implementation (graph runner, future script engine, remote
	// A2A bridge, ...). Producers SHOULD use a stable short token
	// like "graph", "script", "a2a-remote".
	AttrEngineKind = "engine.kind"

	// AttrRunStatus reports the terminal status of a run. Suggested
	// values: "ok" (clean completion), "interrupted" (cooperative
	// stop), "cancelled" (ctx cancellation), "failed" (any other
	// non-nil error). Consumers SHOULD treat unknown values as
	// "failed".
	AttrRunStatus = "run.status"

	// AttrGraphName identifies the graph definition (graph.GraphDefinition.Name)
	// being executed. Emitted by sdk/graph/runner; absent for
	// non-graph engines.
	AttrGraphName = "graph.name"

	// AttrNodeID identifies one graph node (graph.Node.ID) inside a
	// graph run. Emitted on per-node spans, metrics and log records.
	AttrNodeID = "node.id"

	// AttrActorID is the legacy spelling of AttrAgentID. The "actor"
	// terminology pre-dates the agent / step-actor distinction
	// settled in v0.4: the producer identity (envelope agent_id /
	// span attribute) and the engine.SubjectStep* "actor" segment
	// (graph runner: agent.id + ".node." + node id) are two
	// different dimensions, and the single "actor" name conflated
	// them.
	//
	// Deprecated: use [AttrAgentID]. Removed in v0.5.0.
	AttrActorID = "actor.id"

	// AttrToolName identifies the dispatched tool (tool.Tool.Name).
	// Emitted on tool dispatch spans / metrics.
	AttrToolName = "tool.name"

	// AttrToolCallID identifies a single tool invocation
	// (model.ToolCall.ID assigned by the LLM). Use to correlate the
	// tool_call event envelope with its tool_result.
	AttrToolCallID = "tool.call_id"

	// AttrLLMProvider identifies the LLM vendor / SDK family that
	// served a call ("openai", "anthropic", "bytedance", "ollama",
	// "azure", "deepseek", "minimax", "qwen", ...). The pod
	// controller filters/aggregates on this dimension to apply
	// per-provider rate limits, circuit breakers, and cost
	// tracking; producers MUST use the lowercase short token form
	// for cross-package join-ability.
	AttrLLMProvider = "llm.provider"

	// AttrLLMModel identifies the resolved LLM model name a call
	// targets. Emitted by sdk/llm dispatch spans and by the
	// run-summary span when usage is reported.
	AttrLLMModel = "llm.model"

	// AttrLLMInputTokens / AttrLLMOutputTokens / AttrLLMTotalTokens
	// mirror the model.TokenUsage fields. Producers MUST use these
	// exact keys when reporting LLM usage so dashboards can sum
	// across packages without per-package translation rules.
	AttrLLMInputTokens  = "llm.tokens.input"
	AttrLLMOutputTokens = "llm.tokens.output"
	AttrLLMTotalTokens  = "llm.tokens.total"

	// AttrLLMCachedInputTokens mirrors model.TokenUsage.CachedInputTokens —
	// the subset of input tokens served from the provider's prompt
	// cache. It is always a subset of AttrLLMInputTokens (enforced
	// by the adapter normalisation in sdkx/llm) so dashboards can
	// compute a uniform hit-rate as cached / input without
	// provider-specific branching. Producers MUST omit the
	// attribute when zero (no cache hit reported, or provider
	// does not expose a cache breakdown) to match the
	// model.TokenUsage `omitempty` wire convention and keep span
	// payloads slim on the common path.
	AttrLLMCachedInputTokens = "llm.tokens.input.cached"

	// AttrLLMCostMicros is the cost of the call in micro-units of
	// the configured currency (e.g. micro-USD = USD * 1_000_000).
	// Integer math avoids float drift in cumulative budgets. Zero
	// when the host has no pricing catalog configured.
	AttrLLMCostMicros = "llm.cost.micros"

	// AttrLLMLatencyMs is the wall-clock duration of the call in
	// milliseconds.
	AttrLLMLatencyMs = "llm.latency.ms"

	// AttrConversationID identifies the conversation an operation
	// belongs to. Shared by sdk/history (transcript / DAG / archive),
	// sdk/recall (long-term memory writes keyed by conversation),
	// sdk/kanban (when the kanban scope mirrors a conversation), and
	// the future sdk/pod controller (multi-agent pods that share a
	// conversation context). Producers MUST use this constant
	// instead of legacy snake_case "conversation_id" string literals
	// so dashboards can join across the four packages by a single
	// dimension.
	AttrConversationID = "conversation.id"

	// AttrDatasetID identifies a knowledge dataset. Emitted by
	// sdk/knowledge (rebuild / write / delete), the knowledgenode
	// graph node, and any retrieval span that targets one specific
	// dataset. Cross-package dimension; needed for "errors per
	// dataset" / "latency per dataset" splits in the dashboard.
	AttrDatasetID = "dataset.id"

	// AttrErrorMessage carries the human-readable error string on
	// log records and span events. Aligned with OTel semantic-
	// conventions `exception.message` semantically, but kept under
	// the shorter `error.message` key because flowcraft logs do not
	// otherwise emit the OTel exception-event shape (no
	// `exception.type` / `exception.stacktrace`); a single canonical
	// key for the message text is enough.
	//
	// Producers MUST use this constant rather than the legacy
	// "error" key so dashboards can filter by "error.message exists"
	// uniformly. The "error" key was used inconsistently across the
	// SDK (sometimes the message, sometimes a code) — switching to
	// a single canonical name makes the intent unambiguous.
	AttrErrorMessage = "error.message"

	// AttrKanbanCardID identifies one kanban Card (kanban.Card.ID).
	AttrKanbanCardID = "kanban.card.id"

	// AttrKanbanCardKind identifies the card kind ("task" / "signal" / ...).
	AttrKanbanCardKind = "kanban.card.kind"

	// AttrKanbanProducerID identifies the agent that produced a
	// card; mirrors kanban.WithProducerID.
	AttrKanbanProducerID = "kanban.producer.id"

	// AttrKanbanTargetAgentID identifies the consumer agent a task
	// card is targeted at.
	AttrKanbanTargetAgentID = "kanban.target.agent.id"
)

const (
	InstrumentationName = "flowcraft"
	ServiceName         = "flowcraft"
	ServiceVersion      = "0.1.0"
)