@stigmer/protos 0.0.68 → 0.0.70

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

@@ -10,18 +10,9 @@ 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)
+ * @internal
+ * Using a wrapper (instead of a raw string) provides validation,
+ * clear field naming, and extensibility.
  *
  * @generated from message ai.stigmer.agentic.workflowexecution.v1.WorkflowExecutionId
  */
@@ -29,10 +20,8 @@ export type WorkflowExecutionId = Message<"ai.stigmer.agentic.workflowexecution.
     /**
      * Workflow execution identifier.
      *
-     * Format: "wfx-{unique-suffix}" (auto-generated by backend)
-     * Example: "wfx-abc123xyz456"
-     *
-     * Validation: Required field, cannot be empty
+     * @internal
+     * Format: "wfx_{unique-suffix}" (auto-generated by backend)
      *
      * @generated from field: string value = 1;
      */
@@ -46,17 +35,8 @@ 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
+ * @internal
+ * Accepts either a Workflow ID (wf_{slug}) or WorkflowInstance ID (wfi_{slug}).
  *
  * @generated from message ai.stigmer.agentic.workflowexecution.v1.WorkflowId
  */
@@ -64,15 +44,8 @@ export type WorkflowId = Message<"ai.stigmer.agentic.workflowexecution.v1.Workfl
     /**
      * 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
+     * @internal
+     * Can be either a Workflow ID (wf_{slug}) or WorkflowInstance ID (wfi_{slug}).
      *
      * @generated from field: string value = 1;
      */
@@ -86,21 +59,9 @@ 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 ]
- * }
+ * @internal
+ * Returned by list operations (list, list_by_workflow).
+ * Includes pagination metadata and the execution entries for the current page.
  *
  * @generated from message ai.stigmer.agentic.workflowexecution.v1.WorkflowExecutionList
  */
@@ -108,37 +69,15 @@ export type WorkflowExecutionList = Message<"ai.stigmer.agentic.workflowexecutio
     /**
      * 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.
+     * @internal
+     * Calculated as: ceil(total_matching_executions / page_size).
+     * May change between requests if results are created or deleted.
      *
      * @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" }, ... }
-     * ]
+     * Workflow executions in the current page, sorted by created_at descending.
      *
      * @generated from field: repeated ai.stigmer.agentic.workflowexecution.v1.WorkflowExecution entries = 2;
      */
@@ -152,15 +91,8 @@ export declare const WorkflowExecutionListSchema: GenMessage<WorkflowExecutionLi
 /**
  * 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)
+ * @internal
+ * Supports pagination and filtering by phase and tags.
  *
  * @generated from message ai.stigmer.agentic.workflowexecution.v1.ListWorkflowExecutionsRequest
  */
@@ -168,83 +100,36 @@ export type ListWorkflowExecutionsRequest = Message<"ai.stigmer.agentic.workflow
     /**
      * 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
+     * @internal
+     * Default: 50. Maximum: 100 (backend enforces this limit).
      *
      * @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
+     * Opaque pagination token from a previous response.
      *
-     * 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.
+     * @internal
+     * Empty on first request. When empty in a response, no more pages are available.
      *
      * @generated from field: string page_token = 2;
      */
     pageToken: string;
     /**
-     * Filter by execution phase (optional).
+     * Filter by execution phase.
      *
-     * Limits results to executions in a specific phase.
+     * @internal
      * 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.
+     * Filter by resource tags (AND logic).
      *
-     * 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"]
+     * @internal
+     * Limits results to executions that have ALL specified tags.
+     * Tag format: "key:value" or "key" (for boolean tags).
      *
      * @generated from field: repeated string tags = 4;
      */
@@ -256,19 +141,11 @@ export type ListWorkflowExecutionsRequest = Message<"ai.stigmer.agentic.workflow
  */
 export declare const ListWorkflowExecutionsRequestSchema: GenMessage<ListWorkflowExecutionsRequest>;
 /**
- * ListWorkflowExecutionsByWorkflowRequest lists all executions for a specific workflow.
+ * ListWorkflowExecutionsByWorkflowRequest lists executions for a specific workflow.
  *
+ * @internal
  * 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
+ * Unlike ListWorkflowExecutionsRequest (cross-workflow), this scopes to one workflow.
  *
  * @generated from message ai.stigmer.agentic.workflowexecution.v1.ListWorkflowExecutionsByWorkflowRequest
  */
