@stigmer/protos 0.0.34

package/ai/stigmer/agentic/workflowexecution/v1/io_pb.d.ts

@@ -0,0 +1,1198 @@
+import type { GenEnum, GenFile, GenMessage } from "@bufbuild/protobuf/codegenv1";
+import type { ApprovalAction } from "../../agentexecution/v1/enum_pb";
+import type { WorkflowExecution, WorkflowExecutionStatus, WorkflowTask } from "./api_pb";
+import type { ExecutionPhase } from "./enum_pb";
+import type { JsonObject, Message } from "@bufbuild/protobuf";
+/**
+ * Describes the file ai/stigmer/agentic/workflowexecution/v1/io.proto.
+ */
+export declare const file_ai_stigmer_agentic_workflowexecution_v1_io: GenFile;
+/**
+ * WorkflowExecutionId wraps a workflow execution identifier.
+ *
+ * This wrapper message is used as input for RPCs that need an execution ID.
+ * Using a wrapper (instead of a raw string) provides:
+ * - Validation (required field enforcement)
+ * - Clear field naming ("value" instead of unnamed parameter)
+ * - Extensibility (can add fields later without breaking API)
+ *
+ * Format: "wfx-{unique-suffix}"
+ * Example: "wfx-abc123xyz456"
+ *
+ * Used By:
+ * - get(WorkflowExecutionId): Get a single execution by ID
+ * - delete(WorkflowExecutionId): Delete an execution (if implemented)
+ *
+ * @generated from message ai.stigmer.agentic.workflowexecution.v1.WorkflowExecutionId
+ */
+export type WorkflowExecutionId = Message<"ai.stigmer.agentic.workflowexecution.v1.WorkflowExecutionId"> & {
+    /**
+     * Workflow execution identifier.
+     *
+     * Format: "wfx-{unique-suffix}" (auto-generated by backend)
+     * Example: "wfx-abc123xyz456"
+     *
+     * Validation: Required field, cannot be empty
+     *
+     * @generated from field: string value = 1;
+     */
+    value: string;
+};
+/**
+ * Describes the message ai.stigmer.agentic.workflowexecution.v1.WorkflowExecutionId.
+ * Use `create(WorkflowExecutionIdSchema)` to create a new message.
+ */
+export declare const WorkflowExecutionIdSchema: GenMessage<WorkflowExecutionId>;
+/**
+ * WorkflowId wraps a workflow or workflow instance identifier for filtering.
+ *
+ * This wrapper is used to filter executions by a specific Workflow or WorkflowInstance.
+ * It can accept either:
+ * - Workflow ID (wf-{slug}): Lists all executions of any instance of this workflow
+ * - WorkflowInstance ID (wfi-{slug}): Lists executions of a specific instance
+ *
+ * Format Examples:
+ * - Workflow ID: "wf-customer-onboarding"
+ * - WorkflowInstance ID: "wfi-customer-onboarding-prod"
+ *
+ * Used By:
+ * - list_by_workflow(ListWorkflowExecutionsByWorkflowRequest): Filter executions by workflow
+ *
+ * @generated from message ai.stigmer.agentic.workflowexecution.v1.WorkflowId
+ */
+export type WorkflowId = Message<"ai.stigmer.agentic.workflowexecution.v1.WorkflowId"> & {
+    /**
+     * Workflow or WorkflowInstance identifier.
+     *
+     * Can be either:
+     * - Workflow ID (wf-{slug}): Filter by workflow template
+     * - WorkflowInstance ID (wfi-{slug}): Filter by specific instance
+     *
+     * Examples:
+     * - "wf-customer-onboarding" (all instances of this workflow)
+     * - "wfi-customer-onboarding-prod" (specific instance)
+     *
+     * Validation: Required field, cannot be empty
+     *
+     * @generated from field: string value = 1;
+     */
+    value: string;
+};
+/**
+ * Describes the message ai.stigmer.agentic.workflowexecution.v1.WorkflowId.
+ * Use `create(WorkflowIdSchema)` to create a new message.
+ */
+export declare const WorkflowIdSchema: GenMessage<WorkflowId>;
+/**
+ * WorkflowExecutionList contains a paginated list of workflow executions.
+ *
+ * This message is returned by list operations (list, list_by_workflow).
+ * It includes pagination metadata to help clients navigate through large result sets.
+ *
+ * Pagination Pattern:
+ * 1. Client sends request with page_size (e.g., 50)
+ * 2. Server returns up to page_size entries + total_pages count
+ * 3. Client displays entries and "Page 1 of N" indicator
+ * 4. Client can request next page using page_token from response
+ *
+ * Example Usage:
+ * Response for page 1:
+ * {
+ *   "total_pages": 10,
+ *   "entries": [ execution1, execution2, ... execution50 ]
+ * }
+ *
+ * @generated from message ai.stigmer.agentic.workflowexecution.v1.WorkflowExecutionList
+ */
+export type WorkflowExecutionList = Message<"ai.stigmer.agentic.workflowexecution.v1.WorkflowExecutionList"> & {
+    /**
+     * Total number of pages available for this query.
+     *
+     * Calculated as: ceil(total_matching_executions / page_size)
+     *
+     * Example: If 237 executions match and page_size=50, total_pages=5
+     *
+     * Use Cases:
+     * - Display pagination UI ("Page 1 of 5")
+     * - Disable "Next" button when on last page
+     * - Show total result count (total_pages * page_size approximation)
+     *
+     * Note: total_pages may change between requests if new executions are created
+     * or deleted, or if filters change.
+     *
+     * @generated from field: int32 total_pages = 1;
+     */
+    totalPages: number;
+    /**
+     * Workflow executions in the current page.
+     *
+     * Contains up to page_size WorkflowExecution resources.
+     * May contain fewer than page_size if:
+     * - This is the last page (fewer remaining results)
+     * - Fewer results match the filter criteria
+     *
+     * Executions are sorted by created_at descending (newest first).
+     *
+     * Example:
+     * entries: [
+     *   { metadata: { id: "wfx-newest", created_at: "2025-01-11T14:30:22Z" }, ... },
+     *   { metadata: { id: "wfx-second", created_at: "2025-01-11T10:15:00Z" }, ... },
+     *   { metadata: { id: "wfx-third", created_at: "2025-01-10T22:05:33Z" }, ... }
+     * ]
+     *
+     * @generated from field: repeated ai.stigmer.agentic.workflowexecution.v1.WorkflowExecution entries = 2;
+     */
+    entries: WorkflowExecution[];
+};
+/**
+ * Describes the message ai.stigmer.agentic.workflowexecution.v1.WorkflowExecutionList.
+ * Use `create(WorkflowExecutionListSchema)` to create a new message.
+ */
+export declare const WorkflowExecutionListSchema: GenMessage<WorkflowExecutionList>;
+/**
+ * ListWorkflowExecutionsRequest specifies parameters for listing workflow executions.
+ *
+ * Supports pagination and filtering to help users find specific executions.
+ * Used by the list() RPC to retrieve executions across all workflows.
+ *
+ * Common Use Cases:
+ * - List all recent executions (no filters)
+ * - List all in-progress executions (phase filter)
+ * - List all failed executions (phase filter)
+ * - List executions for specific environment (tags filter)
+ * - Page through execution history (pagination)
+ *
+ * @generated from message ai.stigmer.agentic.workflowexecution.v1.ListWorkflowExecutionsRequest
+ */
+export type ListWorkflowExecutionsRequest = Message<"ai.stigmer.agentic.workflowexecution.v1.ListWorkflowExecutionsRequest"> & {
+    /**
+     * Maximum number of executions to return per page.
+     *
+     * Default: 50 (if not specified or 0)
+     * Maximum: 100 (backend enforces this limit)
+     *
+     * Recommendation: Use 20-50 for UI lists, 100 for bulk exports
+     *
+     * Example: page_size=20 returns up to 20 executions
+     *
+     * @generated from field: int32 page_size = 1;
+     */
+    pageSize: number;
+    /**
+     * Token for pagination, obtained from previous response.
+     *
+     * Opaque string generated by the server to represent a cursor in the result set.
+     *
+     * Pagination Flow:
+     * 1. Initial request: page_token is empty (or not set)
+     * 2. Server returns first page + page_token for next page
+     * 3. Subsequent request: include page_token from previous response
+     * 4. Server returns next page + new page_token
+     * 5. When page_token is empty in response, no more pages available
+     *
+     * Example:
+     * Request 1: { page_size: 50 }
+     * Response 1: { entries: [...], page_token: "eyJvZmZzZXQiOjUwfQ==" }
+     * Request 2: { page_size: 50, page_token: "eyJvZmZzZXQiOjUwfQ==" }
+     * Response 2: { entries: [...], page_token: "" }  // Last page
+     *
+     * Note: page_token is opaque - clients should not parse or modify it.
+     *
+     * @generated from field: string page_token = 2;
+     */
+    pageToken: string;
+    /**
+     * Filter by execution phase (optional).
+     *
+     * Limits results to executions in a specific phase.
+     * If not specified (or EXECUTION_PHASE_UNSPECIFIED), all phases are included.
+     *
+     * Common Filters:
+     * - EXECUTION_IN_PROGRESS: Show only running executions
+     * - EXECUTION_FAILED: Show only failed executions (for debugging)
+     * - EXECUTION_COMPLETED: Show only successful executions
+     *
+     * Example Use Cases:
+     * - Monitor dashboard: phase=EXECUTION_IN_PROGRESS
+     * - Debug dashboard: phase=EXECUTION_FAILED
+     * - Success audit: phase=EXECUTION_COMPLETED
+     *
+     * Example: phase=2 (EXECUTION_IN_PROGRESS)
+     *
+     * @generated from field: ai.stigmer.agentic.workflowexecution.v1.ExecutionPhase phase = 3;
+     */
+    phase: ExecutionPhase;
+    /**
+     * Filter by resource tags (optional).
+     *
+     * Limits results to executions that have ALL specified tags (AND logic).
+     * Tags are key-value pairs stored in metadata.tags.
+     *
+     * Tag Format: "key:value" or "key" (for boolean tags)
+     * Example tags:
+     * - "environment:production"
+     * - "team:backend"
+     * - "critical"
+     * - "region:us-west-2"
+     *
+     * Filtering Logic:
+     * If tags=["environment:production", "team:backend"], result must have BOTH tags.
+     *
+     * Example Use Cases:
+     * - List production executions: tags=["environment:production"]
+     * - List backend team's critical executions: tags=["team:backend", "critical"]
+     * - List executions in specific region: tags=["region:us-west-2"]
+     *
+     * Example:
+     * tags: ["environment:production", "critical"]
+     *
+     * @generated from field: repeated string tags = 4;
+     */
+    tags: string[];
+};
+/**
+ * Describes the message ai.stigmer.agentic.workflowexecution.v1.ListWorkflowExecutionsRequest.
+ * Use `create(ListWorkflowExecutionsRequestSchema)` to create a new message.
+ */
+export declare const ListWorkflowExecutionsRequestSchema: GenMessage<ListWorkflowExecutionsRequest>;
+/**
+ * ListWorkflowExecutionsByWorkflowRequest lists all executions for a specific workflow.
+ *
+ * Filters executions by Workflow or WorkflowInstance ID.
+ * Used to view execution history for a particular workflow.
+ *
+ * Difference from ListWorkflowExecutionsRequest:
+ * - ListWorkflowExecutionsRequest: Lists executions across ALL workflows (with optional filters)
+ * - ListWorkflowExecutionsByWorkflowRequest: Lists executions for ONE specific workflow
+ *
+ * Use Cases:
+ * - Workflow details page: Show execution history for this workflow
+ * - Workflow testing: View all test runs of this workflow
+ * - Performance analysis: Analyze execution patterns for this workflow
+ *
+ * @generated from message ai.stigmer.agentic.workflowexecution.v1.ListWorkflowExecutionsByWorkflowRequest
+ */
+export type ListWorkflowExecutionsByWorkflowRequest = Message<"ai.stigmer.agentic.workflowexecution.v1.ListWorkflowExecutionsByWorkflowRequest"> & {
+    /**
+     * Workflow or WorkflowInstance ID to filter by.
+     *
+     * Can be either:
+     * - Workflow ID (wf-{slug}): Lists all executions of any instance
+     * - WorkflowInstance ID (wfi-{slug}): Lists executions of specific instance
+     *
+     * Examples:
+     * - "wf-customer-onboarding" (all instances: prod, dev, staging)
+     * - "wfi-customer-onboarding-prod" (only prod instance)
+     *
+     * Validation: Required field, cannot be empty
+     *
+     * Error Cases:
+     * - NOT_FOUND: No Workflow/WorkflowInstance with this ID exists
+     * - PERMISSION_DENIED: User doesn't have access to this Workflow/WorkflowInstance
+     *
+     * @generated from field: string workflow_id = 1;
+     */
+    workflowId: string;
+    /**
+     * Maximum number of executions to return per page.
+     *
+     * Default: 50 (if not specified or 0)
+     * Maximum: 100 (backend enforces this limit)
+     *
+     * Example: page_size=20 returns up to 20 executions
+     *
+     * @generated from field: int32 page_size = 2;
+     */
+    pageSize: number;
+    /**
+     * Token for pagination, obtained from previous response.
+     *
+     * Same pagination semantics as ListWorkflowExecutionsRequest.page_token.
+     *
+     * Example:
+     * Request 1: { workflow_id: "wfi-prod", page_size: 50 }
+     * Response 1: { entries: [...], page_token: "abc123" }
+     * Request 2: { workflow_id: "wfi-prod", page_size: 50, page_token: "abc123" }
+     *
+     * @generated from field: string page_token = 3;
+     */
+    pageToken: string;
+};
+/**
+ * Describes the message ai.stigmer.agentic.workflowexecution.v1.ListWorkflowExecutionsByWorkflowRequest.
+ * Use `create(ListWorkflowExecutionsByWorkflowRequestSchema)` to create a new message.
+ */
+export declare const ListWorkflowExecutionsByWorkflowRequestSchema: GenMessage<ListWorkflowExecutionsByWorkflowRequest>;
+/**
+ * Input message for updateStatus RPC.
+ * Contains only the execution ID and the status fields to be updated.
+ * This avoids validation errors on incomplete metadata/spec fields and makes the API contract clearer.
+ *
+ * @generated from message ai.stigmer.agentic.workflowexecution.v1.WorkflowExecutionUpdateStatusInput
+ */
+export type WorkflowExecutionUpdateStatusInput = Message<"ai.stigmer.agentic.workflowexecution.v1.WorkflowExecutionUpdateStatusInput"> & {
+    /**
+     * ID of the workflow execution to update (required).
+     * Format: "wex_abc123xyz456"
+     *
+     * @generated from field: string execution_id = 1;
+     */
+    executionId: string;
+    /**
+     * Status fields to update.
+     * The handler will merge these status fields with the existing execution's status.
+     * Only the fields present in this status object will be updated.
+     *
+     * @generated from field: ai.stigmer.agentic.workflowexecution.v1.WorkflowExecutionStatus status = 2;
+     */
+    status?: WorkflowExecutionStatus;
+};
+/**
+ * Describes the message ai.stigmer.agentic.workflowexecution.v1.WorkflowExecutionUpdateStatusInput.
+ * Use `create(WorkflowExecutionUpdateStatusInputSchema)` to create a new message.
+ */
+export declare const WorkflowExecutionUpdateStatusInputSchema: GenMessage<WorkflowExecutionUpdateStatusInput>;
+/**
+ * Input message for submitApproval RPC (HITL Phase 5.3).
+ *
+ * Forwards an approval decision to a child AgentExecution that is waiting for
+ * approval. The child execution ID is resolved from status.pending_approval.child_agent_execution_id.
+ *
+ * ## Usage
+ *
+ * When a workflow task invokes an agent that requires tool approval, the approval
+ * request surfaces at the workflow level via WorkflowExecution.status.pending_approval.
+ * This message captures the user's decision to forward to the child agent.
+ *
+ * ## Example
+ *
+ * {
+ *   "execution_id": "wfx_abc123xyz456",
+ *   "tool_call_id": "call_tool789",
+ *   "action": "APPROVAL_ACTION_APPROVE",
+ *   "comment": "Verified safe to execute"
+ * }
+ *
+ * ## Validation
+ *
+ * - execution_id: Required, must reference an existing WorkflowExecution
+ * - tool_call_id: Required, must match status.pending_approval.tool_call_id
+ * - action: Required, must be APPROVE, SKIP, or REJECT (not UNSPECIFIED)
+ * - comment: Optional, stored in audit trail
+ *
+ * @since Phase 5.3 (Approval Forwarding)
+ *
+ * @generated from message ai.stigmer.agentic.workflowexecution.v1.SubmitWorkflowApprovalInput
+ */
+export type SubmitWorkflowApprovalInput = Message<"ai.stigmer.agentic.workflowexecution.v1.SubmitWorkflowApprovalInput"> & {
+    /**
+     * ID of the workflow execution.
+     * Format: "wfx_abc123xyz456"
+     *
+     * @generated from field: string execution_id = 1;
+     */
+    executionId: string;
+    /**
+     * ID of the tool call to approve/skip/reject.
+     * Must match status.pending_approval.tool_call_id exactly.
+     * Format: Tool call ID from agent runtime (e.g., "call_abc123")
+     *
+     * @generated from field: string tool_call_id = 2;
+     */
+    toolCallId: string;
+    /**
+     * User's decision: APPROVE, SKIP, or REJECT.
+     * APPROVAL_ACTION_UNSPECIFIED (0) is rejected by validation.
+     *
+     * Actions:
+     * - APPROVE: Tool executes with the provided arguments
+     * - SKIP: Tool execution is skipped, agent receives skip message
+     * - REJECT: Agent execution fails with rejection error
+     *
+     * @generated from field: ai.stigmer.agentic.agentexecution.v1.ApprovalAction action = 3;
+     */
+    action: ApprovalAction;
+    /**
+     * Optional reason/comment for the decision.
+     * Stored in audit trail for compliance and debugging.
+     *
+     * Examples:
+     *   - "Verified the target repository is safe to delete" (on APPROVE)
+     *   - "Will handle this operation manually" (on SKIP)
+     *   - "Unexpected target - this looks like the wrong repository" (on REJECT)
+     *
+     * @generated from field: string comment = 4;
+     */
+    comment: string;
+};
+/**
+ * Describes the message ai.stigmer.agentic.workflowexecution.v1.SubmitWorkflowApprovalInput.
+ * Use `create(SubmitWorkflowApprovalInputSchema)` to create a new message.
+ */
+export declare const SubmitWorkflowApprovalInputSchema: GenMessage<SubmitWorkflowApprovalInput>;
+/**
+ * SubscribeWorkflowExecutionRequest subscribes to real-time execution updates.
+ *
+ * Opens a server-side streaming RPC that pushes WorkflowExecution updates
+ * as the execution progresses through its lifecycle.
+ *
+ * Stream Behavior:
+ * 1. Client sends this request with execution_id
+ * 2. Server validates authorization (user must have "get" permission)
+ * 3. Server sends initial WorkflowExecution (current state)
+ * 4. Server streams updates as execution state changes
+ * 5. Server closes stream when execution reaches terminal state
+ *
+ * Use Cases:
+ * - Real-time progress monitoring in UI
+ * - Live dashboards showing execution status
+ * - Debugging with live updates
+ * - Multi-user collaborative monitoring
+ *
+ * @generated from message ai.stigmer.agentic.workflowexecution.v1.SubscribeWorkflowExecutionRequest
+ */
+export type SubscribeWorkflowExecutionRequest = Message<"ai.stigmer.agentic.workflowexecution.v1.SubscribeWorkflowExecutionRequest"> & {
+    /**
+     * Execution ID to subscribe to.
+     *
+     * Format: "wfx-{unique-suffix}"
+     * Example: "wfx-abc123xyz456"
+     *
+     * Validation: Required field, cannot be empty
+     *
+     * Error Cases:
+     * - NOT_FOUND: No WorkflowExecution with this ID exists
+     * - PERMISSION_DENIED: User doesn't have "get" permission on this execution
+     *
+     * Example:
+     * execution_id: "wfx-abc123xyz456"
+     *
+     * After subscription starts, client receives:
+     * - Initial message: Current state of execution
+     * - Update messages: Changes to status.phase, status.tasks, etc.
+     * - Final message: Execution reached terminal state (COMPLETED/FAILED/CANCELLED)
+     * - Stream closes automatically after final message
+     *
+     * @generated from field: string execution_id = 1;
+     */
+    executionId: string;
+};
+/**
+ * Describes the message ai.stigmer.agentic.workflowexecution.v1.SubscribeWorkflowExecutionRequest.
+ * Use `create(SubscribeWorkflowExecutionRequestSchema)` to create a new message.
+ */
+export declare const SubscribeWorkflowExecutionRequestSchema: GenMessage<SubscribeWorkflowExecutionRequest>;
+/**
+ * WorkflowExecutionUpdate represents a real-time execution update event.
+ *
+ * This message is used for WebSocket or SSE (Server-Sent Events) streaming
+ * to provide granular updates about what changed in the execution.
+ *
+ * Difference from subscribe() RPC:
+ * - subscribe() RPC: Sends full WorkflowExecution on each update
+ * - WorkflowExecutionUpdate: Sends only what changed (more efficient for high-frequency updates)
+ *
+ * Use Cases:
+ * - WebSocket streaming (more efficient than full execution on each update)
+ * - Event sourcing patterns (replay update events to reconstruct state)
+ * - Real-time UI updates (apply delta updates to cached state)
+ *
+ * Note: Currently not used by subscribe() RPC (which sends full WorkflowExecution).
+ * This message is reserved for future WebSocket/SSE streaming implementations.
+ *
+ * @generated from message ai.stigmer.agentic.workflowexecution.v1.WorkflowExecutionUpdate
+ */
+export type WorkflowExecutionUpdate = Message<"ai.stigmer.agentic.workflowexecution.v1.WorkflowExecutionUpdate"> & {
+    /**
+     * Type of update that occurred.
+     *
+     * Determines which fields in this message are populated:
+     * - wf_update_status_changed: execution.status.phase changed
+     * - wf_update_task_started: task changed to IN_PROGRESS
+     * - wf_update_task_completed: task changed to COMPLETED
+     * - wf_update_task_failed: task changed to FAILED
+     * - wf_update_execution_completed: execution reached COMPLETED
+     * - wf_update_execution_cancelled: execution reached CANCELLED
+     *
+     * Validation: Must be a defined enum value (not unspecified)
+     *
+     * @generated from field: ai.stigmer.agentic.workflowexecution.v1.WorkflowUpdateType update_type = 1;
+     */
+    updateType: WorkflowUpdateType;
+    /**
+     * Updated execution (full or partial).
+     *
+     * For efficiency, may contain only changed fields:
+     * - wf_update_status_changed: Full execution with updated status.phase
+     * - wf_update_task_*: Partial execution with updated status.tasks[i]
+     * - wf_update_execution_completed: Full execution with final state
+     *
+     * Clients should merge this with cached state to get complete picture.
+     *
+     * Example (task completed update):
+     * execution: {
+     *   metadata: { id: "wfx-abc123" },
+     *   status: {
+     *     completed_tasks: 1,
+     *     tasks: [
+     *       { task_id: "task-1", status: WORKFLOW_TASK_COMPLETED, output: {...} }
+     *     ]
+     *   }
+     * }
+     *
+     * @generated from field: ai.stigmer.agentic.workflowexecution.v1.WorkflowExecution execution = 2;
+     */
+    execution?: WorkflowExecution;
+    /**
+     * Updated task (if update_type is task-related).
+     *
+     * Populated when update_type is:
+     * - wf_update_task_started
+     * - wf_update_task_completed
+     * - wf_update_task_failed
+     *
+     * Provides direct access to the changed task without searching execution.status.tasks[].
+     *
+     * Example (task completed):
+     * task: {
+     *   task_id: "task-1",
+     *   task_name: "validate_email",
+     *   status: WORKFLOW_TASK_COMPLETED,
+     *   output: { "valid": true },
+     *   completed_at: "2025-01-11T14:30:27Z"
+     * }
+     *
+     * @generated from field: ai.stigmer.agentic.workflowexecution.v1.WorkflowTask task = 3;
+     */
+    task?: WorkflowTask;
+};
+/**
+ * Describes the message ai.stigmer.agentic.workflowexecution.v1.WorkflowExecutionUpdate.
+ * Use `create(WorkflowExecutionUpdateSchema)` to create a new message.
+ */
+export declare const WorkflowExecutionUpdateSchema: GenMessage<WorkflowExecutionUpdate>;
+/**
+ * CancelWorkflowExecutionInput requests graceful cancellation of a workflow execution.
+ *
+ * Cancellation sends a signal to the workflow, allowing it to clean up gracefully.
+ * The workflow code can handle the cancellation signal (e.g., via defer blocks,
+ * compensation logic) before the execution transitions to CANCELLED phase.
+ *
+ * ## Behavior
+ *
+ * - Sends cancellation signal to Temporal via CancelWorkflow API
+ * - Workflow code receives the signal and can perform cleanup
+ * - Execution transitions to EXECUTION_CANCELLED phase after cleanup
+ * - In-progress tasks may complete or be interrupted depending on workflow logic
+ *
+ * ## Preconditions
+ *
+ * - Execution must be in EXECUTION_PENDING or EXECUTION_IN_PROGRESS phase
+ * - User must have can_edit permission on the workflow execution
+ *
+ * ## Idempotency
+ *
+ * If the execution is already cancelled (phase == EXECUTION_CANCELLED),
+ * the call succeeds as a no-op and returns the current execution state.
+ *
+ * ## Use Cases
+ *
+ * - User realizes they triggered the wrong workflow
+ * - Business decision to stop a long-running process
+ * - Graceful shutdown before maintenance window
+ * - Cancel stuck workflow that is still responsive
+ *
+ * ## Example
+ *
+ * {
+ *   "id": "wfx-abc123xyz456",
+ *   "reason": "Customer requested cancellation - no longer needed"
+ * }
+ *
+ * @generated from message ai.stigmer.agentic.workflowexecution.v1.CancelWorkflowExecutionInput
+ */
+export type CancelWorkflowExecutionInput = Message<"ai.stigmer.agentic.workflowexecution.v1.CancelWorkflowExecutionInput"> & {
+    /**
+     * Workflow execution ID to cancel.
+     *
+     * Format: "wfx-{ulid}" (auto-generated unique identifier)
+     * Example: "wfx-abc123xyz456"
+     *
+     * Validation: Required, cannot be empty
+     *
+     * @generated from field: string id = 1;
+     */
+    id: string;
+    /**
+     * Human-readable reason for cancellation.
+     *
+     * Stored in the audit trail and passed to Temporal for operational debugging.
+     * Optional but strongly recommended for compliance and troubleshooting.
+     *
+     * Examples:
+     * - "Customer requested cancellation"
+     * - "Incorrect workflow triggered by mistake"
+     * - "Superseded by newer execution wfx-def456"
+     * - "Pre-maintenance shutdown"
+     *
+     * @generated from field: string reason = 2;
+     */
+    reason: string;
+};
+/**
+ * Describes the message ai.stigmer.agentic.workflowexecution.v1.CancelWorkflowExecutionInput.
+ * Use `create(CancelWorkflowExecutionInputSchema)` to create a new message.
+ */
+export declare const CancelWorkflowExecutionInputSchema: GenMessage<CancelWorkflowExecutionInput>;
+/**
+ * TerminateWorkflowExecutionInput requests immediate termination of a workflow execution.
+ *
+ * Termination forcefully kills the workflow without allowing cleanup.
+ * Unlike cancellation, the workflow code cannot respond to termination -
+ * it is stopped immediately. Use this for stuck or unresponsive workflows.
+ *
+ * ## Behavior
+ *
+ * - Force-kills workflow via Temporal TerminateWorkflow API
+ * - Workflow code does NOT receive any signal (cannot clean up)
+ * - Execution transitions to EXECUTION_TERMINATED phase immediately
+ * - All in-progress tasks are stopped abruptly
+ * - No compensation or defer blocks are executed
+ *
+ * ## Preconditions
+ *
+ * - Execution must be in EXECUTION_PENDING or EXECUTION_IN_PROGRESS phase
+ * - User must have can_edit permission on the workflow execution
+ *
+ * ## Idempotency
+ *
+ * If the execution is already terminated (phase == EXECUTION_TERMINATED),
+ * the call succeeds as a no-op and returns the current execution state.
+ *
+ * ## Terminated vs Cancelled
+ *
+ * | Aspect | Cancel | Terminate |
+ * |--------|--------|-----------|
+ * | Signal | Workflow receives cancellation signal | No signal sent |
+ * | Cleanup | Workflow can clean up gracefully | No cleanup possible |
+ * | Use case | Normal cancellation | Stuck/unresponsive workflows |
+ * | Recovery | Cannot recover | Cannot recover |
+ *
+ * ## Use Cases
+ *
+ * - Workflow is stuck and not responding to cancellation
+ * - Workflow is consuming excessive resources (infinite loop, memory leak)
+ * - Emergency stop for misbehaving workflow
+ * - Workflow has a bug causing it to ignore cancellation signals
+ *
+ * ## Example
+ *
+ * {
+ *   "id": "wfx-abc123xyz456",
+ *   "reason": "Workflow stuck for 2 hours, not responding to cancel"
+ * }
+ *
+ * @generated from message ai.stigmer.agentic.workflowexecution.v1.TerminateWorkflowExecutionInput
+ */
+export type TerminateWorkflowExecutionInput = Message<"ai.stigmer.agentic.workflowexecution.v1.TerminateWorkflowExecutionInput"> & {
+    /**
+     * Workflow execution ID to terminate.
+     *
+     * Format: "wfx-{ulid}" (auto-generated unique identifier)
+     * Example: "wfx-abc123xyz456"
+     *
+     * Validation: Required, cannot be empty
+     *
+     * @generated from field: string id = 1;
+     */
+    id: string;
+    /**
+     * Human-readable reason for termination.
+     *
+     * Stored in the audit trail and passed to Temporal for operational debugging.
+     * Optional but strongly recommended - termination is a drastic action
+     * and the reason helps with post-incident analysis.
+     *
+     * Examples:
+     * - "Workflow stuck for 2 hours, not responding to cancel"
+     * - "Infinite loop detected, consuming 100% CPU"
+     * - "Emergency stop - incorrect data being processed"
+     * - "Cancel failed after 3 attempts, force terminating"
+     *
+     * @generated from field: string reason = 2;
+     */
+    reason: string;
+};
+/**
+ * Describes the message ai.stigmer.agentic.workflowexecution.v1.TerminateWorkflowExecutionInput.
+ * Use `create(TerminateWorkflowExecutionInputSchema)` to create a new message.
+ */
+export declare const TerminateWorkflowExecutionInputSchema: GenMessage<TerminateWorkflowExecutionInput>;
+/**
+ * RecoverWorkflowExecutionInput requests recovery of a failed workflow execution.
+ *
+ * Recovery resumes execution from the last successful checkpoint, preserving
+ * all completed work. This uses Temporal's Reset functionality to continue
+ * the workflow without re-executing successful steps.
+ *
+ * ## Behavior
+ *
+ * - Uses Temporal ResetWorkflow API to resume from last successful point
+ * - Completed tasks are preserved - NOT re-executed
+ * - Creates a new Temporal run in the same workflow ID chain
+ * - Execution transitions from FAILED back to IN_PROGRESS phase
+ * - Workflow continues from where it failed
+ *
+ * ## Preconditions
+ *
+ * - Execution must be in EXECUTION_FAILED phase
+ * - TERMINATED executions cannot be recovered (use case: data corruption risk)
+ * - CANCELLED executions cannot be recovered (intentional user action)
+ * - User must have can_edit permission on the workflow execution
+ *
+ * ## Idempotency
+ *
+ * If recovery is already in progress (execution moved to IN_PROGRESS after
+ * a previous recover call), the call succeeds as a no-op and returns current state.
+ *
+ * ## Recovery vs Restart
+ *
+ * | Aspect | Recover | Restart (create new) |
+ * |--------|---------|----------------------|
+ * | Completed work | Preserved | Lost (re-executed) |
+ * | Side effects | Not duplicated | May duplicate |
+ * | Execution ID | Same | New ID |
+ * | Use case | Resume after fix | Start fresh |
+ *
+ * ## Use Cases
+ *
+ * - Workflow failed due to transient error (network timeout, rate limit)
+ * - External dependency was down but is now available
+ * - Bug was fixed and workflow should continue from failure point
+ * - Retry after investigating and fixing the root cause
+ *
+ * ## Example
+ *
+ * {
+ *   "id": "wfx-abc123xyz456",
+ *   "reason": "Stripe API was down, now recovered - resuming payment processing"
+ * }
+ *
+ * @generated from message ai.stigmer.agentic.workflowexecution.v1.RecoverWorkflowExecutionInput
+ */
+export type RecoverWorkflowExecutionInput = Message<"ai.stigmer.agentic.workflowexecution.v1.RecoverWorkflowExecutionInput"> & {
+    /**
+     * Workflow execution ID to recover.
+     *
+     * Must be in FAILED phase. TERMINATED and CANCELLED executions
+     * cannot be recovered.
+     *
+     * Format: "wfx-{ulid}" (auto-generated unique identifier)
+     * Example: "wfx-abc123xyz456"
+     *
+     * Validation: Required, cannot be empty
+     *
+     * @generated from field: string id = 1;
+     */
+    id: string;
+    /**
+     * Human-readable reason for recovery.
+     *
+     * Stored in the audit trail for operational debugging and compliance.
+     * Helps track why the recovery was needed and what was fixed.
+     *
+     * Examples:
+     * - "Stripe API recovered, resuming payment processing"
+     * - "Fixed typo in email template, continuing workflow"
+     * - "Increased timeout for slow API, retrying"
+     * - "Root cause identified and fixed in config"
+     *
+     * @generated from field: string reason = 2;
+     */
+    reason: string;
+};
+/**
+ * Describes the message ai.stigmer.agentic.workflowexecution.v1.RecoverWorkflowExecutionInput.
+ * Use `create(RecoverWorkflowExecutionInputSchema)` to create a new message.
+ */
+export declare const RecoverWorkflowExecutionInputSchema: GenMessage<RecoverWorkflowExecutionInput>;
+/**
+ * PauseWorkflowExecutionInput requests temporarily pausing a workflow execution.
+ *
+ * Pauses the workflow at its current checkpoint. Unlike cancel, the execution
+ * is NOT terminal and can be resumed later from where it left off.
+ *
+ * ## Behavior
+ *
+ * When a workflow is paused:
+ * 1. A "pause" signal is sent to the Temporal workflow
+ * 2. Running activities are gracefully cancelled (checkpoint saved)
+ * 3. Execution transitions to EXECUTION_PAUSED phase
+ * 4. Workflow waits for resume signal (no resources consumed)
+ *
+ * ## Resume Flow
+ *
+ * The paused workflow can be resumed via the resume RPC:
+ * 1. Resume signal unblocks the workflow
+ * 2. Activities are re-invoked with same thread_id
+ * 3. LangGraph loads from checkpoint automatically
+ * 4. Execution continues from exact pause point
+ *
+ * @since Gap A3 (Pause/Resume Propagation)
+ *
+ * @generated from message ai.stigmer.agentic.workflowexecution.v1.PauseWorkflowExecutionInput
+ */
+export type PauseWorkflowExecutionInput = Message<"ai.stigmer.agentic.workflowexecution.v1.PauseWorkflowExecutionInput"> & {
+    /**
+     * Workflow execution ID to pause.
+     *
+     * Must be in PENDING or IN_PROGRESS phase. Cannot pause
+     * executions that are already terminal (COMPLETED, FAILED, CANCELLED, TERMINATED).
+     *
+     * Format: "wfx-{ulid}" (auto-generated unique identifier)
+     * Example: "wfx-abc123xyz456"
+     *
+     * Validation: Required, cannot be empty
+     *
+     * @generated from field: string id = 1;
+     */
+    id: string;
+    /**
+     * Human-readable reason for pausing.
+     *
+     * Stored in the audit trail for operational debugging and compliance.
+     * Helps track why the pause was needed.
+     *
+     * Examples:
+     * - "Pausing for scheduled maintenance window"
+     * - "User requested pause to review progress"
+     * - "Pausing due to rate limit concerns"
+     * - "Emergency pause - investigating issue"
+     *
+     * @generated from field: string reason = 2;
+     */
+    reason: string;
+};
+/**
+ * Describes the message ai.stigmer.agentic.workflowexecution.v1.PauseWorkflowExecutionInput.
+ * Use `create(PauseWorkflowExecutionInputSchema)` to create a new message.
+ */
+export declare const PauseWorkflowExecutionInputSchema: GenMessage<PauseWorkflowExecutionInput>;
+/**
+ * ResumeWorkflowExecutionInput requests resuming a paused workflow execution.
+ *
+ * Continues execution from the checkpoint where it was paused. The workflow
+ * re-invokes activities with the same thread_id, which loads from checkpoint
+ * and continues from where it left off.
+ *
+ * ## Behavior
+ *
+ * When a workflow is resumed:
+ * 1. A "resume" signal is sent to the paused Temporal workflow
+ * 2. Workflow unblocks from its wait state
+ * 3. Activities are re-invoked with same execution context
+ * 4. LangGraph loads checkpoint using thread_id
+ * 5. Execution continues from exact pause point
+ *
+ * ## Preconditions
+ *
+ * - Execution must be in EXECUTION_PAUSED phase
+ * - Cannot resume non-paused executions
+ *
+ * @since Gap A3 (Pause/Resume Propagation)
+ *
+ * @generated from message ai.stigmer.agentic.workflowexecution.v1.ResumeWorkflowExecutionInput
+ */
+export type ResumeWorkflowExecutionInput = Message<"ai.stigmer.agentic.workflowexecution.v1.ResumeWorkflowExecutionInput"> & {
+    /**
+     * Workflow execution ID to resume.
+     *
+     * Must be in PAUSED phase. Cannot resume executions
+     * that are not paused.
+     *
+     * Format: "wfx-{ulid}" (auto-generated unique identifier)
+     * Example: "wfx-abc123xyz456"
+     *
+     * Validation: Required, cannot be empty
+     *
+     * @generated from field: string id = 1;
+     */
+    id: string;
+};
+/**
+ * Describes the message ai.stigmer.agentic.workflowexecution.v1.ResumeWorkflowExecutionInput.
+ * Use `create(ResumeWorkflowExecutionInputSchema)` to create a new message.
+ */
+export declare const ResumeWorkflowExecutionInputSchema: GenMessage<ResumeWorkflowExecutionInput>;
+/**
+ * SendSignalInput requests delivery of a signal to a workflow execution.
+ *
+ * Sends a signal to a running workflow execution, typically to unblock a LISTEN task.
+ * Uses Temporal's SignalWithStart API internally for race-proof delivery - if the
+ * workflow hasn't started yet, it will be started first and then receive the signal.
+ *
+ * ## Behavior
+ *
+ * 1. Validates execution exists and is in a signalable phase
+ * 2. Uses Temporal SignalWithStart for atomic delivery:
+ *    - If workflow exists → sends signal immediately
+ *    - If workflow not started yet → starts workflow, then sends signal
+ * 3. Signal is delivered to workflow's signal channel
+ * 4. LISTEN task waiting for this signal will unblock and continue
+ * 5. Returns the current WorkflowExecution state
+ *
+ * ## Preconditions
+ *
+ * - Execution must be in EXECUTION_PENDING or EXECUTION_IN_PROGRESS phase
+ * - Cannot signal terminal executions (COMPLETED, FAILED, CANCELLED, TERMINATED)
+ * - User must have can_edit permission on the workflow execution
+ *
+ * ## Race-Proof Delivery
+ *
+ * SignalWithStart solves the race condition where a signal might arrive before
+ * the Temporal workflow is fully started. Without it, SignalWorkflow fails with
+ * "WorkflowNotFound" if called too early. SignalWithStart handles both cases
+ * atomically, ensuring signals are never lost.
+ *
+ * ## Use Cases
+ *
+ * - External system events (webhooks, CDC) triggering workflow continuation
+ * - Human-in-the-loop approvals via external systems
+ * - Integration with third-party services that send callbacks
+ * - Testing LISTEN tasks during development
+ *
+ * ## Example
+ *
+ * {
+ *   "execution_id": "wfx-abc123xyz456",
+ *   "signal_name": "payment_confirmed",
+ *   "payload": {
+ *     "transaction_id": "txn_123",
+ *     "amount": 99.99,
+ *     "currency": "USD"
+ *   }
+ * }
+ *
+ * @since Gap B1 (Signal-With-Start)
+ *
+ * @generated from message ai.stigmer.agentic.workflowexecution.v1.SendSignalInput
+ */
+export type SendSignalInput = Message<"ai.stigmer.agentic.workflowexecution.v1.SendSignalInput"> & {
+    /**
+     * Workflow execution ID to send the signal to.
+     *
+     * Format: "wfx-{ulid}" (auto-generated unique identifier)
+     * Example: "wfx-abc123xyz456"
+     *
+     * Validation: Required, cannot be empty
+     *
+     * @generated from field: string execution_id = 1;
+     */
+    executionId: string;
+    /**
+     * Signal name to send.
+     *
+     * Must match the signal ID defined in the workflow's LISTEN task.
+     * Signal names are case-sensitive and should follow snake_case convention.
+     *
+     * Examples:
+     * - "payment_confirmed"
+     * - "approval_received"
+     * - "external_event"
+     * - "verification_complete"
+     *
+     * Validation: Required, cannot be empty
+     *
+     * @generated from field: string signal_name = 2;
+     */
+    signalName: string;
+    /**
+     * Signal payload data.
+     *
+     * JSON-serializable data to send with the signal. The payload is delivered
+     * to the workflow and can be accessed by the LISTEN task.
+     *
+     * Optional - signals can be sent without payload if they just need to
+     * unblock the workflow without passing data.
+     *
+     * Examples:
+     * - { "status": "approved", "approver": "jane@example.com" }
+     * - { "transaction_id": "txn_123", "amount": 99.99 }
+     * - { "verified": true }
+     *
+     * Note: Use google.protobuf.Struct for arbitrary JSON payloads.
+     *
+     * @generated from field: google.protobuf.Struct payload = 3;
+     */
+    payload?: JsonObject;
+    /**
+     * Idempotency key for deduplication of signal delivery.
+     *
+     * Optional - if not provided, signal is processed without dedupe protection.
+     * When provided, duplicate signals with the same key (within the TTL window)
+     * return the cached response instead of re-delivering the signal.
+     *
+     * ## Format Recommendations
+     *
+     * - Webhook sources: "{source}:{event_id}" (e.g., "stripe:evt_1234567890")
+     * - API callers: Client-generated UUID (e.g., "550e8400-e29b-41d4-a716-446655440000")
+     * - Scheduled events: "{schedule_id}:{timestamp}" (e.g., "sched_abc:2026-02-08T12:00:00Z")
+     *
+     * ## Scope
+     *
+     * Keys are scoped to the organization to prevent cross-org collisions.
+     * The effective key stored is: "{org_id}:{idempotency_key}"
+     *
+     * ## TTL (Time-To-Live)
+     *
+     * Keys expire after 24 hours by default. After expiration, the same key
+     * can be reused and will trigger a new signal delivery. This aligns with
+     * industry standards (e.g., Stripe's 24-hour idempotency window).
+     *
+     * ## Behavior on Duplicate
+     *
+     * When a duplicate key is detected:
+     * - The signal is NOT re-delivered to the workflow
+     * - The original WorkflowExecution state is returned (idempotent response)
+     * - No error is returned (success with cached result)
+     *
+     * ## Use Cases
+     *
+     * 1. Webhook retry protection: Stripe/GitHub may retry webhooks on timeout
+     * 2. Client retry safety: API clients can safely retry on network errors
+     * 3. At-least-once to effectively-once: Convert retries into safe operations
+     *
+     * Example: "stripe:evt_1NqZP92eZvKYlo2CqOc7XYRT"
+     *
+     * @since Gap B2 (Event Dedupe)
+     *
+     * @generated from field: string idempotency_key = 4;
+     */
+    idempotencyKey: string;
+};
+/**
+ * Describes the message ai.stigmer.agentic.workflowexecution.v1.SendSignalInput.
+ * Use `create(SendSignalInputSchema)` to create a new message.
+ */
+export declare const SendSignalInputSchema: GenMessage<SendSignalInput>;
+/**
+ * WorkflowUpdateType defines the type of workflow execution update event.
+ *
+ * Used by WorkflowExecutionUpdate to indicate what changed in the execution.
+ * Helps clients apply efficient delta updates instead of re-rendering entire UI.
+ *
+ * Event Sequence Example:
+ * 1. wf_update_status_changed (PENDING → IN_PROGRESS)
+ * 2. wf_update_task_started (task-1 started)
+ * 3. wf_update_task_completed (task-1 completed)
+ * 4. wf_update_task_started (task-2 started)
+ * 5. wf_update_task_completed (task-2 completed)
+ * 6. wf_update_execution_completed (workflow done)
+ *
+ * @generated from enum ai.stigmer.agentic.workflowexecution.v1.WorkflowUpdateType
+ */
+export declare enum WorkflowUpdateType {
+    /**
+     * Unspecified update type (invalid, should never be used).
+     *
+     * @generated from enum value: workflow_update_type_unspecified = 0;
+     */
+    workflow_update_type_unspecified = 0,
+    /**
+     * Workflow execution phase changed.
+     *
+     * Triggered when status.phase transitions:
+     * - PENDING → IN_PROGRESS (execution started)
+     * - IN_PROGRESS → COMPLETED (execution succeeded)
+     * - IN_PROGRESS → FAILED (execution failed)
+     * - IN_PROGRESS → CANCELLED (execution cancelled)
+     *
+     * UI Impact: Update status badge, progress indicator
+     *
+     * @generated from enum value: wf_update_status_changed = 1;
+     */
+    wf_update_status_changed = 1,
+    /**
+     * A workflow task started executing.
+     *
+     * Triggered when task status changes from PENDING to IN_PROGRESS.
+     *
+     * Update includes:
+     * - task.status = WORKFLOW_TASK_IN_PROGRESS
+     * - task.started_at = current timestamp
+     *
+     * UI Impact: Show spinner/loading indicator for this task
+     *
+     * @generated from enum value: wf_update_task_started = 2;
+     */
+    wf_update_task_started = 2,
+    /**
+     * A workflow task completed successfully.
+     *
+     * Triggered when task status changes from IN_PROGRESS to COMPLETED.
+     *
+     * Update includes:
+     * - task.status = WORKFLOW_TASK_COMPLETED
+     * - task.output = task results
+     * - task.completed_at = current timestamp
+     * - execution.completed_tasks incremented
+     *
+     * UI Impact: Show checkmark, display task output, update progress bar
+     *
+     * @generated from enum value: wf_update_task_completed = 3;
+     */
+    wf_update_task_completed = 3,
+    /**
+     * A workflow task failed.
+     *
+     * Triggered when task status changes from IN_PROGRESS to FAILED.
+     *
+     * Update includes:
+     * - task.status = WORKFLOW_TASK_FAILED
+     * - task.error = error message
+     * - task.completed_at = current timestamp
+     * - execution.completed_tasks incremented
+     *
+     * UI Impact: Show error icon, display error message, may trigger workflow failure
+     *
+     * @generated from enum value: wf_update_task_failed = 4;
+     */
+    wf_update_task_failed = 4,
+    /**
+     * Workflow execution completed successfully.
+     *
+     * Triggered when all tasks completed and workflow produces final output.
+     *
+     * Update includes:
+     * - execution.status.phase = EXECUTION_COMPLETED
+     * - execution.status.output = workflow results
+     * - execution.status.completed_at = current timestamp
+     *
+     * UI Impact: Show success badge, display final output, enable download/export
+     *
+     * Note: This is a terminal event - no more updates will follow.
+     *
+     * @generated from enum value: wf_update_execution_completed = 5;
+     */
+    wf_update_execution_completed = 5,
+    /**
+     * Workflow execution was cancelled.
+     *
+     * Triggered when user or system cancels the execution.
+     *
+     * Update includes:
+     * - execution.status.phase = EXECUTION_CANCELLED
+     * - execution.status.completed_at = current timestamp
+     *
+     * UI Impact: Show cancelled badge, grey out in-progress tasks
+     *
+     * Note: This is a terminal event - no more updates will follow.
+     *
+     * @generated from enum value: wf_update_execution_cancelled = 6;
+     */
+    wf_update_execution_cancelled = 6
+}
+/**
+ * Describes the enum ai.stigmer.agentic.workflowexecution.v1.WorkflowUpdateType.
+ */
+export declare const WorkflowUpdateTypeSchema: GenEnum<WorkflowUpdateType>;