@stigmer/protos 0.0.34

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

@@ -0,0 +1,296 @@
+import type { GenFile, GenMessage } from "@bufbuild/protobuf/codegenv1";
+import type { PendingApproval } from "./approval_pb";
+import type { ExecutionArtifact } from "./artifact_pb";
+import type { ContextInfo, ResolvedExecutionContext } from "./context_pb";
+import type { ExecutionPhase, TodoStatus } from "./enum_pb";
+import type { AgentMessage, ToolCall } from "./message_pb";
+import type { AgentExecutionSpec } from "./spec_pb";
+import type { SubAgentExecution } from "./subagent_pb";
+import type { UsageMetrics } from "./usage_pb";
+import type { ApiResourceMetadata } from "../../../commons/apiresource/metadata_pb";
+import type { ApiResourceAudit } from "../../../commons/apiresource/status_pb";
+import type { Message } from "@bufbuild/protobuf";
+/**
+ * Describes the file ai/stigmer/agentic/agentexecution/v1/api.proto.
+ */
+export declare const file_ai_stigmer_agentic_agentexecution_v1_api: GenFile;
+/**
+ * AgentExecution represents a single agent execution instance (conversational).
+ * Follows the standard pattern: spec contains user inputs, status contains execution results.
+ *
+ * @generated from message ai.stigmer.agentic.agentexecution.v1.AgentExecution
+ */
+export type AgentExecution = Message<"ai.stigmer.agentic.agentexecution.v1.AgentExecution"> & {
+    /**
+     * 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.
+     * Agent executions belong to an organization and inherit permissions from the session.
+     *
+     * @generated from field: ai.stigmer.commons.apiresource.ApiResourceMetadata metadata = 3;
+     */
+    metadata?: ApiResourceMetadata;
+    /**
+     * User-provided inputs for this execution.
+     * Contains: session_id, agent_id, message, execution_config, environment_id, credential_overrides
+     *
+     * @generated from field: ai.stigmer.agentic.agentexecution.v1.AgentExecutionSpec spec = 4;
+     */
+    spec?: AgentExecutionSpec;
+    /**
+     * System-managed execution state and results.
+     * Contains: messages, phase, tool_calls, sub_agents, canvas_layout, timestamps, errors
+     *
+     * @generated from field: ai.stigmer.agentic.agentexecution.v1.AgentExecutionStatus status = 5;
+     */
+    status?: AgentExecutionStatus;
+};
+/**
+ * Describes the message ai.stigmer.agentic.agentexecution.v1.AgentExecution.
+ * Use `create(AgentExecutionSchema)` to create a new message.
+ */
+export declare const AgentExecutionSchema: GenMessage<AgentExecution>;
+/**
+ * AgentExecutionStatus contains all execution results and state.
+ * Everything populated during or after execution goes here, not in spec.
+ *
+ * @generated from message ai.stigmer.agentic.agentexecution.v1.AgentExecutionStatus
+ */
+export type AgentExecutionStatus = Message<"ai.stigmer.agentic.agentexecution.v1.AgentExecutionStatus"> & {
+    /**
+     * Standard audit information (created_at, updated_at, created_by, etc.)
+     *
+     * @generated from field: ai.stigmer.commons.apiresource.ApiResourceAudit audit = 99;
+     */
+    audit?: ApiResourceAudit;
+    /**
+     * Sequential stream of execution events: AI messages, tool calls, and system notifications.
+     * Ordered chronologically to reconstruct the complete execution flow.
+     * Each message captures what happened during execution (agent responses, tool invocations, progress updates).
+     *
+     * @generated from field: repeated ai.stigmer.agentic.agentexecution.v1.AgentMessage messages = 1;
+     */
+    messages: AgentMessage[];
+    /**
+     * Current execution lifecycle phase.
+     * Tracks the execution state from creation (PENDING) through active processing (IN_PROGRESS)
+     * to terminal states (COMPLETED/FAILED/CANCELLED).
+     *
+     * @generated from field: ai.stigmer.agentic.agentexecution.v1.ExecutionPhase phase = 2;
+     */
+    phase: ExecutionPhase;
+    /**
+     * Tool calls made during this execution.
+     * Tracked separately for easier querying and display.
+     * Also referenced within messages[].tool_calls for conversation context.
+     *
+     * @generated from field: repeated ai.stigmer.agentic.agentexecution.v1.ToolCall tool_calls = 3;
+     */
+    toolCalls: ToolCall[];
+    /**
+     * Sub-agent executions invoked during this execution.
+     * Tracks when the main agent delegates work to specialized sub-agents.
+     * Ordered chronologically by invocation time.
+     *
+     * @generated from field: repeated ai.stigmer.agentic.agentexecution.v1.SubAgentExecution sub_agent_executions = 4;
+     */
+    subAgentExecutions: SubAgentExecution[];
+    /**
+     * Error message if execution failed.
+     * Only populated when phase == EXECUTION_FAILED.
+     *
+     * @generated from field: string error = 6;
+     */
+    error: string;
+    /**
+     * ISO 8601 timestamp when execution started.
+     * Example: "2025-01-10T10:30:00Z"
+     *
+     * @generated from field: string started_at = 7;
+     */
+    startedAt: string;
+    /**
+     * ISO 8601 timestamp when execution completed, failed, or was cancelled.
+     * Only populated for terminal states.
+     *
+     * @generated from field: string completed_at = 8;
+     */
+    completedAt: string;
+    /**
+     * Todo list tracking multi-step tasks and progress for this execution.
+     * Updated via write_todos tool (if TodoListMiddleware is enabled).
+     * Each execution maintains its own snapshot of todos at execution time.
+     * Key: todo item ID, Value: todo item details
+     *
+     * @generated from field: map<string, ai.stigmer.agentic.agentexecution.v1.TodoItem> todos = 9;
+     */
+    todos: {
+        [key: string]: TodoItem;
+    };
+    /**
+     * Temporal callback token for async activity completion.
+     *
+     * When this AgentExecution is triggered from a Temporal activity (e.g., from a workflow
+     * that invokes an agent), the calling activity passes its task token here. The agent-runner
+     * is responsible for completing the external activity when the agent execution finishes.
+     *
+     * ## Token Handshake Pattern
+     *
+     * Same pattern as WorkflowExecution (see workflowexecution/v1/api.proto for details):
+     * 1. External activity extracts token and stores in AgentExecution.status
+     * 2. Activity returns activity.ErrResultPending (paused, thread freed)
+     * 3. Agent executes (seconds to minutes)
+     * 4. On completion: agent-runner completes external activity via token
+     *
+     * ## Why in Status
+     *
+     * - System-generated by Temporal, not user-provided
+     * - Runtime state, not configuration
+     * - Ephemeral, only relevant during execution
+     *
+     * ## Use Cases
+     *
+     * - **With token**: Agent invoked from workflow, workflow waits for completion
+     * - **Without token**: Agent runs independently (chat, API call)
+     *
+     * ## References
+     *
+     * - WorkflowExecution.spec.callback_token (field 7) - Same pattern
+     * - [ADR](docs/adr/20260122-async-agent-execution-temporal-token-handshake.md)
+     *
+     * @generated from field: bytes callback_token = 10;
+     */
+    callbackToken: Uint8Array;
+    /**
+     * Token and LLM resource usage for this execution (main agent only).
+     * Does NOT include sub-agent usage - sum sub_agent_executions[].usage for total.
+     * Updated progressively during streaming for real-time cost visibility.
+     *
+     * @generated from field: ai.stigmer.agentic.agentexecution.v1.UsageMetrics usage = 11;
+     */
+    usage?: UsageMetrics;
+    /**
+     * Resolved execution context showing what resources the agent had access to.
+     * Populated once before streaming begins, after all resources are resolved.
+     * Immutable after initial population - represents the "snapshot" of resolved state.
+     *
+     * @generated from field: ai.stigmer.agentic.agentexecution.v1.ResolvedExecutionContext resolved_context = 12;
+     */
+    resolvedContext?: ResolvedExecutionContext;
+    /**
+     * All pending approval requests for this execution.
+     *
+     * Lifecycle:
+     * 1. Populated after the event stream ends, by querying graph state for
+     *    pending interrupts. Each interrupt is matched to a tool call.
+     * 2. Phase changes to EXECUTION_WAITING_FOR_APPROVAL.
+     * 3. User submits decisions via SubmitApproval RPC (one per tool call).
+     * 4. After ALL entries have decisions, the Temporal workflow signals resume.
+     * 5. On resume, all decisions are sent to LangGraph in a single Command.
+     *
+     * When populated:
+     * - Each entry's tool_call_id matches an entry in tool_calls[] with status
+     *   WAITING_APPROVAL
+     * - Each entry carries its interrupt_id for targeted resume
+     *
+     * Empty when no approvals are pending.
+     *
+     * @generated from field: repeated ai.stigmer.agentic.agentexecution.v1.PendingApproval pending_approvals = 16;
+     */
+    pendingApprovals: PendingApproval[];
+    /**
+     * Context window utilization and summarization tracking.
+     *
+     * Provides visibility into how the agent is using its context window and
+     * any summarization events that occurred during execution.
+     *
+     * Populated when context management is active (not disabled via config).
+     * Updated progressively during streaming as token counts change.
+     *
+     * Use cases:
+     * - **Monitoring**: Track context utilization across executions
+     * - **Debugging**: Understand why an execution hit context limits
+     * - **Cost optimization**: Identify executions with excessive summarization
+     * - **UX**: Show users their context window health
+     *
+     * @since Phase 3 (Context Summarization Architecture)
+     *
+     * @generated from field: ai.stigmer.agentic.agentexecution.v1.ContextInfo context_info = 14;
+     */
+    contextInfo?: ContextInfo;
+    /**
+     * Files/directories published by the agent for download.
+     *
+     * When an agent creates artifacts (e.g., generated code, reports, skills),
+     * it can call the publish_artifact tool to make them downloadable.
+     * Each artifact includes a pre-signed URL for direct download.
+     *
+     * Artifacts are stored in R2 and URLs expire after a configured period.
+     * Use the execution download endpoint to refresh expired URLs.
+     *
+     * Ordered by creation time (oldest first).
+     *
+     * @since Artifact Lifecycle (Attachments & Artifacts)
+     *
+     * @generated from field: repeated ai.stigmer.agentic.agentexecution.v1.ExecutionArtifact artifacts = 15;
+     */
+    artifacts: ExecutionArtifact[];
+};
+/**
+ * Describes the message ai.stigmer.agentic.agentexecution.v1.AgentExecutionStatus.
+ * Use `create(AgentExecutionStatusSchema)` to create a new message.
+ */
+export declare const AgentExecutionStatusSchema: GenMessage<AgentExecutionStatus>;
+/**
+ * Represents a single item in the agent's todo list.
+ * Used by the write_todos tool to track multi-step tasks and progress.
+ *
+ * @generated from message ai.stigmer.agentic.agentexecution.v1.TodoItem
+ */
+export type TodoItem = Message<"ai.stigmer.agentic.agentexecution.v1.TodoItem"> & {
+    /**
+     * Unique identifier for this todo item.
+     *
+     * @generated from field: string id = 1;
+     */
+    id: string;
+    /**
+     * Description of the task to be completed.
+     *
+     * @generated from field: string content = 2;
+     */
+    content: string;
+    /**
+     * Current status of the todo item.
+     *
+     * @generated from field: ai.stigmer.agentic.agentexecution.v1.TodoStatus status = 3;
+     */
+    status: TodoStatus;
+    /**
+     * ISO 8601 timestamp when the todo was created.
+     *
+     * @generated from field: string created_at = 4;
+     */
+    createdAt: string;
+    /**
+     * ISO 8601 timestamp when the todo was last updated.
+     *
+     * @generated from field: string updated_at = 5;
+     */
+    updatedAt: string;
+};
+/**
+ * Describes the message ai.stigmer.agentic.agentexecution.v1.TodoItem.
+ * Use `create(TodoItemSchema)` to create a new message.
+ */
+export declare const TodoItemSchema: GenMessage<TodoItem>;

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

