@stigmer/protos 0.0.34

package/ai/stigmer/agentic/agentexecution/v1/subagent_pb.d.ts

@@ -0,0 +1,129 @@
+import type { GenFile, GenMessage } from "@bufbuild/protobuf/codegenv1";
+import type { PendingApproval } from "./approval_pb";
+import type { SubAgentStatus } from "./enum_pb";
+import type { AgentMessage, ToolCall } from "./message_pb";
+import type { UsageMetrics } from "./usage_pb";
+import type { JsonObject, Message } from "@bufbuild/protobuf";
+/**
+ * Describes the file ai/stigmer/agentic/agentexecution/v1/subagent.proto.
+ */
+export declare const file_ai_stigmer_agentic_agentexecution_v1_subagent: GenFile;
+/**
+ * Represents a sub-agent invocation within an execution.
+ * When the main agent delegates work to a specialized sub-agent, this message
+ * tracks the complete lifecycle of that delegation including input, output, and timing.
+ *
+ * @generated from message ai.stigmer.agentic.agentexecution.v1.SubAgentExecution
+ */
+export type SubAgentExecution = Message<"ai.stigmer.agentic.agentexecution.v1.SubAgentExecution"> & {
+    /**
+     * Unique identifier for this sub-agent execution.
+     * Matches the tool call ID from the LangGraph "task" tool invocation.
+     *
+     * @generated from field: string id = 1;
+     */
+    id: string;
+    /**
+     * Name of the sub-agent being invoked.
+     * Examples: "code_editor", "researcher", "debugger"
+     * Extracted from tool call args.subagent_type field.
+     *
+     * @generated from field: string name = 2;
+     */
+    name: string;
+    /**
+     * Task/instruction given to the sub-agent.
+     * This is the input prompt that tells the sub-agent what to do.
+     *
+     * @generated from field: string input = 3;
+     */
+    input: string;
+    /**
+     * Result returned by the sub-agent when complete.
+     * Only populated when status == SUB_AGENT_COMPLETED.
+     *
+     * @generated from field: string output = 4;
+     */
+    output: string;
+    /**
+     * Current lifecycle status of the sub-agent execution.
+     *
+     * @generated from field: ai.stigmer.agentic.agentexecution.v1.SubAgentStatus status = 5;
+     */
+    status: SubAgentStatus;
+    /**
+     * ISO 8601 timestamp when the sub-agent was invoked.
+     * Example: "2025-11-22T10:30:00Z"
+     *
+     * @generated from field: string started_at = 6;
+     */
+    startedAt: string;
+    /**
+     * ISO 8601 timestamp when the sub-agent completed or failed.
+     * Only populated for terminal states (completed/failed).
+     *
+     * @generated from field: string completed_at = 7;
+     */
+    completedAt: string;
+    /**
+     * Error message if status == SUB_AGENT_FAILED.
+     * Contains the failure reason for debugging and user display.
+     *
+     * @generated from field: string error = 8;
+     */
+    error: string;
+    /**
+     * Optional sub-agent execution metadata.
+     *
+     * @generated from field: google.protobuf.Struct metadata = 9;
+     */
+    metadata?: JsonObject;
+    /**
+     * Tool calls made by this sub-agent.
+     * Captures the sub-agent's internal tool invocations separately from main agent.
+     * Enables debugging when sub-agent fails (e.g., "failed on 8th tool call").
+     *
+     * @generated from field: repeated ai.stigmer.agentic.agentexecution.v1.ToolCall tool_calls = 10;
+     */
+    toolCalls: ToolCall[];
+    /**
+     * Messages generated by this sub-agent.
+     * Captures AI responses and tool results within the sub-agent context.
+     * Ordered chronologically like AgentExecutionStatus.messages.
+     *
+     * @generated from field: repeated ai.stigmer.agentic.agentexecution.v1.AgentMessage messages = 11;
+     */
+    messages: AgentMessage[];
+    /**
+     * Token and LLM resource usage for this sub-agent execution.
+     * Captures only this sub-agent's direct LLM calls.
+     * Isolated from main agent and other sub-agents for accurate cost attribution.
+     *
+     * @generated from field: ai.stigmer.agentic.agentexecution.v1.UsageMetrics usage = 12;
+     */
+    usage?: UsageMetrics;
+    /**
+     * Concise, human-readable summary of the sub-agent's task (3-10 words).
+     * Populated directly from the task tool's `description` argument — the short
+     * label the invoking LLM provides when calling the "task" tool. No server-side
+     * LLM generation; available instantly when the sub-agent starts.
+     * Used as the primary display label in collapsed and expanded UI views.
+     * Examples: "Explore CLI rendering code", "Fix auth middleware tests"
+     *
+     * @generated from field: string subject = 13;
+     */
+    subject: string;
+    /**
+     * Approval requests pending within this sub-agent's tool calls.
+     * Also surfaced at parent AgentExecutionStatus.pending_approvals for
+     * top-level visibility. Cleared when the approval is resolved.
+     *
+     * @generated from field: repeated ai.stigmer.agentic.agentexecution.v1.PendingApproval pending_approvals = 14;
+     */
+    pendingApprovals: PendingApproval[];
+};
+/**
+ * Describes the message ai.stigmer.agentic.agentexecution.v1.SubAgentExecution.
+ * Use `create(SubAgentExecutionSchema)` to create a new message.
+ */
+export declare const SubAgentExecutionSchema: GenMessage<SubAgentExecution>;

