@stigmer/mcp-server 3.11.0 → 3.11.1-dev.20260812192248

package/src/gen/mcpserver.ts

@@ -13,7 +13,7 @@ import { ApiResourceReferenceSchema } from "@stigmer/protos/ai/stigmer/commons/a
 import { ApiResourceMetadataSchema } from "@stigmer/protos/ai/stigmer/commons/apiresource/metadata_pb";
 import { z } from "zod";
 
-/** McpServerSpec defines the configurable properties of an MCP server. @internal This is the "Template" layer — declares capabilities and requirements. The overview.md file provides the SDK-facing description and example YAML. */
+/** McpServerSpec defines the configurable properties of an MCP server. */
 export const McpServerInputShape = {
   name: z.string().describe("Human-readable name of the resource."),
   slug: z.string().optional().describe("URL-friendly identifier (lowercase alphanumeric with hyphens). Auto-generated from name if omitted."),
@@ -25,9 +25,9 @@ export const McpServerInputShape = {
   icon_url: z.string().optional().describe("Icon URL for UI display in marketplace and agent configuration screens. Should be a publicly accessible URL to an image (SVG, PNG, or JPEG). Example: 'https://github.githubassets.com/favicons/favicon.svg'"),
   stdio: z.lazy(() => StdioServerConfigInputSchema).optional().describe("stdio-based server (subprocess with stdin/stdout communication). Most common type - used for Node.js, Python, and other CLI-based MCP servers."),
   http: z.lazy(() => HttpServerConfigInputSchema).optional().describe("HTTP-based server (HTTP + Server-Sent Events communication). Used for remote/managed MCP services accessible over the network."),
-  default_enabled_tools: z.array(z.string()).optional().describe("Default tools to enable from this MCP server. Empty list means all tools are enabled by default. Applies whenever an agent's McpServerUsage.enabled_tools is empty. @internal Tool names must match exactly what the MCP server reports via tools/list. 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. A name the server does not expose (including a resource template name) is warned and ignored at execution: the runner enforces the INTERSECTION with the server's live toolset, so a stale or mistyped entry narrows the toolset but never widens it or fails the run. Enforcement is per harness — see McpServerUsage.enabled_tools in agent/v1/spec.proto."),
-  env: z.record(z.lazy(() => EnvVarDeclarationInputSchema)).optional().describe("Environment variable declarations for this MCP server. Keys are variable names; values describe their metadata and optionality. @internal Reserved platform keys — declared here like any other variable, but their values are injected by the runner per resolution context and are authoritative over same-named user env entries: STIGMER_CALLER_IDENTITY_KIND — the verified caller's kind token ('whatsapp_phone', 'slack_user_id', 'stigmer_user', 'anonymous') STIGMER_CALLER_IDENTITY_VALUE — the identity value (wa_id, user id, email); empty for anonymous STIGMER_SESSION_ID — the session the identity was resolved for; empty outside a session Reserved keys MUST be declared 'optional: true': they have no value at execution-create time, and a required declaration fails the pipeline's env-completeness validation before the runner ever injects them. Discovery (the connect workflow) runs with no session and injects the anonymous sentinel — a server consuming these keys must answer tools/list for anonymous callers and gate tool CALLS instead. The injected header is runner-asserted, not signed: pair it with a shared secret and treat it as trustworthy only for servers you operate."),
-  pinned_tool_approvals: z.array(z.lazy(() => ToolApprovalPolicyInputSchema)).optional().describe("Manual tool approval overrides set by the MCP server owner. @internal These take precedence over system-generated 'McpServerStatus.tool_approvals'. Never auto-modified — only changed by explicit user action (apply/update). Use cases: - Force approval for a tool the classifier marked as auto-approve - Exempt a safe tool the classifier flagged as needing approval - Establish organization-wide safety policies for dangerous tools Policy chain (lowest to highest priority): 1. McpServerStatus.tool_approvals - System-generated defaults 2. McpServerSpec.pinned_tool_approvals - Manual overrides (this field) 3. Agent.McpServerUsage.tool_approval_overrides - Per-agent customization 4. AgentExecution.auto_approve_all - Runtime bypass"),
+  default_enabled_tools: z.array(z.string()).optional().describe("Default tools to enable from this MCP server. Empty list means all tools are enabled by default. Applies whenever an agent's McpServerUsage.enabled_tools is empty."),
+  env: z.record(z.lazy(() => EnvVarDeclarationInputSchema)).optional().describe("Environment variable declarations for this MCP server. Keys are variable names; values describe their metadata and optionality."),
+  pinned_tool_approvals: z.array(z.lazy(() => ToolApprovalPolicyInputSchema)).optional().describe("Manual tool approval overrides set by the MCP server owner."),
   repository_url: z.string().optional().describe("URL of the upstream source repository for this MCP server. Shown in the marketplace so users can inspect the implementation for trust and transparency. Example: 'https://github.com/modelcontextprotocol/servers'"),
   github_stars: z.number().optional().describe("GitHub star count at the time of curation. Used as a popularity signal in marketplace display. 0 if unknown or non-GitHub repository."),
   auth: z.lazy(() => McpServerAuthInputSchema).optional().describe("OAuth authentication configuration for automated credential acquisition. When set, the MCP server's Connect page offers an OAuth flow instead of (or in addition to) manual credential entry. The acquired access token is stored in a system-managed environment (identified by grant.environment_id) as the env var named by auth.target_env_var. That env var must also be declared in env so the execution pipeline knows about it."),
@@ -45,16 +45,16 @@ type StdioServerConfigInput = z.infer<typeof StdioServerConfigInputSchema>;
 
 const HttpServerConfigInputSchema = z.object({
   url: z.string().describe("Base URL of the MCP server endpoint. Must be a valid HTTP or HTTPS URL. Examples: - 'http://localhost:3000/mcp' - 'https://mcp.example.com/v1' - 'https://api.company.com/mcp/github'"),
-  headers: z.record(z.string()).optional().describe("HTTP headers to include with every request. Use for authentication, API versioning, or custom routing. Header values can reference environment variables using ${VAR_NAME} syntax. These placeholders are resolved at runtime from AgentInstance's environment. Examples: 'Authorization': 'Bearer ${API_TOKEN}' 'X-API-Version': '2024-01' 'X-Tenant-ID': '${TENANT_ID}' @internal Templates may also reference the reserved caller-identity keys (STIGMER_CALLER_IDENTITY_KIND / _VALUE, STIGMER_SESSION_ID) when the server declares them in spec.env — see the env field's reserved-key contract. Placeholders resolve against the env FILTERED to declared keys, so an undeclared reserved key in a template fails resolution."),
+  headers: z.record(z.string()).optional().describe("HTTP headers to include with every request. Use for authentication, API versioning, or custom routing. Header values can reference environment variables using ${VAR_NAME} syntax. These placeholders are resolved at runtime from AgentInstance's environment. Examples: 'Authorization': 'Bearer ${API_TOKEN}' 'X-API-Version': '2024-01' 'X-Tenant-ID': '${TENANT_ID}'"),
   query_params: z.record(z.string()).optional().describe("Query parameters to append to the URL. Values can reference environment variables using ${VAR_NAME} syntax. Examples: 'region': '${AWS_REGION}' 'version': 'v1'"),
   timeout_seconds: z.number().optional().describe("Timeout for HTTP requests in seconds. Applies to both the initial connection and response streaming. Default: 30 seconds if not specified. Set higher values for MCP servers that perform long-running operations."),
 });
 type HttpServerConfigInput = z.infer<typeof HttpServerConfigInputSchema>;
 
 const EnvVarDeclarationInputSchema = z.object({
-  is_secret: z.boolean().optional().describe("Whether the resolved value should be treated as a secret. @internal When true: encrypted at rest, redacted in logs and Temporal history. When false: stored as plaintext, visible in audit logs."),
+  is_secret: z.boolean().optional().describe("Whether the resolved value should be treated as a secret."),
   description: z.string().optional().describe("Human-readable description shown in the UI credential form. Should explain what the variable is used for and where to obtain it."),
-  optional: z.boolean().optional().describe("Whether this variable is optional. @internal When false (default): the execution pipeline rejects a run if this variable is missing from the user's environment. When true: a missing value is acceptable (the MCP server or agent degrades gracefully without it)."),
+  optional: z.boolean().optional().describe("Whether this variable is optional."),
 });
 type EnvVarDeclarationInput = z.infer<typeof EnvVarDeclarationInputSchema>;
 

package/src/gen/workflow.ts

@@ -40,7 +40,7 @@ import { ApiResourceReferenceSchema } from "@stigmer/protos/ai/stigmer/commons/a
 import { ApiResourceMetadataSchema } from "@stigmer/protos/ai/stigmer/commons/apiresource/metadata_pb";
 import { z } from "zod";
 
-/** WorkflowSpec defines the configurable properties of a workflow. @internal Follows the "kind + Struct" pattern from CloudResource (Planton). This replaces the old `synthesized_yaml` field with structured proto definitions. Each workflow task uses WorkflowTaskKind enum + google.protobuf.Struct for configuration, providing maximum flexibility and extensibility. The overview.md file provides the SDK-facing description and example YAML. */
+/** WorkflowSpec defines the configurable properties of a workflow. */
 export const WorkflowInputShape = {
   name: z.string().describe("Human-readable name of the resource."),
   slug: z.string().optional().describe("URL-friendly identifier (lowercase alphanumeric with hyphens). Auto-generated from name if omitted."),
@@ -70,7 +70,7 @@ type WorkflowDocumentInput = z.infer<typeof WorkflowDocumentInputSchema>;
 const RunConfigInputSchema = z.object({
   model_name: z.string().optional().describe("The model each run uses. Example: 'claude-sonnet-4-6'."),
   max_cost_usd: z.number().optional().describe("Maximum estimated cost in USD per run. The surface's platform execution profile caps this value; the lower bound wins."),
-  max_tool_rounds: z.number().optional().describe("Maximum model-to-tools reasoning cycles per run. The surface's platform execution profile caps this value; the lower bound wins. @internal An implementation knob, not a user concept: API-reachable for operators, deliberately absent from creation forms (DD-018 D-5)."),
+  max_tool_rounds: z.number().optional().describe("Maximum model-to-tools reasoning cycles per run. The surface's platform execution profile caps this value; the lower bound wins."),
   service_tier: z.string().optional().describe("Service tier for each run's model calls: standard (the default) or fast, where fast bills at the model's fast-tier rates and requires a model that offers one. In workflow YAML the shorthand spellings 'standard'/'fast' are accepted alongside the canonical enum names. Mirrors ExecutionConfig.service_tier: UNSPECIFIED inherits the surface's platform default, which itself resolves to STANDARD — never the provider account default. FAST requires model_name (here or from the platform profile) to name a model with a registry fast pricing variant; validated fail-closed at create. Allowed values: SERVICE_TIER_STANDARD, SERVICE_TIER_FAST."),
 });
 type RunConfigInput = z.infer<typeof RunConfigInputSchema>;
@@ -87,8 +87,8 @@ const GitRepoSourceInputSchema = z.object({
   url: z.string().describe("HTTPS clone URL for the repository."),
   branch: z.string().optional().describe("Branch to clone. When empty, the repository's default branch is used."),
   commit: z.string().optional().describe("Commit SHA to checkout after cloning. When set, the workspace is checked out at this exact commit. When both branch and commit are set, the branch is cloned first, then the commit is checked out."),
-  depth: z.number().optional().describe("Number of commits to include in the clone history. When not set, defaults to a shallow clone with depth 1. Set to 0 for a full clone with complete history. @internal Uses proto3 optional to distinguish 'not set' from 'set to 0.' Absent: shallow clone depth 1; 0: full clone; N > 0: shallow clone depth N."),
-  write_back_mode: z.string().optional().describe("Controls whether the platform creates a branch and pull request from the agent's file changes. @internal This is a platform-level workflow, not an agent-level decision. The agent focuses on making code changes; the platform packages them incrementally — the PR appears the moment the first file is written and the diff grows in real time as the agent works. Requires GITHUB_TOKEN in the execution environment. If credentials are not available, the write-back is silently skipped regardless of this setting. Default (UNSPECIFIED): platform decides. Currently defaults to write-back enabled when git credentials are available. Allowed values: GIT_WRITE_BACK_BRANCH_AND_PR."),
+  depth: z.number().optional().describe("Number of commits to include in the clone history. When not set, defaults to a shallow clone with depth 1. Set to 0 for a full clone with complete history."),
+  write_back_mode: z.string().optional().describe("Controls whether the platform creates a branch and pull request from the agent's file changes. Allowed values: GIT_WRITE_BACK_BRANCH_AND_PR."),
 });
 type GitRepoSourceInput = z.infer<typeof GitRepoSourceInputSchema>;
 
@@ -116,19 +116,19 @@ const EnvironmentRefInputSchema = z.object({
 type EnvironmentRefInput = z.infer<typeof EnvironmentRefInputSchema>;
 
 const AgentCallTaskConfigInputSchema = z.object({
-  agent: z.string().describe("Agent reference in 'org/slug' or 'slug' format. - 'slug' only: uses the workflow's organization - 'org/slug': explicit organization reference Examples: 'code-reviewer', 'stigmer/code-reviewer', 'acme/data-analyst' Required field. @internal The DSL string form of AgentInvocation.agent_ref. The structured ApiResourceReference shape is deliberately not used here: the authoring surface is YAML written by hand, and 'org/slug' is its idiom."),
+  agent: z.string().describe("Agent reference in 'org/slug' or 'slug' format. - 'slug' only: uses the workflow's organization - 'org/slug': explicit organization reference Examples: 'code-reviewer', 'stigmer/code-reviewer', 'acme/data-analyst' Required field."),
   message: z.string().describe("Instructions/prompt to send to the agent. Supports interpolation of workflow variables using JQ expressions. Example: 'Analyze this code: ${ $context.fetchCode.body }' Required field."),
   env: z.record(z.string()).optional().describe("Runtime environment variables to pass to the agent. Values can be literal strings or JQ expressions that reference workflow context or secrets. Example: {'GITHUB_TOKEN': '${ .secrets.GH_TOKEN }'} Optional."),
-  run_config: z.lazy(() => RunConfigInputSchema).optional().describe("Per-call model choice and run bounds. Unset fields inherit the platform defaults. @internal The shared RunConfig (DD-018 D-2) — the same message schedules embed, so the run-bound vocabulary cannot drift between triggering surfaces. Semantics at the workflow surface: model_name replaces the agent's default outright; max_cost_usd maps to ExecutionConfig.max_cost_usd and is enforced by the runner's harness-generic cost guards; max_tool_rounds maps to ExecutionConfig.max_tool_rounds (native harness only — inert on cursor, whose sole bound is cost). No platform clamp profile is applied at this surface yet: per the RunConfig contract, an unset platform cap means the owner value stands."),
+  run_config: z.lazy(() => RunConfigInputSchema).optional().describe("Per-call model choice and run bounds. Unset fields inherit the platform defaults."),
   output: z.lazy(() => AgentCallOutputContractInputSchema).optional().describe("Structured output contract for this agent call. When set, the workflow runner extracts structured JSON from the agent's final response and validates it against the declared schema. The validated JSON is placed in the task output under the 'structured' key, enabling reliable downstream routing via switch_case expressions. When not set, the task output contains the agent's raw text response. @since T02 (Structured Agent Output Model)"),
   harness: z.string().optional().describe("Execution harness for the agent invocation. Determines which execution engine processes the agent call: - HARNESS_UNSPECIFIED / HARNESS_NATIVE: Stigmer native engine (Python/LangGraph) - HARNESS_CURSOR: Cursor SDK engine (TypeScript/Cursor) The workflow-runner creates a Session with this harness before creating the AgentExecution. The harness is a session-level concern — it determines tool availability, state management, model access, and billing tier. When unspecified, defaults to HARNESS_NATIVE (the workflow surface's platform default). YAML Example: - code_review: call: agent with: agent: 'code-reviewer' harness: cursor message: 'Review this PR' Allowed values: HARNESS_NATIVE, HARNESS_CURSOR."),
-  workspace_entries: z.array(z.lazy(() => WorkspaceEntryInputSchema)).optional().describe("Workspace the child run's session operates on. Empty means no workspace. @internal The shared WorkspaceEntry type (AgentInvocation correspondence). Maps onto SessionSpec.workspace_entries of the session each call creates. Surface constraint, enforced in workflow validation (both editions): sources must be git_repo — no client is connected to serve a local_path when a workflow task fires. Credentials follow DD-018 D-4: the provisioner resolves GITHUB_TOKEN from the merged environment; for private repos the supported contract is an org-visibility Environment holding GITHUB_TOKEN bound via environment_refs. Public repos need no token."),
-  environment_refs: z.array(z.lazy(() => EnvironmentRefInputSchema)).optional().describe("References to Environment resources whose values are provided to the child runs this task creates. This is how a tool-using agent becomes runnable from a workflow: bind an org-shared environment holding the needed credentials, and the child runs receive its values at runtime. The agent and its default instance stay untouched. @internal The AgentShare/AgentChannel/Schedule environment_refs lineage. Never carried in the execution create request and never emitted into execution YAML: CreateExecutionContextStep resolves them from the Workflow row, gated on the trusted runner caller identity and keyed by parent_workflow_id + task label — prepended at LOWEST merge priority (instance refs and runtime_env override on key conflicts). No write-time existence or visibility check: enforcement lives solely at runtime resolution, which fails closed. When kind is unset in YAML, the DSL normalizer defaults it to environment."),
+  workspace_entries: z.array(z.lazy(() => WorkspaceEntryInputSchema)).optional().describe("Workspace the child run's session operates on. Empty means no workspace."),
+  environment_refs: z.array(z.lazy(() => EnvironmentRefInputSchema)).optional().describe("References to Environment resources whose values are provided to the child runs this task creates. This is how a tool-using agent becomes runnable from a workflow: bind an org-shared environment holding the needed credentials, and the child runs receive its values at runtime. The agent and its default instance stay untouched."),
 });
 type AgentCallTaskConfigInput = z.infer<typeof AgentCallTaskConfigInputSchema>;
 
 const CallActivityTaskConfigInputSchema = z.object({
-  activity: z.string().describe("Activity name to execute. @internal Must match a registered Temporal activity."),
+  activity: z.string().describe("Activity name to execute."),
   input: z.record(z.unknown()).optional().describe("Activity input (optional). Can be any JSON structure. Supports expressions in string values."),
 });
 type CallActivityTaskConfigInput = z.infer<typeof CallActivityTaskConfigInputSchema>;
@@ -238,8 +238,8 @@ const HumanInputTaskConfigInputSchema = z.object({
   timeout: z.number().optional().describe("Timeout in seconds before the on_timeout policy applies. Default: 0 (no timeout — the task waits indefinitely). Max: 2592000 (30 days). A timeout of 0 means the workflow will wait until a human responds. For production workflows, setting a timeout with an appropriate on_timeout policy is strongly recommended."),
   on_timeout: z.string().optional().describe("Policy applied when the timeout expires without a response. Only meaningful when timeout > 0; ignored when timeout is 0. Default: HUMAN_INPUT_TIMEOUT_FAIL (task fails with timeout error). Allowed values: HUMAN_INPUT_TIMEOUT_FAIL, HUMAN_INPUT_TIMEOUT_APPROVE, HUMAN_INPUT_TIMEOUT_DENY, HUMAN_INPUT_TIMEOUT_ESCALATE."),
   notification_channels: z.array(z.string()).optional().describe("Channel identifiers for sending approval request notifications. When the task starts, the runtime sends notifications through these channels to alert potential approvers. Format examples: - 'slack:#approvals' — Slack channel - 'email:ops@acme.com' — email address - 'teams:#incident-response' — Microsoft Teams channel The format and routing of notifications is a runtime concern (T13). The proto carries the identifiers; the runtime resolves them to actual notification providers configured in the workflow instance's environment."),
-  payload: z.unknown().optional().describe("Structured material for the reviewer to examine before deciding. Supports ${ } expression interpolation: the whole value can be a single expression string ('${ $context.draft_revision }') or an inline object/array whose nested strings carry embedded expressions. The runtime resolves expressions when the gate activates and attaches the resolved payload to the approval_requested event, so the approval record is permanently bound to exactly what the reviewer saw. Distinct from prompt (the instruction to the reviewer) and form_schema (the shape of the reviewer's response): payload is the thing under review — an article diff, a proposed record set, a generated plan. @internal Resolved payloads at or above the artifact promotion threshold (256KB) are stored in the artifact store; the approval_requested event then carries payload_artifact_id instead of the inline value. See ApprovalRequestedPayload in workflowexecution/v1/event.proto. Expression support is documented here rather than via the is_expression option, which annotates string fields only — matching how other Struct/Value-typed expression-bearing configs are handled. @since Review Payloads (stigmer/stigmer#234)"),
-  ui_hint: z.string().optional().describe("Hint identifying which UI should present the payload. A plain discriminator string (e.g. 'article-diff', 'infra-proposal') that embedding applications match against their registered review renderers. When no renderer is registered for the hint — or the gate is viewed from a surface without custom renderers (CLI, plain console) — the payload is shown as structured data by the built-in approval card, so workflows stay portable across surfaces. @internal Deliberately a hint, not a contract: an unrecognized value must never block the gate. Not expression-valued — the hint is workflow design, not runtime data. @since Review Payloads (stigmer/stigmer#234)"),
+  payload: z.unknown().optional().describe("Structured material for the reviewer to examine before deciding. Supports ${ } expression interpolation: the whole value can be a single expression string ('${ $context.draft_revision }') or an inline object/array whose nested strings carry embedded expressions. The runtime resolves expressions when the gate activates and attaches the resolved payload to the approval_requested event, so the approval record is permanently bound to exactly what the reviewer saw. Distinct from prompt (the instruction to the reviewer) and form_schema (the shape of the reviewer's response): payload is the thing under review — an article diff, a proposed record set, a generated plan."),
+  ui_hint: z.string().optional().describe("Hint identifying which UI should present the payload. A plain discriminator string (e.g. 'article-diff', 'infra-proposal') that embedding applications match against their registered review renderers. When no renderer is registered for the hint — or the gate is viewed from a surface without custom renderers (CLI, plain console) — the payload is shown as structured data by the built-in approval card, so workflows stay portable across surfaces."),
 });
 type HumanInputTaskConfigInput = z.infer<typeof HumanInputTaskConfigInputSchema>;
 
@@ -413,35 +413,35 @@ interface WorkflowTaskInput {
 const WorkflowTaskInputSchema: z.ZodType<WorkflowTaskInput> = z.lazy(() => z.object({
   name: z.string().optional().describe("Task name/identifier (must be unique within workflow). Must be a valid C-style identifier: starts with a letter or underscore, followed by letters, digits, or underscores."),
   kind: z.string().describe("Task type. Set the matching config field (e.g. kind='http_call' -> populate http_call). Allowed values: set_vars, http_call, grpc_call, activity_call, switch_case, for_each, fork, try_catch, listen, wait, raise_error, run_workflow, agent_call, llm_call, transform, human_input, validate, emit_event, notification, eval."),
-  agent_call: z.lazy(() => AgentCallTaskConfigInputSchema).optional().describe("Required when kind='agent_call'. AgentCallTaskConfig defines the configuration for agent_call tasks that invoke AI agents. @internal This message is the workflow DSL's adoption of the shared AgentInvocation vocabulary (agentexecution/v1/invocation.proto) at the TYPE level — issue stigmer/stigmer#358, per DD-018 (whatsapp-proactive-messaging, stigmer-cloud). Because WorkflowTask.task_config is a 'kind + Struct' envelope, this message IS the authoring schema: its field names are the YAML keys workflow authors write. Embedding AgentInvocation as a nested message would force either a nested 'invocation:' authoring block or flatten/unflatten rewrites in every Struct consumer, so the DSL stays flat and shares the vocabulary type-by-type instead. Field-by-field correspondence to AgentInvocation (keep in lockstep; a field added there must be consciously adopted or consciously excluded here, with the reason recorded): - agent ↔ agent_ref — the DSL string form ('org/slug'); the workflow runner parses it into an agent reference. - message ↔ message — expression-carrying in the DSL. - harness ↔ harness — same shared enum, same semantics. - run_config ↔ run_config — the shared message, embedded directly. - workspace_entries ↔ workspace_entries — same shared type; git sources only (no client is connected to serve a local_path when a workflow task fires). - environment_refs ↔ environment_refs — same shared type; resolved server-side at execution create, never carried in the create request (the schedule/channel/share posture). Surface-specific fields with their reasons (the DD-017/018 bucket discipline): - env: the workflow's context-forwarding channel. Values are JQ expressions resolved from workflow state/secrets at run time, not plaintext literals in a manifest — which is why AgentInvocation's runtime_env exclusion does not apply to it. - output: the structured-output contract is a workflow-routing concern (switch_case on typed fields), meaningless to other invocation surfaces. Deleted in the #358 clean break (no reserved numbers; task configs are stored as JSON Structs, so field numbers never hit a wire): - org: redundant with the 'org/slug' form of 'agent', and the proto→YAML converter never emitted it. - AgentExecutionConfig (timeout, temperature, context_management, max_cost_micros): declared knobs the runtime silently ignored. The cost cap lives on run_config.max_cost_usd and is now actually enforced; timeout/temperature had no runtime counterpart at all. The agent is referenced by org/slug format (e.g., 'stigmer/code-reviewer'). Resolution order: 1. 'org/slug': look in that org's agents 2. 'slug' only: use the workflow's org 3. Before external lookup, check manifest (current deployment) YAML Example (without structured output): - analyze: call: agent with: agent: 'code-reviewer' message: 'Review this code: ${ $context.fetchCode.body }' env: GITHUB_TOKEN: '${ .secrets.GH_TOKEN }' run_config: model_name: 'claude-sonnet-4-6' max_cost_usd: 0.50 YAML Example (with structured output): - triage_ticket: call: agent with: agent: 'support-triage' message: '${ .ticket.description }' output: schema: type: object required: [severity, category, customer_impact] properties: severity: type: string enum: [low, medium, high, critical] category: type: string customer_impact: type: boolean rationale: type: string on_invalid: ON_INVALID_RETRY max_retries: 2 fallback_task: human_review export: as: '${ .structured }'"),
-  activity_call: z.lazy(() => CallActivityTaskConfigInputSchema).optional().describe("Required when kind='activity_call'. CallActivityTaskConfig defines the configuration for activity_call tasks that execute activities. @internal Executes Temporal activities. YAML Example: - taskName: call: activity with: activity: 'ProcessDataActivity' input: data: ${ .data } Reference: zigflow-dsl-pattern-catalog.md - Task Type 10"),
-  emit_event: z.lazy(() => EmitEventTaskConfigInputSchema).optional().describe("Required when kind='emit_event'. EmitEventTaskConfig defines the configuration for emit_event tasks that publish CloudEvents to external consumers, other workflows, audit trails, and metrics systems. @internal emit_event is the complement to listen. While listen waits for Temporal signals (internal workflow primitives), emit_event publishes business events using the CloudEvents envelope (a standard external contract). The runtime (T13) bridges the two: an emitted CloudEvent can be delivered as a Temporal signal to another workflow's listen task, or routed to external consumers via message queues, webhooks, or event buses. The task output is the fully-resolved CloudEvents envelope with runtime-generated fields populated: { 'id': '<generated UUID>', 'specversion': '1.0', 'type': 'stigmer.workflow.ticket.classified', 'source': '/workflows/triage/executions/abc-123', 'time': '2026-05-12T14:30:00Z', 'subject': 'TICKET-456', 'datacontenttype': 'application/json', 'data': { <resolved payload> } } YAML Example (emit a classification event): - notify_classified: emit_event: event: type: 'stigmer.workflow.ticket.classified' subject: '${ $context.ticket.id }' data: ticket_id: '${ $context.ticket.id }' severity: '${ $context.triage.severity }' category: '${ $context.triage.category }' classified_by: '${ $context.workflow_instance_id }' export: as: '${ . }' YAML Example (emit with explicit source): - publish_completion: emit_event: event: type: 'acme.order.fulfilled' source: 'urn:acme:fulfillment-service' subject: '${ $context.order.number }' data: order_id: '${ $context.order.id }' status: 'fulfilled' fulfilled_at: '${ $context.timestamp }' export: as: '${ . }'"),
-  eval: z.lazy(() => EvalTaskConfigInputSchema).optional().describe("Required when kind='eval'. EvalTaskConfig defines the configuration for eval tasks that use an LLM judge to assess the semantic quality of workflow data. @internal Use eval when you need to assess quality, correctness, safety, or completeness of LLM-generated or agent-produced content. This fills the gap between structural validation (validate task — JSON Schema, business rules) and human review (human_input task — manual inspection). The eval task constructs a judge prompt from the rubric and subject, calls the specified LLM with structured output enforcement, parses the judge's response, and applies the threshold to determine pass/fail. Key differences from validate: - validate checks deterministic structural properties (schema, rules) - eval checks semantic quality via an LLM judge (hallucination, relevance, safety) Key differences from llm_call: - llm_call is a general-purpose LLM invocation - eval has built-in judge prompt construction, scoring semantics, threshold application, and on_fail branching Task output structure: { 'pass': true/false, 'score': 0.85, // present for numeric_score and multi_criteria 'reasoning': 'The response...', 'criteria': [ // present only for multi_criteria {'name': 'accuracy', 'score': 0.9, 'reasoning': '...'}, {'name': 'safety', 'score': 0.8, 'reasoning': '...'} ], 'model_used': 'gpt-4o', 'subject': <original subject data> } YAML Example (binary pass/fail evaluation): - check_summary_quality: call: eval with: model: 'gpt-4o' subject: '${ $context.summarize.text }' rubric: | Evaluate whether this summary accurately captures the key points of the source document without hallucinations or omissions. The summary should be concise (under 3 sentences) and factually correct. scoring_mode: EVAL_PASS_FAIL on_fail: EVAL_FAIL_BRANCH fallback_task: regenerate_summary export: as: '${ . }' YAML Example (numeric score with threshold): - score_translation: call: eval with: model: 'gpt-4o' subject: '${ $context.translate.text }' rubric: | Rate the quality of this translation on accuracy, fluency, and preservation of meaning. Score 0.0 (unusable) to 1.0 (perfect). scoring_mode: EVAL_NUMERIC_SCORE threshold: 0.7 on_fail: EVAL_FAIL_WARN export: as: '${ . }' YAML Example (multi-criteria evaluation): - evaluate_response: call: eval with: model: 'gpt-4o' subject: '${ $context.agent_response }' rubric: 'Evaluate this customer support response.' scoring_mode: EVAL_MULTI_CRITERIA threshold: 0.75 criteria: - name: accuracy description: 'Is the information factually correct?' weight: 3.0 - name: helpfulness description: 'Does it address the customer's actual question?' weight: 2.0 - name: tone description: 'Is the tone professional and empathetic?' weight: 1.0 on_fail: EVAL_FAIL_RAISE export: as: '${ . }'"),
-  for_each: z.lazy(() => ForTaskConfigInputSchema).optional().describe("Required when kind='for_each'. ForTaskConfig defines the configuration for for_each tasks that iterate over collections. @internal Supports both sequential (default) and parallel execution modes. When max_parallelism is set, iterations run concurrently using Temporal workflow goroutines with bounded concurrency. Backward compatibility: all new fields default to values that preserve the pre-T17 sequential behavior. Existing workflows require no changes. YAML Example (sequential, unchanged from pre-T17): - taskName: for: each: item in: ${ $data.items } do: - processItem: call: http with: method: POST body: item: ${ $data.item } index: ${ $data.index } YAML Example (parallel with bounded concurrency): - batchProcess: for: each: item in: ${ $data.items } max_parallelism: 5 on_error: FOR_EACH_CONTINUE do: - callApi: call: http with: method: POST endpoint: uri: 'https://api.example.com/process' body: item: ${ $data.item } Reference: zigflow-dsl-pattern-catalog.md - Task Type 4 @since max_parallelism, batch_size, on_error: T17 (Advanced Agentic Orchestration)"),
-  fork: z.lazy(() => ForkTaskConfigInputSchema).optional().describe("Required when kind='fork'. ForkTaskConfig defines the configuration for fork tasks that execute branches in parallel. @internal YAML Example: - taskName: fork: branches: - branch1: do: - task1: call: http with: method: POST endpoint: uri: https://api.example.com/branch1 - branch2: do: - task2: call: http Reference: zigflow-dsl-pattern-catalog.md - Task Type 5"),
-  grpc_call: z.lazy(() => GrpcCallTaskConfigInputSchema).optional().describe("Required when kind='grpc_call'. GrpcCallTaskConfig defines the configuration for grpc_call tasks that make gRPC requests. @internal YAML Example: - taskName: call: grpc with: service: 'com.example.UserService' method: 'GetUser' request: userId: ${ .userId } Reference: zigflow-dsl-pattern-catalog.md - Task Type 9"),
-  http_call: z.lazy(() => HttpCallTaskConfigInputSchema).optional().describe("Required when kind='http_call'. HttpCallTaskConfig defines the configuration for http_call tasks that make HTTP requests. @internal YAML Example: - taskName: call: http with: method: POST endpoint: uri: https://api.example.com/data headers: Authorization: 'Bearer ${TOKEN}' body: field1: value Reference: zigflow-dsl-pattern-catalog.md - Task Type 2"),
-  human_input: z.lazy(() => HumanInputTaskConfigInputSchema).optional().describe("Required when kind='human_input'. HumanInputTaskConfig defines the configuration for human_input tasks that pause workflow execution to collect typed input or approval from a human reviewer, then resume based on the reviewer's response. @internal Use human_input when a workflow needs human judgment before proceeding: approvals before API calls, sign-off before publishing, confirmation before customer-impacting actions, or structured data collection from a human operator. This is a workflow-level approval gate — distinct from agent-level HITL (tool approval inside an agent session). Workflow-level gates are visible in the execution viewer as explicit tasks with input/output/timing, and they can route to different branches based on the reviewer's decision. Runtime implementation (T13) will use Temporal signals for workflow resumption. The proto definition is intentionally runtime-agnostic. The reviewer's response (selected outcome + form data) becomes the task output, accessible via export: { 'outcome': 'approve', 'form_data': { <validated form response if form_schema is set> }, 'reviewer': '<canonical identity of the user who responded>', 'reviewer_actor': { 'id': '<canonical identity>', 'display_name': '<human-readable name, empty when unknown>', 'email': '<email address, empty when unknown>', 'avatar': '<avatar URL, empty when unknown>' }, 'responded_at': '<ISO 8601 timestamp>' } 'reviewer' is the stable audit key (use it in switch conditions and audit joins); 'reviewer_actor' is a display snapshot stamped server-side at decision time (use it in notifications and UIs). Both are absent when the gate resolves without attribution (timeout policies, OSS single-user edition). YAML Example (approval gate with custom outcomes): - manager_approval: human_input: prompt: 'Customer-impacting incident classified as ${ $context.triage.severity }. Approve escalation?' form_schema: type: object properties: notes: type: string description: 'Optional notes for the engineering team' priority_override: type: string enum: [P1, P2, P3] outcomes: - name: approve label: 'Approve Escalation' - name: deny label: 'Reject — Not Customer-Impacting' then: re_classify - name: needs_revision label: 'Needs More Info' then: gather_more_context approvers: - 'team:engineering-leads' timeout: 86400 on_timeout: HUMAN_INPUT_TIMEOUT_ESCALATE notification_channels: - 'slack:#incident-approvals' export: as: '${ . }' YAML Example (simple binary approval, no form): - confirm_publish: human_input: prompt: 'Ready to publish ${ $context.document.title } to production?' approvers: - 'role:content-admin' timeout: 3600 on_timeout: HUMAN_INPUT_TIMEOUT_FAIL export: as: '${ . }'"),
-  listen: z.lazy(() => ListenTaskConfigInputSchema).optional().describe("Required when kind='listen'. ListenTaskConfig defines the configuration for listen tasks that wait for external signals. @internal Implemented via Temporal signals. YAML Example: - taskName: listen: to: one: with: id: approval_signal type: signal Reference: zigflow-dsl-pattern-catalog.md - Task Type 7"),
-  llm_call: z.lazy(() => LlmCallTaskConfigInputSchema).optional().describe("Required when kind='llm_call'. LlmCallTaskConfig defines the configuration for llm_call tasks that make direct LLM API calls without the overhead of a full agent invocation. @internal Use llm_call when the task is focused and deterministic: classification, extraction, scoring, summarization, moderation, or routing. An agent_call carries setup overhead (system prompt, tool resolution, MCP server setup, session management) that is unnecessary when all you need is a single prompt-response cycle with optional structured output. When response_schema is set, the runner requests structured output from the provider and validates the response against the schema. The on_invalid / max_retries / fallback_task fields control what happens when validation fails, using the same OnInvalidOutputPolicy enum as agent_call's output contract. YAML Example (classification with structured output): - classify_severity: call: llm with: model: 'gpt-4o-mini' system_prompt: 'You are a support ticket classifier.' prompt: 'Classify this ticket: ${ $context.ticket.description }' response_schema: type: object required: [severity, category] properties: severity: type: string enum: [low, medium, high, critical] category: type: string on_invalid: ON_INVALID_RETRY max_retries: 2 export: as: '${ . }' YAML Example (simple summarization, no schema): - summarize: call: llm with: model: 'claude-sonnet-4-5' prompt: 'Summarize in 2 sentences: ${ $context.document.text }' temperature: 0.3 max_tokens: 200 export: as: '${ . }'"),
-  notification: z.lazy(() => NotificationTaskConfigInputSchema).optional().describe("Required when kind='notification'. NotificationTaskConfig defines the configuration for notification tasks that send messages to humans through channels like Slack, email, Discord, Microsoft Teams, or webhooks. @internal notification is a convenience abstraction for 'send a message to humans' — simpler and more intuitive than emit_event for common operational notification patterns. While emit_event publishes system-level CloudEvents for machine consumption, notification is purpose-built for human-readable messages with channel routing and recipient targeting. Key distinction from related task types: emit_event = system-to-system (CloudEvents, consumed by workflows/services) notification = system-to-human (Slack, email, Discord — read by people) human_input = system-to-human-to-system (waits for a response; notification is fire-and-forget) Notifications are fire-and-forget by default. The task output confirms delivery was attempted but does not wait for acknowledgment: { 'channel': 'slack', 'recipients': ['#incident-response'], 'delivered': true, 'delivered_at': '<ISO 8601 timestamp>' } For notifications that require acknowledgment or a response, use human_input instead — it pauses the workflow until a human responds. The channel field is a string (not an enum) to allow extensibility: new notification channels can be added without proto changes. The runtime (T13) resolves channel identifiers to actual notification providers configured in the workflow instance's environment. YAML Example (Slack notification): - alert_slack: notification: channel: 'slack' recipients: - '#incident-response' - '@oncall-lead' subject: 'P${ $context.triage.severity } Incident: ${ $context.ticket.title }' body: | *Severity*: ${ $context.triage.severity } *Category*: ${ $context.triage.category } *Customer Impact*: ${ $context.triage.customer_impact } *Summary*: ${ $context.agent_analysis.structured.summary } metadata: thread_ts: '${ $context.slack_thread_id }' export: as: '${ . }' YAML Example (email with template): - send_confirmation: notification: channel: 'email' recipients: - '${ $context.customer.email }' subject: 'Order ${ $context.order.number } Confirmed' body: 'Your order has been confirmed. You will receive tracking information shortly.' template: 'order-confirmation' metadata: priority: 'high' reply_to: 'support@acme.com' export: as: '${ . }'"),
-  raise_error: z.lazy(() => RaiseTaskConfigInputSchema).optional().describe("Required when kind='raise_error'. RaiseTaskConfig defines the configuration for raise_error tasks that raise errors. @internal YAML Example: - taskName: raise: error: ValidationError message: ${ .errorMessage } Reference: zigflow-dsl-pattern-catalog.md - Task Type 11"),
-  run_workflow: z.lazy(() => RunTaskConfigInputSchema).optional().describe("Required when kind='run_workflow'. RunTaskConfig defines the configuration for run_workflow tasks that execute sub-workflows. @internal Implemented via Temporal child workflows. YAML Example: - taskName: run: workflow: 'sub-workflow-name' input: data: ${ .data } Reference: zigflow-dsl-pattern-catalog.md - Task Type 12"),
-  set_vars: z.lazy(() => SetTaskConfigInputSchema).optional().describe("Required when kind='set_vars'. SetTaskConfig defines the configuration for set_vars tasks that assign variables in workflow state. @internal YAML Example: - taskName: set: variable1: value variable2: ${ expression } computed: ${ .a + .b } Reference: zigflow-dsl-pattern-catalog.md - Task Type 1"),
-  switch_case: z.lazy(() => SwitchTaskConfigInputSchema).optional().describe("Required when kind='switch_case'. SwitchTaskConfig defines the configuration for switch_case tasks that branch conditionally. @internal YAML Example: - taskName: switch: - case1: when: ${ $context.value > 5 } then: highValueTask - defaultCase: then: unknownTask Reference: zigflow-dsl-pattern-catalog.md - Task Type 3"),
-  transform: z.lazy(() => TransformTaskConfigInputSchema).optional().describe("Required when kind='transform'. TransformTaskConfig defines the configuration for transform tasks that perform deterministic data transformation without LLM calls. @internal Use transform when you need to reshape data between tasks: projecting fields, joining objects, converting formats, or building API payloads. Unlike set_vars (which mutates workflow state variables as a side effect), transform produces an explicit output that flows through export like any other task — visible and inspectable in the execution viewer. The distinction from set_vars: set_vars = imperative assignment ('set X to Y'), mutates workflow context transform = functional transformation ('reshape this data'), produces output YAML Example (JQ — reshape data for an API call): - build_api_payload: transform: engine: jq expression: '{name: .customer.full_name, severity: .triage.severity, summary: .agent_analysis.structured.summary}' input: '${ $context }' export: as: '${ . }' YAML Example (template — render a notification message): - render_notification: transform: engine: template expression: 'Ticket {{ .ticket_id }} classified as {{ .severity }} — {{ .summary }}' input: '${ $context.build_api_payload }' export: as: '${ . }'"),
-  try_catch: z.lazy(() => TryTaskConfigInputSchema).optional().describe("Required when kind='try_catch'. TryTaskConfig defines the configuration for try_catch tasks that handle errors. @internal YAML Example: - taskName: try: - attemptTask: call: http with: method: POST endpoint: uri: https://api.example.com/flaky catch: as: error do: - errorHandler: call: http with: body: error: ${ .error } Reference: zigflow-dsl-pattern-catalog.md - Task Type 6"),
-  validate: z.lazy(() => ValidateTaskConfigInputSchema).optional().describe("Required when kind='validate'. ValidateTaskConfig defines the configuration for validate tasks that perform explicit schema and business-rule validation on workflow data. @internal Use validate when you need an explicit validation checkpoint before downstream actions. This is how you distinguish 'the API call succeeded' from 'the data is safe and complete enough to continue.' While switch_case + raise_error can approximate validation, a dedicated validate task makes the intent explicit, the error messages richer, and the execution trace clearer. In the execution viewer (T09), a validate task shows exactly what was checked, what passed, and what failed — visible as a distinct verification step. The task supports two complementary validation modes: - schema: JSON Schema validation for structural correctness - rules: business-rule expressions for domain-specific constraints At least one of schema or rules must be set. Both can be used together for comprehensive validation (schema checks structure, rules check business logic). This cross-field constraint is enforced at runtime validation since buf.validate cannot express it on individual fields. Task output includes the full validation result: { 'valid': true/false, 'errors': [ {'rule': 'critical_needs_rationale', 'message': 'Critical severity requires a rationale'}, {'path': '$.category', 'message': 'must have at least 1 character'} ], 'data': <original input data> } YAML Example (schema + business rules): - check_triage_quality: validate: input: '${ $context.triage }' schema: type: object required: [severity, category, customer_impact] properties: severity: type: string enum: [low, medium, high, critical] category: type: string minLength: 1 customer_impact: type: boolean rules: - name: critical_needs_rationale expression: '${ .severity != 'critical' || (.rationale != null && .rationale != '') }' message: 'Critical severity requires a rationale' - name: customer_impact_needs_severity expression: '${ .customer_impact != true || .severity in ['high', 'critical'] }' message: 'Customer-impacting issues must be high or critical severity' on_fail: VALIDATION_FAIL_BRANCH fallback_task: human_review export: as: '${ . }' YAML Example (schema-only validation with warn policy): - check_payload_shape: validate: input: '${ $context.api_payload }' schema: type: object required: [name, email] properties: name: type: string email: type: string format: email on_fail: VALIDATION_FAIL_WARN export: as: '${ . }'"),
-  wait: z.lazy(() => WaitTaskConfigInputSchema).optional().describe("Required when kind='wait'. WaitTaskConfig defines the configuration for wait tasks that pause workflow execution. Supports both relative durations and absolute timestamps. @internal Implemented via Temporal timers. YAML Examples: Relative duration: - waitForApproval: wait: duration: days: 7 Absolute timestamp: - waitUntilMarketOpen: wait: until: '2026-03-02T09:30:00Z' Reference: zigflow-dsl-pattern-catalog.md - Task Type 8"),
+  agent_call: z.lazy(() => AgentCallTaskConfigInputSchema).optional().describe("Required when kind='agent_call'. AgentCallTaskConfig defines the configuration for agent_call tasks that invoke AI agents."),
+  activity_call: z.lazy(() => CallActivityTaskConfigInputSchema).optional().describe("Required when kind='activity_call'. CallActivityTaskConfig defines the configuration for activity_call tasks that execute activities."),
+  emit_event: z.lazy(() => EmitEventTaskConfigInputSchema).optional().describe("Required when kind='emit_event'. EmitEventTaskConfig defines the configuration for emit_event tasks that publish CloudEvents to external consumers, other workflows, audit trails, and metrics systems."),
+  eval: z.lazy(() => EvalTaskConfigInputSchema).optional().describe("Required when kind='eval'. EvalTaskConfig defines the configuration for eval tasks that use an LLM judge to assess the semantic quality of workflow data."),
+  for_each: z.lazy(() => ForTaskConfigInputSchema).optional().describe("Required when kind='for_each'. ForTaskConfig defines the configuration for for_each tasks that iterate over collections."),
+  fork: z.lazy(() => ForkTaskConfigInputSchema).optional().describe("Required when kind='fork'. ForkTaskConfig defines the configuration for fork tasks that execute branches in parallel."),
+  grpc_call: z.lazy(() => GrpcCallTaskConfigInputSchema).optional().describe("Required when kind='grpc_call'. GrpcCallTaskConfig defines the configuration for grpc_call tasks that make gRPC requests."),
+  http_call: z.lazy(() => HttpCallTaskConfigInputSchema).optional().describe("Required when kind='http_call'. HttpCallTaskConfig defines the configuration for http_call tasks that make HTTP requests."),
+  human_input: z.lazy(() => HumanInputTaskConfigInputSchema).optional().describe("Required when kind='human_input'. HumanInputTaskConfig defines the configuration for human_input tasks that pause workflow execution to collect typed input or approval from a human reviewer, then resume based on the reviewer's response."),
+  listen: z.lazy(() => ListenTaskConfigInputSchema).optional().describe("Required when kind='listen'. ListenTaskConfig defines the configuration for listen tasks that wait for external signals."),
+  llm_call: z.lazy(() => LlmCallTaskConfigInputSchema).optional().describe("Required when kind='llm_call'. LlmCallTaskConfig defines the configuration for llm_call tasks that make direct LLM API calls without the overhead of a full agent invocation."),
+  notification: z.lazy(() => NotificationTaskConfigInputSchema).optional().describe("Required when kind='notification'. NotificationTaskConfig defines the configuration for notification tasks that send messages to humans through channels like Slack, email, Discord, Microsoft Teams, or webhooks."),
+  raise_error: z.lazy(() => RaiseTaskConfigInputSchema).optional().describe("Required when kind='raise_error'. RaiseTaskConfig defines the configuration for raise_error tasks that raise errors."),
+  run_workflow: z.lazy(() => RunTaskConfigInputSchema).optional().describe("Required when kind='run_workflow'. RunTaskConfig defines the configuration for run_workflow tasks that execute sub-workflows."),
+  set_vars: z.lazy(() => SetTaskConfigInputSchema).optional().describe("Required when kind='set_vars'. SetTaskConfig defines the configuration for set_vars tasks that assign variables in workflow state."),
+  switch_case: z.lazy(() => SwitchTaskConfigInputSchema).optional().describe("Required when kind='switch_case'. SwitchTaskConfig defines the configuration for switch_case tasks that branch conditionally."),
+  transform: z.lazy(() => TransformTaskConfigInputSchema).optional().describe("Required when kind='transform'. TransformTaskConfig defines the configuration for transform tasks that perform deterministic data transformation without LLM calls."),
+  try_catch: z.lazy(() => TryTaskConfigInputSchema).optional().describe("Required when kind='try_catch'. TryTaskConfig defines the configuration for try_catch tasks that handle errors."),
+  validate: z.lazy(() => ValidateTaskConfigInputSchema).optional().describe("Required when kind='validate'. ValidateTaskConfig defines the configuration for validate tasks that perform explicit schema and business-rule validation on workflow data."),
+  wait: z.lazy(() => WaitTaskConfigInputSchema).optional().describe("Required when kind='wait'. WaitTaskConfig defines the configuration for wait tasks that pause workflow execution. Supports both relative durations and absolute timestamps."),
   export: z.lazy(() => ExportInputSchema).optional().describe("Export configuration (how to save task output to context). Optional - if not set, output is not saved."),
   flow: z.lazy(() => FlowControlInputSchema).optional().describe("Flow control (which task executes next). Optional - if not set, continues to next task in sequence."),
-  compensate: z.array(z.lazy(() => WorkflowTaskInputSchema)).optional().describe("Compensation tasks to execute if this task needs to be 'undone.' @internal Saga-style compensation for workflows with side effects. When a try_catch block catches an error, it can optionally run the compensation tasks for all already-completed tasks in reverse order. The compensation tasks receive the original task's output in their input context, allowing them to construct the appropriate undo operation (e.g., cancel an API call, delete a created resource, send a reversal notification). Only executed when: 1. The task completed successfully (failed tasks are not compensated) 2. A subsequent task within the same try_catch scope fails 3. The catch block is configured to run compensations YAML Example: try: - create_order: call: http with: method: POST endpoint: { uri: 'https://api.example.com/orders' } body: { ... } compensate: - cancel_order: call: http with: method: DELETE endpoint: { uri: 'https://api.example.com/orders/${ $context.create_order.id }' } export: as: '${ . }' - charge_payment: call: http with: method: POST endpoint: { uri: 'https://api.example.com/payments' } catch: as: error compensate: true do: - log_failure: call: notification with: ... Optional - when empty, this task has no compensation action. @since T17 (Advanced Agentic Orchestration)"),
+  compensate: z.array(z.lazy(() => WorkflowTaskInputSchema)).optional().describe("Compensation tasks to execute if this task needs to be 'undone.'"),
 }));
 
 const EnvVarDeclarationInputSchema = z.object({
-  is_secret: z.boolean().optional().describe("Whether the resolved value should be treated as a secret. @internal When true: encrypted at rest, redacted in logs and Temporal history. When false: stored as plaintext, visible in audit logs."),
+  is_secret: z.boolean().optional().describe("Whether the resolved value should be treated as a secret."),
   description: z.string().optional().describe("Human-readable description shown in the UI credential form. Should explain what the variable is used for and where to obtain it."),
-  optional: z.boolean().optional().describe("Whether this variable is optional. @internal When false (default): the execution pipeline rejects a run if this variable is missing from the user's environment. When true: a missing value is acceptable (the MCP server or agent degrades gracefully without it)."),
+  optional: z.boolean().optional().describe("Whether this variable is optional."),
 });
 type EnvVarDeclarationInput = z.infer<typeof EnvVarDeclarationInputSchema>;