@@ -0,0 +1,35 @@
+// @generated by protoc-gen-es v2.2.2 with parameter "target=ts"
+// @generated from file ai/stigmer/agentic/agentexecution/v1/api.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_artifact } from "./artifact_pb";
+import { file_ai_stigmer_agentic_agentexecution_v1_context } from "./context_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_spec } from "./spec_pb";
+import { file_ai_stigmer_agentic_agentexecution_v1_subagent } from "./subagent_pb";
+import { file_ai_stigmer_agentic_agentexecution_v1_usage } from "./usage_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/agentexecution/v1/api.proto.
+ */
+export const file_ai_stigmer_agentic_agentexecution_v1_api = /*@__PURE__*/ fileDesc("Ci5haS9zdGlnbWVyL2FnZW50aWMvYWdlbnRleGVjdXRpb24vdjEvYXBpLnByb3RvEiRhaS5zdGlnbWVyLmFnZW50aWMuYWdlbnRleGVjdXRpb24udjEiywIKDkFnZW50RXhlY3V0aW9uEjEKC2FwaV92ZXJzaW9uGAEgASgJQhy6SBlyFwoVYWdlbnRpYy5zdGlnbWVyLmFpL3YxEiMKBGtpbmQYAiABKAlCFbpIEnIQCg5BZ2VudEV4ZWN1dGlvbhJNCghtZXRhZGF0YRgDIAEoCzIzLmFpLnN0aWdtZXIuY29tbW9ucy5hcGlyZXNvdXJjZS5BcGlSZXNvdXJjZU1ldGFkYXRhQga6SAPIAQESRgoEc3BlYxgEIAEoCzI4LmFpLnN0aWdtZXIuYWdlbnRpYy5hZ2VudGV4ZWN1dGlvbi52MS5BZ2VudEV4ZWN1dGlvblNwZWMSSgoGc3RhdHVzGAUgASgLMjouYWkuc3RpZ21lci5hZ2VudGljLmFnZW50ZXhlY3V0aW9uLnYxLkFnZW50RXhlY3V0aW9uU3RhdHVzIpAIChRBZ2VudEV4ZWN1dGlvblN0YXR1cxI/CgVhdWRpdBhjIAEoCzIwLmFpLnN0aWdtZXIuY29tbW9ucy5hcGlyZXNvdXJjZS5BcGlSZXNvdXJjZUF1ZGl0EkQKCG1lc3NhZ2VzGAEgAygLMjIuYWkuc3RpZ21lci5hZ2VudGljLmFnZW50ZXhlY3V0aW9uLnYxLkFnZW50TWVzc2FnZRJNCgVwaGFzZRgCIAEoDjI0LmFpLnN0aWdtZXIuYWdlbnRpYy5hZ2VudGV4ZWN1dGlvbi52MS5FeGVjdXRpb25QaGFzZUIIukgFggECEAESQgoKdG9vbF9jYWxscxgDIAMoCzIuLmFpLnN0aWdtZXIuYWdlbnRpYy5hZ2VudGV4ZWN1dGlvbi52MS5Ub29sQ2FsbBJVChRzdWJfYWdlbnRfZXhlY3V0aW9ucxgEIAMoCzI3LmFpLnN0aWdtZXIuYWdlbnRpYy5hZ2VudGV4ZWN1dGlvbi52MS5TdWJBZ2VudEV4ZWN1dGlvbhINCgVlcnJvchgGIAEoCRISCgpzdGFydGVkX2F0GAcgASgJEhQKDGNvbXBsZXRlZF9hdBgIIAEoCRJUCgV0b2RvcxgJIAMoCzJFLmFpLnN0aWdtZXIuYWdlbnRpYy5hZ2VudGV4ZWN1dGlvbi52MS5BZ2VudEV4ZWN1dGlvblN0YXR1cy5Ub2Rvc0VudHJ5EhYKDmNhbGxiYWNrX3Rva2VuGAogASgMEkEKBXVzYWdlGAsgASgLMjIuYWkuc3RpZ21lci5hZ2VudGljLmFnZW50ZXhlY3V0aW9uLnYxLlVzYWdlTWV0cmljcxJYChByZXNvbHZlZF9jb250ZXh0GAwgASgLMj4uYWkuc3RpZ21lci5hZ2VudGljLmFnZW50ZXhlY3V0aW9uLnYxLlJlc29sdmVkRXhlY3V0aW9uQ29udGV4dBJQChFwZW5kaW5nX2FwcHJvdmFscxgQIAMoCzI1LmFpLnN0aWdtZXIuYWdlbnRpYy5hZ2VudGV4ZWN1dGlvbi52MS5QZW5kaW5nQXBwcm92YWwSRwoMY29udGV4dF9pbmZvGA4gASgLMjEuYWkuc3RpZ21lci5hZ2VudGljLmFnZW50ZXhlY3V0aW9uLnYxLkNvbnRleHRJbmZvEkoKCWFydGlmYWN0cxgPIAMoCzI3LmFpLnN0aWdtZXIuYWdlbnRpYy5hZ2VudGV4ZWN1dGlvbi52MS5FeGVjdXRpb25BcnRpZmFjdBpcCgpUb2Rvc0VudHJ5EgsKA2tleRgBIAEoCRI9CgV2YWx1ZRgCIAEoCzIuLmFpLnN0aWdtZXIuYWdlbnRpYy5hZ2VudGV4ZWN1dGlvbi52MS5Ub2RvSXRlbToCOAEikQEKCFRvZG9JdGVtEgoKAmlkGAEgASgJEg8KB2NvbnRlbnQYAiABKAkSQAoGc3RhdHVzGAMgASgOMjAuYWkuc3RpZ21lci5hZ2VudGljLmFnZW50ZXhlY3V0aW9uLnYxLlRvZG9TdGF0dXMSEgoKY3JlYXRlZF9hdBgEIAEoCRISCgp1cGRhdGVkX2F0GAUgASgJYgZwcm90bzM", [file_ai_stigmer_agentic_agentexecution_v1_approval, file_ai_stigmer_agentic_agentexecution_v1_artifact, file_ai_stigmer_agentic_agentexecution_v1_context, file_ai_stigmer_agentic_agentexecution_v1_enum, file_ai_stigmer_agentic_agentexecution_v1_message, file_ai_stigmer_agentic_agentexecution_v1_spec, file_ai_stigmer_agentic_agentexecution_v1_subagent, file_ai_stigmer_agentic_agentexecution_v1_usage, file_ai_stigmer_commons_apiresource_metadata, file_ai_stigmer_commons_apiresource_status, file_buf_validate_validate]);
+/**
+ * Describes the message ai.stigmer.agentic.agentexecution.v1.AgentExecution.
+ * Use `create(AgentExecutionSchema)` to create a new message.
+ */
+export const AgentExecutionSchema = /*@__PURE__*/ messageDesc(file_ai_stigmer_agentic_agentexecution_v1_api, 0);
+/**
+ * Describes the message ai.stigmer.agentic.agentexecution.v1.AgentExecutionStatus.
+ * Use `create(AgentExecutionStatusSchema)` to create a new message.
+ */
+export const AgentExecutionStatusSchema = /*@__PURE__*/ messageDesc(file_ai_stigmer_agentic_agentexecution_v1_api, 1);
+/**
+ * Describes the message ai.stigmer.agentic.agentexecution.v1.TodoItem.
+ * Use `create(TodoItemSchema)` to create a new message.
+ */
+export const TodoItemSchema = /*@__PURE__*/ messageDesc(file_ai_stigmer_agentic_agentexecution_v1_api, 2);
+//# sourceMappingURL=api_pb.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"api_pb.js","sourceRoot":"","sources":["../../../../../../ai/stigmer/agentic/agentexecution/v1/api_pb.ts"],"names":[],"mappings":"AAAA,gEAAgE;AAChE,oIAAoI;AACpI,oBAAoB;AAGpB,OAAO,EAAE,QAAQ,EAAE,WAAW,EAAE,MAAM,8BAA8B,CAAC;AAErE,OAAO,EAAE,kDAAkD,EAAE,MAAM,eAAe,CAAC;AAEnF,OAAO,EAAE,kDAAkD,EAAE,MAAM,eAAe,CAAC;AAEnF,OAAO,EAAE,iDAAiD,EAAE,MAAM,cAAc,CAAC;AAEjF,OAAO,EAAE,8CAA8C,EAAE,MAAM,WAAW,CAAC;AAE3E,OAAO,EAAE,iDAAiD,EAAE,MAAM,cAAc,CAAC;AAEjF,OAAO,EAAE,8CAA8C,EAAE,MAAM,WAAW,CAAC;AAE3E,OAAO,EAAE,kDAAkD,EAAE,MAAM,eAAe,CAAC;AAEnF,OAAO,EAAE,+CAA+C,EAAE,MAAM,YAAY,CAAC;AAE7E,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,6CAA6C,GAAY,aAAa,CACjF,QAAQ,CAAC,inEAAinE,EAAE,CAAC,kDAAkD,EAAE,kDAAkD,EAAE,iDAAiD,EAAE,8CAA8C,EAAE,iDAAiD,EAAE,8CAA8C,EAAE,kDAAkD,EAAE,+CAA+C,EAAE,4CAA4C,EAAE,0CAA0C,EAAE,0BAA0B,CAAC,CAAC,CAAC;AAgDzoF;;;GAGG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAA+B,aAAa,CAC3E,WAAW,CAAC,6CAA6C,EAAE,CAAC,CAAC,CAAC;AAyMhE;;;GAGG;AACH,MAAM,CAAC,MAAM,0BAA0B,GAAqC,aAAa,CACvF,WAAW,CAAC,6CAA6C,EAAE,CAAC,CAAC,CAAC;AA6ChE;;;GAGG;AACH,MAAM,CAAC,MAAM,cAAc,GAAyB,aAAa,CAC/D,WAAW,CAAC,6CAA6C,EAAE,CAAC,CAAC,CAAC"}

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