package/ai/stigmer/agentic/agentexecution/v1/subagent_pb.js

@@ -0,0 +1,20 @@
+// @generated by protoc-gen-es v2.2.2 with parameter "target=ts"
+// @generated from file ai/stigmer/agentic/agentexecution/v1/subagent.proto (package ai.stigmer.agentic.agentexecution.v1, syntax proto3)
+/* eslint-disable */
+import { fileDesc, messageDesc } from "@bufbuild/protobuf/codegenv1";
+import { file_ai_stigmer_agentic_agentexecution_v1_approval } from "./approval_pb";
+import { file_ai_stigmer_agentic_agentexecution_v1_enum } from "./enum_pb";
+import { file_ai_stigmer_agentic_agentexecution_v1_message } from "./message_pb";
+import { file_ai_stigmer_agentic_agentexecution_v1_usage } from "./usage_pb";
+import { file_buf_validate_validate } from "../../../../../buf/validate/validate_pb";
+import { file_google_protobuf_struct } from "@bufbuild/protobuf/wkt";
+/**
+ * Describes the file ai/stigmer/agentic/agentexecution/v1/subagent.proto.
+ */
+export const file_ai_stigmer_agentic_agentexecution_v1_subagent = /*@__PURE__*/ fileDesc("CjNhaS9zdGlnbWVyL2FnZW50aWMvYWdlbnRleGVjdXRpb24vdjEvc3ViYWdlbnQucHJvdG8SJGFpLnN0aWdtZXIuYWdlbnRpYy5hZ2VudGV4ZWN1dGlvbi52MSKwBAoRU3ViQWdlbnRFeGVjdXRpb24SCgoCaWQYASABKAkSDAoEbmFtZRgCIAEoCRINCgVpbnB1dBgDIAEoCRIOCgZvdXRwdXQYBCABKAkSTgoGc3RhdHVzGAUgASgOMjQuYWkuc3RpZ21lci5hZ2VudGljLmFnZW50ZXhlY3V0aW9uLnYxLlN1YkFnZW50U3RhdHVzQgi6SAWCAQIQARISCgpzdGFydGVkX2F0GAYgASgJEhQKDGNvbXBsZXRlZF9hdBgHIAEoCRINCgVlcnJvchgIIAEoCRIpCghtZXRhZGF0YRgJIAEoCzIXLmdvb2dsZS5wcm90b2J1Zi5TdHJ1Y3QSQgoKdG9vbF9jYWxscxgKIAMoCzIuLmFpLnN0aWdtZXIuYWdlbnRpYy5hZ2VudGV4ZWN1dGlvbi52MS5Ub29sQ2FsbBJECghtZXNzYWdlcxgLIAMoCzIyLmFpLnN0aWdtZXIuYWdlbnRpYy5hZ2VudGV4ZWN1dGlvbi52MS5BZ2VudE1lc3NhZ2USQQoFdXNhZ2UYDCABKAsyMi5haS5zdGlnbWVyLmFnZW50aWMuYWdlbnRleGVjdXRpb24udjEuVXNhZ2VNZXRyaWNzEg8KB3N1YmplY3QYDSABKAkSUAoRcGVuZGluZ19hcHByb3ZhbHMYDiADKAsyNS5haS5zdGlnbWVyLmFnZW50aWMuYWdlbnRleGVjdXRpb24udjEuUGVuZGluZ0FwcHJvdmFsYgZwcm90bzM", [file_ai_stigmer_agentic_agentexecution_v1_approval, file_ai_stigmer_agentic_agentexecution_v1_enum, file_ai_stigmer_agentic_agentexecution_v1_message, file_ai_stigmer_agentic_agentexecution_v1_usage, file_buf_validate_validate, file_google_protobuf_struct]);
+/**
+ * Describes the message ai.stigmer.agentic.agentexecution.v1.SubAgentExecution.
+ * Use `create(SubAgentExecutionSchema)` to create a new message.
+ */
+export const SubAgentExecutionSchema = /*@__PURE__*/ messageDesc(file_ai_stigmer_agentic_agentexecution_v1_subagent, 0);
+//# sourceMappingURL=subagent_pb.js.map

package/ai/stigmer/agentic/agentexecution/v1/subagent_pb.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"subagent_pb.js","sourceRoot":"","sources":["../../../../../../ai/stigmer/agentic/agentexecution/v1/subagent_pb.ts"],"names":[],"mappings":"AAAA,gEAAgE;AAChE,yIAAyI;AACzI,oBAAoB;AAGpB,OAAO,EAAE,QAAQ,EAAE,WAAW,EAAE,MAAM,8BAA8B,CAAC;AAErE,OAAO,EAAE,kDAAkD,EAAE,MAAM,eAAe,CAAC;AAEnF,OAAO,EAAE,8CAA8C,EAAE,MAAM,WAAW,CAAC;AAE3E,OAAO,EAAE,iDAAiD,EAAE,MAAM,cAAc,CAAC;AAEjF,OAAO,EAAE,+CAA+C,EAAE,MAAM,YAAY,CAAC;AAC7E,OAAO,EAAE,0BAA0B,EAAE,MAAM,yCAAyC,CAAC;AACrF,OAAO,EAAE,2BAA2B,EAAE,MAAM,wBAAwB,CAAC;AAGrE;;GAEG;AACH,MAAM,CAAC,MAAM,kDAAkD,GAAY,aAAa,CACtF,QAAQ,CAAC,q3BAAq3B,EAAE,CAAC,kDAAkD,EAAE,8CAA8C,EAAE,iDAAiD,EAAE,+CAA+C,EAAE,0BAA0B,EAAE,2BAA2B,CAAC,CAAC,CAAC;AAkIroC;;;GAGG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAAkC,aAAa,CACjF,WAAW,CAAC,kDAAkD,EAAE,CAAC,CAAC,CAAC"}

