@stigmer/protos 0.0.34

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

@@ -0,0 +1,391 @@
+import type { GenFile, GenService } from "@bufbuild/protobuf/codegenv1";
+import type { WorkflowExecutionSchema } from "./api_pb";
+import type { ListWorkflowExecutionsByWorkflowRequestSchema, ListWorkflowExecutionsRequestSchema, SubscribeWorkflowExecutionRequestSchema, WorkflowExecutionIdSchema, WorkflowExecutionListSchema } from "./io_pb";
+/**
+ * Describes the file ai/stigmer/agentic/workflowexecution/v1/query.proto.
+ */
+export declare const file_ai_stigmer_agentic_workflowexecution_v1_query: GenFile;
+/**
+ * WorkflowExecutionQueryController handles read operations (Get, List, Subscribe) for WorkflowExecution resources.
+ *
+ * This service follows the Command-Query Separation (CQS) pattern:
+ * - CommandController: Write operations (create, update, delete)
+ * - QueryController: Read operations (get, list, search, subscribe)
+ *
+ * Authorization:
+ * - get: Standard authorization - user must have "get" permission on the specific WorkflowExecution
+ * - list: Custom authorization - filters results based on user's owner scope and permissions
+ * - list_by_workflow: Custom authorization - verifies user has access to the Workflow/WorkflowInstance
+ * - subscribe: Standard authorization - user must have "get" permission to subscribe to updates
+ *
+ * Service Options:
+ * - api_resource_kind: workflow_execution - Links this service to the WorkflowExecution resource
+ *
+ * @generated from service ai.stigmer.agentic.workflowexecution.v1.WorkflowExecutionQueryController
+ */
+export declare const WorkflowExecutionQueryController: GenService<{
+    /**
+     * Get a single workflow execution by ID.
+     *
+     * Retrieves the complete WorkflowExecution resource including:
+     * - spec: User inputs (workflow_instance_id, trigger_message, etc.)
+     * - status: Current execution state (phase, tasks, progress_events, output/error)
+     * - metadata: Resource identification (id, name, labels, tags)
+     *
+     * Authorization:
+     * Standard authorization checks that user has "get" permission on the WorkflowExecution.
+     * Permission is granted if:
+     * - User created the execution (metadata.audit.created_by matches user)
+     * - User has organization-level "workflow_execution:get" permission
+     * - User has explicit permission via IamPolicy
+     *
+     * Use Cases:
+     *
+     * 1. View Execution Details:
+     * - User clicks on an execution in the UI
+     * - UI calls get() to fetch full details
+     * - UI displays execution status, tasks, progress, output/error
+     *
+     * 2. Poll for Completion:
+     * - Client triggers execution via create()
+     * - Client periodically calls get() to check if phase is terminal
+     * - Client retrieves output when phase == EXECUTION_COMPLETED
+     *
+     * 3. Debug Failed Execution:
+     * - User sees execution failed
+     * - User calls get() to inspect status.error and status.tasks
+     * - User checks status.tasks[] for task-level execution details
+     *
+     * 4. Retry Failed Execution:
+     * - User calls get() to retrieve failed execution's spec
+     * - User creates new execution with same spec values
+     * - New execution retries with identical inputs
+     *
+     * Error Cases:
+     *
+     * - NOT_FOUND:
+     *   - No WorkflowExecution exists with the given ID
+     *
+     * - PERMISSION_DENIED:
+     *   - User doesn't have "get" permission on this WorkflowExecution
+     *   - WorkflowExecution belongs to different organization
+     *
+     * Example Request:
+     * {
+     *   "value": "wfx-abc123xyz456"
+     * }
+     *
+     * Example Response:
+     * {
+     *   "api_version": "agentic.stigmer.ai/v1",
+     *   "kind": "WorkflowExecution",
+     *   "metadata": {
+     *     "id": "wfx-abc123xyz456",
+     *     "name": "customer-onboarding-20250111-143022",
+     *     "org": "acme"
+     *   },
+     *   "spec": {
+     *     "workflow_instance_id": "wfi-customer-onboarding-prod",
+     *     "trigger_message": "New signup: john.doe@example.com"
+     *   },
+     *   "status": {
+     *     "phase": 2,  // EXECUTION_IN_PROGRESS
+     *     "total_tasks": 3,
+     *     "completed_tasks": 1,
+     *     "tasks": [ ... ],
+     *     "started_at": "2025-01-11T14:30:22Z"
+     *   }
+     * }
+     *
+     * @generated from rpc ai.stigmer.agentic.workflowexecution.v1.WorkflowExecutionQueryController.get
+     */
+    get: {
+        methodKind: "unary";
+        input: typeof WorkflowExecutionIdSchema;
+        output: typeof WorkflowExecutionSchema;
+    };
+    /**
+     * List workflow executions with pagination and optional filtering.
+     *
+     * Returns a paginated list of WorkflowExecution resources that the user has access to.
+     * Results are automatically filtered based on user's permissions and owner scope.
+     *
+     * Authorization:
+     * Custom authorization filters results to only include executions the user can access:
+     * - Organization users: Only executions in their organization
+     * - Users with cross-org access: Public executions from other orgs
+     *
+     * Pagination:
+     * - page_size: Maximum number of results to return (default: 50, max: 100)
+     * - page_token: Opaque token from previous response for next page
+     * - Returns total_pages count for UI pagination
+     *
+     * Filtering:
+     * - phase: Filter by execution phase (PENDING, IN_PROGRESS, COMPLETED, FAILED, CANCELLED)
+     * - tags: Filter by resource tags (AND logic - must match all tags)
+     *
+     * Sorting:
+     * Results are sorted by created_at descending (newest first).
+     *
+     * Use Cases:
+     *
+     * 1. Execution History Dashboard:
+     * - UI displays list of all recent executions
+     * - User can filter by status (show only failed, show only in-progress)
+     * - User can page through historical executions
+     *
+     * 2. Monitor Active Executions:
+     * - UI calls list(phase=EXECUTION_IN_PROGRESS) to show running executions
+     * - UI displays progress for each execution (completed_tasks / total_tasks)
+     * - UI refreshes list periodically to show updates
+     *
+     * 3. Audit and Compliance:
+     * - Admin lists all executions for a time period
+     * - Admin filters by tags (environment, team, project)
+     * - Admin exports execution history for audit logs
+     *
+     * 4. Debug and Troubleshooting:
+     * - Developer lists failed executions (phase=EXECUTION_FAILED)
+     * - Developer inspects error messages and retry patterns
+     * - Developer identifies systematic failures
+     *
+     * Error Cases:
+     *
+     * - INVALID_ARGUMENT:
+     *   - page_size is negative or exceeds maximum
+     *   - Invalid page_token (expired, corrupted)
+     *
+     * Example Request (Filter for failed executions):
+     * {
+     *   "page_size": 20,
+     *   "phase": 4,  // EXECUTION_FAILED
+     *   "tags": ["environment:production"]
+     * }
+     *
+     * Example Response:
+     * {
+     *   "total_pages": 3,
+     *   "entries": [
+     *     {
+     *       "metadata": { "id": "wfx-failed-1", ... },
+     *       "status": { "phase": 4, "error": "Task failed: API timeout", ... }
+     *     },
+     *     {
+     *       "metadata": { "id": "wfx-failed-2", ... },
+     *       "status": { "phase": 4, "error": "Task failed: Rate limit", ... }
+     *     }
+     *   ]
+     * }
+     *
+     * @generated from rpc ai.stigmer.agentic.workflowexecution.v1.WorkflowExecutionQueryController.list
+     */
+    list: {
+        methodKind: "unary";
+        input: typeof ListWorkflowExecutionsRequestSchema;
+        output: typeof WorkflowExecutionListSchema;
+    };
+    /**
+     * List all executions for a specific Workflow or WorkflowInstance.
+     *
+     * Returns executions filtered by a specific Workflow ID.
+     * This is useful for viewing execution history of a particular workflow.
+     *
+     * Authorization:
+     * Custom authorization verifies:
+     * 1. User has access to the referenced Workflow or WorkflowInstance
+     * 2. Results are filtered to only include executions user can access
+     *
+     * Pagination:
+     * - page_size: Maximum number of results to return (default: 50, max: 100)
+     * - page_token: Opaque token from previous response for next page
+     *
+     * Sorting:
+     * Results are sorted by created_at descending (newest first).
+     *
+     * Use Cases:
+     *
+     * 1. Workflow Execution History:
+     * - User views a Workflow in the UI
+     * - UI calls listByWorkflow(workflow_id) to show all executions
+     * - UI displays timeline of executions with success/failure indicators
+     *
+     * 2. Performance Analysis:
+     * - Developer wants to analyze workflow performance over time
+     * - Developer calls listByWorkflow() to get all executions
+     * - Developer calculates average duration, success rate, failure patterns
+     *
+     * 3. Retry Analysis:
+     * - User sees failed execution
+     * - User calls listByWorkflow() to see if other executions also failed
+     * - User determines if failure is systematic or one-off
+     *
+     * 4. Workflow Testing:
+     * - Developer tests a workflow with multiple executions
+     * - Developer calls listByWorkflow() to see all test runs
+     * - Developer compares outputs across executions
+     *
+     * Error Cases:
+     *
+     * - INVALID_ARGUMENT:
+     *   - workflow_id is empty or invalid format
+     *   - page_size is negative or exceeds maximum
+     *
+     * - PERMISSION_DENIED:
+     *   - User doesn't have access to the referenced Workflow/WorkflowInstance
+     *
+     * - NOT_FOUND:
+     *   - No Workflow or WorkflowInstance exists with the given ID
+     *
+     * Example Request:
+     * {
+     *   "workflow_id": "wfi-customer-onboarding-prod",
+     *   "page_size": 50
+     * }
+     *
+     * Example Response:
+     * {
+     *   "total_pages": 5,
+     *   "entries": [
+     *     {
+     *       "metadata": { "id": "wfx-latest", "created_at": "2025-01-11T14:30:22Z" },
+     *       "status": { "phase": 3, ... }  // COMPLETED
+     *     },
+     *     {
+     *       "metadata": { "id": "wfx-previous", "created_at": "2025-01-11T10:15:00Z" },
+     *       "status": { "phase": 4, ... }  // FAILED
+     *     }
+     *   ]
+     * }
+     *
+     * @generated from rpc ai.stigmer.agentic.workflowexecution.v1.WorkflowExecutionQueryController.listByWorkflow
+     */
+    listByWorkflow: {
+        methodKind: "unary";
+        input: typeof ListWorkflowExecutionsByWorkflowRequestSchema;
+        output: typeof WorkflowExecutionListSchema;
+    };
+    /**
+     * Subscribe to real-time updates for a specific workflow execution (server streaming).
+     *
+     * Opens a bidirectional stream that pushes WorkflowExecution updates as they occur.
+     * Client receives updates when:
+     * - Execution phase changes (PENDING → IN_PROGRESS → COMPLETED)
+     * - Tasks start or complete
+     * - Progress events are appended
+     * - Output or error fields are set
+     *
+     * Authorization:
+     * Standard authorization checks that user has "get" permission on the WorkflowExecution.
+     * This is the same permission check as get() RPC.
+     *
+     * Stream Lifecycle:
+     * 1. Client sends SubscribeWorkflowExecutionRequest with execution_id
+     * 2. Server validates authorization
+     * 3. Server sends initial WorkflowExecution (current state)
+     * 4. Server streams updates as execution progresses
+     * 5. Server closes stream when execution reaches terminal state (COMPLETED/FAILED/CANCELLED)
+     * 6. Client can close stream early (e.g., user navigates away from page)
+     *
+     * Update Frequency:
+     * - Updates are sent immediately when execution state changes
+     * - No polling necessary (server pushes updates)
+     * - Typical update latency: < 100ms
+     *
+     * Use Cases:
+     *
+     * 1. Real-Time Progress Monitoring:
+     * - User triggers an execution from UI
+     * - UI subscribes to execution updates
+     * - UI displays live progress: tasks completing, progress bar updating
+     * - UI shows final output when execution completes
+     *
+     * 2. Long-Running Workflow Monitoring:
+     * - Workflow takes hours to complete (e.g., data processing)
+     * - UI subscribes and shows live progress
+     * - User can leave page, come back, and reconnect to same execution
+     *
+     * 3. Debugging with Live Updates:
+     * - Developer triggers test execution
+     * - Developer subscribes to watch execution progress
+     * - Developer sees exactly which task is running and when failures occur
+     *
+     * 4. Multi-User Collaboration:
+     * - Multiple users watching same execution
+     * - All users receive same updates simultaneously
+     * - All users see consistent view of execution state
+     *
+     * Stream Message Format:
+     * Each message is a complete WorkflowExecution resource with updated status.
+     *
+     * Error Cases:
+     *
+     * - NOT_FOUND:
+     *   - No WorkflowExecution exists with the given ID
+     *
+     * - PERMISSION_DENIED:
+     *   - User doesn't have "get" permission on this WorkflowExecution
+     *
+     * - DEADLINE_EXCEEDED:
+     *   - Client timeout (client should reconnect)
+     *
+     * - UNAVAILABLE:
+     *   - Server unavailable (client should retry with backoff)
+     *
+     * Example Request:
+     * {
+     *   "execution_id": "wfx-abc123xyz456"
+     * }
+     *
+     * Example Stream (sequence of messages):
+     *
+     * Message 1 (initial state):
+     * {
+     *   "metadata": { "id": "wfx-abc123xyz456" },
+     *   "status": {
+     *     "phase": 1,  // EXECUTION_PENDING
+     *     "total_tasks": 3,
+     *     "completed_tasks": 0
+     *   }
+     * }
+     *
+     * Message 2 (execution started):
+     * {
+     *   "metadata": { "id": "wfx-abc123xyz456" },
+     *   "status": {
+     *     "phase": 2,  // EXECUTION_IN_PROGRESS
+     *     "started_at": "2025-01-11T14:30:22Z"
+     *   }
+     * }
+     *
+     * Message 3 (task 1 completed):
+     * {
+     *   "metadata": { "id": "wfx-abc123xyz456" },
+     *   "status": {
+     *     "phase": 2,  // EXECUTION_IN_PROGRESS
+     *     "completed_tasks": 1,
+     *     "tasks": [
+     *       { "task_id": "task-1", "status": 3, "output": { ... } }
+     *     ]
+     *   }
+     * }
+     *
+     * Message 4 (execution completed):
+     * {
+     *   "metadata": { "id": "wfx-abc123xyz456" },
+     *   "status": {
+     *     "phase": 3,  // EXECUTION_COMPLETED
+     *     "completed_tasks": 3,
+     *     "output": { ... },
+     *     "completed_at": "2025-01-11T14:35:47Z"
+     *   }
+     * }
+     * [Stream closes]
+     *
+     * @generated from rpc ai.stigmer.agentic.workflowexecution.v1.WorkflowExecutionQueryController.subscribe
+     */
+    subscribe: {
+        methodKind: "server_streaming";
+        input: typeof SubscribeWorkflowExecutionRequestSchema;
+        output: typeof WorkflowExecutionSchema;
+    };
+}>;