@@ -0,0 +1,206 @@
+import type { GenFile, GenMessage } from "@bufbuild/protobuf/codegenv1";
+import type { Message } from "@bufbuild/protobuf";
+/**
+ * Describes the file ai/stigmer/agentic/agentexecution/v1/approval.proto.
+ */
+export declare const file_ai_stigmer_agentic_agentexecution_v1_approval: GenFile;
+/**
+ * PendingApproval surfaces the current approval request for UI display.
+ *
+ * ## Purpose
+ *
+ * This message provides all information needed for a UI to render an approval
+ * dialog/card. It's populated when an execution enters WAITING_FOR_APPROVAL phase.
+ *
+ * ## Relationship to ToolCall
+ *
+ * While ToolCall contains the canonical approval state, PendingApproval provides
+ * a denormalized view optimized for UI consumption. The tool_call_id links back
+ * to the authoritative ToolCall record.
+ *
+ * ## Sub-Agent Approvals
+ *
+ * When a sub-agent's tool requires approval, the main agent's pending_approval
+ * is populated with from_sub_agent=true. This allows UI to show:
+ * "Sub-agent 'code-reviewer' needs approval to execute 'delete_file'"
+ *
+ * ## Lifecycle
+ *
+ * 1. Tool with requires_approval=true is about to execute
+ * 2. PendingApproval is populated, phase becomes WAITING_FOR_APPROVAL
+ * 3. User calls SubmitApproval RPC with their decision
+ * 4. PendingApproval is cleared, phase returns to IN_PROGRESS (or FAILED on REJECT)
+ *
+ * @generated from message ai.stigmer.agentic.agentexecution.v1.PendingApproval
+ */
+export type PendingApproval = Message<"ai.stigmer.agentic.agentexecution.v1.PendingApproval"> & {
+    /**
+     * ID of the tool call waiting for approval.
+     * Use this when calling SubmitApproval to identify which tool call to resume.
+     * Format: Tool call ID from the agent runtime (e.g., "call_abc123")
+     *
+     * @generated from field: string tool_call_id = 1;
+     */
+    toolCallId: string;
+    /**
+     * Name of the tool requiring approval.
+     * Matches ToolCall.name for correlation.
+     * Example: "delete_repository", "send_email", "execute_sql"
+     *
+     * @generated from field: string tool_name = 2;
+     */
+    toolName: string;
+    /**
+     * Human-readable approval message for display.
+     * Copied from ToolCall.approval_message for UI convenience.
+     * Contains resolved placeholders (e.g., "Delete repo: my-repo")
+     *
+     * @generated from field: string message = 3;
+     */
+    message: string;
+    /**
+     * Sanitized preview of tool arguments for informed decision-making.
+     * Sensitive values (passwords, tokens) are redacted.
+     * Displayed as formatted JSON or key-value pairs in UI.
+     *
+     * Example:
+     *   {
+     *     "repository": "acme/important-repo",
+     *     "force": true,
+     *     "reason": "cleanup"
+     *   }
+     *
+     * @generated from field: string args_preview = 4;
+     */
+    argsPreview: string;
+    /**
+     * ISO 8601 timestamp when the approval was requested.
+     * Enables UI to show waiting duration: "Waiting for 2 minutes"
+     * Example: "2026-01-30T15:30:00Z"
+     *
+     * @generated from field: string requested_at = 5;
+     */
+    requestedAt: string;
+    /**
+     * True if this approval originates from a sub-agent.
+     * Enables differentiated UI treatment:
+     *   - false: "Agent needs approval to..."
+     *   - true: "Sub-agent 'name' needs approval to..."
+     *
+     * @generated from field: bool from_sub_agent = 6;
+     */
+    fromSubAgent: boolean;
+    /**
+     * Name of the sub-agent if from_sub_agent is true.
+     * Example: "code-reviewer", "researcher", "debugger"
+     * Empty if from_sub_agent is false.
+     *
+     * @generated from field: string sub_agent_name = 7;
+     */
+    subAgentName: string;
+    /**
+     * ID of the child agent execution (for workflow-level approvals only).
+     *
+     * Populated when this PendingApproval is surfaced at WorkflowExecution level.
+     * Empty when pending_approval is on AgentExecution directly.
+     *
+     * Use this ID to forward approvals from workflow to child agent via
+     * AgentExecution.submitApproval RPC.
+     *
+     * Format: "aex_abc123xyz456"
+     *
+     * @since Phase 5.3 (Approval Forwarding)
+     *
+     * @generated from field: string child_agent_execution_id = 8;
+     */
+    childAgentExecutionId: string;
+    /**
+     * LangGraph interrupt ID for targeted resume.
+     *
+     * When the LLM returns multiple tool calls requiring approval in a single
+     * response, LangGraph creates one interrupt per tool. Each interrupt receives
+     * a unique ID. On resume, `Command(resume={interrupt_id: value})` must target
+     * the specific interrupt; otherwise LangGraph raises
+     * "multiple pending interrupts, you must specify the interrupt id."
+     *
+     * Populated by the agent-runner after the event stream ends by querying
+     * `graph.get_state(config).interrupts`. Matched to the tool call via
+     * the interrupt's value payload (which contains tool_name).
+     *
+     * Empty for legacy executions or single-interrupt scenarios (backward compat).
+     *
+     * @since Batch Approval (Multiple Interrupts)
+     *
+     * @generated from field: string interrupt_id = 9;
+     */
+    interruptId: string;
+};
+/**
+ * Describes the message ai.stigmer.agentic.agentexecution.v1.PendingApproval.
+ * Use `create(PendingApprovalSchema)` to create a new message.
+ */
+export declare const PendingApprovalSchema: GenMessage<PendingApproval>;
+/**
+ * ChildApprovalNotification is the signal payload sent to parent workflows
+ * when a child agent enters WAITING_FOR_APPROVAL state.
+ *
+ * This enables events-based notification instead of polling, providing
+ * sub-100ms latency for approval state propagation from child agents to
+ * parent workflows.
+ *
+ * ## Signal Flow
+ *
+ * 1. Child agent requires tool approval (phase = WAITING_FOR_APPROVAL)
+ * 2. Java workflow detects this and builds ChildApprovalNotification
+ * 3. Java sends Temporal signal "child_approval_required" to parent workflow
+ * 4. Parent Go workflow receives signal via signal channel
+ * 5. Parent updates task status to WORKFLOW_TASK_WAITING_APPROVAL
+ * 6. Parent populates WorkflowExecution.status.pending_approvals
+ *
+ * ## Parent Workflow Actions
+ *
+ * Upon receiving this signal, the parent workflow should:
+ * 1. Update its task status to WORKFLOW_TASK_WAITING_APPROVAL
+ * 2. Populate WorkflowExecution.status.pending_approvals with all entries
+ * 3. Surface the approval requests to users via UI/API
+ *
+ * ## Graceful Degradation
+ *
+ * If the signal fails to send (parent workflow completed, network error),
+ * the system continues to function. Users can still submit approvals directly
+ * via the AgentExecution.SubmitApproval RPC.
+ *
+ * @since Phase 5.1 (Events-Based Approval Notification)
+ *
+ * @generated from message ai.stigmer.agentic.agentexecution.v1.ChildApprovalNotification
+ */
+export type ChildApprovalNotification = Message<"ai.stigmer.agentic.agentexecution.v1.ChildApprovalNotification"> & {
+    /**
+     * Child agent execution ID that requires approval.
+     * Format: AgentExecution.metadata.id (e.g., "agx-abc123xyz456")
+     * Used by parent to track which child needs approval.
+     *
+     * @generated from field: string execution_id = 1;
+     */
+    executionId: string;
+    /**
+     * All pending approvals from this child agent execution.
+     *
+     * Contains one entry per tool call requiring approval. Each entry carries
+     * the full PendingApproval details (tool_call_id, tool_name, message,
+     * args_preview, requested_at, interrupt_id).
+     *
+     * The child_agent_execution_id on each entry is set to execution_id above
+     * so the parent can correlate approvals to the originating child.
+     *
+     * One signal, complete picture, no partial states.
+     *
+     * @generated from field: repeated ai.stigmer.agentic.agentexecution.v1.PendingApproval pending_approvals = 2;
+     */
+    pendingApprovals: PendingApproval[];
+};
+/**
+ * Describes the message ai.stigmer.agentic.agentexecution.v1.ChildApprovalNotification.
+ * Use `create(ChildApprovalNotificationSchema)` to create a new message.
+ */
+export declare const ChildApprovalNotificationSchema: GenMessage<ChildApprovalNotification>;

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