package/ai/stigmer/agentic/agentexecution/v1/usage_pb.d.ts

@@ -0,0 +1,413 @@
+import type { GenFile, GenMessage } from "@bufbuild/protobuf/codegenv1";
+import type { Message } from "@bufbuild/protobuf";
+/**
+ * Describes the file ai/stigmer/agentic/agentexecution/v1/usage.proto.
+ */
+export declare const file_ai_stigmer_agentic_agentexecution_v1_usage: GenFile;
+/**
+ * UsageMetrics tracks token consumption, cost, and LLM resource usage.
+ * Provides execution-level aggregation for cost tracking, billing, and analytics.
+ *
+ * ## Scope
+ *
+ * Each UsageMetrics instance represents direct LLM usage within its context:
+ * - AgentExecutionStatus.usage: Main agent's LLM calls (excludes sub-agents)
+ * - SubAgentExecution.usage: That sub-agent's LLM calls
+ *
+ * To calculate total execution cost, sum: status.usage + sum(sub_agent.usage)
+ *
+ * ## Token Counting
+ *
+ * - prompt_tokens: Total input tokens sent to the LLM (includes cached tokens)
+ * - completion_tokens: Output tokens generated by the LLM (response)
+ * - cache_creation_tokens / cache_read_tokens: Cache-aware breakdown
+ * - Extracted from on_chat_model_end events via LangChain usage_metadata
+ *
+ * ## Relationship Between Token Fields
+ *
+ * prompt_tokens is the total across all input token types:
+ *   prompt_tokens = sum(model_breakdown[].input_tokens
+ *                       + model_breakdown[].cache_creation_tokens
+ *                       + model_breakdown[].cache_read_tokens)
+ *
+ * At the aggregate level, cache_creation_tokens and cache_read_tokens are the
+ * sums of their respective fields across all model breakdowns. The "fresh"
+ * (non-cached) input portion equals:
+ *   prompt_tokens - cache_creation_tokens - cache_read_tokens
+ *
+ * ## Cost Computation
+ *
+ * estimated_cost_usd is computed at execution time using pricing rates stamped
+ * on each ModelUsage entry. This makes historical data self-contained — an
+ * execution from January 2026 carries January 2026 rates even if prices change.
+ *
+ * ## Model Tracking
+ *
+ * primary_model reflects the configured model from ExecutionConfig.model_name.
+ * When model is auto-selected or varies per call, this captures the first/main model used.
+ * model_breakdown provides per-model detail when multiple models are used.
+ *
+ * @generated from message ai.stigmer.agentic.agentexecution.v1.UsageMetrics
+ */
+export type UsageMetrics = Message<"ai.stigmer.agentic.agentexecution.v1.UsageMetrics"> & {
+    /**
+     * Total input tokens (prompts) consumed across all LLM calls in this context.
+     * Includes all input token types: regular, cache writes, and cache reads.
+     * Accumulated from each on_chat_model_end event's usage_metadata.input_tokens.
+     *
+     * @generated from field: int32 prompt_tokens = 1;
+     */
+    promptTokens: number;
+    /**
+     * Total output tokens (completions) generated across all LLM calls in this context.
+     * Accumulated from each on_chat_model_end event's usage_metadata.output_tokens.
+     *
+     * @generated from field: int32 completion_tokens = 2;
+     */
+    completionTokens: number;
+    /**
+     * Total tokens (prompt + completion). Convenience field for quick reference.
+     * Equals: prompt_tokens + completion_tokens
+     *
+     * @generated from field: int32 total_tokens = 3;
+     */
+    totalTokens: number;
+    /**
+     * Number of LLM API calls made in this context.
+     * Incremented for each on_chat_model_end event.
+     * Useful for: average tokens per call, call frequency analysis.
+     *
+     * @generated from field: int32 llm_call_count = 4;
+     */
+    llmCallCount: number;
+    /**
+     * Primary model used for this execution.
+     * Typically matches ExecutionConfig.model_name or the first model detected.
+     * Examples: "claude-sonnet-4-20250514", "gpt-4o", "gemini-1.5-pro"
+     *
+     * @generated from field: string primary_model = 5;
+     */
+    primaryModel: string;
+    /**
+     * Tokens written to provider prompt cache across all LLM calls.
+     * Anthropic: cache_creation_input_tokens (billed at 1.25x input rate)
+     * OpenAI: N/A (caching is automatic, no separate write metric)
+     * Zero if prompt caching is not active or not supported by provider.
+     *
+     * @generated from field: int32 cache_creation_tokens = 6;
+     */
+    cacheCreationTokens: number;
+    /**
+     * Tokens read from provider prompt cache (cache hits) across all LLM calls.
+     * Anthropic: cache_read_input_tokens (billed at 0.1x input rate)
+     * OpenAI: prompt_tokens_details.cached_tokens (billed at 0.5x input rate)
+     * Zero if no cache hits occurred.
+     *
+     * @generated from field: int32 cache_read_tokens = 7;
+     */
+    cacheReadTokens: number;
+    /**
+     * Breakdown of token usage and cost per model.
+     * Each entry aggregates all LLM calls for a specific model within this context.
+     * Used for cost reports: "claude-sonnet-4 used 50K input tokens = $0.15."
+     *
+     * @generated from field: repeated ai.stigmer.agentic.agentexecution.v1.ModelUsage model_breakdown = 8;
+     */
+    modelBreakdown: ModelUsage[];
+    /**
+     * Total estimated cost in USD for this execution context.
+     * Computed at execution time using the pricing rates stamped on each ModelUsage.
+     * Equals: sum(model_breakdown[].estimated_cost_usd)
+     *
+     * Captured at write time because pricing changes over time — storing the
+     * computed cost makes historical data self-contained and accurate without
+     * needing a pricing history table.
+     *
+     * @generated from field: double estimated_cost_usd = 9;
+     */
+    estimatedCostUsd: number;
+    /**
+     * Total characters truncated from tool results during this execution.
+     * Non-zero indicates the agent received tool outputs that exceeded the
+     * configured max_tool_result_chars limit.
+     * Useful for: tuning truncation limits, identifying verbose tools.
+     *
+     * @generated from field: int64 tool_result_chars_truncated = 10;
+     */
+    toolResultCharsTruncated: bigint;
+    /**
+     * Per-call breakdown of every LLM API call in this context.
+     * Ordered chronologically (call 1, call 2, ...).
+     * Enables debugging expensive calls, tracking token growth across calls,
+     * and verifying cache hit patterns.
+     *
+     * This is the detailed view — model_breakdown is the per-model aggregate.
+     * Both are populated: model_breakdown for reports, llm_calls for debugging.
+     *
+     * @generated from field: repeated ai.stigmer.agentic.agentexecution.v1.LlmCallMetrics llm_calls = 11;
+     */
+    llmCalls: LlmCallMetrics[];
+    /**
+     * Total wall-clock duration of the execution in milliseconds.
+     * Convenience field equivalent to (completed_at - started_at).
+     * Includes all time: LLM calls, tool execution, approval waits, overhead.
+     *
+     * @generated from field: int32 total_duration_ms = 12;
+     */
+    totalDurationMs: number;
+    /**
+     * Time spent waiting for LLM responses in milliseconds.
+     * Sum of all LLM call durations (llm_calls[].duration_ms).
+     * Directly correlates with token generation cost.
+     *
+     * @generated from field: int32 llm_duration_ms = 13;
+     */
+    llmDurationMs: number;
+    /**
+     * Time spent executing tools in milliseconds.
+     * Sum of all tool execution durations (tool start to tool complete).
+     * Represents compute resource usage in the sandbox.
+     *
+     * @generated from field: int32 tool_duration_ms = 14;
+     */
+    toolDurationMs: number;
+    /**
+     * Time spent waiting for user approval in milliseconds.
+     * Sum of all approval wait times (approval_requested_at to approval_decided_at).
+     * This is idle time — no LLM or compute resources consumed.
+     * Useful for excluding from "active execution cost" calculations.
+     *
+     * @generated from field: int32 approval_wait_duration_ms = 15;
+     */
+    approvalWaitDurationMs: number;
+    /**
+     * Provider that served the primary model.
+     * Examples: "anthropic", "openai", "google", "ollama", "aws-bedrock"
+     * Matches the provider field in model_breakdown for the primary model.
+     * Useful for quick display without diving into model_breakdown.
+     *
+     * @generated from field: string primary_provider = 16;
+     */
+    primaryProvider: string;
+};
+/**
+ * Describes the message ai.stigmer.agentic.agentexecution.v1.UsageMetrics.
+ * Use `create(UsageMetricsSchema)` to create a new message.
+ */
+export declare const UsageMetricsSchema: GenMessage<UsageMetrics>;
+/**
+ * ModelUsage captures token usage and cost for a single model within an execution.
+ * Provides the per-model breakdown needed for accurate cost calculation when
+ * multiple models are used (e.g., main model + summarization model).
+ *
+ * ## Token Bucket Design
+ *
+ * The four token fields (input_tokens, output_tokens, cache_creation_tokens,
+ * cache_read_tokens) are disjoint, non-overlapping buckets. Every token falls
+ * into exactly one bucket, making cost calculation straightforward:
+ *   cost = (input_tokens * input_price / 1M)
+ *        + (output_tokens * output_price / 1M)
+ *        + (cache_creation_tokens * cache_creation_price / 1M)
+ *        + (cache_read_tokens * cache_read_price / 1M)
+ *
+ * ## input_tokens Semantics
+ *
+ * input_tokens represents regular (non-cached) input tokens only — tokens
+ * billed at the standard input rate. This follows the Anthropic provider
+ * convention where input_tokens excludes cache tokens.
+ *
+ * Total input for this model = input_tokens + cache_creation_tokens + cache_read_tokens
+ *
+ * ## Pricing Rates
+ *
+ * Pricing fields are stamped at execution time from the Model Pricing Registry.
+ * This makes historical data self-contained: an execution from January 2026
+ * carries January 2026 rates even if provider pricing changes later.
+ *
+ * @generated from message ai.stigmer.agentic.agentexecution.v1.ModelUsage
+ */
+export type ModelUsage = Message<"ai.stigmer.agentic.agentexecution.v1.ModelUsage"> & {
+    /**
+     * Model identifier as returned by the provider.
+     * Example: "claude-sonnet-4-20250514", "gpt-4o-2024-08-06"
+     *
+     * @generated from field: string model = 1;
+     */
+    model: string;
+    /**
+     * Provider identifier. Determines which pricing table to use.
+     * Examples: "anthropic", "openai", "google", "ollama", "aws-bedrock"
+     *
+     * @generated from field: string provider = 2;
+     */
+    provider: string;
+    /**
+     * Regular input tokens (non-cached) billed at the standard input rate.
+     * Anthropic: input_tokens (excludes cache tokens)
+     * OpenAI: prompt_tokens - cached_tokens
+     *
+     * Total input = input_tokens + cache_creation_tokens + cache_read_tokens
+     *
+     * @generated from field: int32 input_tokens = 3;
+     */
+    inputTokens: number;
+    /**
+     * Output tokens generated by the model.
+     *
+     * @generated from field: int32 output_tokens = 4;
+     */
+    outputTokens: number;
+    /**
+     * Tokens written to prompt cache during this execution.
+     * Anthropic: cache_creation_input_tokens (billed at 1.25x input rate)
+     * OpenAI: N/A (caching is automatic, no separate write metric)
+     *
+     * @generated from field: int32 cache_creation_tokens = 5;
+     */
+    cacheCreationTokens: number;
+    /**
+     * Tokens read from prompt cache (cache hits).
+     * Anthropic: cache_read_input_tokens (billed at 0.1x input rate)
+     * OpenAI: prompt_tokens_details.cached_tokens (billed at 0.5x input rate)
+     *
+     * @generated from field: int32 cache_read_tokens = 6;
+     */
+    cacheReadTokens: number;
+    /**
+     * Number of LLM API calls made with this model.
+     *
+     * @generated from field: int32 call_count = 7;
+     */
+    callCount: number;
+    /**
+     * Input token price per million tokens (USD) at execution time.
+     *
+     * @generated from field: double input_price_per_million = 8;
+     */
+    inputPricePerMillion: number;
+    /**
+     * Output token price per million tokens (USD) at execution time.
+     *
+     * @generated from field: double output_price_per_million = 9;
+     */
+    outputPricePerMillion: number;
+    /**
+     * Cache write token price per million tokens (USD) at execution time.
+     * Anthropic: 1.25x of input_price. OpenAI: same as input.
+     *
+     * @generated from field: double cache_creation_price_per_million = 10;
+     */
+    cacheCreationPricePerMillion: number;
+    /**
+     * Cache read token price per million tokens (USD) at execution time.
+     * Anthropic: 0.1x of input_price. OpenAI: 0.5x of input_price.
+     *
+     * @generated from field: double cache_read_price_per_million = 11;
+     */
+    cacheReadPricePerMillion: number;
+    /**
+     * Computed cost in USD for this model's usage in this execution.
+     * = (input_tokens * input_price / 1M)
+     *   + (output_tokens * output_price / 1M)
+     *   + (cache_creation_tokens * cache_creation_price / 1M)
+     *   + (cache_read_tokens * cache_read_price / 1M)
+     *
+     * @generated from field: double estimated_cost_usd = 12;
+     */
+    estimatedCostUsd: number;
+};
+/**
+ * Describes the message ai.stigmer.agentic.agentexecution.v1.ModelUsage.
+ * Use `create(ModelUsageSchema)` to create a new message.
+ */
+export declare const ModelUsageSchema: GenMessage<ModelUsage>;
+/**
+ * Metrics for a single LLM API call during execution.
+ * Provides per-call granularity for debugging, optimization, and cost attribution.
+ *
+ * One entry is created for each on_chat_model_end event.
+ * Ordered chronologically — the Nth entry corresponds to the Nth LLM call.
+ *
+ * ## Cache Verification
+ *
+ * Especially valuable for verifying prompt caching: you expect call 1 to be a
+ * cache miss (or cache write), and calls 2+ to have high cache_read_tokens.
+ * If they don't, something is wrong with cache breakpoint placement.
+ *
+ * ## Size Consideration
+ *
+ * A typical execution has 3-15 LLM calls. Each LlmCallMetrics is ~10 fields /
+ * ~80 bytes. Even a 50-call execution adds only ~4KB — negligible compared to
+ * the messages[] and tool_calls[] arrays which carry full content strings.
+ *
+ * @generated from message ai.stigmer.agentic.agentexecution.v1.LlmCallMetrics
+ */
+export type LlmCallMetrics = Message<"ai.stigmer.agentic.agentexecution.v1.LlmCallMetrics"> & {
+    /**
+     * Sequence number of this LLM call within the execution (1-based).
+     *
+     * @generated from field: int32 sequence = 1;
+     */
+    sequence: number;
+    /**
+     * Model used for this specific call.
+     * May differ from primary_model if model fallback or routing occurred.
+     *
+     * @generated from field: string model = 2;
+     */
+    model: string;
+    /**
+     * Provider for this call.
+     *
+     * @generated from field: string provider = 3;
+     */
+    provider: string;
+    /**
+     * Input tokens for this call (total prompt size sent to the model).
+     *
+     * @generated from field: int32 input_tokens = 4;
+     */
+    inputTokens: number;
+    /**
+     * Output tokens generated by the model in this call.
+     *
+     * @generated from field: int32 output_tokens = 5;
+     */
+    outputTokens: number;
+    /**
+     * Cache tokens written during this call.
+     *
+     * @generated from field: int32 cache_creation_tokens = 6;
+     */
+    cacheCreationTokens: number;
+    /**
+     * Cache tokens read (cache hits) during this call.
+     *
+     * @generated from field: int32 cache_read_tokens = 7;
+     */
+    cacheReadTokens: number;
+    /**
+     * Computed cost in USD for this single call.
+     *
+     * @generated from field: double estimated_cost_usd = 8;
+     */
+    estimatedCostUsd: number;
+    /**
+     * Wall-clock duration of this LLM call in milliseconds.
+     * From request sent to response complete.
+     *
+     * @generated from field: int32 duration_ms = 9;
+     */
+    durationMs: number;
+    /**
+     * ISO 8601 timestamp when this LLM call started.
+     *
+     * @generated from field: string timestamp = 10;
+     */
+    timestamp: string;
+};
+/**
+ * Describes the message ai.stigmer.agentic.agentexecution.v1.LlmCallMetrics.
+ * Use `create(LlmCallMetricsSchema)` to create a new message.
+ */
+export declare const LlmCallMetricsSchema: GenMessage<LlmCallMetrics>;

