@stigmer/protos 0.0.34

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

@@ -0,0 +1,403 @@
+import type { GenFile, GenMessage } from "@bufbuild/protobuf/codegenv1";
+import type { SummarizationSource } from "./enum_pb";
+import type { Message } from "@bufbuild/protobuf";
+/**
+ * Describes the file ai/stigmer/agentic/agentexecution/v1/context.proto.
+ */
+export declare const file_ai_stigmer_agentic_agentexecution_v1_context: GenFile;
+/**
+ * ResolvedExecutionContext captures the resolved configuration state at execution time.
+ * Populated once after all resources are resolved, before the agent begins processing.
+ *
+ * ## Purpose
+ *
+ * Provides visibility into what the agent actually had access to during execution:
+ * - Which environment variables were available (keys only, not values for security)
+ * - Which MCP servers were configured and their resolution status
+ * - Which skills were injected into the agent's context
+ *
+ * This enables:
+ * - **Debugging**: Understanding what environment/tools were available when investigating failures
+ * - **Auditing**: Tracking what resources each execution consumed
+ * - **Security review**: Verifying which secrets (by key name only) were exposed
+ * - **UX transparency**: Showing users what their agent can access
+ *
+ * ## Timing
+ *
+ * Populated in execute_graphton.py after Steps 3-5 complete (skills, env vars, MCP servers)
+ * but before the streaming loop begins. This represents the "snapshot" of resolved state.
+ * Once set, this field is immutable for the remainder of the execution.
+ *
+ * ## Security Considerations
+ *
+ * - Environment values are NEVER included (only keys)
+ * - MCP server credentials are not exposed
+ * - This is safe to include in status responses to clients
+ *
+ * @generated from message ai.stigmer.agentic.agentexecution.v1.ResolvedExecutionContext
+ */
+export type ResolvedExecutionContext = Message<"ai.stigmer.agentic.agentexecution.v1.ResolvedExecutionContext"> & {
+    /**
+     * Environment variable keys available to the agent (NOT values for security).
+     * Represents the merged result of: template env_spec + instance environment_refs + runtime_env.
+     * Keys are sorted alphabetically for consistent ordering and deterministic comparison.
+     * Examples: ["API_KEY", "DATABASE_URL", "LOG_LEVEL"]
+     *
+     * @generated from field: repeated string environment_keys = 1;
+     */
+    environmentKeys: string[];
+    /**
+     * MCP servers referenced by the agent and their resolution status.
+     * Key: MCP server slug (e.g., "github-mcp", "slack-mcp")
+     * Value: Resolution status including success/failure and diagnostic information
+     *
+     * Note: This tracks configuration resolution, not runtime connection status.
+     * A server showing resolved=true means it was found and transformed successfully;
+     * actual WebSocket/stdio connection happens later in the Graphton runtime.
+     *
+     * @generated from field: map<string, ai.stigmer.agentic.agentexecution.v1.McpServerResolutionStatus> mcp_servers = 2;
+     */
+    mcpServers: {
+        [key: string]: McpServerResolutionStatus;
+    };
+    /**
+     * Names of skills injected into the agent's system prompt.
+     * Each skill's SKILL.md content is appended to the instructions.
+     * Sorted alphabetically for consistent ordering and deterministic comparison.
+     * Examples: ["code-review", "docker-expert", "kubernetes-operator"]
+     *
+     * @generated from field: repeated string skill_names = 3;
+     */
+    skillNames: string[];
+    /**
+     * Skills that were available but excluded from the system prompt because
+     * they were not relevant to the current execution context.
+     * Enables visibility into the filtering decision for debugging and tuning.
+     * Sorted alphabetically for consistent ordering and deterministic comparison.
+     *
+     * When smart context filtering is active, this captures skills that were
+     * configured on the agent but scored below the relevance threshold for the
+     * current user message. Empty when all skills are included (no filtering).
+     *
+     * @generated from field: repeated string excluded_skill_names = 4;
+     */
+    excludedSkillNames: string[];
+};
+/**
+ * Describes the message ai.stigmer.agentic.agentexecution.v1.ResolvedExecutionContext.
+ * Use `create(ResolvedExecutionContextSchema)` to create a new message.
+ */
+export declare const ResolvedExecutionContextSchema: GenMessage<ResolvedExecutionContext>;
+/**
+ * McpServerResolutionStatus captures the resolution outcome for a single MCP server.
+ * Provides richer information than a simple boolean for better debugging and visibility.
+ *
+ * ## Resolution vs Connection
+ *
+ * This tracks whether the MCP server definition was successfully loaded and configured,
+ * NOT whether the runtime connection succeeded. Resolution includes:
+ * - Looking up the McpServer resource by reference
+ * - Transforming the server config (resolving env var placeholders)
+ * - Determining which tools to enable
+ *
+ * Runtime connection (WebSocket/stdio) happens later and is not tracked here.
+ *
+ * @generated from message ai.stigmer.agentic.agentexecution.v1.McpServerResolutionStatus
+ */
+export type McpServerResolutionStatus = Message<"ai.stigmer.agentic.agentexecution.v1.McpServerResolutionStatus"> & {
+    /**
+     * Whether the MCP server was successfully resolved and configured.
+     * true: Server found, config transformed, ready for runtime connection
+     * false: Resolution failed (server not found, missing env var, invalid config)
+     *
+     * @generated from field: bool resolved = 1;
+     */
+    resolved: boolean;
+    /**
+     * Human-readable status message explaining the resolution outcome.
+     * For success: "Configured successfully"
+     * For failure: Describes what went wrong
+     * Examples:
+     *   - "Configured successfully"
+     *   - "Server not found"
+     *   - "Missing required environment variable: GITHUB_TOKEN"
+     *   - "Invalid server configuration: missing command"
+     *
+     * @generated from field: string message = 2;
+     */
+    message: string;
+    /**
+     * Number of tools enabled from this MCP server.
+     * Reflects the intersection of server's available tools and enabled_tools config.
+     * 0 if resolution failed, server has no tools, or all tools disabled.
+     *
+     * @generated from field: int32 enabled_tool_count = 3;
+     */
+    enabledToolCount: number;
+};
+/**
+ * Describes the message ai.stigmer.agentic.agentexecution.v1.McpServerResolutionStatus.
+ * Use `create(McpServerResolutionStatusSchema)` to create a new message.
+ */
+export declare const McpServerResolutionStatusSchema: GenMessage<McpServerResolutionStatus>;
+/**
+ * SummarizationEvent records a single summarization occurrence during execution.
+ *
+ * Each time the context window approaches the model's limit and summarization
+ * is triggered, an event is recorded with before/after metrics.
+ *
+ * ## Purpose
+ *
+ * - **Debugging**: Understand when and why summarization occurred
+ * - **Monitoring**: Track summarization frequency and effectiveness
+ * - **Cost analysis**: Measure compression ratios and summarization costs
+ * - **Performance**: Track summarization latency
+ *
+ * ## Event Timing
+ *
+ * Events are recorded immediately after successful summarization, capturing:
+ * - Token counts before and after (to measure compression)
+ * - Message counts before and after (to understand conversation reduction)
+ * - Duration in milliseconds (to track performance)
+ * - Model used (to understand cost implications)
+ *
+ * @since Phase 3 (Context Summarization Architecture)
+ *
+ * @generated from message ai.stigmer.agentic.agentexecution.v1.SummarizationEvent
+ */
+export type SummarizationEvent = Message<"ai.stigmer.agentic.agentexecution.v1.SummarizationEvent"> & {
+    /**
+     * ISO 8601 timestamp when summarization occurred.
+     * Example: "2026-01-31T14:30:00.123Z"
+     *
+     * @generated from field: string timestamp = 1;
+     */
+    timestamp: string;
+    /**
+     * Token count before summarization.
+     * This was the token count that exceeded the trigger threshold.
+     *
+     * @generated from field: int32 tokens_before = 2;
+     */
+    tokensBefore: number;
+    /**
+     * Token count after summarization.
+     * Should be approximately at or below the target_tokens threshold.
+     *
+     * @generated from field: int32 tokens_after = 3;
+     */
+    tokensAfter: number;
+    /**
+     * Compression ratio achieved (0.0 to 1.0).
+     *
+     * Calculated as: 1 - (tokens_after / tokens_before)
+     * Example: 0.6 means 60% reduction in tokens (from 100K to 40K).
+     *
+     * Higher values indicate more aggressive compression.
+     * Typical values range from 0.3 to 0.7 depending on conversation content.
+     *
+     * @generated from field: float compression_ratio = 4;
+     */
+    compressionRatio: number;
+    /**
+     * Time taken to perform summarization in milliseconds.
+     *
+     * Includes the LLM call to the summarization model, message processing,
+     * and summary injection. Does not include token counting.
+     *
+     * Typical values: 1000-5000ms depending on context size and model.
+     *
+     * @generated from field: int32 duration_ms = 5;
+     */
+    durationMs: number;
+    /**
+     * Model used for summarization (economy-tier model).
+     *
+     * Summarization uses cost-effective models to minimize expense:
+     * - For Anthropic: claude-haiku-4
+     * - For OpenAI: gpt-4o-mini
+     * - For Ollama: local model
+     *
+     * Example: "claude-haiku-4", "gpt-4o-mini"
+     *
+     * @generated from field: string summarization_model = 6;
+     */
+    summarizationModel: string;
+    /**
+     * Number of messages in conversation before summarization.
+     * Provides insight into conversation length that triggered summarization.
+     *
+     * @generated from field: int32 messages_before = 7;
+     */
+    messagesBefore: number;
+    /**
+     * Number of messages in conversation after summarization.
+     * Typically reduced significantly as historical messages are collapsed.
+     *
+     * @generated from field: int32 messages_after = 8;
+     */
+    messagesAfter: number;
+    /**
+     * What triggered this summarization event.
+     *
+     * Enables the CLI to distinguish between:
+     * - graph_start: compaction at the beginning of a new invocation
+     * - mid_execution: compaction triggered by accumulated tool responses
+     *
+     * @generated from field: ai.stigmer.agentic.agentexecution.v1.SummarizationSource source = 9;
+     */
+    source: SummarizationSource;
+    /**
+     * Input tokens consumed by the summarization LLM call.
+     * This is the context sent to the summarization model for compression.
+     *
+     * @generated from field: int32 summarization_input_tokens = 10;
+     */
+    summarizationInputTokens: number;
+    /**
+     * Output tokens generated by the summarization model (the summary).
+     *
+     * @generated from field: int32 summarization_output_tokens = 11;
+     */
+    summarizationOutputTokens: number;
+    /**
+     * Cost in USD of this summarization call.
+     * Computed using the summarization model's pricing rates at execution time.
+     *
+     * @generated from field: double summarization_cost_usd = 12;
+     */
+    summarizationCostUsd: number;
+};
+/**
+ * Describes the message ai.stigmer.agentic.agentexecution.v1.SummarizationEvent.
+ * Use `create(SummarizationEventSchema)` to create a new message.
+ */
+export declare const SummarizationEventSchema: GenMessage<SummarizationEvent>;
+/**
+ * ContextInfo provides visibility into context window utilization.
+ *
+ * This message enables monitoring, debugging, and optimization of context
+ * usage during agent executions. It tracks both the current state and
+ * historical summarization events.
+ *
+ * ## Real-Time Updates
+ *
+ * Fields are updated progressively during execution:
+ * - current_token_count: Updated after each LLM call
+ * - utilization_percent: Recalculated when token count changes
+ * - summarization_events: Appended when summarization occurs
+ *
+ * ## Configuration Visibility
+ *
+ * The message also surfaces the effective configuration:
+ * - What thresholds are in effect (model defaults or custom overrides)
+ * - Whether summarization is enabled
+ * - The model's context window limit
+ *
+ * ## Use Cases
+ *
+ * - **Dashboard**: Show context health indicator (green/yellow/red based on utilization)
+ * - **Alerts**: Notify when utilization consistently exceeds thresholds
+ * - **Analytics**: Track summarization frequency across agent fleet
+ * - **Debugging**: Understand context-related failures
+ *
+ * @since Phase 3 (Context Summarization Architecture)
+ *
+ * @generated from message ai.stigmer.agentic.agentexecution.v1.ContextInfo
+ */
+export type ContextInfo = Message<"ai.stigmer.agentic.agentexecution.v1.ContextInfo"> & {
+    /**
+     * Current token count in the context window.
+     *
+     * This is the most recent token count, updated after each LLM call
+     * or summarization event. Represents the total tokens in the
+     * conversation (system prompt + messages + tool results).
+     *
+     * Updated progressively during streaming for real-time visibility.
+     *
+     * @generated from field: int32 current_token_count = 1;
+     */
+    currentTokenCount: number;
+    /**
+     * Model's maximum context window size in tokens.
+     *
+     * Retrieved from Model Registry for the configured model.
+     * Example values:
+     * - claude-sonnet-4.5: 200,000
+     * - gpt-4o: 128,000
+     * - gpt-4-turbo: 128,000
+     *
+     * Used to calculate utilization_percent.
+     *
+     * @generated from field: int32 context_window_limit = 2;
+     */
+    contextWindowLimit: number;
+    /**
+     * Token threshold that triggers summarization.
+     *
+     * When current_token_count exceeds this value, summarization is triggered
+     * to reduce context size. This is either the model default from Model
+     * Registry or a custom override from ContextManagementConfig.
+     *
+     * Typically set to ~90% of context_window_limit.
+     *
+     * @generated from field: int32 summarization_trigger_threshold = 3;
+     */
+    summarizationTriggerThreshold: number;
+    /**
+     * Target token count after summarization.
+     *
+     * Summarization aims to reduce context to approximately this size.
+     * This is either the model default from Model Registry or a custom
+     * override from ContextManagementConfig.
+     *
+     * Typically set to ~80% of context_window_limit.
+     *
+     * @generated from field: int32 summarization_target_tokens = 4;
+     */
+    summarizationTargetTokens: number;
+    /**
+     * Whether summarization is enabled for this execution.
+     *
+     * false if ContextManagementConfig.disable_summarization was true.
+     * true otherwise (default).
+     *
+     * When false, no summarization events will occur regardless of
+     * token count. The execution may fail if context exceeds limits.
+     *
+     * @generated from field: bool summarization_enabled = 5;
+     */
+    summarizationEnabled: boolean;
+    /**
+     * Summarization events that occurred during this execution.
+     *
+     * Ordered chronologically (oldest first).
+     * Empty if no summarization was triggered during execution.
+     *
+     * Multiple events indicate a very long-running conversation that
+     * required multiple rounds of summarization.
+     *
+     * @generated from field: repeated ai.stigmer.agentic.agentexecution.v1.SummarizationEvent summarization_events = 6;
+     */
+    summarizationEvents: SummarizationEvent[];
+    /**
+     * Context utilization as a percentage (0-100).
+     *
+     * Calculated as: (current_token_count / context_window_limit) * 100
+     *
+     * Use for health indicators:
+     * - 0-70%: Green (healthy)
+     * - 70-90%: Yellow (approaching threshold)
+     * - 90-100%: Red (at or above trigger threshold)
+     *
+     * Updated progressively during streaming.
+     *
+     * @generated from field: float utilization_percent = 7;
+     */
+    utilizationPercent: number;
+};
+/**
+ * Describes the message ai.stigmer.agentic.agentexecution.v1.ContextInfo.
+ * Use `create(ContextInfoSchema)` to create a new message.
+ */
+export declare const ContextInfoSchema: GenMessage<ContextInfo>;

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

