@stigmer/protos 0.0.69 → 0.0.71

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

@@ -7,77 +7,56 @@ import type { Message } from "@bufbuild/protobuf";
  */
 export declare const file_ai_stigmer_agentic_agent_v1_spec: GenFile;
 /**
- * AgentSpec defines the configurable properties of an AI agent.
- * This is the "Template" layer - declares capabilities and requirements.
+ * AgentSpec defines the configurable properties of an agent.
  *
- * Example YAML:
- *   apiVersion: agentic.stigmer.ai/v1
- *   kind: Agent
- *   metadata:
- *     name: engineering-assistant
- *     slug: eng-assistant
- *   spec:
- *     description: "Helps engineering teams with code review"
- *     instructions: "You are an engineering assistant..."
- *     mcp_server_usages:
- *       - mcp_server_ref:
- *           kind: mcp_server
- *           slug: github
- *         enabled_tools: [search_code, create_pr]
- *     skill_refs:
- *       - kind: skill
- *         slug: code-review-best-practices
+ * @internal
+ * This is the "Template" layer — declares capabilities and requirements.
+ * The overview.md file provides the SDK-facing description and example YAML.
  *
  * @generated from message ai.stigmer.agentic.agent.v1.AgentSpec
  */
 export type AgentSpec = Message<"ai.stigmer.agentic.agent.v1.AgentSpec"> & {
     /**
      * Human-readable description for UI and marketplace display.
-     * Should explain what this agent does and its primary capabilities.
      *
      * @generated from field: string description = 1;
      */
     description: string;
     /**
      * Icon URL for marketplace and UI display.
-     * Should be a publicly accessible URL to an image (SVG, PNG, or JPEG).
+     * Must be a publicly accessible URL to an image (SVG, PNG, or JPEG).
      *
      * @generated from field: string icon_url = 2;
      */
     iconUrl: string;
     /**
-     * Instructions defining the agent's behavior and personality.
-     * This is the agent's system prompt - the core logic that shapes its responses.
-     * Should be at least 10 characters to ensure meaningful instructions.
+     * System prompt defining the agent's behavior and personality.
      *
      * @generated from field: string instructions = 3;
      */
     instructions: string;
     /**
-     * MCP servers this Agent can use.
-     * Each usage references a McpServer resource by its ref.
-     * The slug from each reference must be unique within this Agent.
+     * MCP servers this agent can use.
+     * Each entry must reference a unique McpServer resource by slug.
      *
      * @generated from field: repeated ai.stigmer.agentic.agent.v1.McpServerUsage mcp_server_usages = 4;
      */
     mcpServerUsages: McpServerUsage[];
     /**
-     * Skill resources providing agent knowledge.
-     * Skills are injected into the agent's context as additional capabilities.
+     * Skill resources providing additional knowledge to the agent.
      *
      * @generated from field: repeated ai.stigmer.commons.apiresource.ApiResourceReference skill_refs = 5;
      */
     skillRefs: ApiResourceReference[];
     /**
      * Sub-agents that can be delegated to.
-     * Sub-agents inherit the parent's MCP server usages but can have restricted access.
+     * Sub-agents can access a subset of the parent's MCP servers and tools.
      *
      * @generated from field: repeated ai.stigmer.agentic.agent.v1.SubAgent sub_agents = 6;
      */
     subAgents: SubAgent[];
     /**
      * Environment variables required by the agent.
-     * Uses the shared EnvironmentSpec for consistent env var handling across resources.
      *
      * @generated from field: ai.stigmer.agentic.environment.v1.EnvironmentSpec env_spec = 7;
      */
@@ -90,79 +69,53 @@ export type AgentSpec = Message<"ai.stigmer.agentic.agent.v1.AgentSpec"> & {
 export declare const AgentSpecSchema: GenMessage<AgentSpec>;
 /**
  * SubAgent defines a specialized agent that the parent can delegate to.
- * SubAgents have restricted access to the parent's MCP servers.
  *
- * Permission Model:
- * - SubAgent can only access MCP servers that parent has in mcp_server_usages
- * - SubAgent tools must be a subset of parent's enabled tools (can restrict, not expand)
- * - SubAgent skills can reference any Skill resource (independent of parent)
+ * A sub-agent can only access MCP servers that the parent has in
+ * mcp_server_usages, and its tools must be a subset of the parent's
+ * enabled tools. Skills are independent of the parent.
  *
- * Example YAML:
- *   sub_agents:
- *     - name: code-reviewer
- *       description: "Reviews code changes for quality and security"
- *       instructions: "You review code changes. Focus on security..."
- *       mcp_access:
- *         - mcp_server: github
- *           enabled_tools: [search_code, get_file]
- *       skill_refs:
- *         - kind: skill
- *           slug: code-review-best-practices
+ * @internal
+ * Permission model enforced at execution time by the delegation handler.
  *
  * @generated from message ai.stigmer.agentic.agent.v1.SubAgent
  */
 export type SubAgent = Message<"ai.stigmer.agentic.agent.v1.SubAgent"> & {
     /**
      * Unique name of the sub-agent within the parent agent.
-     * Used for delegation routing and logging.
-     * Examples: "code-reviewer", "researcher", "writer"
      *
      * @generated from field: string name = 1;
      */
     name: string;
     /**
-     * Description of what this sub-agent specializes in.
-     * Helps the parent agent decide when to delegate to this sub-agent.
-     * Example: "Reviews code changes for security issues and best practices"
+     * What this sub-agent specializes in.
      *
      * @generated from field: string description = 2;
      */
     description: string;
     /**
-     * Behavior instructions for this sub-agent.
-     * Defines the sub-agent's personality, expertise, and constraints.
-     * Should be at least 10 characters to ensure meaningful instructions.
+     * System prompt for this sub-agent.
      *
      * @generated from field: string instructions = 3;
      */
     instructions: string;
     /**
      * MCP server access grants for this sub-agent.
-     * Each McpAccess references a parent's McpServerUsage by slug and
-     * optionally restricts which tools are available.
-     * Sub-agent can only use MCP servers listed here.
+     * Each entry references a parent McpServerUsage by slug and optionally
+     * restricts which tools are available.
      *
      * @generated from field: repeated ai.stigmer.agentic.agent.v1.McpAccess mcp_access = 4;
      */
     mcpAccess: McpAccess[];
     /**
-     * Skill resources for this sub-agent's knowledge.
-     * Skills provide domain-specific knowledge and capabilities.
+     * Skill resources for this sub-agent.
      *
      * @generated from field: repeated ai.stigmer.commons.apiresource.ApiResourceReference skill_refs = 5;
      */
     skillRefs: ApiResourceReference[];
     /**
      * Model override for this sub-agent.
-     * When set, this sub-agent uses this model instead of the parent's model.
-     * Enables cost optimization by routing simple sub-agent tasks to cheaper models.
-     *
-     * Examples:
-     *   - Parent uses "claude-sonnet-4" ($3/$15 per MTok)
-     *   - File search sub-agent overrides to "claude-haiku-4" ($0.25/$1.25)
-     *   - Code review sub-agent keeps parent model (leave empty)
-     *
-     * When empty: inherits the parent agent's model (current behavior).
+     * When set, uses this model instead of the parent's model.
+     * When empty, inherits the parent agent's model.
      *
      * @generated from field: string model_override = 6;
      */
@@ -174,45 +127,33 @@ export type SubAgent = Message<"ai.stigmer.agentic.agent.v1.SubAgent"> & {
  */
 export declare const SubAgentSchema: GenMessage<SubAgent>;
 /**
- * McpServerUsage declares that this Agent uses a McpServer resource.
- * The slug from mcp_server_ref becomes the identifier for SubAgent access.
+ * McpServerUsage declares that this agent uses a McpServer resource.
  *
- * Design principle: Users already named their McpServer with a slug.
- * We use that slug as the identifier - no extra naming required.
+ * The slug from mcp_server_ref identifies this server for SubAgent access
+ * grants via McpAccess.
  *
- * Example YAML:
- *   mcp_server_usages:
- *     - mcp_server_ref:
- *         kind: mcp_server
- *         slug: github
- *       enabled_tools: [search_code, get_file, create_pr]
- *       tool_approval_overrides:
- *         - tool_name: delete_repository
- *           requires_approval: false  # Trust this agent
- *     - mcp_server_ref:
- *         org: acme-corp
- *         kind: mcp_server
- *         slug: internal-tools
+ * @internal
+ * Design principle: Users already named their McpServer with a slug.
+ * We use that slug as the identifier — no extra naming required.
  *
  * @generated from message ai.stigmer.agentic.agent.v1.McpServerUsage
  */
 export type McpServerUsage = Message<"ai.stigmer.agentic.agent.v1.McpServerUsage"> & {
     /**
      * Reference to the McpServer resource.
-     * Must reference a resource with kind=mcp_server (44).
-     * The slug from this reference is how SubAgents identify this server.
      *
      * @generated from field: ai.stigmer.commons.apiresource.ApiResourceReference mcp_server_ref = 1;
      */
     mcpServerRef?: ApiResourceReference;
     /**
-     * Tools to enable from this MCP server for this Agent.
-     * This defines the maximum tool set - SubAgents can only restrict further.
-     * Empty list = use McpServer's default_enabled_tools (or all if not specified).
+     * Tools to enable from this MCP server for this agent.
+     * Empty list uses the McpServer's default_enabled_tools.
+     * Sub-agents can only restrict this set further, not expand it.
      *
+     * @internal
      * Tool names must match exactly what the MCP server reports via tools/list.
-     * IMPORTANT: Only names from `discovered_capabilities.tools` are valid here.
-     * Do NOT include names from `discovered_capabilities.resource_templates` —
+     * Only names from discovered_capabilities.tools are valid here.
+     * Do NOT include names from discovered_capabilities.resource_templates —
      * resource templates are read-only data endpoints, not callable tools.
      * Including a resource template name here causes a fatal runtime error.
      *
@@ -221,30 +162,7 @@ export type McpServerUsage = Message<"ai.stigmer.agentic.agent.v1.McpServerUsage
     enabledTools: string[];
     /**
      * Override approval requirements for specific tools.
-     *
-     * These overrides take precedence over McpServer.default_tool_approvals,
-     * allowing per-agent customization of the approval policy.
-     *
-     * Use cases:
-     * - Disable approval for a trusted automation agent
-     * - Add approval for a tool that doesn't have default approval
-     * - Customize the approval message for this agent's context
-     *
-     * Example (trusted deployment agent - disable defaults):
-     *   tool_approval_overrides:
-     *     - tool_name: "delete_repository"
-     *       requires_approval: false  # Trust this agent for deletions
-     *     - tool_name: "force_push"
-     *       requires_approval: false  # Trust this agent for force pushes
-     *
-     * Example (stricter approval for customer-facing agent):
-     *   tool_approval_overrides:
-     *     - tool_name: "send_email"
-     *       requires_approval: true
-     *       message: "Send customer communication: {{args.subject}}"
-     *     - tool_name: "create_ticket"
-     *       requires_approval: true
-     *       message: "Create support ticket for customer"
+     * Takes precedence over McpServer.default_tool_approvals.
      *
      * @generated from field: repeated ai.stigmer.agentic.agent.v1.ToolApprovalOverride tool_approval_overrides = 3;
      */
@@ -256,37 +174,27 @@ export type McpServerUsage = Message<"ai.stigmer.agentic.agent.v1.McpServerUsage
  */
 export declare const McpServerUsageSchema: GenMessage<McpServerUsage>;
 /**
- * McpAccess grants a SubAgent access to one of the parent Agent's MCP servers.
- * Uses the same slug that identifies the McpServer resource.
+ * McpAccess grants a sub-agent access to one of the parent's MCP servers.
  *
- * Permission model:
- * - SubAgent can only access servers that parent has in mcp_server_usages
- * - SubAgent tools must be a subset of parent's enabled tools
- *
- * Example YAML:
- *   sub_agents:
- *     - name: code-reviewer
- *       mcp_access:
- *         - mcp_server: github
- *           enabled_tools: [search_code, get_file]
- *         - mcp_server: slack
- *           # enabled_tools empty = all tools from parent
+ * @internal
+ * Permission model enforced at execution time: sub-agent can only access
+ * servers in the parent's mcp_server_usages, and tools must be a subset
+ * of the parent's enabled_tools.
  *
  * @generated from message ai.stigmer.agentic.agent.v1.McpAccess
  */
 export type McpAccess = Message<"ai.stigmer.agentic.agent.v1.McpAccess"> & {
     /**
      * Slug of the McpServer to grant access to.
-     * Must match mcp_server_ref.slug from one of parent's mcp_server_usages.
+     * Must match a mcp_server_ref.slug from the parent's mcp_server_usages.
      *
      * @generated from field: string mcp_server = 1;
      */
     mcpServer: string;
     /**
-     * Tools this SubAgent can use from this MCP server.
+     * Tools this sub-agent can use from this MCP server.
      * Must be a subset of the parent's enabled_tools for this server.
-     * Empty list = all tools that parent has enabled (no additional restriction).
-     * Only MCP tool names are valid — never include resource template names.
+     * Empty list grants access to all tools the parent has enabled.
      *
      * @generated from field: repeated string enabled_tools = 2;
      */
@@ -300,29 +208,18 @@ export declare const McpAccessSchema: GenMessage<McpAccess>;
 /**
  * ToolApprovalOverride allows per-agent customization of approval requirements.
  *
- * ## Override Semantics
- *
- * - requires_approval=true: Tool requires approval (even if MCP has no default)
- * - requires_approval=false: Tool does NOT require approval (overrides MCP default)
+ * Set requires_approval to true to require approval even when the McpServer
+ * has no default, or to false to skip approval even when the McpServer
+ * requires it. These overrides take precedence over
+ * McpServer.default_tool_approvals but can be bypassed at execution time
+ * by AgentExecution.auto_approve_all.
  *
- * ## Message Inheritance
+ * @internal
+ * Policy chain (lowest to highest priority):
+ * 1. McpServer.default_tool_approvals — platform/org defaults
+ * 2. Agent.McpServerUsage.tool_approval_overrides — per-agent (this message)
+ * 3. AgentExecution.auto_approve_all — runtime bypass
  *
- * When requires_approval=true and message is empty:
- * - If McpServer has default_tool_approvals for this tool, uses that message
- * - Otherwise, auto-generates: "Execute tool: {tool_name}"
- *
- * When message is provided, it overrides any McpServer default message.
- *
- * ## Policy Chain Position
- *
- * This sits in the middle of the approval policy chain:
- * 1. McpServer.default_tool_approvals - Platform/org defaults (lowest priority)
- * 2. Agent.McpServerUsage.tool_approval_overrides (this message) - Per-agent customization
- * 3. AgentExecution.auto_approve_all - Runtime bypass (highest priority)
- *
- * ## Validation
- *
- * The tool_name should match a tool in the referenced McpServer's tools/list.
  * Invalid tool names are silently ignored (no approval applied).
  * This allows forward-compatibility when MCP servers add/remove tools.
  *
@@ -331,8 +228,6 @@ export declare const McpAccessSchema: GenMessage<McpAccess>;
 export type ToolApprovalOverride = Message<"ai.stigmer.agentic.agent.v1.ToolApprovalOverride"> & {
     /**
      * Name of the tool to override.
-     * Must match exactly (case-sensitive) with MCP server's tool name.
-     * Example: "delete_repository", "send_email", "execute_sql"
      *
      * @generated from field: string tool_name = 1;
      */
@@ -340,27 +235,14 @@ export type ToolApprovalOverride = Message<"ai.stigmer.agentic.agent.v1.ToolAppr
     /**
      * Whether this tool requires approval for this agent.
      *
-     * false: No approval needed (overrides any McpServer default)
-     * true: Approval required (even if McpServer has no default)
-     *
-     * Note: This can be further overridden at execution time by
-     * AgentExecutionSpec.auto_approve_all=true
-     *
      * @generated from field: bool requires_approval = 2;
      */
     requiresApproval: boolean;
     /**
-     * Optional: Custom approval message for this agent.
-     * Supports {{args.field}} placeholders like ToolApprovalPolicy.message.
-     *
-     * If empty and requires_approval=true:
-     * - Uses McpServer's default message for this tool (if exists)
-     * - Otherwise auto-generates: "Execute tool: {tool_name}"
-     *
-     * Guidelines for effective messages:
-     *   - Be specific to this agent's context
-     *   - Include the most important argument values
-     *   - Keep under 100 characters for UI display
+     * Custom approval message shown to the reviewer.
+     * Supports {{args.field}} placeholders.
+     * When empty, falls back to the McpServer default or auto-generates
+     * "Execute tool: {tool_name}".
      *
      * @generated from field: string message = 3;
      */

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

@@ -1 +1 @@
-{"version":3,"file":"spec_pb.js","sourceRoot":"","sources":["../../../../../../ai/stigmer/agentic/agent/v1/spec_pb.ts"],"names":[],"mappings":"AAAA,gEAAgE;AAChE,mHAAmH;AACnH,oBAAoB;AAGpB,OAAO,EAAE,QAAQ,EAAE,WAAW,EAAE,MAAM,8BAA8B,CAAC;AAErE,OAAO,EAAE,2CAA2C,EAAE,MAAM,8BAA8B,CAAC;AAC3F,OAAO,EAAE,iDAAiD,EAAE,MAAM,+CAA+C,CAAC;AAElH,OAAO,EAAE,sCAAsC,EAAE,MAAM,oCAAoC,CAAC;AAC5F,OAAO,EAAE,0BAA0B,EAAE,MAAM,yCAAyC,CAAC;AAGrF;;GAEG;AACH,MAAM,CAAC,MAAM,qCAAqC,GAAY,aAAa,CACzE,QAAQ,CAAC,k1DAAk1D,EAAE,CAAC,2CAA2C,EAAE,iDAAiD,EAAE,sCAAsC,EAAE,0BAA0B,CAAC,CAAC,CAAC;AAsFrgE;;;GAGG;AACH,MAAM,CAAC,MAAM,eAAe,GAA0B,aAAa,CACjE,WAAW,CAAC,qCAAqC,EAAE,CAAC,CAAC,CAAC;AAwFxD;;;GAGG;AACH,MAAM,CAAC,MAAM,cAAc,GAAyB,aAAa,CAC/D,WAAW,CAAC,qCAAqC,EAAE,CAAC,CAAC,CAAC;AAkFxD;;;GAGG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAA+B,aAAa,CAC3E,WAAW,CAAC,qCAAqC,EAAE,CAAC,CAAC,CAAC;AAyCxD;;;GAGG;AACH,MAAM,CAAC,MAAM,eAAe,GAA0B,aAAa,CACjE,WAAW,CAAC,qCAAqC,EAAE,CAAC,CAAC,CAAC;AA0ExD;;;GAGG;AACH,MAAM,CAAC,MAAM,0BAA0B,GAAqC,aAAa,CACvF,WAAW,CAAC,qCAAqC,EAAE,CAAC,CAAC,CAAC"}
+{"version":3,"file":"spec_pb.js","sourceRoot":"","sources":["../../../../../../ai/stigmer/agentic/agent/v1/spec_pb.ts"],"names":[],"mappings":"AAAA,gEAAgE;AAChE,mHAAmH;AACnH,oBAAoB;AAGpB,OAAO,EAAE,QAAQ,EAAE,WAAW,EAAE,MAAM,8BAA8B,CAAC;AAErE,OAAO,EAAE,2CAA2C,EAAE,MAAM,8BAA8B,CAAC;AAC3F,OAAO,EAAE,iDAAiD,EAAE,MAAM,+CAA+C,CAAC;AAElH,OAAO,EAAE,sCAAsC,EAAE,MAAM,oCAAoC,CAAC;AAC5F,OAAO,EAAE,0BAA0B,EAAE,MAAM,yCAAyC,CAAC;AAGrF;;GAEG;AACH,MAAM,CAAC,MAAM,qCAAqC,GAAY,aAAa,CACzE,QAAQ,CAAC,k1DAAk1D,EAAE,CAAC,2CAA2C,EAAE,iDAAiD,EAAE,sCAAsC,EAAE,0BAA0B,CAAC,CAAC,CAAC;AAiErgE;;;GAGG;AACH,MAAM,CAAC,MAAM,eAAe,GAA0B,aAAa,CACjE,WAAW,CAAC,qCAAqC,EAAE,CAAC,CAAC,CAAC;AA8DxD;;;GAGG;AACH,MAAM,CAAC,MAAM,cAAc,GAAyB,aAAa,CAC/D,WAAW,CAAC,qCAAqC,EAAE,CAAC,CAAC,CAAC;AA+CxD;;;GAGG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAA+B,aAAa,CAC3E,WAAW,CAAC,qCAAqC,EAAE,CAAC,CAAC,CAAC;AA+BxD;;;GAGG;AACH,MAAM,CAAC,MAAM,eAAe,GAA0B,aAAa,CACjE,WAAW,CAAC,qCAAqC,EAAE,CAAC,CAAC,CAAC;AAgDxD;;;GAGG;AACH,MAAM,CAAC,MAAM,0BAA0B,GAAqC,aAAa,CACvF,WAAW,CAAC,qCAAqC,EAAE,CAAC,CAAC,CAAC"}

package/ai/stigmer/agentic/agent/v1/status_pb.d.ts

@@ -6,7 +6,7 @@ import type { Message } from "@bufbuild/protobuf";
  */
 export declare const file_ai_stigmer_agentic_agent_v1_status: GenFile;
 /**
- * AgentStatus contains system-managed state for an Agent resource.
+ * AgentStatus contains system-managed state for an agent.
  *
  * @generated from message ai.stigmer.agentic.agent.v1.AgentStatus
  */
@@ -18,10 +18,10 @@ export type AgentStatus = Message<"ai.stigmer.agentic.agent.v1.AgentStatus"> & {
      */
     audit?: ApiResourceAudit;
     /**
-     * ID of the default agent instance created automatically for this agent.
-     * Every agent has exactly one default instance that requires no configuration.
-     * This instance has no environment variables and uses all agent defaults.
-     * Created automatically when the agent is created.
+     * ID of the default agent instance.
+     * Every agent has exactly one default instance that uses all agent defaults
+     * and requires no additional configuration. Created automatically when the
+     * agent is created.
      *
      * @generated from field: string default_instance_id = 1;
      */

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

@@ -131,35 +131,31 @@ export type AgentExecutionStatus = Message<"ai.stigmer.agentic.agentexecution.v1
         [key: string]: TodoItem;
     };
     /**
-     * Temporal callback token for async activity completion.
+     * Callback token for notifying a parent workflow when this execution completes.
      *
-     * When this AgentExecution is triggered from a Temporal activity (e.g., from a workflow
-     * that invokes an agent), the calling activity passes its task token here. The agent-runner
-     * is responsible for completing the external activity when the agent execution finishes.
+     * Present when this execution was triggered by a workflow. Empty when the
+     * execution runs independently (chat, API call).
      *
-     * ## Token Handshake Pattern
+     * @internal
      *
-     * Same pattern as WorkflowExecution (see workflowexecution/v1/api.proto for details):
+     * When this AgentExecution is triggered from a Temporal activity, the
+     * calling activity passes its task token here. The agent-runner completes
+     * the external activity when the execution finishes.
+     *
+     * Token Handshake Pattern:
      * 1. External activity extracts token and stores in AgentExecution.status
      * 2. Activity returns activity.ErrResultPending (paused, thread freed)
      * 3. Agent executes (seconds to minutes)
      * 4. On completion: agent-runner completes external activity via token
      *
-     * ## Why in Status
-     *
+     * Why in Status (not Spec):
      * - System-generated by Temporal, not user-provided
      * - Runtime state, not configuration
      * - Ephemeral, only relevant during execution
      *
-     * ## Use Cases
-     *
-     * - **With token**: Agent invoked from workflow, workflow waits for completion
-     * - **Without token**: Agent runs independently (chat, API call)
-     *
-     * ## References
-     *
+     * References:
      * - WorkflowExecution.spec.callback_token (field 7) - Same pattern
-     * - [ADR](docs/adr/20260122-async-agent-execution-temporal-token-handshake.md)
+     * - ADR: docs/adr/20260122-async-agent-execution-temporal-token-handshake.md
      *
      * @generated from field: bytes callback_token = 10;
      */
@@ -175,6 +171,12 @@ export type AgentExecutionStatus = Message<"ai.stigmer.agentic.agentexecution.v1
     /**
      * Active pending approval requests for this execution.
      *
+     * Contains one entry per tool call that requires user approval before
+     * it can proceed. Sub-agent approvals are included with from_sub_agent
+     * set to true. Empty when no approvals are pending.
+     *
+     * @internal
+     *
      * Computed server-side by the Go/Java UpdateStatus handlers on every write.
      * The handler scans messages[].tool_calls and
      * sub_agent_executions[].messages[].tool_calls, collecting entries where
@@ -185,9 +187,6 @@ export type AgentExecutionStatus = Message<"ai.stigmer.agentic.agentexecution.v1
      * with the authoritative tool call state embedded in messages. No lifecycle
      * state machine, no merge logic, no forward-only enforcement needed.
      *
-     * Sub-agent approvals are included with from_sub_agent=true and
-     * sub_agent_name set, so the UI can attribute each approval to its origin.
-     *
      * Lifecycle:
      * 1. Agent-runner sets ToolCall.status = WAITING_APPROVAL on the message
      * 2. UpdateStatus handler recomputes this field, entry appears
@@ -195,8 +194,6 @@ export type AgentExecutionStatus = Message<"ai.stigmer.agentic.agentexecution.v1
      * 4. User submits decisions via SubmitApproval RPC (one per tool call)
      * 5. Agent resumes, ToolCall.status advances, next recompute drops the entry
      *
-     * Empty when no approvals are pending.
-     *
      * @generated from field: repeated ai.stigmer.agentic.agentexecution.v1.PendingApproval pending_approvals = 16;
      */
     pendingApprovals: PendingApproval[];
@@ -271,8 +268,9 @@ export type AgentExecutionStatus = Message<"ai.stigmer.agentic.agentexecution.v1
  */
 export declare const AgentExecutionStatusSchema: GenMessage<AgentExecutionStatus>;
 /**
- * Setup progress reported by the agent-runner during the EXECUTION_PENDING phase.
+ * Setup progress reported during the EXECUTION_PENDING phase.
  *
+ * @internal
  * Designed as a sub-message (rather than a bare string) so future fields
  * (completed_phases, total_phases, phase_index) can be added without
  * deprecation or breaking changes.

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

@@ -1 +1 @@
-{"version":3,"file":"api_pb.js","sourceRoot":"","sources":["../../../../../../ai/stigmer/agentic/agentexecution/v1/api_pb.ts"],"names":[],"mappings":"AAAA,gEAAgE;AAChE,oIAAoI;AACpI,oBAAoB;AAGpB,OAAO,EAAE,QAAQ,EAAE,WAAW,EAAE,MAAM,8BAA8B,CAAC;AAErE,OAAO,EAAE,kDAAkD,EAAE,MAAM,eAAe,CAAC;AAEnF,OAAO,EAAE,kDAAkD,EAAE,MAAM,eAAe,CAAC;AAEnF,OAAO,EAAE,iDAAiD,EAAE,MAAM,cAAc,CAAC;AAEjF,OAAO,EAAE,8CAA8C,EAAE,MAAM,WAAW,CAAC;AAE3E,OAAO,EAAE,iDAAiD,EAAE,MAAM,cAAc,CAAC;AAEjF,OAAO,EAAE,8CAA8C,EAAE,MAAM,WAAW,CAAC;AAE3E,OAAO,EAAE,kDAAkD,EAAE,MAAM,eAAe,CAAC;AAEnF,OAAO,EAAE,8CAA8C,EAAE,MAAM,WAAW,CAAC;AAE3E,OAAO,EAAE,mDAAmD,EAAE,MAAM,gBAAgB,CAAC;AAErF,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,6CAA6C,GAAY,aAAa,CACjF,QAAQ,CAAC,0gEAA0gE,EAAE,CAAC,kDAAkD,EAAE,kDAAkD,EAAE,iDAAiD,EAAE,8CAA8C,EAAE,iDAAiD,EAAE,8CAA8C,EAAE,kDAAkD,EAAE,8CAA8C,EAAE,mDAAmD,EAAE,4CAA4C,EAAE,0CAA0C,EAAE,0BAA0B,CAAC,CAAC,CAAC;AAgDtlF;;;GAGG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAA+B,aAAa,CAC3E,WAAW,CAAC,6CAA6C,EAAE,CAAC,CAAC,CAAC;AA2NhE;;;GAGG;AACH,MAAM,CAAC,MAAM,0BAA0B,GAAqC,aAAa,CACvF,WAAW,CAAC,6CAA6C,EAAE,CAAC,CAAC,CAAC;AAsBhE;;;GAGG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAA8B,aAAa,CACzE,WAAW,CAAC,6CAA6C,EAAE,CAAC,CAAC,CAAC"}
+{"version":3,"file":"api_pb.js","sourceRoot":"","sources":["../../../../../../ai/stigmer/agentic/agentexecution/v1/api_pb.ts"],"names":[],"mappings":"AAAA,gEAAgE;AAChE,oIAAoI;AACpI,oBAAoB;AAGpB,OAAO,EAAE,QAAQ,EAAE,WAAW,EAAE,MAAM,8BAA8B,CAAC;AAErE,OAAO,EAAE,kDAAkD,EAAE,MAAM,eAAe,CAAC;AAEnF,OAAO,EAAE,kDAAkD,EAAE,MAAM,eAAe,CAAC;AAEnF,OAAO,EAAE,iDAAiD,EAAE,MAAM,cAAc,CAAC;AAEjF,OAAO,EAAE,8CAA8C,EAAE,MAAM,WAAW,CAAC;AAE3E,OAAO,EAAE,iDAAiD,EAAE,MAAM,cAAc,CAAC;AAEjF,OAAO,EAAE,8CAA8C,EAAE,MAAM,WAAW,CAAC;AAE3E,OAAO,EAAE,kDAAkD,EAAE,MAAM,eAAe,CAAC;AAEnF,OAAO,EAAE,8CAA8C,EAAE,MAAM,WAAW,CAAC;AAE3E,OAAO,EAAE,mDAAmD,EAAE,MAAM,gBAAgB,CAAC;AAErF,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,6CAA6C,GAAY,aAAa,CACjF,QAAQ,CAAC,0gEAA0gE,EAAE,CAAC,kDAAkD,EAAE,kDAAkD,EAAE,iDAAiD,EAAE,8CAA8C,EAAE,iDAAiD,EAAE,8CAA8C,EAAE,kDAAkD,EAAE,8CAA8C,EAAE,mDAAmD,EAAE,4CAA4C,EAAE,0CAA0C,EAAE,0BAA0B,CAAC,CAAC,CAAC;AAgDtlF;;;GAGG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAA+B,aAAa,CAC3E,WAAW,CAAC,6CAA6C,EAAE,CAAC,CAAC,CAAC;AAwNhE;;;GAGG;AACH,MAAM,CAAC,MAAM,0BAA0B,GAAqC,aAAa,CACvF,WAAW,CAAC,6CAA6C,EAAE,CAAC,CAAC,CAAC;AAuBhE;;;GAGG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAA8B,aAAa,CACzE,WAAW,CAAC,6CAA6C,EAAE,CAAC,CAAC,CAAC"}

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

@@ -5,25 +5,21 @@ import type { Message } from "@bufbuild/protobuf";
  */
 export declare const file_ai_stigmer_agentic_agentexecution_v1_approval: GenFile;
 /**
- * PendingApproval is a UI-facing projection computed server-side from tool
- * call state in messages.
+ * A pending approval request for a tool call that requires user consent before execution.
  *
- * ## How It Works
+ * Each entry represents one tool call waiting for a user decision (approve, skip,
+ * or reject). Sub-agent approvals are included with from_sub_agent set to true
+ * and sub_agent_name identifying the origin.
  *
- * The Go/Java UpdateStatus handlers recompute this projection on every write
- * by scanning messages[].tool_calls (and sub_agent_executions[].messages[].tool_calls),
+ * @internal
+ *
+ * Computed server-side by the UpdateStatus handlers on every write. The handler
+ * scans messages[].tool_calls and sub_agent_executions[].messages[].tool_calls,
  * collecting entries where status == WAITING_APPROVAL && requires_approval == true.
  * Because the list is recomputed rather than merged, it is always consistent
  * with the authoritative tool call state embedded in messages.
  *
- * ## Sub-Agent Approvals
- *
- * When a sub-agent's tool requires approval, the computed projection includes
- * it with from_sub_agent=true and sub_agent_name set. This allows UI to show:
- * "Sub-agent 'code-reviewer' needs approval to execute 'delete_file'"
- *
- * ## Lifecycle
- *
+ * Lifecycle:
  * 1. Tool with requires_approval=true is about to execute
  * 2. Agent-runner sets ToolCall.status = WAITING_APPROVAL on the message
  * 3. Server recomputes pending_approvals, entry appears
@@ -128,15 +124,15 @@ export type PendingApproval = Message<"ai.stigmer.agentic.agentexecution.v1.Pend
  */
 export declare const PendingApprovalSchema: GenMessage<PendingApproval>;
 /**
- * ChildApprovalNotification is the signal payload sent to parent workflows
- * when a child agent enters WAITING_FOR_APPROVAL state.
+ * Notification sent to a parent workflow when a child agent needs tool approval.
  *
- * This enables events-based notification instead of polling, providing
- * sub-100ms latency for approval state propagation from child agents to
- * parent workflows.
+ * Contains all pending approvals from a single child agent execution,
+ * enabling the parent workflow to surface approval requests to users
+ * without polling.
  *
- * ## Signal Flow
+ * @internal
  *
+ * Signal Flow:
  * 1. Child agent requires tool approval (phase = WAITING_FOR_APPROVAL)
  * 2. Java workflow detects this and builds ChildApprovalNotification
  * 3. Java sends Temporal signal "child_approval_required" to parent workflow
@@ -144,15 +140,7 @@ export declare const PendingApprovalSchema: GenMessage<PendingApproval>;
  * 5. Parent updates task status to WORKFLOW_TASK_WAITING_APPROVAL
  * 6. Parent populates WorkflowExecution.status.pending_approvals
  *
- * ## Parent Workflow Actions
- *
- * Upon receiving this signal, the parent workflow should:
- * 1. Update its task status to WORKFLOW_TASK_WAITING_APPROVAL
- * 2. Populate WorkflowExecution.status.pending_approvals with all entries
- * 3. Surface the approval requests to users via UI/API
- *
- * ## Graceful Degradation
- *
+ * Graceful Degradation:
  * If the signal fails to send (parent workflow completed, network error),
  * the system continues to function. Users can still submit approvals directly
  * via the AgentExecution.SubmitApproval RPC.

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

@@ -1 +1 @@
-{"version":3,"file":"approval_pb.js","sourceRoot":"","sources":["../../../../../../ai/stigmer/agentic/agentexecution/v1/approval_pb.ts"],"names":[],"mappings":"AAAA,gEAAgE;AAChE,yIAAyI;AACzI,oBAAoB;AAGpB,OAAO,EAAE,QAAQ,EAAE,WAAW,EAAE,MAAM,8BAA8B,CAAC;AAGrE;;GAEG;AACH,MAAM,CAAC,MAAM,kDAAkD,GAAY,aAAa,CACtF,QAAQ,CAAC,imBAAimB,CAAC,CAAC;AAiI9mB;;;GAGG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAgC,aAAa,CAC7E,WAAW,CAAC,kDAAkD,EAAE,CAAC,CAAC,CAAC;AA+DrE;;;GAGG;AACH,MAAM,CAAC,MAAM,+BAA+B,GAA0C,aAAa,CACjG,WAAW,CAAC,kDAAkD,EAAE,CAAC,CAAC,CAAC"}
+{"version":3,"file":"approval_pb.js","sourceRoot":"","sources":["../../../../../../ai/stigmer/agentic/agentexecution/v1/approval_pb.ts"],"names":[],"mappings":"AAAA,gEAAgE;AAChE,yIAAyI;AACzI,oBAAoB;AAGpB,OAAO,EAAE,QAAQ,EAAE,WAAW,EAAE,MAAM,8BAA8B,CAAC;AAGrE;;GAEG;AACH,MAAM,CAAC,MAAM,kDAAkD,GAAY,aAAa,CACtF,QAAQ,CAAC,imBAAimB,CAAC,CAAC;AA6H9mB;;;GAGG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAgC,aAAa,CAC7E,WAAW,CAAC,kDAAkD,EAAE,CAAC,CAAC,CAAC;AAuDrE;;;GAGG;AACH,MAAM,CAAC,MAAM,+BAA+B,GAA0C,aAAa,CACjG,WAAW,CAAC,kDAAkD,EAAE,CAAC,CAAC,CAAC"}