@stigmer/protos 0.0.68 → 0.0.70

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

@@ -23,8 +23,9 @@ export declare const WorkflowExecutionCommandController: {
          * Create and trigger a new workflow execution.
          *
          * This RPC creates a WorkflowExecution resource and immediately triggers it for execution.
-         * The workflow execution engine (Temporal) picks up the execution and begins processing tasks.
+         * The workflow execution engine picks up the execution and begins processing tasks.
          *
+         * @internal
          * Input Validation:
          * - metadata.org must be specified
          * - spec.workflow_instance_id is required and must reference an existing WorkflowInstance
@@ -106,7 +107,7 @@ export declare const WorkflowExecutionCommandController: {
          *     "org": "acme"
          *   },
          *   "spec": {
-         *     "workflow_instance_id": "wfi-customer-onboarding-prod",
+         *     "workflow_instance_id": "wfi_customer-onboarding-prod",
          *     "trigger_message": "New signup: john.doe@example.com",
          *     "trigger_metadata": {
          *       "source": "api",
@@ -124,7 +125,7 @@ export declare const WorkflowExecutionCommandController: {
          *   "api_version": "agentic.stigmer.ai/v1",
          *   "kind": "WorkflowExecution",
          *   "metadata": {
-         *     "id": "wfx-abc123xyz456",  // Auto-generated
+         *     "id": "wfx_abc123xyz456",  // Auto-generated
          *     "name": "customer-onboarding-20250111-143022",
          *     "org": "acme"
          *   },
@@ -147,7 +148,9 @@ export declare const WorkflowExecutionCommandController: {
             readonly kind: any;
         };
         /**
-         * Update execution with full state.
+         * Update an existing workflow execution with full state.
+         *
+         * @internal
          * Used by users to update execution configuration (spec fields).
          * No individual field updates - always provide complete state.
          *
@@ -161,8 +164,11 @@ export declare const WorkflowExecutionCommandController: {
         };
         /**
          * Update execution status during workflow execution.
-         * Used by workflow-runner to send progressive status updates (messages, task states, phase, etc.)
-         * This RPC is optimized for frequent status updates and merges status fields with existing state.
+         *
+         * @internal
+         * System-level RPC used by workflow-runner to send progressive status updates
+         * (messages, task states, phase, etc.). Optimized for frequent status updates
+         * and merges status fields with existing state.
          *
          * This RPC is used by the workflow execution engine (Temporal) to update the status
          * of a running workflow execution. Users cannot call this RPC directly.
@@ -235,7 +241,7 @@ export declare const WorkflowExecutionCommandController: {
          * Example Request (Task Completed):
          * {
          *   "metadata": {
-         *     "id": "wfx-abc123xyz456"
+         *     "id": "wfx_abc123xyz456"
          *   },
          *   "status": {
          *     "phase": 2,  // EXECUTION_IN_PROGRESS
@@ -267,29 +273,27 @@ export declare const WorkflowExecutionCommandController: {
             readonly kind: any;
         };
         /**
-         * Submit approval for a child agent's tool execution (HITL Phase 5.3).
+         * Submit an approval decision for a child agent's tool execution.
          *
          * This RPC forwards the approval decision to the child AgentExecution that
          * is waiting for approval. The child is identified by the child_agent_execution_id
          * in status.pending_approval.
          *
-         * ## Behavior
-         *
          * When a workflow invokes an agent that requires tool approval, the approval
          * request surfaces at the workflow level via status.pending_approval. Users can
          * submit their decision through this RPC, which forwards it to the child agent.
          *
+         * @internal
          * The approval is forwarded to the child via AgentExecution.submitApproval RPC,
          * ensuring consistent validation and Temporal workflow signaling.
          *
-         * ## Preconditions
-         *
+         * Preconditions:
          * - status.pending_approval must be populated
          * - tool_call_id must match status.pending_approval.tool_call_id
          * - status.pending_approval.child_agent_execution_id must not be empty
          * - User must have can_edit permission on the workflow execution
          *
-         * ## State Transitions
+         * State Transitions
          *
          * After successful approval:
          * - Approval is forwarded to child AgentExecution
@@ -298,13 +302,13 @@ export declare const WorkflowExecutionCommandController: {
          * - WorkflowExecution.status.pending_approval is eventually cleared
          * - Workflow task status returns from WAITING_APPROVAL to IN_PROGRESS
          *
-         * ## Approval Actions
+         * Approval Actions
          *
          * - APPROVE: Tool executes with the provided arguments
          * - SKIP: Tool execution is skipped, agent continues with skip message
          * - REJECT: Agent execution fails with rejection error
          *
-         * ## Error Cases
+         * Error Cases
          *
          * - NOT_FOUND: Workflow execution doesn't exist
          * - PERMISSION_DENIED: User doesn't have can_edit permission
@@ -312,12 +316,12 @@ export declare const WorkflowExecutionCommandController: {
          * - INVALID_ARGUMENT: Tool call ID mismatch, or action is UNSPECIFIED
          * - UNAVAILABLE: Failed to forward to child agent (transient error)
          *
-         * ## Idempotency
+         * Idempotency
          *
          * If the same approval is submitted twice (same workflow execution, tool_call_id,
          * and action), the second call is a no-op if the approval was already processed.
          *
-         * ## Alternative: Direct Agent Approval
+         * Alternative: Direct Agent Approval
          *
          * Users can also submit approvals directly via AgentExecution.submitApproval
          * using the child_agent_execution_id. Both paths are equivalent and result
@@ -334,7 +338,7 @@ export declare const WorkflowExecutionCommandController: {
             readonly kind: any;
         };
         /**
-         * Delete an execution.
+         * Delete a workflow execution.
          *
          * @generated from rpc ai.stigmer.agentic.workflowexecution.v1.WorkflowExecutionCommandController.delete
          */
@@ -348,9 +352,13 @@ export declare const WorkflowExecutionCommandController: {
          * Send a signal to a running workflow execution.
          *
          * Delivers a signal to a workflow execution, typically to unblock a LISTEN task.
+         * Delivery is race-proof: the signal is guaranteed to arrive even if sent
+         * before the workflow is fully started.
+         *
+         * @internal
          * Uses Temporal's SignalWithStart API internally for race-proof delivery.
          *
-         * ## Behavior
+         * Behavior
          *
          * 1. Validates execution exists and is in a signalable phase
          * 2. Uses Temporal SignalWithStart for atomic delivery:
@@ -360,13 +368,13 @@ export declare const WorkflowExecutionCommandController: {
          * 4. LISTEN task waiting for this signal will unblock and continue
          * 5. Returns the current WorkflowExecution state
          *
-         * ## Preconditions
+         * 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)
+         * Race-Proof Delivery (SignalWithStart)
          *
          * This RPC uses Temporal's SignalWithStart API to handle the race condition
          * where a signal might arrive before the workflow is fully started:
@@ -374,7 +382,7 @@ export declare const WorkflowExecutionCommandController: {
          * - SignalWithStart atomically: starts workflow if needed, then sends signal
          * - Guarantees signal delivery even in race conditions
          *
-         * ## Signal Matching
+         * Signal Matching
          *
          * The signal_name must match the signal ID defined in the workflow's LISTEN task:
          *
@@ -390,17 +398,17 @@ export declare const WorkflowExecutionCommandController: {
          * API Call:
          *   { "signal_name": "payment_confirmed", "payload": {...} }
          *
-         * ## Error Cases
+         * Error Cases
          *
          * - NOT_FOUND: Workflow execution doesn't exist
          * - PERMISSION_DENIED: User doesn't have can_edit permission
          * - FAILED_PRECONDITION: Execution is in a terminal phase
          * - INVALID_ARGUMENT: execution_id or signal_name is empty
          *
-         * ## Example Request
+         * Example Request
          *
          * {
-         *   "execution_id": "wfx-abc123xyz456",
+         *   "execution_id": "wfx_abc123xyz456",
          *   "signal_name": "payment_confirmed",
          *   "payload": {
          *     "transaction_id": "txn_123",
@@ -409,7 +417,7 @@ export declare const WorkflowExecutionCommandController: {
          *   }
          * }
          *
-         * ## Example Response
+         * Example Response
          *
          * Returns the current WorkflowExecution state (phase may still be IN_PROGRESS
          * as the workflow continues after receiving the signal).
@@ -427,14 +435,14 @@ export declare const WorkflowExecutionCommandController: {
         /**
          * Cancel a running workflow execution gracefully.
          *
-         * Sends a cancellation signal to the workflow via Temporal's CancelWorkflow API.
-         * The workflow code can handle the cancellation signal to perform cleanup
-         * (e.g., compensation logic, resource cleanup, notifications) before
-         * transitioning to the CANCELLED phase.
+         * Sends a cancellation signal to the workflow. The workflow code can handle
+         * the cancellation signal to perform cleanup (e.g., compensation logic,
+         * resource cleanup, notifications) before transitioning to the CANCELLED phase.
          *
+         * @internal
          * Temporal Equivalent: `temporal workflow cancel --workflow-id <id>`
          *
-         * ## Behavior
+         * Behavior
          *
          * 1. Validates execution exists and is in a cancellable phase
          * 2. Sends cancellation signal to Temporal workflow
@@ -442,43 +450,43 @@ export declare const WorkflowExecutionCommandController: {
          * 4. Execution transitions to EXECUTION_CANCELLED phase
          * 5. Returns updated WorkflowExecution with new phase
          *
-         * ## Preconditions
+         * Preconditions
          *
          * - Execution must be in EXECUTION_PENDING or EXECUTION_IN_PROGRESS phase
          * - Cannot cancel already-terminal executions (COMPLETED, FAILED, CANCELLED, TERMINATED)
          *
-         * ## State Transitions
+         * State Transitions
          *
          * - status.phase: PENDING/IN_PROGRESS → CANCELLED
          * - status.completed_at: Set to current timestamp
          * - In-progress tasks: May complete cleanup or be interrupted
          *
-         * ## Idempotency
+         * Idempotency
          *
          * Cancelling an already-cancelled execution succeeds as a no-op.
          * The call returns the current execution state without side effects.
          * This ensures safe retry of cancel requests.
          *
-         * ## Error Cases
+         * Error Cases
          *
          * - NOT_FOUND: Execution with given ID doesn't exist
          * - PERMISSION_DENIED: User lacks can_edit permission on the execution
          * - FAILED_PRECONDITION: Execution is in a terminal phase (COMPLETED, FAILED, TERMINATED)
          * - INVALID_ARGUMENT: ID is empty or malformed
          *
-         * ## Example Request
+         * Example Request
          *
          * {
-         *   "id": "wfx-abc123xyz456",
+         *   "id": "wfx_abc123xyz456",
          *   "reason": "Customer requested cancellation - order no longer needed"
          * }
          *
-         * ## Example Response
+         * Example Response
          *
          * {
          *   "api_version": "agentic.stigmer.ai/v1",
          *   "kind": "WorkflowExecution",
-         *   "metadata": { "id": "wfx-abc123xyz456" },
+         *   "metadata": { "id": "wfx_abc123xyz456" },
          *   "status": {
          *     "phase": 5,  // EXECUTION_CANCELLED
          *     "completed_at": "2026-02-07T18:30:00Z"
@@ -496,14 +504,14 @@ export declare const WorkflowExecutionCommandController: {
         /**
          * Terminate a workflow execution immediately.
          *
-         * Force-stops the workflow via Temporal's TerminateWorkflow API without
-         * allowing cleanup. Unlike cancel, the workflow code cannot respond to
-         * termination - it is stopped immediately. Use this for stuck or
-         * unresponsive workflows that don't respond to cancellation.
+         * Force-stops the workflow without allowing cleanup. Unlike cancel,
+         * the workflow code cannot respond to termination - it is stopped immediately.
+         * Use this for stuck or unresponsive workflows that don't respond to cancellation.
          *
+         * @internal
          * Temporal Equivalent: `temporal workflow terminate --workflow-id <id>`
          *
-         * ## Behavior
+         * Behavior
          *
          * 1. Validates execution exists and is in a terminable phase
          * 2. Force-kills workflow via Temporal (no signal sent to workflow)
@@ -511,19 +519,19 @@ export declare const WorkflowExecutionCommandController: {
          * 4. No cleanup callbacks or defer blocks are executed
          * 5. Returns updated WorkflowExecution with TERMINATED phase
          *
-         * ## Preconditions
+         * Preconditions
          *
          * - Execution must be in EXECUTION_PENDING or EXECUTION_IN_PROGRESS phase
          * - Cannot terminate already-terminal executions
          *
-         * ## State Transitions
+         * State Transitions
          *
          * - status.phase: PENDING/IN_PROGRESS → TERMINATED
          * - status.completed_at: Set to current timestamp
          * - status.error: May contain termination reason
          * - In-progress tasks: Stopped abruptly (no cleanup)
          *
-         * ## Terminated vs Cancelled
+         * Terminated vs Cancelled
          *
          * | Aspect | cancel | terminate |
          * |--------|--------|-----------|
@@ -532,31 +540,31 @@ export declare const WorkflowExecutionCommandController: {
          * | Use case | Normal stop | Stuck workflows |
          * | Can recover? | No | No |
          *
-         * ## Idempotency
+         * Idempotency
          *
          * Terminating an already-terminated execution succeeds as a no-op.
          * The call returns the current execution state without side effects.
          *
-         * ## Error Cases
+         * Error Cases
          *
          * - NOT_FOUND: Execution with given ID doesn't exist
          * - PERMISSION_DENIED: User lacks can_edit permission on the execution
          * - FAILED_PRECONDITION: Execution is in a terminal phase
          * - INVALID_ARGUMENT: ID is empty or malformed
          *
-         * ## Example Request
+         * Example Request
          *
          * {
-         *   "id": "wfx-abc123xyz456",
+         *   "id": "wfx_abc123xyz456",
          *   "reason": "Workflow stuck for 2 hours, not responding to cancel"
          * }
          *
-         * ## Example Response
+         * Example Response
          *
          * {
          *   "api_version": "agentic.stigmer.ai/v1",
          *   "kind": "WorkflowExecution",
-         *   "metadata": { "id": "wfx-abc123xyz456" },
+         *   "metadata": { "id": "wfx_abc123xyz456" },
          *   "status": {
          *     "phase": 6,  // EXECUTION_TERMINATED
          *     "completed_at": "2026-02-07T18:35:00Z",
@@ -575,14 +583,14 @@ export declare const WorkflowExecutionCommandController: {
         /**
          * Recover a failed workflow execution from the last checkpoint.
          *
-         * Resumes execution from the last successful point using Temporal's
-         * ResetWorkflow API. Completed work is preserved - successful tasks
-         * are NOT re-executed. This enables "retry and resume" semantics
-         * without duplicating side effects.
+         * Resumes execution from the last successful point. Completed work is
+         * preserved - successful tasks are NOT re-executed. This enables
+         * "retry and resume" semantics without duplicating side effects.
          *
+         * @internal
          * Temporal Equivalent: `temporal workflow reset --workflow-id <id> --type LastWorkflowTask`
          *
-         * ## Behavior
+         * Behavior
          *
          * 1. Validates execution is in FAILED phase (recoverable)
          * 2. Identifies the last successful checkpoint in workflow history
@@ -591,14 +599,14 @@ export declare const WorkflowExecutionCommandController: {
          * 5. Workflow continues from where it failed
          * 6. Returns updated WorkflowExecution with IN_PROGRESS phase
          *
-         * ## Preconditions
+         * Preconditions
          *
          * - Execution must be in EXECUTION_FAILED phase
          * - TERMINATED executions cannot be recovered (intentional hard stop)
          * - CANCELLED executions cannot be recovered (intentional user action)
          * - COMPLETED executions don't need recovery
          *
-         * ## State Transitions
+         * State Transitions
          *
          * - status.phase: FAILED → IN_PROGRESS
          * - status.completed_at: Cleared (execution is running again)
@@ -606,7 +614,7 @@ export declare const WorkflowExecutionCommandController: {
          * - Completed tasks: Preserved (not re-executed)
          * - Failed tasks: Reset to pending, will be retried
          *
-         * ## Recovery vs Restart
+         * Recovery vs Restart
          *
          * | Aspect | recover | Create new execution |
          * |--------|---------|----------------------|
@@ -615,13 +623,13 @@ export declare const WorkflowExecutionCommandController: {
          * | Execution ID | Same | New ID |
          * | Use case | Resume after fix | Start fresh |
          *
-         * ## Idempotency
+         * Idempotency
          *
          * If recovery already succeeded (execution is now IN_PROGRESS from a
          * previous recover call), the call succeeds as a no-op and returns
          * the current execution state.
          *
-         * ## Error Cases
+         * Error Cases
          *
          * - NOT_FOUND: Execution with given ID doesn't exist
          * - PERMISSION_DENIED: User lacks can_edit permission on the execution
@@ -631,19 +639,19 @@ export declare const WorkflowExecutionCommandController: {
          *   - Execution is CANCELLED (cannot recover)
          * - INVALID_ARGUMENT: ID is empty or malformed
          *
-         * ## Example Request
+         * Example Request
          *
          * {
-         *   "id": "wfx-abc123xyz456",
+         *   "id": "wfx_abc123xyz456",
          *   "reason": "Stripe API recovered, resuming payment processing"
          * }
          *
-         * ## Example Response
+         * Example Response
          *
          * {
          *   "api_version": "agentic.stigmer.ai/v1",
          *   "kind": "WorkflowExecution",
-         *   "metadata": { "id": "wfx-abc123xyz456" },
+         *   "metadata": { "id": "wfx_abc123xyz456" },
          *   "status": {
          *     "phase": 2,  // EXECUTION_IN_PROGRESS
          *     "started_at": "2026-02-07T10:00:00Z",
@@ -669,7 +677,9 @@ export declare const WorkflowExecutionCommandController: {
          * the execution is NOT terminal and can be resumed later from where it left off.
          * The workflow gracefully checkpoints and exits, preserving all progress.
          *
-         * ## Behavior
+         * @internal
+         *
+         * Behavior
          *
          * 1. Validates execution exists and is in a pausable phase
          * 2. Sends "pause" signal to Temporal workflow
@@ -679,19 +689,19 @@ export declare const WorkflowExecutionCommandController: {
          * 6. Workflow waits for resume signal (no resources consumed)
          * 7. Returns updated WorkflowExecution with PAUSED phase
          *
-         * ## Preconditions
+         * Preconditions
          *
          * - Execution must be in EXECUTION_PENDING or EXECUTION_IN_PROGRESS phase
          * - Cannot pause already-terminal executions (COMPLETED, FAILED, CANCELLED, TERMINATED)
          *
-         * ## State Transitions
+         * State Transitions
          *
          * - status.phase: PENDING/IN_PROGRESS → PAUSED
          * - status.completed_at: NOT set (execution is not finished)
          * - Running activities: Gracefully cancelled, checkpoint saved
          * - LangGraph state: Preserved via thread_id checkpoint
          *
-         * ## Paused vs Cancelled
+         * Paused vs Cancelled
          *
          * | Aspect | pause | cancel |
          * |--------|-------|--------|
@@ -701,7 +711,7 @@ export declare const WorkflowExecutionCommandController: {
          * | Progress preserved? | Yes | No |
          * | Use case | Temporary stop, maintenance | Permanent stop |
          *
-         * ## Agent Activity Behavior
+         * Agent Activity Behavior
          *
          * When pause is signaled to a workflow running an agent:
          * 1. Workflow cancels the running activity gracefully
@@ -710,31 +720,31 @@ export declare const WorkflowExecutionCommandController: {
          * 4. Activity returns with paused status
          * 5. On resume, activity loads from checkpoint and continues
          *
-         * ## Idempotency
+         * Idempotency
          *
          * Pausing an already-paused execution succeeds as a no-op.
          * The call returns the current execution state without side effects.
          *
-         * ## Error Cases
+         * Error Cases
          *
          * - NOT_FOUND: Execution with given ID doesn't exist
          * - PERMISSION_DENIED: User lacks can_edit permission on the execution
          * - FAILED_PRECONDITION: Execution is in a terminal phase
          * - INVALID_ARGUMENT: ID is empty or malformed
          *
-         * ## Example Request
+         * Example Request
          *
          * {
-         *   "id": "wfx-abc123xyz456",
+         *   "id": "wfx_abc123xyz456",
          *   "reason": "Pausing for scheduled maintenance window"
          * }
          *
-         * ## Example Response
+         * Example Response
          *
          * {
          *   "api_version": "agentic.stigmer.ai/v1",
          *   "kind": "WorkflowExecution",
-         *   "metadata": { "id": "wfx-abc123xyz456" },
+         *   "metadata": { "id": "wfx_abc123xyz456" },
          *   "status": {
          *     "phase": 7,  // EXECUTION_PAUSED
          *     "started_at": "2026-02-07T10:00:00Z"
@@ -759,7 +769,9 @@ export declare const WorkflowExecutionCommandController: {
          * re-invokes activities with the same thread_id, which loads from checkpoint
          * and continues from where it left off.
          *
-         * ## Behavior
+         * @internal
+         *
+         * Behavior
          *
          * 1. Validates execution is in EXECUTION_PAUSED phase
          * 2. Sends "resume" signal to Temporal workflow
@@ -769,18 +781,18 @@ export declare const WorkflowExecutionCommandController: {
          * 6. Execution transitions back to EXECUTION_IN_PROGRESS phase
          * 7. Returns updated WorkflowExecution with IN_PROGRESS phase
          *
-         * ## Preconditions
+         * Preconditions
          *
          * - Execution must be in EXECUTION_PAUSED phase
          * - Cannot resume non-paused executions
          *
-         * ## State Transitions
+         * State Transitions
          *
          * - status.phase: PAUSED → IN_PROGRESS
          * - Activities: Re-invoked, load from checkpoint
          * - LangGraph state: Loaded from checkpoint via thread_id
          *
-         * ## Resume Behavior
+         * Resume Behavior
          *
          * When resume is signaled to a paused workflow:
          * 1. Java workflow unblocks from Workflow.await()
@@ -789,30 +801,30 @@ export declare const WorkflowExecutionCommandController: {
          * 4. LangGraph loads checkpoint using thread_id
          * 5. Agent continues from exact position where it was paused
          *
-         * ## Idempotency
+         * Idempotency
          *
          * Resuming an already-running execution succeeds as a no-op.
          * The call returns the current execution state without side effects.
          *
-         * ## Error Cases
+         * Error Cases
          *
          * - NOT_FOUND: Execution with given ID doesn't exist
          * - PERMISSION_DENIED: User lacks can_edit permission on the execution
          * - FAILED_PRECONDITION: Execution is not in PAUSED phase
          * - INVALID_ARGUMENT: ID is empty or malformed
          *
-         * ## Example Request
+         * Example Request
          *
          * {
-         *   "id": "wfx-abc123xyz456"
+         *   "id": "wfx_abc123xyz456"
          * }
          *
-         * ## Example Response
+         * Example Response
          *
          * {
          *   "api_version": "agentic.stigmer.ai/v1",
          *   "kind": "WorkflowExecution",
-         *   "metadata": { "id": "wfx-abc123xyz456" },
+         *   "metadata": { "id": "wfx_abc123xyz456" },
          *   "status": {
          *     "phase": 2,  // EXECUTION_IN_PROGRESS
          *     "started_at": "2026-02-07T10:00:00Z"