@@ -0,0 +1,30 @@
+// @generated by protoc-gen-es v2.2.2 with parameter "target=ts"
+// @generated from file ai/stigmer/agentic/agentexecution/v1/context.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_enum } from "./enum_pb";
+/**
+ * Describes the file ai/stigmer/agentic/agentexecution/v1/context.proto.
+ */
+export const file_ai_stigmer_agentic_agentexecution_v1_context = /*@__PURE__*/ fileDesc("CjJhaS9zdGlnbWVyL2FnZW50aWMvYWdlbnRleGVjdXRpb24vdjEvY29udGV4dC5wcm90bxIkYWkuc3RpZ21lci5hZ2VudGljLmFnZW50ZXhlY3V0aW9uLnYxIsACChhSZXNvbHZlZEV4ZWN1dGlvbkNvbnRleHQSGAoQZW52aXJvbm1lbnRfa2V5cxgBIAMoCRJjCgttY3Bfc2VydmVycxgCIAMoCzJOLmFpLnN0aWdtZXIuYWdlbnRpYy5hZ2VudGV4ZWN1dGlvbi52MS5SZXNvbHZlZEV4ZWN1dGlvbkNvbnRleHQuTWNwU2VydmVyc0VudHJ5EhMKC3NraWxsX25hbWVzGAMgAygJEhwKFGV4Y2x1ZGVkX3NraWxsX25hbWVzGAQgAygJGnIKD01jcFNlcnZlcnNFbnRyeRILCgNrZXkYASABKAkSTgoFdmFsdWUYAiABKAsyPy5haS5zdGlnbWVyLmFnZW50aWMuYWdlbnRleGVjdXRpb24udjEuTWNwU2VydmVyUmVzb2x1dGlvblN0YXR1czoCOAEiWgoZTWNwU2VydmVyUmVzb2x1dGlvblN0YXR1cxIQCghyZXNvbHZlZBgBIAEoCBIPCgdtZXNzYWdlGAIgASgJEhoKEmVuYWJsZWRfdG9vbF9jb3VudBgDIAEoBSKGAwoSU3VtbWFyaXphdGlvbkV2ZW50EhEKCXRpbWVzdGFtcBgBIAEoCRIVCg10b2tlbnNfYmVmb3JlGAIgASgFEhQKDHRva2Vuc19hZnRlchgDIAEoBRIZChFjb21wcmVzc2lvbl9yYXRpbxgEIAEoAhITCgtkdXJhdGlvbl9tcxgFIAEoBRIbChNzdW1tYXJpemF0aW9uX21vZGVsGAYgASgJEhcKD21lc3NhZ2VzX2JlZm9yZRgHIAEoBRIWCg5tZXNzYWdlc19hZnRlchgIIAEoBRJJCgZzb3VyY2UYCSABKA4yOS5haS5zdGlnbWVyLmFnZW50aWMuYWdlbnRleGVjdXRpb24udjEuU3VtbWFyaXphdGlvblNvdXJjZRIiChpzdW1tYXJpemF0aW9uX2lucHV0X3Rva2VucxgKIAEoBRIjChtzdW1tYXJpemF0aW9uX291dHB1dF90b2tlbnMYCyABKAUSHgoWc3VtbWFyaXphdGlvbl9jb3N0X3VzZBgMIAEoASKqAgoLQ29udGV4dEluZm8SGwoTY3VycmVudF90b2tlbl9jb3VudBgBIAEoBRIcChRjb250ZXh0X3dpbmRvd19saW1pdBgCIAEoBRInCh9zdW1tYXJpemF0aW9uX3RyaWdnZXJfdGhyZXNob2xkGAMgASgFEiMKG3N1bW1hcml6YXRpb25fdGFyZ2V0X3Rva2VucxgEIAEoBRIdChVzdW1tYXJpemF0aW9uX2VuYWJsZWQYBSABKAgSVgoUc3VtbWFyaXphdGlvbl9ldmVudHMYBiADKAsyOC5haS5zdGlnbWVyLmFnZW50aWMuYWdlbnRleGVjdXRpb24udjEuU3VtbWFyaXphdGlvbkV2ZW50EhsKE3V0aWxpemF0aW9uX3BlcmNlbnQYByABKAJiBnByb3RvMw", [file_ai_stigmer_agentic_agentexecution_v1_enum]);
+/**
+ * Describes the message ai.stigmer.agentic.agentexecution.v1.ResolvedExecutionContext.
+ * Use `create(ResolvedExecutionContextSchema)` to create a new message.
+ */
+export const ResolvedExecutionContextSchema = /*@__PURE__*/ messageDesc(file_ai_stigmer_agentic_agentexecution_v1_context, 0);
+/**
+ * Describes the message ai.stigmer.agentic.agentexecution.v1.McpServerResolutionStatus.
+ * Use `create(McpServerResolutionStatusSchema)` to create a new message.
+ */
+export const McpServerResolutionStatusSchema = /*@__PURE__*/ messageDesc(file_ai_stigmer_agentic_agentexecution_v1_context, 1);
+/**
+ * Describes the message ai.stigmer.agentic.agentexecution.v1.SummarizationEvent.
+ * Use `create(SummarizationEventSchema)` to create a new message.
+ */
+export const SummarizationEventSchema = /*@__PURE__*/ messageDesc(file_ai_stigmer_agentic_agentexecution_v1_context, 2);
+/**
+ * Describes the message ai.stigmer.agentic.agentexecution.v1.ContextInfo.
+ * Use `create(ContextInfoSchema)` to create a new message.
+ */
+export const ContextInfoSchema = /*@__PURE__*/ messageDesc(file_ai_stigmer_agentic_agentexecution_v1_context, 3);
+//# sourceMappingURL=context_pb.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"context_pb.js","sourceRoot":"","sources":["../../../../../../ai/stigmer/agentic/agentexecution/v1/context_pb.ts"],"names":[],"mappings":"AAAA,gEAAgE;AAChE,wIAAwI;AACxI,oBAAoB;AAGpB,OAAO,EAAE,QAAQ,EAAE,WAAW,EAAE,MAAM,8BAA8B,CAAC;AAErE,OAAO,EAAE,8CAA8C,EAAE,MAAM,WAAW,CAAC;AAG3E;;GAEG;AACH,MAAM,CAAC,MAAM,iDAAiD,GAAY,aAAa,CACrF,QAAQ,CAAC,4kDAA4kD,EAAE,CAAC,8CAA8C,CAAC,CAAC,CAAC;AAkF3oD;;;GAGG;AACH,MAAM,CAAC,MAAM,8BAA8B,GAAyC,aAAa,CAC/F,WAAW,CAAC,iDAAiD,EAAE,CAAC,CAAC,CAAC;AAoDpE;;;GAGG;AACH,MAAM,CAAC,MAAM,+BAA+B,GAA0C,aAAa,CACjG,WAAW,CAAC,iDAAiD,EAAE,CAAC,CAAC,CAAC;AA8IpE;;;GAGG;AACH,MAAM,CAAC,MAAM,wBAAwB,GAAmC,aAAa,CACnF,WAAW,CAAC,iDAAiD,EAAE,CAAC,CAAC,CAAC;AAoIpE;;;GAGG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAA4B,aAAa,CACrE,WAAW,CAAC,iDAAiD,EAAE,CAAC,CAAC,CAAC"}