package/ai/stigmer/agentic/workflowexecution/v1/query_pb.js

@@ -0,0 +1,32 @@
+// @generated by protoc-gen-es v2.2.2 with parameter "target=ts"
+// @generated from file ai/stigmer/agentic/workflowexecution/v1/query.proto (package ai.stigmer.agentic.workflowexecution.v1, syntax proto3)
+/* eslint-disable */
+import { fileDesc, serviceDesc } from "@bufbuild/protobuf/codegenv1";
+import { file_ai_stigmer_agentic_workflowexecution_v1_api } from "./api_pb";
+import { file_ai_stigmer_agentic_workflowexecution_v1_io } from "./io_pb";
+import { file_ai_stigmer_commons_apiresource_rpc_service_options } from "../../../commons/apiresource/rpc_service_options_pb";
+import { file_ai_stigmer_iam_iampolicy_v1_rpcauthorization_method_options } from "../../../iam/iampolicy/v1/rpcauthorization/method_options_pb";
+/**
+ * Describes the file ai/stigmer/agentic/workflowexecution/v1/query.proto.
+ */
+export const file_ai_stigmer_agentic_workflowexecution_v1_query = /*@__PURE__*/ fileDesc("CjNhaS9zdGlnbWVyL2FnZW50aWMvd29ya2Zsb3dleGVjdXRpb24vdjEvcXVlcnkucHJvdG8SJ2FpLnN0aWdtZXIuYWdlbnRpYy53b3JrZmxvd2V4ZWN1dGlvbi52MTKEBgogV29ya2Zsb3dFeGVjdXRpb25RdWVyeUNvbnRyb2xsZXISuAEKA2dldBI8LmFpLnN0aWdtZXIuYWdlbnRpYy53b3JrZmxvd2V4ZWN1dGlvbi52MS5Xb3JrZmxvd0V4ZWN1dGlvbklkGjouYWkuc3RpZ21lci5hZ2VudGljLndvcmtmbG93ZXhlY3V0aW9uLnYxLldvcmtmbG93RXhlY3V0aW9uIjfCuBgzCAMQNCIFdmFsdWUqJnVuYXV0aG9yaXplZCB0byBnZXQgd29ya2Zsb3cgZXhlY3V0aW9uEpQBCgRsaXN0EkYuYWkuc3RpZ21lci5hZ2VudGljLndvcmtmbG93ZXhlY3V0aW9uLnYxLkxpc3RXb3JrZmxvd0V4ZWN1dGlvbnNSZXF1ZXN0Gj4uYWkuc3RpZ21lci5hZ2VudGljLndvcmtmbG93ZXhlY3V0aW9uLnYxLldvcmtmbG93RXhlY3V0aW9uTGlzdCIE0LgYARKoAQoObGlzdEJ5V29ya2Zsb3cSUC5haS5zdGlnbWVyLmFnZW50aWMud29ya2Zsb3dleGVjdXRpb24udjEuTGlzdFdvcmtmbG93RXhlY3V0aW9uc0J5V29ya2Zsb3dSZXF1ZXN0Gj4uYWkuc3RpZ21lci5hZ2VudGljLndvcmtmbG93ZXhlY3V0aW9uLnYxLldvcmtmbG93RXhlY3V0aW9uTGlzdCIE0LgYARLcAQoJc3Vic2NyaWJlEkouYWkuc3RpZ21lci5hZ2VudGljLndvcmtmbG93ZXhlY3V0aW9uLnYxLlN1YnNjcmliZVdvcmtmbG93RXhlY3V0aW9uUmVxdWVzdBo6LmFpLnN0aWdtZXIuYWdlbnRpYy53b3JrZmxvd2V4ZWN1dGlvbi52MS5Xb3JrZmxvd0V4ZWN1dGlvbiJFwrgYQQgDEDQiDGV4ZWN1dGlvbl9pZCotdW5hdXRob3JpemVkIHRvIGdldCB3b3JrZmxvdyBleGVjdXRpb24gc3RyZWFtMAEaBKD/KzRiBnByb3RvMw", [file_ai_stigmer_agentic_workflowexecution_v1_api, file_ai_stigmer_agentic_workflowexecution_v1_io, file_ai_stigmer_commons_apiresource_rpc_service_options, file_ai_stigmer_iam_iampolicy_v1_rpcauthorization_method_options]);
+/**
+ * WorkflowExecutionQueryController handles read operations (Get, List, Subscribe) for WorkflowExecution resources.
+ *
+ * This service follows the Command-Query Separation (CQS) pattern:
+ * - CommandController: Write operations (create, update, delete)
+ * - QueryController: Read operations (get, list, search, subscribe)
+ *
+ * Authorization:
+ * - get: Standard authorization - user must have "get" permission on the specific WorkflowExecution
+ * - list: Custom authorization - filters results based on user's owner scope and permissions
+ * - list_by_workflow: Custom authorization - verifies user has access to the Workflow/WorkflowInstance
+ * - subscribe: Standard authorization - user must have "get" permission to subscribe to updates
+ *
+ * Service Options:
+ * - api_resource_kind: workflow_execution - Links this service to the WorkflowExecution resource
+ *
+ * @generated from service ai.stigmer.agentic.workflowexecution.v1.WorkflowExecutionQueryController
+ */
+export const WorkflowExecutionQueryController = /*@__PURE__*/ serviceDesc(file_ai_stigmer_agentic_workflowexecution_v1_query, 0);
+//# sourceMappingURL=query_pb.js.map