@@ -276,19 +153,8 @@ export type ListWorkflowExecutionsByWorkflowRequest = Message<"ai.stigmer.agenti
     /**
      * 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
+     * @internal
+     * Can be either a Workflow ID (wf_{slug}) or WorkflowInstance ID (wfi_{slug}).
      *
      * @generated from field: string workflow_id = 1;
      */
@@ -296,23 +162,14 @@ export type ListWorkflowExecutionsByWorkflowRequest = Message<"ai.stigmer.agenti
     /**
      * 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
+     * @internal
+     * Default: 50. Maximum: 100 (backend enforces this limit).
      *
      * @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" }
+     * Opaque pagination token from a previous response.
      *
      * @generated from field: string page_token = 3;
      */
@@ -324,23 +181,28 @@ export type ListWorkflowExecutionsByWorkflowRequest = Message<"ai.stigmer.agenti
  */
 export declare const ListWorkflowExecutionsByWorkflowRequestSchema: GenMessage<ListWorkflowExecutionsByWorkflowRequest>;
 /**
- * Input message for updateStatus RPC.
+ * Input for the updateStatus RPC.
+ *
+ * @internal
  * 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.
+ * This avoids validation errors on incomplete metadata/spec fields.
  *
  * @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).
+     * ID of the workflow execution to update.
+     *
+     * @internal
      * 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.
+     * Status fields to merge into the existing execution status.
+     *
+     * @internal
      * Only the fields present in this status object will be updated.
      *
      * @generated from field: ai.stigmer.agentic.workflowexecution.v1.WorkflowExecutionStatus status = 2;
@@ -353,73 +215,51 @@ export type WorkflowExecutionUpdateStatusInput = Message<"ai.stigmer.agentic.wor
  */
 export declare const WorkflowExecutionUpdateStatusInputSchema: GenMessage<WorkflowExecutionUpdateStatusInput>;
 /**
- * Input message for submitApproval RPC (HITL Phase 5.3).
+ * Input for the submitApproval RPC.
  *
+ * @internal
  * 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
+ * approval. The child execution ID is resolved from
+ * status.pending_approval.child_agent_execution_id.
  *
+ * 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.
+     *
+     * @internal
      * Format: "wfx_abc123xyz456"
      *
      * @generated from field: string execution_id = 1;
      */
     executionId: string;
     /**
-     * ID of the tool call to approve/skip/reject.
+     * ID of the tool call to approve, skip, or reject.
+     *
+     * @internal
      * 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.
+     * Approval decision: APPROVE, SKIP, or REJECT.
      *
-     * Actions:
-     * - APPROVE: Tool executes with the provided arguments
-     * - SKIP: Tool execution is skipped, agent receives skip message
-     * - REJECT: Agent execution fails with rejection error
+     * @internal
+     * APPROVAL_ACTION_UNSPECIFIED (0) is rejected by validation.
      *
      * @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)
+     * Optional reason or comment for the decision, stored in the audit trail.
      *
      * @generated from field: string comment = 4;
      */
@@ -433,21 +273,9 @@ export declare const SubmitWorkflowApprovalInputSchema: GenMessage<SubmitWorkflo
 /**
  * SubscribeWorkflowExecutionRequest subscribes to real-time execution updates.
  *
+ * @internal
  * 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
+ * as the execution progresses. Stream closes when execution reaches a terminal state.
  *
  * @generated from message ai.stigmer.agentic.workflowexecution.v1.SubscribeWorkflowExecutionRequest
  */
@@ -455,23 +283,8 @@ export type SubscribeWorkflowExecutionRequest = Message<"ai.stigmer.agentic.work
     /**
      * 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
+     * @internal
+     * Format: "wfx_{unique-suffix}"
      *
      * @generated from field: string execution_id = 1;
      */
@@ -485,20 +298,9 @@ export declare const SubscribeWorkflowExecutionRequestSchema: GenMessage<Subscri
 /**
  * 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.
+ * @internal
+ * Reserved for future WebSocket/SSE streaming implementations.
+ * Currently not used by subscribe() RPC (which sends full WorkflowExecution).
  *
  * @generated from message ai.stigmer.agentic.workflowexecution.v1.WorkflowExecutionUpdate
  */