package/ai/stigmer/agentic/agentexecution/v1/usage_pb.js

@@ -0,0 +1,24 @@
+// @generated by protoc-gen-es v2.2.2 with parameter "target=ts"
+// @generated from file ai/stigmer/agentic/agentexecution/v1/usage.proto (package ai.stigmer.agentic.agentexecution.v1, syntax proto3)
+/* eslint-disable */
+import { fileDesc, messageDesc } from "@bufbuild/protobuf/codegenv1";
+/**
+ * Describes the file ai/stigmer/agentic/agentexecution/v1/usage.proto.
+ */
+export const file_ai_stigmer_agentic_agentexecution_v1_usage = /*@__PURE__*/ fileDesc("CjBhaS9zdGlnbWVyL2FnZW50aWMvYWdlbnRleGVjdXRpb24vdjEvdXNhZ2UucHJvdG8SJGFpLnN0aWdtZXIuYWdlbnRpYy5hZ2VudGV4ZWN1dGlvbi52MSKfBAoMVXNhZ2VNZXRyaWNzEhUKDXByb21wdF90b2tlbnMYASABKAUSGQoRY29tcGxldGlvbl90b2tlbnMYAiABKAUSFAoMdG90YWxfdG9rZW5zGAMgASgFEhYKDmxsbV9jYWxsX2NvdW50GAQgASgFEhUKDXByaW1hcnlfbW9kZWwYBSABKAkSHQoVY2FjaGVfY3JlYXRpb25fdG9rZW5zGAYgASgFEhkKEWNhY2hlX3JlYWRfdG9rZW5zGAcgASgFEkkKD21vZGVsX2JyZWFrZG93bhgIIAMoCzIwLmFpLnN0aWdtZXIuYWdlbnRpYy5hZ2VudGV4ZWN1dGlvbi52MS5Nb2RlbFVzYWdlEhoKEmVzdGltYXRlZF9jb3N0X3VzZBgJIAEoARIjCht0b29sX3Jlc3VsdF9jaGFyc190cnVuY2F0ZWQYCiABKAMSRwoJbGxtX2NhbGxzGAsgAygLMjQuYWkuc3RpZ21lci5hZ2VudGljLmFnZW50ZXhlY3V0aW9uLnYxLkxsbUNhbGxNZXRyaWNzEhkKEXRvdGFsX2R1cmF0aW9uX21zGAwgASgFEhcKD2xsbV9kdXJhdGlvbl9tcxgNIAEoBRIYChB0b29sX2R1cmF0aW9uX21zGA4gASgFEiEKGWFwcHJvdmFsX3dhaXRfZHVyYXRpb25fbXMYDyABKAUSGAoQcHJpbWFyeV9wcm92aWRlchgQIAEoCSLXAgoKTW9kZWxVc2FnZRINCgVtb2RlbBgBIAEoCRIQCghwcm92aWRlchgCIAEoCRIUCgxpbnB1dF90b2tlbnMYAyABKAUSFQoNb3V0cHV0X3Rva2VucxgEIAEoBRIdChVjYWNoZV9jcmVhdGlvbl90b2tlbnMYBSABKAUSGQoRY2FjaGVfcmVhZF90b2tlbnMYBiABKAUSEgoKY2FsbF9jb3VudBgHIAEoBRIfChdpbnB1dF9wcmljZV9wZXJfbWlsbGlvbhgIIAEoARIgChhvdXRwdXRfcHJpY2VfcGVyX21pbGxpb24YCSABKAESKAogY2FjaGVfY3JlYXRpb25fcHJpY2VfcGVyX21pbGxpb24YCiABKAESJAocY2FjaGVfcmVhZF9wcmljZV9wZXJfbWlsbGlvbhgLIAEoARIaChJlc3RpbWF0ZWRfY29zdF91c2QYDCABKAEi7gEKDkxsbUNhbGxNZXRyaWNzEhAKCHNlcXVlbmNlGAEgASgFEg0KBW1vZGVsGAIgASgJEhAKCHByb3ZpZGVyGAMgASgJEhQKDGlucHV0X3Rva2VucxgEIAEoBRIVCg1vdXRwdXRfdG9rZW5zGAUgASgFEh0KFWNhY2hlX2NyZWF0aW9uX3Rva2VucxgGIAEoBRIZChFjYWNoZV9yZWFkX3Rva2VucxgHIAEoBRIaChJlc3RpbWF0ZWRfY29zdF91c2QYCCABKAESEwoLZHVyYXRpb25fbXMYCSABKAUSEQoJdGltZXN0YW1wGAogASgJYgZwcm90bzM");
+/**
+ * Describes the message ai.stigmer.agentic.agentexecution.v1.UsageMetrics.
+ * Use `create(UsageMetricsSchema)` to create a new message.
+ */
+export const UsageMetricsSchema = /*@__PURE__*/ messageDesc(file_ai_stigmer_agentic_agentexecution_v1_usage, 0);
+/**
+ * Describes the message ai.stigmer.agentic.agentexecution.v1.ModelUsage.
+ * Use `create(ModelUsageSchema)` to create a new message.
+ */
+export const ModelUsageSchema = /*@__PURE__*/ messageDesc(file_ai_stigmer_agentic_agentexecution_v1_usage, 1);
+/**
+ * Describes the message ai.stigmer.agentic.agentexecution.v1.LlmCallMetrics.
+ * Use `create(LlmCallMetricsSchema)` to create a new message.
+ */
+export const LlmCallMetricsSchema = /*@__PURE__*/ messageDesc(file_ai_stigmer_agentic_agentexecution_v1_usage, 2);
+//# sourceMappingURL=usage_pb.js.map