package/ai/stigmer/agentic/workflowexecution/v1/query_pb.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"query_pb.js","sourceRoot":"","sources":["../../../../../../ai/stigmer/agentic/workflowexecution/v1/query_pb.ts"],"names":[],"mappings":"AAAA,gEAAgE;AAChE,4IAA4I;AAC5I,oBAAoB;AAGpB,OAAO,EAAE,QAAQ,EAAE,WAAW,EAAE,MAAM,8BAA8B,CAAC;AAErE,OAAO,EAAE,gDAAgD,EAAE,MAAM,UAAU,CAAC;AAE5E,OAAO,EAAE,+CAA+C,EAAE,MAAM,SAAS,CAAC;AAC1E,OAAO,EAAE,uDAAuD,EAAE,MAAM,qDAAqD,CAAC;AAC9H,OAAO,EAAE,gEAAgE,EAAE,MAAM,8DAA8D,CAAC;AAEhJ;;GAEG;AACH,MAAM,CAAC,MAAM,kDAAkD,GAAY,aAAa,CACtF,QAAQ,CAAC,opCAAopC,EAAE,CAAC,gDAAgD,EAAE,+CAA+C,EAAE,uDAAuD,EAAE,gEAAgE,CAAC,CAAC,CAAC;AAEj4C;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,CAAC,MAAM,gCAAgC,GA6WxC,aAAa,CAChB,WAAW,CAAC,kDAAkD,EAAE,CAAC,CAAC,CAAC"}