@@ -506,62 +308,27 @@ export type WorkflowExecutionUpdate = Message<"ai.stigmer.agentic.workflowexecut
     /**
      * 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)
+     * @internal
+     * Determines which fields in this message are populated.
      *
      * @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: {...} }
-     *     ]
-     *   }
-     * }
+     * Updated execution state (full or partial).
+     *
+     * @internal
+     * May contain only changed fields. Clients should merge with cached state.
      *
      * @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
+     * Updated task, populated only for task-related update types.
      *
+     * @internal
      * 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;
@@ -574,40 +341,15 @@ export declare const WorkflowExecutionUpdateSchema: GenMessage<WorkflowExecution
 /**
  * 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
+ * @internal
+ * Sends a cancellation signal to the workflow engine, allowing the workflow code
+ * to perform cleanup before transitioning to EXECUTION_CANCELLED phase.
  *
+ * 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
+ * - User must have can_edit permission
  *
- * ## Example
- *
- * {
- *   "id": "wfx-abc123xyz456",
- *   "reason": "Customer requested cancellation - no longer needed"
- * }
+ * Idempotent: if already cancelled, returns current state as a no-op.
  *
  * @generated from message ai.stigmer.agentic.workflowexecution.v1.CancelWorkflowExecutionInput
  */
@@ -615,25 +357,14 @@ export type CancelWorkflowExecutionInput = Message<"ai.stigmer.agentic.workflowe
     /**
      * Workflow execution ID to cancel.
      *
-     * Format: "wfx-{ulid}" (auto-generated unique identifier)
-     * Example: "wfx-abc123xyz456"
-     *
-     * Validation: Required, cannot be empty
+     * @internal
+     * Format: "wfx_{ulid}"
      *
      * @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"
+     * Human-readable reason for cancellation, stored in the audit trail.
      *
      * @generated from field: string reason = 2;
      */
@@ -647,50 +378,15 @@ export declare const CancelWorkflowExecutionInputSchema: GenMessage<CancelWorkfl
 /**
  * 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
+ * @internal
+ * Force-kills the workflow without allowing cleanup. Unlike cancellation,
+ * the workflow code cannot respond to termination.
  *
+ * 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.
+ * - User must have can_edit permission
  *
- * ## 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"
- * }
+ * Idempotent: if already terminated, returns current state as a no-op.
  *
  * @generated from message ai.stigmer.agentic.workflowexecution.v1.TerminateWorkflowExecutionInput
  */
@@ -698,26 +394,14 @@ export type TerminateWorkflowExecutionInput = Message<"ai.stigmer.agentic.workfl
     /**
      * Workflow execution ID to terminate.
      *
-     * Format: "wfx-{ulid}" (auto-generated unique identifier)
-     * Example: "wfx-abc123xyz456"
-     *
-     * Validation: Required, cannot be empty
+     * @internal
+     * Format: "wfx_{ulid}"
      *
      * @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"
+     * Human-readable reason for termination, stored in the audit trail.
      *
      * @generated from field: string reason = 2;
      */
@@ -731,81 +415,32 @@ export declare const TerminateWorkflowExecutionInputSchema: GenMessage<Terminate
 /**
  * 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
+ * @internal
+ * Resumes execution from the last successful checkpoint, preserving all completed work.
+ * Uses the workflow engine's reset functionality to continue without re-executing
+ * successful steps.
  *
+ * 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 |
+ * - TERMINATED and CANCELLED executions cannot be recovered
+ * - User must have can_edit permission
  *
- * ## 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"
- * }
+ * Idempotent: if recovery is already in progress, returns current state as a no-op.
  *
  * @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"
+     * Workflow execution ID to recover (must be in FAILED phase).
      *
-     * Validation: Required, cannot be empty
+     * @internal
+     * Format: "wfx_{ulid}"
      *
      * @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"
+     * Human-readable reason for recovery, stored in the audit trail.
      *
      * @generated from field: string reason = 2;
      */
@@ -819,24 +454,9 @@ export declare const RecoverWorkflowExecutionInputSchema: GenMessage<RecoverWork
 /**
  * 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
+ * @internal
+ * Pauses the workflow at its current checkpoint. The execution is NOT terminal
+ * and can be resumed later via the resume RPC.
  *
  * @since Gap A3 (Pause/Resume Propagation)
  *
@@ -844,30 +464,16 @@ export declare const RecoverWorkflowExecutionInputSchema: GenMessage<RecoverWork
  */
 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"