package/ai/stigmer/agentic/agentexecution/v1/usage_pb.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"usage_pb.js","sourceRoot":"","sources":["../../../../../../ai/stigmer/agentic/agentexecution/v1/usage_pb.ts"],"names":[],"mappings":"AAAA,gEAAgE;AAChE,sIAAsI;AACtI,oBAAoB;AAGpB,OAAO,EAAE,QAAQ,EAAE,WAAW,EAAE,MAAM,8BAA8B,CAAC;AAGrE;;GAEG;AACH,MAAM,CAAC,MAAM,+CAA+C,GAAY,aAAa,CACnF,QAAQ,CAAC,ymDAAymD,CAAC,CAAC;AA4MtnD;;;GAGG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAA6B,aAAa,CACvE,WAAW,CAAC,+CAA+C,EAAE,CAAC,CAAC,CAAC;AAuIlE;;;GAGG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAA2B,aAAa,CACnE,WAAW,CAAC,+CAA+C,EAAE,CAAC,CAAC,CAAC;AAiGlE;;;GAGG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAA+B,aAAa,CAC3E,WAAW,CAAC,+CAA+C,EAAE,CAAC,CAAC,CAAC"}

package/ai/stigmer/agentic/agentinstance/v1/api_pb.d.ts

@@ -0,0 +1,52 @@
+import type { GenFile, GenMessage } from "@bufbuild/protobuf/codegenv1";
+import type { AgentInstanceSpec } from "./spec_pb";
+import type { ApiResourceMetadata } from "../../../commons/apiresource/metadata_pb";
+import type { ApiResourceAuditStatus } from "../../../commons/apiresource/status_pb";
+import type { Message } from "@bufbuild/protobuf";
+/**
+ * Describes the file ai/stigmer/agentic/agentinstance/v1/api.proto.
+ */
+export declare const file_ai_stigmer_agentic_agentinstance_v1_api: GenFile;
+/**
+ * AgentInstance represents a configured deployment of an Agent template.
+ *
+ * @generated from message ai.stigmer.agentic.agentinstance.v1.AgentInstance
+ */
+export type AgentInstance = Message<"ai.stigmer.agentic.agentinstance.v1.AgentInstance"> & {
+    /**
+     * API version for this resource type.
+     *
+     * @generated from field: string api_version = 1;
+     */
+    apiVersion: string;
+    /**
+     * Resource kind identifier.
+     *
+     * @generated from field: string kind = 2;
+     */
+    kind: string;
+    /**
+     * Standard resource metadata including name, id, labels, and tags.
+     * AgentInstances can have platform, organization, or identity_account scope.
+     *
+     * @generated from field: ai.stigmer.commons.apiresource.ApiResourceMetadata metadata = 3;
+     */
+    metadata?: ApiResourceMetadata;
+    /**
+     * Spec defining the instance configuration.
+     *
+     * @generated from field: ai.stigmer.agentic.agentinstance.v1.AgentInstanceSpec spec = 4;
+     */
+    spec?: AgentInstanceSpec;
+    /**
+     * Status of the instance.
+     *
+     * @generated from field: ai.stigmer.commons.apiresource.ApiResourceAuditStatus status = 5;
+     */
+    status?: ApiResourceAuditStatus;
+};
+/**
+ * Describes the message ai.stigmer.agentic.agentinstance.v1.AgentInstance.
+ * Use `create(AgentInstanceSchema)` to create a new message.
+ */
+export declare const AgentInstanceSchema: GenMessage<AgentInstance>;

