@stigmer/protos 0.0.34

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

@@ -0,0 +1,16 @@
+// @generated by protoc-gen-es v2.2.2 with parameter "target=ts"
+// @generated from file ai/stigmer/agentic/agentexecution/v1/artifact.proto (package ai.stigmer.agentic.agentexecution.v1, syntax proto3)
+/* eslint-disable */
+import { fileDesc, messageDesc } from "@bufbuild/protobuf/codegenv1";
+import { file_ai_stigmer_agentic_agentexecution_v1_enum } from "./enum_pb";
+import { file_buf_validate_validate } from "../../../../../buf/validate/validate_pb";
+/**
+ * Describes the file ai/stigmer/agentic/agentexecution/v1/artifact.proto.
+ */
+export const file_ai_stigmer_agentic_agentexecution_v1_artifact = /*@__PURE__*/ fileDesc("CjNhaS9zdGlnbWVyL2FnZW50aWMvYWdlbnRleGVjdXRpb24vdjEvYXJ0aWZhY3QucHJvdG8SJGFpLnN0aWdtZXIuYWdlbnRpYy5hZ2VudGV4ZWN1dGlvbi52MSLzAQoRRXhlY3V0aW9uQXJ0aWZhY3QSDAoEbmFtZRgBIAEoCRIUCgxzYW5kYm94X3BhdGgYAiABKAkSUwoEa2luZBgDIAEoDjI7LmFpLnN0aWdtZXIuYWdlbnRpYy5hZ2VudGV4ZWN1dGlvbi52MS5FeGVjdXRpb25BcnRpZmFjdEtpbmRCCLpIBYIBAhABEhIKCnNpemVfYnl0ZXMYBCABKAMSEwoLc3RvcmFnZV9rZXkYBSABKAkSFAoMZG93bmxvYWRfdXJsGAYgASgJEhIKCmNyZWF0ZWRfYXQYByABKAkSEgoKZXhwaXJlc19hdBgIIAEoCWIGcHJvdG8z", [file_ai_stigmer_agentic_agentexecution_v1_enum, file_buf_validate_validate]);
+/**
+ * Describes the message ai.stigmer.agentic.agentexecution.v1.ExecutionArtifact.
+ * Use `create(ExecutionArtifactSchema)` to create a new message.
+ */
+export const ExecutionArtifactSchema = /*@__PURE__*/ messageDesc(file_ai_stigmer_agentic_agentexecution_v1_artifact, 0);
+//# sourceMappingURL=artifact_pb.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"artifact_pb.js","sourceRoot":"","sources":["../../../../../../ai/stigmer/agentic/agentexecution/v1/artifact_pb.ts"],"names":[],"mappings":"AAAA,gEAAgE;AAChE,yIAAyI;AACzI,oBAAoB;AAGpB,OAAO,EAAE,QAAQ,EAAE,WAAW,EAAE,MAAM,8BAA8B,CAAC;AAErE,OAAO,EAAE,8CAA8C,EAAE,MAAM,WAAW,CAAC;AAC3E,OAAO,EAAE,0BAA0B,EAAE,MAAM,yCAAyC,CAAC;AAGrF;;GAEG;AACH,MAAM,CAAC,MAAM,kDAAkD,GAAY,aAAa,CACtF,QAAQ,CAAC,8cAA8c,EAAE,CAAC,8CAA8C,EAAE,0BAA0B,CAAC,CAAC,CAAC;AAyFziB;;;GAGG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAAkC,aAAa,CACjF,WAAW,CAAC,kDAAkD,EAAE,CAAC,CAAC,CAAC"}

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

@@ -0,0 +1,413 @@
+/**
+ * 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 declare const AgentExecutionCommandController: {
+    readonly typeName: "ai.stigmer.agentic.agentexecution.v1.AgentExecutionCommandController";
+    readonly 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
+         */
+        readonly create: {
+            readonly name: "create";
+            readonly I: any;
+            readonly O: any;
+            readonly kind: any;
+        };
+        /**
+         * 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
+         */
+        readonly update: {
+            readonly name: "update";
+            readonly I: any;
+            readonly O: any;
+            readonly kind: any;
+        };
+        /**
+         * 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
+         */
+        readonly updateStatus: {
+            readonly name: "updateStatus";
+            readonly I: any;
+            readonly O: any;
+            readonly kind: any;
+        };
+        /**
+         * Delete an execution.
+         *
+         * @generated from rpc ai.stigmer.agentic.agentexecution.v1.AgentExecutionCommandController.delete
+         */
+        readonly delete: {
+            readonly name: "delete";
+            readonly I: any;
+            readonly O: any;
+            readonly kind: any;
+        };
+        /**
+         * 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
+         */
+        readonly submitApproval: {
+            readonly name: "submitApproval";
+            readonly I: any;
+            readonly O: any;
+            readonly kind: any;
+        };
+        /**
+         * 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
+         */
+        readonly cancel: {
+            readonly name: "cancel";
+            readonly I: any;
+            readonly O: any;
+            readonly kind: any;
+        };
+        /**
+         * 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
+         */
+        readonly terminate: {
+            readonly name: "terminate";
+            readonly I: any;
+            readonly O: any;
+            readonly kind: any;
+        };
+        /**
+         * 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
+         */
+        readonly recover: {
+            readonly name: "recover";
+            readonly I: any;
+            readonly O: any;
+            readonly kind: any;
+        };
+        /**
+         * 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
+         */
+        readonly pause: {
+            readonly name: "pause";
+            readonly I: any;
+            readonly O: any;
+            readonly kind: any;
+        };
+        /**
+         * 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
+         */
+        readonly resume: {
+            readonly name: "resume";
+            readonly I: any;
+            readonly O: any;
+            readonly kind: any;
+        };
+        /**
+         * 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
+         */
+        readonly uploadAttachment: {
+            readonly name: "uploadAttachment";
+            readonly I: any;
+            readonly O: any;
+            readonly kind: any;
+        };
+    };
+};