@@ -0,0 +1,19 @@
+// @generated by protoc-gen-es v2.2.2 with parameter "target=ts"
+// @generated from file ai/stigmer/agentic/agentexecution/v1/approval.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/approval.proto.
+ */
+export const file_ai_stigmer_agentic_agentexecution_v1_approval = /*@__PURE__*/ fileDesc("CjNhaS9zdGlnbWVyL2FnZW50aWMvYWdlbnRleGVjdXRpb24vdjEvYXBwcm92YWwucHJvdG8SJGFpLnN0aWdtZXIuYWdlbnRpYy5hZ2VudGV4ZWN1dGlvbi52MSLfAQoPUGVuZGluZ0FwcHJvdmFsEhQKDHRvb2xfY2FsbF9pZBgBIAEoCRIRCgl0b29sX25hbWUYAiABKAkSDwoHbWVzc2FnZRgDIAEoCRIUCgxhcmdzX3ByZXZpZXcYBCABKAkSFAoMcmVxdWVzdGVkX2F0GAUgASgJEhYKDmZyb21fc3ViX2FnZW50GAYgASgIEhYKDnN1Yl9hZ2VudF9uYW1lGAcgASgJEiAKGGNoaWxkX2FnZW50X2V4ZWN1dGlvbl9pZBgIIAEoCRIUCgxpbnRlcnJ1cHRfaWQYCSABKAkigwEKGUNoaWxkQXBwcm92YWxOb3RpZmljYXRpb24SFAoMZXhlY3V0aW9uX2lkGAEgASgJElAKEXBlbmRpbmdfYXBwcm92YWxzGAIgAygLMjUuYWkuc3RpZ21lci5hZ2VudGljLmFnZW50ZXhlY3V0aW9uLnYxLlBlbmRpbmdBcHByb3ZhbGIGcHJvdG8z");
+/**
+ * Describes the message ai.stigmer.agentic.agentexecution.v1.PendingApproval.
+ * Use `create(PendingApprovalSchema)` to create a new message.
+ */
+export const PendingApprovalSchema = /*@__PURE__*/ messageDesc(file_ai_stigmer_agentic_agentexecution_v1_approval, 0);
+/**
+ * Describes the message ai.stigmer.agentic.agentexecution.v1.ChildApprovalNotification.
+ * Use `create(ChildApprovalNotificationSchema)` to create a new message.
+ */
+export const ChildApprovalNotificationSchema = /*@__PURE__*/ messageDesc(file_ai_stigmer_agentic_agentexecution_v1_approval, 1);
+//# sourceMappingURL=approval_pb.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"approval_pb.js","sourceRoot":"","sources":["../../../../../../ai/stigmer/agentic/agentexecution/v1/approval_pb.ts"],"names":[],"mappings":"AAAA,gEAAgE;AAChE,yIAAyI;AACzI,oBAAoB;AAGpB,OAAO,EAAE,QAAQ,EAAE,WAAW,EAAE,MAAM,8BAA8B,CAAC;AAGrE;;GAEG;AACH,MAAM,CAAC,MAAM,kDAAkD,GAAY,aAAa,CACtF,QAAQ,CAAC,smBAAsmB,CAAC,CAAC;AA8InnB;;;GAGG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAgC,aAAa,CAC7E,WAAW,CAAC,kDAAkD,EAAE,CAAC,CAAC,CAAC;AA+DrE;;;GAGG;AACH,MAAM,CAAC,MAAM,+BAA+B,GAA0C,aAAa,CACjG,WAAW,CAAC,kDAAkD,EAAE,CAAC,CAAC,CAAC"}

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

