@stigmer/protos 0.0.34

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

@@ -0,0 +1,419 @@
+// @generated by protoc-gen-connect-es v1.6.1 with parameter "target=ts"
+// @generated from file ai/stigmer/agentic/agentexecution/v1/command.proto (package ai.stigmer.agentic.agentexecution.v1, syntax proto3)
+/* eslint-disable */
+// @ts-nocheck
+import { MethodKind } from "@bufbuild/protobuf";
+/**
+ * AgentExecutionCommandController handles write operations for agent executions.
+ * Follows the standard pattern: create, update, delete (no granular field updates).
+ *
+ * @generated from service ai.stigmer.agentic.agentexecution.v1.AgentExecutionCommandController
+ */
+export const AgentExecutionCommandController = {
+    typeName: "ai.stigmer.agentic.agentexecution.v1.AgentExecutionCommandController",
+    methods: {
+        /**
+         * Create and trigger a new agent execution.
+         * Session is optional - can be provided or auto-created from agent_id.
+         * Authorization is handled in handler:
+         *   - If session_id provided: checks can_create_execution_in on session
+         *   - If session_id NOT provided: checks can_create_execution_in on organization
+         *
+         * @generated from rpc ai.stigmer.agentic.agentexecution.v1.AgentExecutionCommandController.create
+         */
+        create: {
+            name: "create",
+            I: AgentExecution,
+            O: AgentExecution,
+            kind: MethodKind.Unary,
+        },
+        /**
+         * Update an execution with full state.
+         * Used by users to update execution configuration (spec fields).
+         * No individual field updates - always provide complete state.
+         *
+         * @generated from rpc ai.stigmer.agentic.agentexecution.v1.AgentExecutionCommandController.update
+         */
+        update: {
+            name: "update",
+            I: AgentExecution,
+            O: AgentExecution,
+            kind: MethodKind.Unary,
+        },
+        /**
+         * Update execution status during agent execution.
+         * Used by agent-runner to send progressive status updates (messages, tool_calls, phase, etc.)
+         * This RPC is optimized for frequent status updates and merges status fields with existing state.
+         *
+         * @generated from rpc ai.stigmer.agentic.agentexecution.v1.AgentExecutionCommandController.updateStatus
+         */
+        updateStatus: {
+            name: "updateStatus",
+            I: AgentExecutionUpdateStatusInput,
+            O: AgentExecution,
+            kind: MethodKind.Unary,
+        },
+        /**
+         * Delete an execution.
+         *
+         * @generated from rpc ai.stigmer.agentic.agentexecution.v1.AgentExecutionCommandController.delete
+         */
+        delete: {
+            name: "delete",
+            I: ApiResourceId,
+            O: AgentExecution,
+            kind: MethodKind.Unary,
+        },
+        /**
+         * Submit approval decision for a pending tool call (HITL Phase 1).
+         *
+         * ## Preconditions
+         *
+         * - Execution must be in EXECUTION_WAITING_FOR_APPROVAL phase
+         * - tool_call_id must match status.pending_approval.tool_call_id
+         * - User must have can_edit permission on the execution
+         *
+         * ## Behavior by Action
+         *
+         * - APPROVE: Tool executes normally, execution resumes to IN_PROGRESS
+         * - SKIP: Tool returns skip message to LLM, execution continues to IN_PROGRESS
+         * - REJECT: Execution fails with rejection error, phase becomes FAILED
+         *
+         * ## State Transitions
+         *
+         * On success:
+         * - ToolCall.approval_action = submitted action
+         * - ToolCall.approval_decided_at = current timestamp
+         * - ToolCall.approved_by = authenticated user ID
+         * - AgentExecutionStatus.pending_approval = cleared
+         * - ExecutionPhase = EXECUTION_IN_PROGRESS (or EXECUTION_FAILED if REJECT)
+         *
+         * ## Error Conditions
+         *
+         * - NOT_FOUND: Execution doesn't exist
+         * - FAILED_PRECONDITION: Execution not in WAITING_FOR_APPROVAL phase
+         * - INVALID_ARGUMENT: tool_call_id doesn't match pending approval, or action is UNSPECIFIED
+         * - PERMISSION_DENIED: User lacks can_edit permission
+         *
+         * ## Idempotency
+         *
+         * If the same approval is submitted twice (same execution, tool_call, action),
+         * the second call is a no-op and returns the current state.
+         *
+         * @generated from rpc ai.stigmer.agentic.agentexecution.v1.AgentExecutionCommandController.submitApproval
+         */
+        submitApproval: {
+            name: "submitApproval",
+            I: SubmitApprovalInput,
+            O: AgentExecution,
+            kind: MethodKind.Unary,
+        },
+        /**
+         * Cancel a running agent execution gracefully.
+         *
+         * Sends a cancellation signal to the agent execution via Temporal's CancelWorkflow API.
+         * The agent can handle the cancellation signal to save checkpoint and clean up
+         * before transitioning to the CANCELLED phase.
+         *
+         * Temporal Equivalent: `temporal workflow cancel --workflow-id <id>`
+         *
+         * ## Behavior
+         *
+         * 1. Validates execution exists and is in a cancellable phase
+         * 2. Sends cancellation signal to Temporal workflow
+         * 3. Python activity receives cancellation and saves LangGraph checkpoint
+         * 4. Execution transitions to EXECUTION_CANCELLED phase
+         * 5. Returns updated AgentExecution with new phase
+         *
+         * ## Preconditions
+         *
+         * - Execution must be in EXECUTION_PENDING or EXECUTION_IN_PROGRESS phase
+         * - Cannot cancel already-terminal executions (COMPLETED, FAILED, CANCELLED, TERMINATED)
+         *
+         * ## State Transitions
+         *
+         * - status.phase: PENDING/IN_PROGRESS → CANCELLED
+         * - status.completed_at: Set to current timestamp
+         * - LangGraph checkpoint: Preserved for potential future reference
+         *
+         * ## Idempotency
+         *
+         * Cancelling an already-cancelled execution succeeds as a no-op.
+         * The call returns the current execution state without side effects.
+         *
+         * ## 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
+         *
+         * @since Agent Execution Lifecycle
+         *
+         * @generated from rpc ai.stigmer.agentic.agentexecution.v1.AgentExecutionCommandController.cancel
+         */
+        cancel: {
+            name: "cancel",
+            I: CancelAgentExecutionInput,
+            O: AgentExecution,
+            kind: MethodKind.Unary,
+        },
+        /**
+         * Terminate an agent execution immediately.
+         *
+         * Force-stops the agent execution via Temporal's TerminateWorkflow API without
+         * allowing cleanup. Unlike cancel, the agent cannot respond to termination -
+         * it is stopped immediately. Use this for stuck or unresponsive agents.
+         *
+         * Temporal Equivalent: `temporal workflow terminate --workflow-id <id>`
+         *
+         * ## Behavior
+         *
+         * 1. Validates execution exists and is in a terminable phase
+         * 2. Force-kills workflow via Temporal (no signal sent to agent)
+         * 3. Execution transitions to EXECUTION_TERMINATED phase immediately
+         * 4. No cleanup callbacks or checkpoint saves occur
+         * 5. Returns updated AgentExecution with TERMINATED phase
+         *
+         * ## Preconditions
+         *
+         * - Execution must be in EXECUTION_PENDING or EXECUTION_IN_PROGRESS phase
+         * - Cannot terminate already-terminal executions
+         *
+         * ## State Transitions
+         *
+         * - status.phase: PENDING/IN_PROGRESS → TERMINATED
+         * - status.completed_at: Set to current timestamp
+         * - LangGraph checkpoint: May be incomplete (no graceful save)
+         *
+         * ## Terminated vs Cancelled
+         *
+         * | Aspect | cancel | terminate |
+         * |--------|--------|-----------|
+         * | Signal to agent | Yes (can handle) | No |
+         * | Checkpoint saved | Yes (graceful) | No |
+         * | Use case | Normal stop | Stuck agents |
+         * | Can recover? | No | No |
+         *
+         * ## Idempotency
+         *
+         * Terminating an already-terminated execution succeeds as a no-op.
+         *
+         * ## 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
+         *
+         * @since Agent Execution Lifecycle
+         *
+         * @generated from rpc ai.stigmer.agentic.agentexecution.v1.AgentExecutionCommandController.terminate
+         */
+        terminate: {
+            name: "terminate",
+            I: TerminateAgentExecutionInput,
+            O: AgentExecution,
+            kind: MethodKind.Unary,
+        },
+        /**
+         * Recover a failed agent execution from the last checkpoint.
+         *
+         * Resumes execution from the last LangGraph checkpoint using Temporal's
+         * ResetWorkflow API. Completed work is preserved - successful tool calls
+         * are NOT re-executed.
+         *
+         * Temporal Equivalent: `temporal workflow reset --workflow-id <id> --type LastWorkflowTask`
+         *
+         * ## Behavior
+         *
+         * 1. Validates execution is in FAILED phase (recoverable)
+         * 2. Uses Temporal ResetWorkflow to resume from last checkpoint
+         * 3. Activity re-invoked with same thread_id
+         * 4. LangGraph loads from checkpoint automatically
+         * 5. Execution transitions from FAILED to IN_PROGRESS phase
+         * 6. Agent continues from where it failed
+         *
+         * ## Preconditions
+         *
+         * - Execution must be in EXECUTION_FAILED phase
+         * - TERMINATED executions cannot be recovered (incomplete checkpoint)
+         * - CANCELLED executions cannot be recovered (intentional user action)
+         *
+         * ## State Transitions
+         *
+         * - status.phase: FAILED → IN_PROGRESS
+         * - status.completed_at: Cleared
+         * - status.error: Cleared
+         * - Completed tool calls: Preserved (not re-executed)
+         *
+         * ## Idempotency
+         *
+         * If recovery already succeeded (execution is now IN_PROGRESS),
+         * the call succeeds as a no-op.
+         *
+         * ## Error Cases
+         *
+         * - NOT_FOUND: Execution with given ID doesn't exist
+         * - PERMISSION_DENIED: User lacks can_edit permission
+         * - FAILED_PRECONDITION: Execution is not in FAILED phase
+         * - INVALID_ARGUMENT: ID is empty or malformed
+         *
+         * @since Agent Execution Lifecycle
+         *
+         * @generated from rpc ai.stigmer.agentic.agentexecution.v1.AgentExecutionCommandController.recover
+         */
+        recover: {
+            name: "recover",
+            I: RecoverAgentExecutionInput,
+            O: AgentExecution,
+            kind: MethodKind.Unary,
+        },
+        /**
+         * Pause a running agent execution.
+         *
+         * Temporarily stops the agent at its current checkpoint. Unlike cancel,
+         * the execution is NOT terminal and can be resumed later from where it left off.
+         *
+         * ## Behavior
+         *
+         * 1. Validates execution exists and is in a pausable phase
+         * 2. Sends "pause" signal to Temporal workflow
+         * 3. Workflow cancels running activity gracefully
+         * 4. Python activity saves LangGraph checkpoint on cancellation
+         * 5. Execution transitions to EXECUTION_PAUSED phase
+         * 6. Workflow waits for resume signal (no resources consumed)
+         *
+         * ## Preconditions
+         *
+         * - Execution must be in EXECUTION_PENDING or EXECUTION_IN_PROGRESS phase
+         * - Cannot pause already-terminal or already-paused executions
+         *
+         * ## State Transitions
+         *
+         * - status.phase: PENDING/IN_PROGRESS → PAUSED
+         * - status.completed_at: NOT set (execution is not finished)
+         * - LangGraph checkpoint: Saved via thread_id
+         *
+         * ## Paused vs Cancelled
+         *
+         * | Aspect | pause | cancel |
+         * |--------|-------|--------|
+         * | Terminal state? | No | Yes |
+         * | Can resume? | Yes (via resume RPC) | No |
+         * | Checkpoint saved? | Yes | Best-effort |
+         * | Use case | Temporary stop | Permanent stop |
+         *
+         * ## Idempotency
+         *
+         * Pausing an already-paused execution succeeds as a no-op.
+         *
+         * ## Error Cases
+         *
+         * - NOT_FOUND: Execution with given ID doesn't exist
+         * - PERMISSION_DENIED: User lacks can_edit permission
+         * - FAILED_PRECONDITION: Execution is in a terminal phase
+         * - INVALID_ARGUMENT: ID is empty or malformed
+         *
+         * @since Agent Execution Lifecycle
+         *
+         * @generated from rpc ai.stigmer.agentic.agentexecution.v1.AgentExecutionCommandController.pause
+         */
+        pause: {
+            name: "pause",
+            I: PauseAgentExecutionInput,
+            O: AgentExecution,
+            kind: MethodKind.Unary,
+        },
+        /**
+         * Resume a paused agent execution.
+         *
+         * Continues execution from the checkpoint where it was paused. The agent
+         * re-invokes with the same thread_id, loading from LangGraph checkpoint
+         * and continuing from where it left off.
+         *
+         * ## Behavior
+         *
+         * 1. Validates execution is in EXECUTION_PAUSED phase
+         * 2. Sends "resume" signal to Temporal workflow
+         * 3. Workflow unblocks and re-invokes activity
+         * 4. Activity loads from LangGraph checkpoint using thread_id
+         * 5. Execution transitions back to EXECUTION_IN_PROGRESS phase
+         * 6. Agent continues from exact pause point
+         *
+         * ## Preconditions
+         *
+         * - Execution must be in EXECUTION_PAUSED phase
+         * - Cannot resume non-paused executions
+         *
+         * ## State Transitions
+         *
+         * - status.phase: PAUSED → IN_PROGRESS
+         * - Activities: Re-invoked, load from checkpoint
+         * - LangGraph state: Loaded from checkpoint via thread_id
+         *
+         * ## Idempotency
+         *
+         * Resuming an already-running execution succeeds as a no-op.
+         *
+         * ## Error Cases
+         *
+         * - NOT_FOUND: Execution with given ID doesn't exist
+         * - PERMISSION_DENIED: User lacks can_edit permission
+         * - FAILED_PRECONDITION: Execution is not in PAUSED phase
+         * - INVALID_ARGUMENT: ID is empty or malformed
+         *
+         * @since Agent Execution Lifecycle
+         *
+         * @generated from rpc ai.stigmer.agentic.agentexecution.v1.AgentExecutionCommandController.resume
+         */
+        resume: {
+            name: "resume",
+            I: ResumeAgentExecutionInput,
+            O: AgentExecution,
+            kind: MethodKind.Unary,
+        },
+        /**
+         * Upload a file attachment for use in an agent execution.
+         *
+         * Pre-uploads files to artifact storage before creating an execution.
+         * The returned storage_key can be used in Attachment.storage_key when
+         * creating the execution.
+         *
+         * ## Authorization
+         *
+         * This endpoint does not require authorization. The storage_key returned
+         * acts as a capability token - knowing the key grants access to the content.
+         * This simplifies the upload flow for CLI and other clients.
+         *
+         * ## Storage Path
+         *
+         * Files are stored at: attachments/{ulid}/{filename}
+         * The ULID ensures unique paths and enables future cleanup policies.
+         *
+         * ## Use Cases
+         *
+         * - CLI uploading files (>4MB) before agent execution
+         * - Pre-uploading datasets for agent processing
+         * - Uploading binary files that cannot be embedded inline in Attachment
+         *
+         * ## Example Flow
+         *
+         * 1. Client calls uploadAttachment with file content
+         * 2. Server uploads to storage, returns storage_key
+         * 3. Client creates AgentExecution with Attachment using storage_key
+         * 4. Agent-runner downloads attachment content when execution starts
+         *
+         * @since Artifact Lifecycle (Attachments & Artifacts)
+         *
+         * @generated from rpc ai.stigmer.agentic.agentexecution.v1.AgentExecutionCommandController.uploadAttachment
+         */
+        uploadAttachment: {
+            name: "uploadAttachment",
+            I: UploadAttachmentRequest,
+            O: UploadAttachmentResponse,
+            kind: MethodKind.Unary,
+        },
+    }
+};
+//# sourceMappingURL=command_connect.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"command_connect.js","sourceRoot":"","sources":["../../../../../../ai/stigmer/agentic/agentexecution/v1/command_connect.ts"],"names":[],"mappings":"AAAA,wEAAwE;AACxE,wIAAwI;AACxI,oBAAoB;AACpB,cAAc;AAGd,OAAO,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAIhD;;;;;GAKG;AACH,MAAM,CAAC,MAAM,+BAA+B,GAAG;IAC7C,QAAQ,EAAE,sEAAsE;IAChF,OAAO,EAAE;QACP;;;;;;;;WAQG;QACH,MAAM,EAAE;YACN,IAAI,EAAE,QAAQ;YACd,CAAC,EAAE,cAAc;YACjB,CAAC,EAAE,cAAc;YACjB,IAAI,EAAE,UAAU,CAAC,KAAK;SACvB;QACD;;;;;;WAMG;QACH,MAAM,EAAE;YACN,IAAI,EAAE,QAAQ;YACd,CAAC,EAAE,cAAc;YACjB,CAAC,EAAE,cAAc;YACjB,IAAI,EAAE,UAAU,CAAC,KAAK;SACvB;QACD;;;;;;WAMG;QACH,YAAY,EAAE;YACZ,IAAI,EAAE,cAAc;YACpB,CAAC,EAAE,+BAA+B;YAClC,CAAC,EAAE,cAAc;YACjB,IAAI,EAAE,UAAU,CAAC,KAAK;SACvB;QACD;;;;WAIG;QACH,MAAM,EAAE;YACN,IAAI,EAAE,QAAQ;YACd,CAAC,EAAE,aAAa;YAChB,CAAC,EAAE,cAAc;YACjB,IAAI,EAAE,UAAU,CAAC,KAAK;SACvB;QACD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;WAqCG;QACH,cAAc,EAAE;YACd,IAAI,EAAE,gBAAgB;YACtB,CAAC,EAAE,mBAAmB;YACtB,CAAC,EAAE,cAAc;YACjB,IAAI,EAAE,UAAU,CAAC,KAAK;SACvB;QACD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;WA2CG;QACH,MAAM,EAAE;YACN,IAAI,EAAE,QAAQ;YACd,CAAC,EAAE,yBAAyB;YAC5B,CAAC,EAAE,cAAc;YACjB,IAAI,EAAE,UAAU,CAAC,KAAK;SACvB;QACD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;WAmDG;QACH,SAAS,EAAE;YACT,IAAI,EAAE,WAAW;YACjB,CAAC,EAAE,4BAA4B;YAC/B,CAAC,EAAE,cAAc;YACjB,IAAI,EAAE,UAAU,CAAC,KAAK;SACvB;QACD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;WA8CG;QACH,OAAO,EAAE;YACP,IAAI,EAAE,SAAS;YACf,CAAC,EAAE,0BAA0B;YAC7B,CAAC,EAAE,cAAc;YACjB,IAAI,EAAE,UAAU,CAAC,KAAK;SACvB;QACD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;WAiDG;QACH,KAAK,EAAE;YACL,IAAI,EAAE,OAAO;YACb,CAAC,EAAE,wBAAwB;YAC3B,CAAC,EAAE,cAAc;YACjB,IAAI,EAAE,UAAU,CAAC,KAAK;SACvB;QACD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;WAyCG;QACH,MAAM,EAAE;YACN,IAAI,EAAE,QAAQ;YACd,CAAC,EAAE,yBAAyB;YAC5B,CAAC,EAAE,cAAc;YACjB,IAAI,EAAE,UAAU,CAAC,KAAK;SACvB;QACD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;WAkCG;QACH,gBAAgB,EAAE;YAChB,IAAI,EAAE,kBAAkB;YACxB,CAAC,EAAE,uBAAuB;YAC1B,CAAC,EAAE,wBAAwB;YAC3B,IAAI,EAAE,UAAU,CAAC,KAAK;SACvB;KACF;CACO,CAAC"}