package/ai/stigmer/agentic/agentinstance/v1/api_pb.js

@@ -0,0 +1,18 @@
+// @generated by protoc-gen-es v2.2.2 with parameter "target=ts"
+// @generated from file ai/stigmer/agentic/agentinstance/v1/api.proto (package ai.stigmer.agentic.agentinstance.v1, syntax proto3)
+/* eslint-disable */
+import { fileDesc, messageDesc } from "@bufbuild/protobuf/codegenv1";
+import { file_ai_stigmer_agentic_agentinstance_v1_spec } from "./spec_pb";
+import { file_ai_stigmer_commons_apiresource_metadata } from "../../../commons/apiresource/metadata_pb";
+import { file_ai_stigmer_commons_apiresource_status } from "../../../commons/apiresource/status_pb";
+import { file_buf_validate_validate } from "../../../../../buf/validate/validate_pb";
+/**
+ * Describes the file ai/stigmer/agentic/agentinstance/v1/api.proto.
+ */
+export const file_ai_stigmer_agentic_agentinstance_v1_api = /*@__PURE__*/ fileDesc("Ci1haS9zdGlnbWVyL2FnZW50aWMvYWdlbnRpbnN0YW5jZS92MS9hcGkucHJvdG8SI2FpLnN0aWdtZXIuYWdlbnRpYy5hZ2VudGluc3RhbmNlLnYxIsMCCg1BZ2VudEluc3RhbmNlEjEKC2FwaV92ZXJzaW9uGAEgASgJQhy6SBlyFwoVYWdlbnRpYy5zdGlnbWVyLmFpL3YxEiIKBGtpbmQYAiABKAlCFLpIEXIPCg1BZ2VudEluc3RhbmNlEk0KCG1ldGFkYXRhGAMgASgLMjMuYWkuc3RpZ21lci5jb21tb25zLmFwaXJlc291cmNlLkFwaVJlc291cmNlTWV0YWRhdGFCBrpIA8gBARJECgRzcGVjGAQgASgLMjYuYWkuc3RpZ21lci5hZ2VudGljLmFnZW50aW5zdGFuY2UudjEuQWdlbnRJbnN0YW5jZVNwZWMSRgoGc3RhdHVzGAUgASgLMjYuYWkuc3RpZ21lci5jb21tb25zLmFwaXJlc291cmNlLkFwaVJlc291cmNlQXVkaXRTdGF0dXNiBnByb3RvMw", [file_ai_stigmer_agentic_agentinstance_v1_spec, file_ai_stigmer_commons_apiresource_metadata, file_ai_stigmer_commons_apiresource_status, file_buf_validate_validate]);
+/**
+ * Describes the message ai.stigmer.agentic.agentinstance.v1.AgentInstance.
+ * Use `create(AgentInstanceSchema)` to create a new message.
+ */
+export const AgentInstanceSchema = /*@__PURE__*/ messageDesc(file_ai_stigmer_agentic_agentinstance_v1_api, 0);
+//# sourceMappingURL=api_pb.js.map