@@ -0,0 +1,91 @@
+import type { GenFile, GenMessage } from "@bufbuild/protobuf/codegenv1";
+import type { ExecutionArtifactKind } from "./enum_pb";
+import type { Message } from "@bufbuild/protobuf";
+/**
+ * Describes the file ai/stigmer/agentic/agentexecution/v1/artifact.proto.
+ */
+export declare const file_ai_stigmer_agentic_agentexecution_v1_artifact: GenFile;
+/**
+ * ExecutionArtifact represents a file or directory published by an agent.
+ *
+ * When an agent creates artifacts that users should download, it calls
+ * the publish_artifact tool. This generates a downloadable artifact stored
+ * in R2 with a time-limited signed URL.
+ *
+ * ## Storage
+ *
+ * Artifacts are stored in R2 under: artifacts/{execution_id}/{filename}
+ * Download URLs are pre-signed and expire after a configured period.
+ *
+ * ## Directory Handling
+ *
+ * Directories are automatically archived as ZIP files before storage.
+ * The kind field indicates DIRECTORY so clients know to extract after download.
+ *
+ * @since Artifact Lifecycle (Attachments & Artifacts)
+ *
+ * @generated from message ai.stigmer.agentic.agentexecution.v1.ExecutionArtifact
+ */
+export type ExecutionArtifact = Message<"ai.stigmer.agentic.agentexecution.v1.ExecutionArtifact"> & {
+    /**
+     * Display name for this artifact.
+     * Example: "generated-skill", "analysis-report"
+     *
+     * @generated from field: string name = 1;
+     */
+    name: string;
+    /**
+     * Original path in sandbox where the artifact was created.
+     * Example: "/workspace/my-skill", "/tmp/report.pdf"
+     *
+     * @generated from field: string sandbox_path = 2;
+     */
+    sandboxPath: string;
+    /**
+     * Type of artifact: file or directory.
+     *
+     * @generated from field: ai.stigmer.agentic.agentexecution.v1.ExecutionArtifactKind kind = 3;
+     */
+    kind: ExecutionArtifactKind;
+    /**
+     * Total size in bytes.
+     * For directories, this is the ZIP file size.
+     *
+     * @generated from field: int64 size_bytes = 4;
+     */
+    sizeBytes: bigint;
+    /**
+     * Storage location in R2.
+     * Format: "artifacts/{execution_id}/{filename}"
+     *
+     * @generated from field: string storage_key = 5;
+     */
+    storageKey: string;
+    /**
+     * Pre-signed URL for downloading the artifact.
+     * Expires after a configured period (default: 7 days).
+     * Clients can call the refresh endpoint to get a new URL if expired.
+     *
+     * @generated from field: string download_url = 6;
+     */
+    downloadUrl: string;
+    /**
+     * ISO 8601 timestamp when the artifact was created.
+     * Example: "2026-02-13T10:30:00Z"
+     *
+     * @generated from field: string created_at = 7;
+     */
+    createdAt: string;
+    /**
+     * ISO 8601 timestamp when the download URL expires.
+     * Example: "2026-02-20T10:30:00Z"
+     *
+     * @generated from field: string expires_at = 8;
+     */
+    expiresAt: string;
+};
+/**
+ * Describes the message ai.stigmer.agentic.agentexecution.v1.ExecutionArtifact.
+ * Use `create(ExecutionArtifactSchema)` to create a new message.
+ */
+export declare const ExecutionArtifactSchema: GenMessage<ExecutionArtifact>;