+     * Workflow execution ID to pause (must be in PENDING or IN_PROGRESS phase).
      *
-     * Validation: Required, cannot be empty
+     * @internal
+     * Format: "wfx_{ulid}"
      *
      * @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"
+     * Human-readable reason for pausing, stored in the audit trail.
      *
      * @generated from field: string reason = 2;
      */
@@ -881,23 +487,9 @@ export declare const PauseWorkflowExecutionInputSchema: GenMessage<PauseWorkflow
 /**
  * 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
+ * @internal
+ * Continues execution from the checkpoint where it was paused.
+ * Execution must be in EXECUTION_PAUSED phase.
  *
  * @since Gap A3 (Pause/Resume Propagation)
  *
@@ -905,15 +497,10 @@ export declare const PauseWorkflowExecutionInputSchema: GenMessage<PauseWorkflow
  */
 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.
+     * Workflow execution ID to resume (must be in PAUSED phase).
      *
-     * Format: "wfx-{ulid}" (auto-generated unique identifier)
-     * Example: "wfx-abc123xyz456"
-     *
-     * Validation: Required, cannot be empty
+     * @internal
+     * Format: "wfx_{ulid}"
      *
      * @generated from field: string id = 1;
      */
@@ -925,53 +512,15 @@ export type ResumeWorkflowExecutionInput = Message<"ai.stigmer.agentic.workflowe
  */
 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
+ * SendSignalInput delivers a named signal to a workflow execution.
  *
- * ## Preconditions
+ * @internal
+ * Sends a signal to a running or pending workflow execution, typically to unblock
+ * a LISTEN task. Uses race-proof delivery internally (SignalWithStart).
  *
+ * 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"
- *   }
- * }
+ * - User must have can_edit permission
  *
  * @since Gap B1 (Signal-With-Start)
  *
@@ -981,88 +530,34 @@ export type SendSignalInput = Message<"ai.stigmer.agentic.workflowexecution.v1.S
     /**
      * Workflow execution ID to send the signal to.
      *
-     * Format: "wfx-{ulid}" (auto-generated unique identifier)
-     * Example: "wfx-abc123xyz456"
-     *
-     * Validation: Required, cannot be empty
+     * @internal
+     * Format: "wfx_{ulid}"
      *
      * @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.
+     * Signal name matching the workflow's LISTEN task signal ID.
      *
-     * Examples:
-     * - "payment_confirmed"
-     * - "approval_received"
-     * - "external_event"
-     * - "verification_complete"
-     *
-     * Validation: Required, cannot be empty
+     * @internal
+     * Case-sensitive, follows snake_case convention.
      *
      * @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.
+     * Optional JSON payload delivered to the LISTEN task.
      *
      * @generated from field: google.protobuf.Struct payload = 3;
      */
     payload?: JsonObject;
     /**
-     * Idempotency key for deduplication of signal delivery.
+     * Optional 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)
+     * @internal
+     * When provided, duplicate signals with the same key (within the 24-hour 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)
      *
@@ -1078,22 +573,17 @@ export declare const SendSignalInputSchema: GenMessage<SendSignalInput>;
 /**
  * WorkflowUpdateType defines the type of workflow execution update event.
  *
+ * @internal
  * 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).
+     * Unspecified update type (invalid).
+     *
+     * @internal
+     * Exists only for proto3 zero-value semantics.
      *
      * @generated from enum value: workflow_update_type_unspecified = 0;
      */
@@ -1101,13 +591,8 @@ export declare enum WorkflowUpdateType {
     /**
      * 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
+     * @internal
+     * Triggered when status.phase transitions to a new value.
      *
      * @generated from enum value: wf_update_status_changed = 1;
      */
@@ -1115,62 +600,35 @@ export declare enum WorkflowUpdateType {
     /**
      * A workflow task started executing.
      *
+     * @internal
      * 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.
      *
+     * @internal
      * 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.
      *
+     * @internal
      * 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.
+     * @internal
+     * Terminal event - no more updates will follow.
      *
      * @generated from enum value: wf_update_execution_completed = 5;
      */
@@ -1178,15 +636,8 @@ export declare enum WorkflowUpdateType {
     /**
      * 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.
+     * @internal
+     * Terminal event - no more updates will follow.
      *
      * @generated from enum value: wf_update_execution_cancelled = 6;
      */