@stigmer/protos 0.0.68 → 0.0.70

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

@@ -73,13 +73,19 @@ export type AgentExecutionSpec = Message<"ai.stigmer.agentic.agentexecution.v1.A
         [key: string]: ExecutionValue;
     };
     /**
-     * Temporal task token for async activity completion (optional).
+     * Callback token for async activity completion (optional).
      *
-     * **Purpose**: Enables async activity completion pattern where the caller
-     * (typically a Zigflow workflow activity) waits for actual agent completion
-     * without blocking worker threads.
+     * When a workflow invokes an agent, this token enables the workflow to
+     * wait for the agent to finish without blocking. When empty, the
+     * execution runs independently (CLI, API calls, non-workflow triggers).
      *
-     * **Flow**:
+     * @internal
+     *
+     * Enables async completion pattern where the caller (typically a
+     * workflow activity) waits for actual agent completion without blocking
+     * worker threads.
+     *
+     * Flow:
      * 1. Caller (Go Temporal activity) extracts its task token
      * 2. Passes token in this field when creating AgentExecution
      * 3. Returns activity.ErrResultPending (activity paused, thread released)
@@ -87,82 +93,39 @@ export type AgentExecutionSpec = Message<"ai.stigmer.agentic.agentexecution.v1.A
      * 5. Agent workflow calls ActivityCompletionClient.complete(token, result)
      * 6. Temporal resumes the paused activity with the result
      *
-     * **Benefits**:
-     * - Correctness: Caller waits for actual completion, not just ACK
-     * - Scalability: Worker threads not blocked during long-running execution
-     * - Resilience: Token is durable in Temporal; survives restarts
-     * - Decoupling: Caller doesn't poll or manage agent lifecycle
-     *
-     * **When Empty**:
-     * - Empty/null = fire-and-forget or direct API call (backward compatible)
-     * - Agent execution proceeds normally, no callback performed
-     * - Use case: CLI commands, API requests, non-workflow triggers
-     *
-     * **When Provided**:
-     * - Agent workflow MUST complete the external activity using this token
-     * - Both success and failure paths must call completion
-     * - Token uniquely identifies the external activity execution
-     *
-     * **Token Format**:
+     * Token Format:
      * - Opaque binary blob from Temporal SDK (typically 100-200 bytes)
      * - Contains: namespace, workflow ID, run ID, activity ID, attempt
      * - DO NOT parse or modify - treat as opaque handle
      *
-     * **Security**:
+     * Security:
      * - Token grants ability to complete the activity (bearer token)
      * - Should only be passed through trusted internal services
      * - Logged as Base64-encoded string (truncated for security)
      *
-     * **Timeout**:
+     * Timeout:
      * - Caller should set StartToCloseTimeout (e.g., 24 hours)
      * - If token callback never arrives, activity times out
-     * - Prevents infinite hangs if agent workflow crashes
-     *
-     * **Observability**:
-     * - Token is logged at creation time (Base64, first 20 chars)
-     * - Activity appears as "Running" in Temporal UI until completed
-     * - Both caller workflow and agent workflow visible in Temporal
      *
-     * **Example Usage (Go)**:
+     * Example Usage (Go):
      * ```go
-     * // In Zigflow workflow activity
      * func CallAgentActivity(ctx context.Context, config *AgentCallTaskConfig) {
-     *     // Extract task token
      *     taskToken := activity.GetInfo(ctx).TaskToken
-     *
-     *     // Create agent execution with token
      *     execution := &AgentExecution{
      *         Spec: &AgentExecutionSpec{
      *             AgentId: config.Agent,
      *             Message: config.Message,
-     *             CallbackToken: taskToken,  // 👈 Pass token here
+     *             CallbackToken: taskToken,
      *         },
      *     }
-     *
      *     client.Create(ctx, execution)
-     *
-     *     // Return pending - activity paused, thread released
      *     return nil, activity.ErrResultPending
      * }
      * ```
      *
-     * **Example Usage (Java Completion)**:
-     * ```java
-     * // In agent workflow (after completion)
-     * if (spec.getCallbackToken() != null && !spec.getCallbackToken().isEmpty()) {
-     *     // Complete the external activity
-     *     systemActivities.completeZigflowToken(
-     *         spec.getCallbackToken(),
-     *         result
-     *     );
-     * }
-     * ```
-     *
-     * **References**:
+     * References:
      * - ADR: docs/adr/20260122-async-agent-execution-temporal-token-handshake.md
      * - Temporal Docs: https://docs.temporal.io/activities#asynchronous-activity-completion
-     * - Go SDK: https://pkg.go.dev/go.temporal.io/sdk/activity#ErrResultPending
-     * - Java SDK: https://www.javadoc.io/doc/io.temporal/temporal-sdk/latest/io/temporal/client/ActivityCompletionClient.html
      *
      * @since 2026-01-22 (Phase 2: Async Agent Execution Integration)
      *
@@ -193,31 +156,24 @@ export type AgentExecutionSpec = Message<"ai.stigmer.agentic.agentexecution.v1.A
      */
     autoApproveAll: boolean;
     /**
-     * Parent workflow context for events-based approval notification (optional).
+     * Parent workflow ID when this execution was triggered by a workflow (optional).
      *
-     * When a workflow invokes an agent via CallAgentActivity, this field captures
-     * the parent workflow's Temporal workflow ID. This enables the agent execution
-     * workflow to signal the parent when approval is required, eliminating polling.
+     * When set, the platform notifies the parent workflow about approval
+     * requests instead of requiring polling. When empty, approvals are
+     * submitted directly via the SubmitApproval RPC.
      *
-     * ## Signal Pattern
+     * @internal
      *
+     * Signal Pattern:
      * 1. Go workflow passes its workflow ID when creating AgentExecution
      * 2. Go workflow starts signal listener for "child_approval_required"
      * 3. When agent enters WAITING_FOR_APPROVAL, Java sends signal to parent
      * 4. Go workflow receives signal, updates task status to WAITING_APPROVAL
      *
-     * ## Format
-     *
+     * Format:
      * Temporal workflow ID, typically: "stigmer/workflow-execution/invoke/{execution-id}"
-     * Example: "stigmer/workflow-execution/invoke/wfx-abc123xyz456"
-     *
-     * ## When Empty
-     *
-     * - Agent invoked directly (not from workflow) - no parent to notify
-     * - Older clients that don't support this field - fallback to direct approval
-     *
-     * ## Backward Compatibility
      *
+     * Backward Compatibility:
      * This field is optional. Agents invoked without a parent workflow ID will
      * continue to work normally - approval is submitted directly via the
      * AgentExecution.SubmitApproval RPC.
@@ -484,8 +440,7 @@ export declare const ContextManagementConfigSchema: GenMessage<ContextManagement
  * Attachment represents a file attached to an agent execution.
  *
  * All files must be pre-uploaded via the uploadAttachment RPC and referenced
- * by storage_key. This ensures consistent behavior regardless of file size
- * and avoids Temporal payload limits (2MB).
+ * by storage_key. This ensures consistent behavior regardless of file size.
  *
  * ## Usage Flow
  *

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

@@ -1 +1 @@
-{"version":3,"file":"spec_pb.js","sourceRoot":"","sources":["../../../../../../ai/stigmer/agentic/agentexecution/v1/spec_pb.ts"],"names":[],"mappings":"AAAA,gEAAgE;AAChE,qIAAqI;AACrI,oBAAoB;AAGpB,OAAO,EAAE,QAAQ,EAAE,WAAW,EAAE,MAAM,8BAA8B,CAAC;AAErE,OAAO,EAAE,gDAAgD,EAAE,MAAM,mCAAmC,CAAC;AACrG,OAAO,EAAE,0BAA0B,EAAE,MAAM,yCAAyC,CAAC;AAGrF;;GAEG;AACH,MAAM,CAAC,MAAM,8CAA8C,GAAY,aAAa,CAClF,QAAQ,CAAC,w/CAAw/C,EAAE,CAAC,gDAAgD,EAAE,0BAA0B,CAAC,CAAC,CAAC;AAqRrlD;;;GAGG;AACH,MAAM,CAAC,MAAM,wBAAwB,GAAmC,aAAa,CACnF,WAAW,CAAC,8CAA8C,EAAE,CAAC,CAAC,CAAC;AAuGjE;;;GAGG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAgC,aAAa,CAC7E,WAAW,CAAC,8CAA8C,EAAE,CAAC,CAAC,CAAC;AAsGjE;;;GAGG;AACH,MAAM,CAAC,MAAM,6BAA6B,GAAwC,aAAa,CAC7F,WAAW,CAAC,8CAA8C,EAAE,CAAC,CAAC,CAAC;AA6FjE;;;GAGG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAA2B,aAAa,CACnE,WAAW,CAAC,8CAA8C,EAAE,CAAC,CAAC,CAAC"}
+{"version":3,"file":"spec_pb.js","sourceRoot":"","sources":["../../../../../../ai/stigmer/agentic/agentexecution/v1/spec_pb.ts"],"names":[],"mappings":"AAAA,gEAAgE;AAChE,qIAAqI;AACrI,oBAAoB;AAGpB,OAAO,EAAE,QAAQ,EAAE,WAAW,EAAE,MAAM,8BAA8B,CAAC;AAErE,OAAO,EAAE,gDAAgD,EAAE,MAAM,mCAAmC,CAAC;AACrG,OAAO,EAAE,0BAA0B,EAAE,MAAM,yCAAyC,CAAC;AAGrF;;GAEG;AACH,MAAM,CAAC,MAAM,8CAA8C,GAAY,aAAa,CAClF,QAAQ,CAAC,w/CAAw/C,EAAE,CAAC,gDAAgD,EAAE,0BAA0B,CAAC,CAAC,CAAC;AAyOrlD;;;GAGG;AACH,MAAM,CAAC,MAAM,wBAAwB,GAAmC,aAAa,CACnF,WAAW,CAAC,8CAA8C,EAAE,CAAC,CAAC,CAAC;AAuGjE;;;GAGG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAgC,aAAa,CAC7E,WAAW,CAAC,8CAA8C,EAAE,CAAC,CAAC,CAAC;AAsGjE;;;GAGG;AACH,MAAM,CAAC,MAAM,6BAA6B,GAAwC,aAAa,CAC7F,WAAW,CAAC,8CAA8C,EAAE,CAAC,CAAC,CAAC;AA4FjE;;;GAGG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAA2B,aAAa,CACnE,WAAW,CAAC,8CAA8C,EAAE,CAAC,CAAC,CAAC"}

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

@@ -105,6 +105,8 @@ export declare const WorkspaceWriteBackSchema: GenMessage<WorkspaceWriteBack>;
  */
 export declare enum WorkspaceWriteBackPhase {
     /**
+     * Default value, not a valid write-back phase.
+     *
      * @generated from enum value: WORKSPACE_WRITE_BACK_PHASE_UNSPECIFIED = 0;
      */
     WORKSPACE_WRITE_BACK_PHASE_UNSPECIFIED = 0,

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

@@ -23,6 +23,8 @@ export const WorkspaceWriteBackSchema = /*@__PURE__*/ messageDesc(file_ai_stigme
 export var WorkspaceWriteBackPhase;
 (function (WorkspaceWriteBackPhase) {
     /**
+     * Default value, not a valid write-back phase.
+     *
      * @generated from enum value: WORKSPACE_WRITE_BACK_PHASE_UNSPECIFIED = 0;
      */
     WorkspaceWriteBackPhase[WorkspaceWriteBackPhase["WORKSPACE_WRITE_BACK_PHASE_UNSPECIFIED"] = 0] = "WORKSPACE_WRITE_BACK_PHASE_UNSPECIFIED";

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

@@ -1 +1 @@
-{"version":3,"file":"writeback_pb.js","sourceRoot":"","sources":["../../../../../../ai/stigmer/agentic/agentexecution/v1/writeback_pb.ts"],"names":[],"mappings":"AAAA,gEAAgE;AAChE,0IAA0I;AAC1I,oBAAoB;AAGpB,OAAO,EAAE,QAAQ,EAAE,QAAQ,EAAE,WAAW,EAAE,MAAM,8BAA8B,CAAC;AAG/E;;GAEG;AACH,MAAM,CAAC,MAAM,mDAAmD,GAAY,aAAa,CACvF,QAAQ,CAAC,6xBAA6xB,CAAC,CAAC;AAgG1yB;;;GAGG;AACH,MAAM,CAAC,MAAM,wBAAwB,GAAmC,aAAa,CACnF,WAAW,CAAC,mDAAmD,EAAE,CAAC,CAAC,CAAC;AAEtE;;;;;;;;GAQG;AACH,MAAM,CAAN,IAAY,uBAiCX;AAjCD,WAAY,uBAAuB;IACjC;;OAEG;IACH,yIAA0C,CAAA;IAE1C;;;;OAIG;IACH,yHAAkC,CAAA;IAElC;;;;OAIG;IACH,mHAA+B,CAAA;IAE/B;;;;OAIG;IACH,2HAAmC,CAAA;IAEnC;;;;OAIG;IACH,mHAA+B,CAAA;AACjC,CAAC,EAjCW,uBAAuB,KAAvB,uBAAuB,QAiClC;AAED;;GAEG;AACH,MAAM,CAAC,MAAM,6BAA6B,GAAqC,aAAa,CAC1F,QAAQ,CAAC,mDAAmD,EAAE,CAAC,CAAC,CAAC"}
+{"version":3,"file":"writeback_pb.js","sourceRoot":"","sources":["../../../../../../ai/stigmer/agentic/agentexecution/v1/writeback_pb.ts"],"names":[],"mappings":"AAAA,gEAAgE;AAChE,0IAA0I;AAC1I,oBAAoB;AAGpB,OAAO,EAAE,QAAQ,EAAE,QAAQ,EAAE,WAAW,EAAE,MAAM,8BAA8B,CAAC;AAG/E;;GAEG;AACH,MAAM,CAAC,MAAM,mDAAmD,GAAY,aAAa,CACvF,QAAQ,CAAC,6xBAA6xB,CAAC,CAAC;AAgG1yB;;;GAGG;AACH,MAAM,CAAC,MAAM,wBAAwB,GAAmC,aAAa,CACnF,WAAW,CAAC,mDAAmD,EAAE,CAAC,CAAC,CAAC;AAEtE;;;;;;;;GAQG;AACH,MAAM,CAAN,IAAY,uBAmCX;AAnCD,WAAY,uBAAuB;IACjC;;;;OAIG;IACH,yIAA0C,CAAA;IAE1C;;;;OAIG;IACH,yHAAkC,CAAA;IAElC;;;;OAIG;IACH,mHAA+B,CAAA;IAE/B;;;;OAIG;IACH,2HAAmC,CAAA;IAEnC;;;;OAIG;IACH,mHAA+B,CAAA;AACjC,CAAC,EAnCW,uBAAuB,KAAvB,uBAAuB,QAmClC;AAED;;GAEG;AACH,MAAM,CAAC,MAAM,6BAA6B,GAAqC,aAAa,CAC1F,QAAQ,CAAC,mDAAmD,EAAE,CAAC,CAAC,CAAC"}

package/ai/stigmer/agentic/agentinstance/v1/api_pb.d.ts

@@ -8,7 +8,10 @@ import type { Message } from "@bufbuild/protobuf";
  */
 export declare const file_ai_stigmer_agentic_agentinstance_v1_api: GenFile;
 /**
- * AgentInstance represents a configured deployment of an Agent template.
+ * AgentInstance defines a configured deployment of an Agent template.
+ *
+ * @internal
+ * Uses Graphton configuration for state management.
  *
  * @generated from message ai.stigmer.agentic.agentinstance.v1.AgentInstance
  */
@@ -26,20 +29,22 @@ export type AgentInstance = Message<"ai.stigmer.agentic.agentinstance.v1.AgentIn
      */
     kind: string;
     /**
-     * Standard resource metadata including name, id, labels, and tags.
+     * Resource metadata including name, organization, scope, and labels.
+     *
+     * @internal
      * AgentInstances can have platform, organization, or identity_account scope.
      *
      * @generated from field: ai.stigmer.commons.apiresource.ApiResourceMetadata metadata = 3;
      */
     metadata?: ApiResourceMetadata;
     /**
-     * Spec defining the instance configuration.
+     * Configurable properties: agent binding, description, and environment references.
      *
      * @generated from field: ai.stigmer.agentic.agentinstance.v1.AgentInstanceSpec spec = 4;
      */
     spec?: AgentInstanceSpec;
     /**
-     * Status of the instance.
+     * System-managed audit trail including creation and update timestamps.
      *
      * @generated from field: ai.stigmer.commons.apiresource.ApiResourceAuditStatus status = 5;
      */

package/ai/stigmer/agentic/agentinstance/v1/api_pb.js.map

@@ -1 +1 @@
-{"version":3,"file":"api_pb.js","sourceRoot":"","sources":["../../../../../../ai/stigmer/agentic/agentinstance/v1/api_pb.ts"],"names":[],"mappings":"AAAA,gEAAgE;AAChE,kIAAkI;AAClI,oBAAoB;AAGpB,OAAO,EAAE,QAAQ,EAAE,WAAW,EAAE,MAAM,8BAA8B,CAAC;AAErE,OAAO,EAAE,6CAA6C,EAAE,MAAM,WAAW,CAAC;AAE1E,OAAO,EAAE,4CAA4C,EAAE,MAAM,0CAA0C,CAAC;AAExG,OAAO,EAAE,0CAA0C,EAAE,MAAM,wCAAwC,CAAC;AACpG,OAAO,EAAE,0BAA0B,EAAE,MAAM,yCAAyC,CAAC;AAGrF;;GAEG;AACH,MAAM,CAAC,MAAM,4CAA4C,GAAY,aAAa,CAChF,QAAQ,CAAC,gjBAAgjB,EAAE,CAAC,6CAA6C,EAAE,4CAA4C,EAAE,0CAA0C,EAAE,0BAA0B,CAAC,CAAC,CAAC;AA6CpuB;;;GAGG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAA8B,aAAa,CACzE,WAAW,CAAC,4CAA4C,EAAE,CAAC,CAAC,CAAC"}
+{"version":3,"file":"api_pb.js","sourceRoot":"","sources":["../../../../../../ai/stigmer/agentic/agentinstance/v1/api_pb.ts"],"names":[],"mappings":"AAAA,gEAAgE;AAChE,kIAAkI;AAClI,oBAAoB;AAGpB,OAAO,EAAE,QAAQ,EAAE,WAAW,EAAE,MAAM,8BAA8B,CAAC;AAErE,OAAO,EAAE,6CAA6C,EAAE,MAAM,WAAW,CAAC;AAE1E,OAAO,EAAE,4CAA4C,EAAE,MAAM,0CAA0C,CAAC;AAExG,OAAO,EAAE,0CAA0C,EAAE,MAAM,wCAAwC,CAAC;AACpG,OAAO,EAAE,0BAA0B,EAAE,MAAM,yCAAyC,CAAC;AAGrF;;GAEG;AACH,MAAM,CAAC,MAAM,4CAA4C,GAAY,aAAa,CAChF,QAAQ,CAAC,gjBAAgjB,EAAE,CAAC,6CAA6C,EAAE,4CAA4C,EAAE,0CAA0C,EAAE,0BAA0B,CAAC,CAAC,CAAC;AAkDpuB;;;GAGG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAA8B,aAAa,CACzE,WAAW,CAAC,4CAA4C,EAAE,CAAC,CAAC,CAAC"}

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

@@ -1,6 +1,5 @@
 /**
  * AgentInstanceCommandController handles write operations for agent instances.
- * Follows the standard pattern: create, update, delete (no granular field updates).
  *
  * @generated from service ai.stigmer.agentic.agentinstance.v1.AgentInstanceCommandController
  */
@@ -9,6 +8,8 @@ export declare const AgentInstanceCommandController: {
     readonly methods: {
         /**
          * Create or update an agent instance.
+         *
+         * @internal
          * The authorization and state-operation are determined depending on whether the agent instance
          * is going to be created or updated which is determined as part of the request execution.
          *
@@ -21,14 +22,14 @@ export declare const AgentInstanceCommandController: {
             readonly kind: any;
         };
         /**
-         * Create a new agent instance with full state.
-         * Provide organization_id in metadata.org, and complete spec with configuration and secrets.
+         * Create an agent instance.
          *
-         * Authorization: FGA can_create_instance on parent agent (handler-level)
-         * - Checks can_create_instance on parent agent (via spec.agent_id)
-         * - Public agents: Any authenticated user can create instances (cross-org allowed)
-         * - Private agents: Only org members and agent owner can create instances
+         * Public agents allow any authenticated user to create instances (cross-org allowed).
+         * Private agents restrict instance creation to org members and the agent owner.
          *
+         * @internal
+         * Provide organization_id in metadata.org, and complete spec with configuration and secrets.
+         * Authorization: FGA can_create_instance on parent agent (handler-level).
          * FGA is the single source of truth — no hardcoded org-matching rules.
          * Agents are blueprints with zero secrets; instances are personal resources in the caller's org.
          *
@@ -41,10 +42,12 @@ export declare const AgentInstanceCommandController: {
             readonly kind: any;
         };
         /**
-         * Update an instance with full state.
-         * Used to update entire instance configuration including metadata, spec, and secrets.
-         * No individual field updates - always provide complete state.
-         * Authorization: Only owner can update (can_edit permission)
+         * Update an existing agent instance.
+         *
+         * @internal
+         * Replaces the entire instance configuration including metadata, spec, and secrets.
+         * No individual field updates — always provide complete state.
+         * Authorization: Only owner can update (can_edit permission).
          *
          * @generated from rpc ai.stigmer.agentic.agentinstance.v1.AgentInstanceCommandController.update
          */
@@ -56,7 +59,9 @@ export declare const AgentInstanceCommandController: {
         };
         /**
          * Delete an agent instance.
-         * Authorization: Only owner can delete (can_delete permission)
+         *
+         * @internal
+         * Authorization: Only owner can delete (can_delete permission).
          *
          * @generated from rpc ai.stigmer.agentic.agentinstance.v1.AgentInstanceCommandController.delete
          */

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

@@ -5,7 +5,6 @@
 import { MethodKind } from "@bufbuild/protobuf";
 /**
  * AgentInstanceCommandController handles write operations for agent instances.
- * Follows the standard pattern: create, update, delete (no granular field updates).
  *
  * @generated from service ai.stigmer.agentic.agentinstance.v1.AgentInstanceCommandController
  */
@@ -14,6 +13,8 @@ export const AgentInstanceCommandController = {
     methods: {
         /**
          * Create or update an agent instance.
+         *
+         * @internal
          * The authorization and state-operation are determined depending on whether the agent instance
          * is going to be created or updated which is determined as part of the request execution.
          *
@@ -26,14 +27,14 @@ export const AgentInstanceCommandController = {
             kind: MethodKind.Unary,
         },
         /**
-         * Create a new agent instance with full state.
-         * Provide organization_id in metadata.org, and complete spec with configuration and secrets.
+         * Create an agent instance.
          *
-         * Authorization: FGA can_create_instance on parent agent (handler-level)
-         * - Checks can_create_instance on parent agent (via spec.agent_id)
-         * - Public agents: Any authenticated user can create instances (cross-org allowed)
-         * - Private agents: Only org members and agent owner can create instances
+         * Public agents allow any authenticated user to create instances (cross-org allowed).
+         * Private agents restrict instance creation to org members and the agent owner.
          *
+         * @internal
+         * Provide organization_id in metadata.org, and complete spec with configuration and secrets.
+         * Authorization: FGA can_create_instance on parent agent (handler-level).
          * FGA is the single source of truth — no hardcoded org-matching rules.
          * Agents are blueprints with zero secrets; instances are personal resources in the caller's org.
          *
@@ -46,10 +47,12 @@ export const AgentInstanceCommandController = {
             kind: MethodKind.Unary,
         },
         /**
-         * Update an instance with full state.
-         * Used to update entire instance configuration including metadata, spec, and secrets.
-         * No individual field updates - always provide complete state.
-         * Authorization: Only owner can update (can_edit permission)
+         * Update an existing agent instance.
+         *
+         * @internal
+         * Replaces the entire instance configuration including metadata, spec, and secrets.
+         * No individual field updates — always provide complete state.
+         * Authorization: Only owner can update (can_edit permission).
          *
          * @generated from rpc ai.stigmer.agentic.agentinstance.v1.AgentInstanceCommandController.update
          */
@@ -61,7 +64,9 @@ export const AgentInstanceCommandController = {
         },
         /**
          * Delete an agent instance.
-         * Authorization: Only owner can delete (can_delete permission)
+         *
+         * @internal
+         * Authorization: Only owner can delete (can_delete permission).
          *
          * @generated from rpc ai.stigmer.agentic.agentinstance.v1.AgentInstanceCommandController.delete
          */

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

@@ -1 +1 @@
-{"version":3,"file":"command_connect.js","sourceRoot":"","sources":["../../../../../../ai/stigmer/agentic/agentinstance/v1/command_connect.ts"],"names":[],"mappings":"AAAA,wEAAwE;AACxE,sIAAsI;AACtI,oBAAoB;AACpB,cAAc;AAGd,OAAO,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAGhD;;;;;GAKG;AACH,MAAM,CAAC,MAAM,8BAA8B,GAAG;IAC5C,QAAQ,EAAE,oEAAoE;IAC9E,OAAO,EAAE;QACP;;;;;;WAMG;QACH,KAAK,EAAE;YACL,IAAI,EAAE,OAAO;YACb,CAAC,EAAE,aAAa;YAChB,CAAC,EAAE,aAAa;YAChB,IAAI,EAAE,UAAU,CAAC,KAAK;SACvB;QACD;;;;;;;;;;;;;WAaG;QACH,MAAM,EAAE;YACN,IAAI,EAAE,QAAQ;YACd,CAAC,EAAE,aAAa;YAChB,CAAC,EAAE,aAAa;YAChB,IAAI,EAAE,UAAU,CAAC,KAAK;SACvB;QACD;;;;;;;WAOG;QACH,MAAM,EAAE;YACN,IAAI,EAAE,QAAQ;YACd,CAAC,EAAE,aAAa;YAChB,CAAC,EAAE,aAAa;YAChB,IAAI,EAAE,UAAU,CAAC,KAAK;SACvB;QACD;;;;;WAKG;QACH,MAAM,EAAE;YACN,IAAI,EAAE,QAAQ;YACd,CAAC,EAAE,eAAe;YAClB,CAAC,EAAE,aAAa;YAChB,IAAI,EAAE,UAAU,CAAC,KAAK;SACvB;KACF;CACO,CAAC"}
+{"version":3,"file":"command_connect.js","sourceRoot":"","sources":["../../../../../../ai/stigmer/agentic/agentinstance/v1/command_connect.ts"],"names":[],"mappings":"AAAA,wEAAwE;AACxE,sIAAsI;AACtI,oBAAoB;AACpB,cAAc;AAGd,OAAO,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAGhD;;;;GAIG;AACH,MAAM,CAAC,MAAM,8BAA8B,GAAG;IAC5C,QAAQ,EAAE,oEAAoE;IAC9E,OAAO,EAAE;QACP;;;;;;;;WAQG;QACH,KAAK,EAAE;YACL,IAAI,EAAE,OAAO;YACb,CAAC,EAAE,aAAa;YAChB,CAAC,EAAE,aAAa;YAChB,IAAI,EAAE,UAAU,CAAC,KAAK;SACvB;QACD;;;;;;;;;;;;;WAaG;QACH,MAAM,EAAE;YACN,IAAI,EAAE,QAAQ;YACd,CAAC,EAAE,aAAa;YAChB,CAAC,EAAE,aAAa;YAChB,IAAI,EAAE,UAAU,CAAC,KAAK;SACvB;QACD;;;;;;;;;WASG;QACH,MAAM,EAAE;YACN,IAAI,EAAE,QAAQ;YACd,CAAC,EAAE,aAAa;YAChB,CAAC,EAAE,aAAa;YAChB,IAAI,EAAE,UAAU,CAAC,KAAK;SACvB;QACD;;;;;;;WAOG;QACH,MAAM,EAAE;YACN,IAAI,EAAE,QAAQ;YACd,CAAC,EAAE,eAAe;YAClB,CAAC,EAAE,aAAa;YAChB,IAAI,EAAE,UAAU,CAAC,KAAK;SACvB;KACF;CACO,CAAC"}

package/ai/stigmer/agentic/agentinstance/v1/command_pb.d.ts

@@ -7,13 +7,14 @@ import type { AgentInstanceIdSchema } from "./io_pb";
 export declare const file_ai_stigmer_agentic_agentinstance_v1_command: GenFile;
 /**
  * AgentInstanceCommandController handles write operations for agent instances.
- * Follows the standard pattern: create, update, delete (no granular field updates).
  *
  * @generated from service ai.stigmer.agentic.agentinstance.v1.AgentInstanceCommandController
  */
 export declare const AgentInstanceCommandController: GenService<{
     /**
      * Create or update an agent instance.
+     *
+     * @internal
      * The authorization and state-operation are determined depending on whether the agent instance
      * is going to be created or updated which is determined as part of the request execution.
      *
@@ -25,14 +26,14 @@ export declare const AgentInstanceCommandController: GenService<{
         output: typeof AgentInstanceSchema;
     };
     /**
-     * Create a new agent instance with full state.
-     * Provide organization_id in metadata.org, and complete spec with configuration and secrets.
+     * Create an agent instance.
      *
-     * Authorization: FGA can_create_instance on parent agent (handler-level)
-     * - Checks can_create_instance on parent agent (via spec.agent_id)
-     * - Public agents: Any authenticated user can create instances (cross-org allowed)
-     * - Private agents: Only org members and agent owner can create instances
+     * Public agents allow any authenticated user to create instances (cross-org allowed).
+     * Private agents restrict instance creation to org members and the agent owner.
      *
+     * @internal
+     * Provide organization_id in metadata.org, and complete spec with configuration and secrets.
+     * Authorization: FGA can_create_instance on parent agent (handler-level).
      * FGA is the single source of truth — no hardcoded org-matching rules.
      * Agents are blueprints with zero secrets; instances are personal resources in the caller's org.
      *
@@ -44,10 +45,12 @@ export declare const AgentInstanceCommandController: GenService<{
         output: typeof AgentInstanceSchema;
     };
     /**
-     * Update an instance with full state.
-     * Used to update entire instance configuration including metadata, spec, and secrets.
-     * No individual field updates - always provide complete state.
-     * Authorization: Only owner can update (can_edit permission)
+     * Update an existing agent instance.
+     *
+     * @internal
+     * Replaces the entire instance configuration including metadata, spec, and secrets.
+     * No individual field updates — always provide complete state.
+     * Authorization: Only owner can update (can_edit permission).
      *
      * @generated from rpc ai.stigmer.agentic.agentinstance.v1.AgentInstanceCommandController.update
      */
@@ -58,7 +61,9 @@ export declare const AgentInstanceCommandController: GenService<{
     };
     /**
      * Delete an agent instance.
-     * Authorization: Only owner can delete (can_delete permission)
+     *
+     * @internal
+     * Authorization: Only owner can delete (can_delete permission).
      *
      * @generated from rpc ai.stigmer.agentic.agentinstance.v1.AgentInstanceCommandController.delete
      */

package/ai/stigmer/agentic/agentinstance/v1/command_pb.js

@@ -12,7 +12,6 @@ import { file_ai_stigmer_iam_iampolicy_v1_rpcauthorization_method_options } from
 export const file_ai_stigmer_agentic_agentinstance_v1_command = /*@__PURE__*/ fileDesc("CjFhaS9zdGlnbWVyL2FnZW50aWMvYWdlbnRpbnN0YW5jZS92MS9jb21tYW5kLnByb3RvEiNhaS5zdGlnbWVyLmFnZW50aWMuYWdlbnRpbnN0YW5jZS52MTLtBAoeQWdlbnRJbnN0YW5jZUNvbW1hbmRDb250cm9sbGVyEm8KBWFwcGx5EjIuYWkuc3RpZ21lci5hZ2VudGljLmFnZW50aW5zdGFuY2UudjEuQWdlbnRJbnN0YW5jZRoyLmFpLnN0aWdtZXIuYWdlbnRpYy5hZ2VudGluc3RhbmNlLnYxLkFnZW50SW5zdGFuY2USdgoGY3JlYXRlEjIuYWkuc3RpZ21lci5hZ2VudGljLmFnZW50aW5zdGFuY2UudjEuQWdlbnRJbnN0YW5jZRoyLmFpLnN0aWdtZXIuYWdlbnRpYy5hZ2VudGluc3RhbmNlLnYxLkFnZW50SW5zdGFuY2UiBNC4GAESrgEKBnVwZGF0ZRIyLmFpLnN0aWdtZXIuYWdlbnRpYy5hZ2VudGluc3RhbmNlLnYxLkFnZW50SW5zdGFuY2UaMi5haS5zdGlnbWVyLmFnZW50aWMuYWdlbnRpbnN0YW5jZS52MS5BZ2VudEluc3RhbmNlIjzCuBg4CAQQLSILbWV0YWRhdGEuaWQqJXVuYXV0aG9yaXplZCB0byB1cGRhdGUgYWdlbnQgaW5zdGFuY2USqgEKBmRlbGV0ZRI0LmFpLnN0aWdtZXIuYWdlbnRpYy5hZ2VudGluc3RhbmNlLnYxLkFnZW50SW5zdGFuY2VJZBoyLmFpLnN0aWdtZXIuYWdlbnRpYy5hZ2VudGluc3RhbmNlLnYxLkFnZW50SW5zdGFuY2UiNsK4GDIIAhAtIgV2YWx1ZSoldW5hdXRob3JpemVkIHRvIGRlbGV0ZSBhZ2VudCBpbnN0YW5jZRoEoP8rLWIGcHJvdG8z", [file_ai_stigmer_agentic_agentinstance_v1_api, file_ai_stigmer_agentic_agentinstance_v1_io, file_ai_stigmer_commons_apiresource_rpc_service_options, file_ai_stigmer_iam_iampolicy_v1_rpcauthorization_method_options]);
 /**
  * AgentInstanceCommandController handles write operations for agent instances.
- * Follows the standard pattern: create, update, delete (no granular field updates).
  *
  * @generated from service ai.stigmer.agentic.agentinstance.v1.AgentInstanceCommandController
  */

package/ai/stigmer/agentic/agentinstance/v1/command_pb.js.map

@@ -1 +1 @@
-{"version":3,"file":"command_pb.js","sourceRoot":"","sources":["../../../../../../ai/stigmer/agentic/agentinstance/v1/command_pb.ts"],"names":[],"mappings":"AAAA,gEAAgE;AAChE,sIAAsI;AACtI,oBAAoB;AAGpB,OAAO,EAAE,QAAQ,EAAE,WAAW,EAAE,MAAM,8BAA8B,CAAC;AAErE,OAAO,EAAE,4CAA4C,EAAE,MAAM,UAAU,CAAC;AAExE,OAAO,EAAE,2CAA2C,EAAE,MAAM,SAAS,CAAC;AACtE,OAAO,EAAE,uDAAuD,EAAE,MAAM,qDAAqD,CAAC;AAC9H,OAAO,EAAE,gEAAgE,EAAE,MAAM,8DAA8D,CAAC;AAEhJ;;GAEG;AACH,MAAM,CAAC,MAAM,gDAAgD,GAAY,aAAa,CACpF,QAAQ,CAAC,k8BAAk8B,EAAE,CAAC,4CAA4C,EAAE,2CAA2C,EAAE,uDAAuD,EAAE,gEAAgE,CAAC,CAAC,CAAC;AAEvqC;;;;;GAKG;AACH,MAAM,CAAC,MAAM,8BAA8B,GAwDtC,aAAa,CAChB,WAAW,CAAC,gDAAgD,EAAE,CAAC,CAAC,CAAC"}
+{"version":3,"file":"command_pb.js","sourceRoot":"","sources":["../../../../../../ai/stigmer/agentic/agentinstance/v1/command_pb.ts"],"names":[],"mappings":"AAAA,gEAAgE;AAChE,sIAAsI;AACtI,oBAAoB;AAGpB,OAAO,EAAE,QAAQ,EAAE,WAAW,EAAE,MAAM,8BAA8B,CAAC;AAErE,OAAO,EAAE,4CAA4C,EAAE,MAAM,UAAU,CAAC;AAExE,OAAO,EAAE,2CAA2C,EAAE,MAAM,SAAS,CAAC;AACtE,OAAO,EAAE,uDAAuD,EAAE,MAAM,qDAAqD,CAAC;AAC9H,OAAO,EAAE,gEAAgE,EAAE,MAAM,8DAA8D,CAAC;AAEhJ;;GAEG;AACH,MAAM,CAAC,MAAM,gDAAgD,GAAY,aAAa,CACpF,QAAQ,CAAC,k8BAAk8B,EAAE,CAAC,4CAA4C,EAAE,2CAA2C,EAAE,uDAAuD,EAAE,gEAAgE,CAAC,CAAC,CAAC;AAEvqC;;;;GAIG;AACH,MAAM,CAAC,MAAM,8BAA8B,GA8DtC,aAAa,CAChB,WAAW,CAAC,gDAAgD,EAAE,CAAC,CAAC,CAAC"}

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

@@ -7,13 +7,13 @@ import type { Message } from "@bufbuild/protobuf";
  */
 export declare const file_ai_stigmer_agentic_agentinstance_v1_io: GenFile;
 /**
- * GetAgentInstanceRequest retrieves a single agent instance by ID.
+ * AgentInstanceId wraps an agent instance identifier.
  *
  * @generated from message ai.stigmer.agentic.agentinstance.v1.AgentInstanceId
  */
 export type AgentInstanceId = Message<"ai.stigmer.agentic.agentinstance.v1.AgentInstanceId"> & {
     /**
-     * Instance ID (required).
+     * Unique identifier of the agent instance.
      *
      * @generated from field: string value = 1;
      */
@@ -25,13 +25,13 @@ export type AgentInstanceId = Message<"ai.stigmer.agentic.agentinstance.v1.Agent
  */
 export declare const AgentInstanceIdSchema: GenMessage<AgentInstanceId>;
 /**
- * GetAgentInstancesByAgentRequest gets all instances of a specific agent template.
+ * Input for retrieving all instances deployed from a specific agent.
  *
  * @generated from message ai.stigmer.agentic.agentinstance.v1.GetAgentInstancesByAgentRequest
  */
 export type GetAgentInstancesByAgentRequest = Message<"ai.stigmer.agentic.agentinstance.v1.GetAgentInstancesByAgentRequest"> & {
     /**
-     * Agent ID to filter by (required).
+     * Identifier of the agent whose instances to retrieve.
      *
      * @generated from field: string agent_id = 1;
      */
@@ -49,19 +49,19 @@ export type GetAgentInstancesByAgentRequest = Message<"ai.stigmer.agentic.agenti
  */
 export declare const GetAgentInstancesByAgentRequestSchema: GenMessage<GetAgentInstancesByAgentRequest>;
 /**
- * AgentInstanceList represents a list of agent instances.
+ * Response containing a paginated list of agent instances.
  *
  * @generated from message ai.stigmer.agentic.agentinstance.v1.AgentInstanceList
  */
 export type AgentInstanceList = Message<"ai.stigmer.agentic.agentinstance.v1.AgentInstanceList"> & {
     /**
-     * Total count of instances.
+     * Total number of agent instances matching the query.
      *
      * @generated from field: int32 total_count = 1;
      */
     totalCount: number;
     /**
-     * List of instances.
+     * Agent instances in the current page.
      *
      * @generated from field: repeated ai.stigmer.agentic.agentinstance.v1.AgentInstance items = 2;
      */
@@ -73,19 +73,21 @@ export type AgentInstanceList = Message<"ai.stigmer.agentic.agentinstance.v1.Age
  */
 export declare const AgentInstanceListSchema: GenMessage<AgentInstanceList>;
 /**
- * ListAgentInstancesRequest specifies parameters for listing agent instances.
+ * Input for listing agent instances within an organization.
  *
  * @generated from message ai.stigmer.agentic.agentinstance.v1.ListAgentInstancesRequest
  */
 export type ListAgentInstancesRequest = Message<"ai.stigmer.agentic.agentinstance.v1.ListAgentInstancesRequest"> & {
     /**
-     * Organization to list agent instances for (required).
+     * Organization slug to scope the listing.
      *
      * @generated from field: string org = 1;
      */
     org: string;
     /**
-     * Filter by metadata labels (optional). AND semantics: resource must match ALL labels.
+     * Filter by metadata labels. AND semantics: all labels must match.
+     *
+     * @internal
      * Example: {"stigmer.ai/personal": "true"} returns only personal agent instances.
      *
      * @generated from field: map<string, string> labels = 2;
@@ -94,7 +96,7 @@ export type ListAgentInstancesRequest = Message<"ai.stigmer.agentic.agentinstanc
         [key: string]: string;
     };
     /**
-     * Pagination options (optional).
+     * Pagination options.
      *
      * @generated from field: ai.stigmer.commons.rpc.PageInfo page_info = 3;
      */

package/ai/stigmer/agentic/agentinstance/v1/io_pb.js.map

@@ -1 +1 @@
-{"version":3,"file":"io_pb.js","sourceRoot":"","sources":["../../../../../../ai/stigmer/agentic/agentinstance/v1/io_pb.ts"],"names":[],"mappings":"AAAA,gEAAgE;AAChE,iIAAiI;AACjI,oBAAoB;AAGpB,OAAO,EAAE,QAAQ,EAAE,WAAW,EAAE,MAAM,8BAA8B,CAAC;AAErE,OAAO,EAAE,4CAA4C,EAAE,MAAM,UAAU,CAAC;AAExE,OAAO,EAAE,sCAAsC,EAAE,MAAM,oCAAoC,CAAC;AAC5F,OAAO,EAAE,0BAA0B,EAAE,MAAM,yCAAyC,CAAC;AAGrF;;GAEG;AACH,MAAM,CAAC,MAAM,2CAA2C,GAAY,aAAa,CAC/E,QAAQ,CAAC,kyBAAkyB,EAAE,CAAC,4CAA4C,EAAE,sCAAsC,EAAE,0BAA0B,CAAC,CAAC,CAAC;AAgBn6B;;;GAGG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAgC,aAAa,CAC7E,WAAW,CAAC,2CAA2C,EAAE,CAAC,CAAC,CAAC;AAuB9D;;;GAGG;AACH,MAAM,CAAC,MAAM,qCAAqC,GAAgD,aAAa,CAC7G,WAAW,CAAC,2CAA2C,EAAE,CAAC,CAAC,CAAC;AAuB9D;;;GAGG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAAkC,aAAa,CACjF,WAAW,CAAC,2CAA2C,EAAE,CAAC,CAAC,CAAC;AA+B9D;;;GAGG;AACH,MAAM,CAAC,MAAM,+BAA+B,GAA0C,aAAa,CACjG,WAAW,CAAC,2CAA2C,EAAE,CAAC,CAAC,CAAC"}
+{"version":3,"file":"io_pb.js","sourceRoot":"","sources":["../../../../../../ai/stigmer/agentic/agentinstance/v1/io_pb.ts"],"names":[],"mappings":"AAAA,gEAAgE;AAChE,iIAAiI;AACjI,oBAAoB;AAGpB,OAAO,EAAE,QAAQ,EAAE,WAAW,EAAE,MAAM,8BAA8B,CAAC;AAErE,OAAO,EAAE,4CAA4C,EAAE,MAAM,UAAU,CAAC;AAExE,OAAO,EAAE,sCAAsC,EAAE,MAAM,oCAAoC,CAAC;AAC5F,OAAO,EAAE,0BAA0B,EAAE,MAAM,yCAAyC,CAAC;AAGrF;;GAEG;AACH,MAAM,CAAC,MAAM,2CAA2C,GAAY,aAAa,CAC/E,QAAQ,CAAC,kyBAAkyB,EAAE,CAAC,4CAA4C,EAAE,sCAAsC,EAAE,0BAA0B,CAAC,CAAC,CAAC;AAgBn6B;;;GAGG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAgC,aAAa,CAC7E,WAAW,CAAC,2CAA2C,EAAE,CAAC,CAAC,CAAC;AAuB9D;;;GAGG;AACH,MAAM,CAAC,MAAM,qCAAqC,GAAgD,aAAa,CAC7G,WAAW,CAAC,2CAA2C,EAAE,CAAC,CAAC,CAAC;AAuB9D;;;GAGG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAAkC,aAAa,CACjF,WAAW,CAAC,2CAA2C,EAAE,CAAC,CAAC,CAAC;AAiC9D;;;GAGG;AACH,MAAM,CAAC,MAAM,+BAA+B,GAA0C,aAAa,CACjG,WAAW,CAAC,2CAA2C,EAAE,CAAC,CAAC,CAAC"}

package/ai/stigmer/agentic/agentinstance/v1/query_connect.d.ts

@@ -1,5 +1,5 @@
 /**
- * AgentInstanceQueryController provides queries for retrieving agent instances.
+ * AgentInstanceQueryController handles read operations for agent instances.
  *
  * @generated from service ai.stigmer.agentic.agentinstance.v1.AgentInstanceQueryController
  */
@@ -19,9 +19,11 @@ export declare const AgentInstanceQueryController: {
         };
         /**
          * Get all instances of a specific agent template.
+         * Returns only instances the caller has access to.
+         *
+         * @internal
          * Authorization is handled in handler via FGA query for authorized agent_instance_ids,
-         * then filtered by agent_id. This ensures users only see instances they have access to,
-         * even if the parent agent is shared across organizations.
+         * then filtered by agent_id.
          *
          * @generated from rpc ai.stigmer.agentic.agentinstance.v1.AgentInstanceQueryController.getByAgent
          */
@@ -32,7 +34,10 @@ export declare const AgentInstanceQueryController: {
             readonly kind: any;
         };
         /**
-         * Custom authorization in handler
+         * Get an agent instance by its organization-scoped reference (org/slug).
+         *
+         * @internal
+         * Custom authorization in handler.
          *
          * @generated from rpc ai.stigmer.agentic.agentinstance.v1.AgentInstanceQueryController.getByReference
          */
@@ -44,6 +49,8 @@ export declare const AgentInstanceQueryController: {
         };
         /**
          * List agent instances with optional label filtering.
+         *
+         * @internal
          * Authorization is handled in-handler via FGA-filtered queries (cloud)
          * or unrestricted store queries (OSS).
          *