package/ai/stigmer/agentic/agentinstance/v1/api_pb.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"api_pb.js","sourceRoot":"","sources":["../../../../../../ai/stigmer/agentic/agentinstance/v1/api_pb.ts"],"names":[],"mappings":"AAAA,gEAAgE;AAChE,kIAAkI;AAClI,oBAAoB;AAGpB,OAAO,EAAE,QAAQ,EAAE,WAAW,EAAE,MAAM,8BAA8B,CAAC;AAErE,OAAO,EAAE,6CAA6C,EAAE,MAAM,WAAW,CAAC;AAE1E,OAAO,EAAE,4CAA4C,EAAE,MAAM,0CAA0C,CAAC;AAExG,OAAO,EAAE,0CAA0C,EAAE,MAAM,wCAAwC,CAAC;AACpG,OAAO,EAAE,0BAA0B,EAAE,MAAM,yCAAyC,CAAC;AAGrF;;GAEG;AACH,MAAM,CAAC,MAAM,4CAA4C,GAAY,aAAa,CAChF,QAAQ,CAAC,gjBAAgjB,EAAE,CAAC,6CAA6C,EAAE,4CAA4C,EAAE,0CAA0C,EAAE,0BAA0B,CAAC,CAAC,CAAC;AA6CpuB;;;GAGG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAA8B,aAAa,CACzE,WAAW,CAAC,4CAA4C,EAAE,CAAC,CAAC,CAAC"}