# Stacksona Docs Full LLM Export This file combines the public Stacksona integration docs into one Markdown context file. --- # AI should choose the path. You govern the moment it acts. Source: https://docs.stacksona.com/ Markdown: https://docs.stacksona.com/index.md Add policy and human review to governed agent actions without rebuilding your runtime or workflow. Start here Give a runtime a task, context, memory, and a set of tools. It reasons, chooses a capability, observes the result, and decides what to do next. Stacksona Gate stays at the execution boundary so the AI can remain flexible while policy and humans control the actions that matter. 01 Goal, not workflow Tell the runtime the outcome. Do not predesign every possible route. 02 Tools, not steps Expose capabilities. The AI chooses what it needs and in what order. 03 Govern execution Gate the exact side effect, not the AI's reasoning loop. ## Interactive architecture: all components ### Task + Context The runtime starts with an outcome, current context, and whatever memory your application provides. It receives a goal, not a fixed sequence. - Goal + constraints - Conversation + memory - No hard-coded route ``` const task = { id: 'refund-1042', goal: 'Resolve eligible refund requests', context: customerCase, memory: await loadTaskMemory('refund-1042') }; ``` ### AI Runtime Node Your runtime owns reasoning. It can use new tool results, memory, and reviewer feedback to decide what the next useful action should be. - Plans dynamically - Adapts from outcomes - Runtime keeps model credentials ``` const next = await runtime.plan({ goal: task.goal, context: task.context, memory: task.memory, tools: availableTools }); // next = { tool_name, arguments } ``` ### Available Tools Tools are capabilities the runtime may choose from. They are not a workflow diagram. Gate can optionally supply governed descriptions and input schemas. - Capabilities, not steps - Runtime chooses the order - Optional Gate contracts ``` const toolRegistry = { send_email: sendEmail, issue_refund: issueRefund, update_crm: updateCrm }; const contracts = await gate('/api/agent/tools/resolve', { tools: Object.keys(toolRegistry) }); ``` ### Stacksona Gate Immediately before a governed side effect, send the exact selected tool and final arguments to Gate. This is the stable safety boundary no matter which path the AI created. - Policy check - Human review when needed - Audit + approval proof ``` const decision = await gate( \`/api/agent/tasks/${encodeURIComponent(task.id)}/requests\`, { tool_name: next.tool_name, payload: next.arguments } ); ``` ### Human Review When Needed Human review is not a mandatory workflow step. Gate only pauses the exact action when policy requires a decision, and the runtime can resume the same review later. - Exact thread persists - Workflow can yield - Feedback returns as context ``` if (decision.status === 'pending_review') { await saveReviewState({ task_id: task.id, thread_id: decision.thread_id, proposal: next }); return { state: 'waiting_for_human' }; } ``` ### Execute Tool Only an executable decision reaches the real tool. Capture the result and return it to the runtime loop rather than treating one tool call as task completion. - Validate proof when required - Execute exact proposed arguments - Capture the tool result ``` if (decision.status === 'approved' && decision.approval_token) { const proof = await gate('/api/agent/approvals/validate', { task_id: task.id, signature: decision.approval_token }); if (!proof?.valid) throw new Error('Invalid approval proof'); } if (!['allow', 'approved'].includes(decision.status)) { return runtime.handleDecision(decision); } const result = await toolRegistry[next.tool_name](next.arguments); ``` ### Observe, Update Context, Repeat After each tool call, the result becomes new context. The runtime reasons again and either chooses another tool or decides the goal is complete. - Result becomes context - Runtime re-plans from the current state - No predefined number or order of actions ``` task.memory.push({ tool: next.tool_name, result }); const nextDecision = await runtime.plan({ goal: task.goal, context: task.context, memory: task.memory, tools: availableTools }); // If the goal is not complete, Gate + execute the next chosen tool. // Then observe its result and run this loop again. ``` ### Final Output The runtime exits the action loop only when it determines the task goal is complete. The final response is separate from any intermediate tool result. - Completion is decided by the runtime - Intermediate actions stay inside the loop - Return one final task result ``` if (nextDecision.done) { return nextDecision.output; } // Otherwise continue the runtime loop. ``` ## The runtime loop stays simple - **Reason from the task and current context.** The runtime decides what it needs next using the goal, prior tool results, memory, and reviewer feedback. - **Choose a tool and build its exact arguments.** The AI selects from the capabilities you expose. It is not selecting a prebuilt workflow path. - **Gate only the action that is about to execute.** Allowed actions continue immediately. Reviewable actions wait without breaking the workflow. Requested changes go back to the runtime as new context. - **Observe the result and run the loop again.** The tool outcome becomes context. If the task is not complete, the runtime reasons again, chooses another capability, and Gate governs that next action. - **Return final output only when the task is complete.** Intermediate tool results stay inside the runtime loop. The runtime exits only when it determines the goal has been satisfied. “Learn” here means the runtime can adapt from context and outcomes. Stacksona does not train the model. Your runtime can use tool results, reviewer feedback, memory, and prior outcomes to make better next-step decisions while Gate keeps governed execution controlled. ## Choose your integration shape [Code runtime Wrap a function or tool Use this when you own the code that executes the action. Node, agent frameworks, backend services](integrations/node-typescript/index.html) [Workflow platform Put Gate before the side-effect step Use this when actions are workflow nodes, modules, or app steps. n8n, Zapier, Make, Dify](integrations/n8n/index.html) [Tool / proxy Wrap the executable tool boundary Use this when tools are exposed through MCP, a proxy, or a shared action service. MCP, shared tools, service wrappers](integrations/mcp/index.html) Find your platform ## Popular guides [### Node / TypeScript Code Minimal function wrapper around execution.](integrations/node-typescript/index.html) [### n8n Native node Put Stacksona immediately before governed action nodes.](integrations/n8n/index.html) [### MCP Tools Enforce Gate in the tool wrapper, not only in model instructions.](integrations/mcp/index.html) [### REST API Universal Call Gate directly from any HTTP-capable runtime.](integrations/custom-rest/index.html) You do not need every Gate feature to start. Tool-contract resolution, revision events, signed approvals, webhooks, detailed event logging, and advanced decision handling are available when your workflow needs them. Start with the execution check first. Advanced and reference docs [### Gate API Full endpoint and schema reference.](reference/api-contract/index.html) [### Decision states Exact status semantics and fail-closed behavior.](reference/decision-statuses/index.html) [### Security Signed proof, credentials, and verification.](reference/security/index.html) [### Patterns Durable review, revisions, and runtime patterns.](patterns/index.html) --- # Stacksona for Copilot Studio Source: https://docs.stacksona.com/integrations/copilot-studio Markdown: https://docs.stacksona.com/integrations/copilot-studio.md Wrap governed Copilot actions in a connector, Power Automate flow, HTTP action, or service that checks Gate before execution. Workflow platform Wrap governed Copilot actions in a connector, Power Automate flow, HTTP action, or service that checks Gate before execution. Where Gate goes ## Inside the action, connector, flow, or service that owns the real side effect. Keep the platform's normal reasoning and orchestration. Gate only the exact action at the last safe point before execution. Copilot selects action → Governed connector/flow checks Gate → Action executes or conversation continues ## Start here - **Build the final action.** Let Copilot Studio choose the action and produce the arguments it intends to execute. - **Check the exact action with Gate.** Send tool_name and the final payload immediately before the side effect. - **Follow one of four outcomes.** Continue, wait, revise, or stop. You do not need the advanced features to get this basic path working. ## Minimal setup When a built-in action cannot be intercepted safely, replace the raw action with a governed connector or service wrapper that owns both the Gate check and the real execution. ## Handle the decision | Outcome | Gate status | What Copilot Studio should do | | --- | --- | --- | | Continue | allow or approved | Execute the exact proposed action. If signed proof is required, validate it first. | | Wait | pending_review | Store thread_id and resume that exact review later. | | Revise | changes_requested | Return reviewer feedback to the part of the runtime that can revise the proposal. | | Stop | reject or rejected | Do not execute. Replan, fall back, or end the action. | Unknown or failed decision = stop. Fail closed if Gate cannot be reached, returns an unknown state, or required approval proof is missing or invalid. ## Platform notes - Keep conversation reasoning and action selection in the Microsoft stack. - Store exact review state in flow, conversation, or external durable state. - Return reviewer-requested changes to the Copilot or planning path. Advanced: review threads, revisions, proof, and audit task_id is your grouping ID. thread_id identifies the exact Gate review and should be persisted whenever work can pause. For changes_requested , revise on the same review thread using the revision event contract. For high-impact actions that require signed proof, validate the returned approval token before execution. Log execution success or failure when you need complete audit evidence. For long reviews, use the platform's durable continuation mechanism instead of keeping a process, workflow, or runner open. Advanced runtime patterns Full Gate API Exact decision states --- # Stacksona for CrewAI Source: https://docs.stacksona.com/integrations/crewai Markdown: https://docs.stacksona.com/integrations/crewai.md Wrap side-effecting CrewAI tools so the crew can reason and delegate normally while Gate controls execution. Code runtime Wrap side-effecting CrewAI tools so the crew can reason and delegate normally while Gate controls execution. Where Gate goes ## Inside each governed tool wrapper that owns the real side effect. Keep the platform's normal reasoning and orchestration. Gate only the exact action at the last safe point before execution. Crew chooses tool → Governed wrapper checks Gate → Tool executes or crew replans ## Start here - **Build the final action.** Let CrewAI choose the action and produce the arguments it intends to execute. - **Check the exact action with Gate.** Send tool_name and the final payload immediately before the side effect. - **Follow one of four outcomes.** Continue, wait, revise, or stop. You do not need the advanced features to get this basic path working. ## Minimal setup Give agents the governed tool wrapper, not both the governed wrapper and the raw side-effecting implementation. The wrapper should carry useful reviewer context such as the task, subject, and proposed payload. ## Handle the decision | Outcome | Gate status | What CrewAI should do | | --- | --- | --- | | Continue | allow or approved | Execute the exact proposed action. If signed proof is required, validate it first. | | Wait | pending_review | Store thread_id and resume that exact review later. | | Revise | changes_requested | Return reviewer feedback to the part of the runtime that can revise the proposal. | | Stop | reject or rejected | Do not execute. Replan, fall back, or end the action. | Unknown or failed decision = stop. Fail closed if Gate cannot be reached, returns an unknown state, or required approval proof is missing or invalid. ## Platform notes - Keep multi-agent reasoning and delegation in CrewAI. - Persist the exact review thread in task or crew state if work can pause. - Return requested-change feedback to the agent that can revise the proposal. Advanced: review threads, revisions, proof, and audit task_id is your grouping ID. thread_id identifies the exact Gate review and should be persisted whenever work can pause. For changes_requested , revise on the same review thread using the revision event contract. For high-impact actions that require signed proof, validate the returned approval token before execution. Log execution success or failure when you need complete audit evidence. For long reviews, use the platform's durable continuation mechanism instead of keeping a process, workflow, or runner open. Advanced runtime patterns Full Gate API Exact decision states --- # Stacksona for Custom REST Source: https://docs.stacksona.com/integrations/custom-rest Markdown: https://docs.stacksona.com/integrations/custom-rest.md Call the Gate Agent API directly from any HTTP-capable runtime before executing the governed action. Code runtime Call the Gate Agent API directly from any HTTP-capable runtime before executing the governed action. Where Gate goes ## In your service or runtime immediately before the external API call, write, deployment, mutation, or other side effect. Keep the platform's normal reasoning and orchestration. Gate only the exact action at the last safe point before execution. Runtime builds request → POST exact action to Gate → Execute, wait, revise, or stop ## Start here - **Build the final action.** Let Custom REST choose the action and produce the arguments it intends to execute. - **Check the exact action with Gate.** Send tool_name and the final payload immediately before the side effect. - **Follow one of four outcomes.** Continue, wait, revise, or stop. You do not need the advanced features to get this basic path working. ## Minimal setup ``` curl -sS -X POST "$STACKSONA_GATE_URL/api/agent/tasks/order-1042/requests" \ -H "Authorization: Bearer $STACKSONA_API_KEY" \ -H "Content-Type: application/json" \ -d '{"tool_name":"issue_refund","payload":{"amount":389.99,"currency":"usd"}}' ``` ## Handle the decision | Outcome | Gate status | What Custom REST should do | | --- | --- | --- | | Continue | allow or approved | Execute the exact proposed action. If signed proof is required, validate it first. | | Wait | pending_review | Store thread_id and resume that exact review later. | | Revise | changes_requested | Return reviewer feedback to the part of the runtime that can revise the proposal. | | Stop | reject or rejected | Do not execute. Replan, fall back, or end the action. | Unknown or failed decision = stop. Fail closed if Gate cannot be reached, returns an unknown state, or required approval proof is missing or invalid. ## Platform notes - Only tool_name is required for the decision request; add reviewer context as useful. - Prefer exact thread_id when resuming a human review. - Use webhooks or durable jobs when a review may take longer than one live request. Advanced: review threads, revisions, proof, and audit task_id is your grouping ID. thread_id identifies the exact Gate review and should be persisted whenever work can pause. For changes_requested , revise on the same review thread using the revision event contract. For high-impact actions that require signed proof, validate the returned approval token before execution. Log execution success or failure when you need complete audit evidence. For long reviews, use the platform's durable continuation mechanism instead of keeping a process, workflow, or runner open. Advanced runtime patterns Full Gate API Exact decision states --- # Stacksona for Dify Source: https://docs.stacksona.com/integrations/dify Markdown: https://docs.stacksona.com/integrations/dify.md Put a Gate HTTP node or governed action service immediately before the Dify action that changes the outside world. Workflow platform Put a Gate HTTP node or governed action service immediately before the Dify action that changes the outside world. Where Gate goes ## In the governed workflow branch before the side-effecting HTTP, tool, or action node. Keep the platform's normal reasoning and orchestration. Gate only the exact action at the last safe point before execution. Agent/router chooses branch → Gate HTTP/action service checks it → Action executes or branch returns ## Start here - **Build the final action.** Let Dify choose the action and produce the arguments it intends to execute. - **Check the exact action with Gate.** Send tool_name and the final payload immediately before the side effect. - **Follow one of four outcomes.** Continue, wait, revise, or stop. You do not need the advanced features to get this basic path working. ## Minimal setup If a Dify-managed tool cannot be intercepted before execution, expose that capability through a governed HTTP wrapper service and let Dify call the wrapper instead of the raw service. ## Handle the decision | Outcome | Gate status | What Dify should do | | --- | --- | --- | | Continue | allow or approved | Execute the exact proposed action. If signed proof is required, validate it first. | | Wait | pending_review | Store thread_id and resume that exact review later. | | Revise | changes_requested | Return reviewer feedback to the part of the runtime that can revise the proposal. | | Stop | reject or rejected | Do not execute. Replan, fall back, or end the action. | Unknown or failed decision = stop. Fail closed if Gate cannot be reached, returns an unknown state, or required approval proof is missing or invalid. ## Platform notes - Keep Dify LLM, Agent, router, and workflow logic unchanged. - Route changes_requested back to the LLM, template, or parameter revision path. - For long reviews, use callback or a separate continuation workflow. Advanced: review threads, revisions, proof, and audit task_id is your grouping ID. thread_id identifies the exact Gate review and should be persisted whenever work can pause. For changes_requested , revise on the same review thread using the revision event contract. For high-impact actions that require signed proof, validate the returned approval token before execution. Log execution success or failure when you need complete audit evidence. For long reviews, use the platform's durable continuation mechanism instead of keeping a process, workflow, or runner open. Advanced runtime patterns Full Gate API Exact decision states --- # Stacksona for GitHub Actions Source: https://docs.stacksona.com/integrations/github-actions Markdown: https://docs.stacksona.com/integrations/github-actions.md Check the exact deployment, release, migration, or production operation immediately before the job performs it. Tool / proxy Check the exact deployment, release, migration, or production operation immediately before the job performs it. Where Gate goes ## In the job or script directly before the production side effect. Keep the platform's normal reasoning and orchestration. Gate only the exact action at the last safe point before execution. Job prepares operation → Gate checks exact operation → Deploy, migrate, or release executes or job stops ## Start here - **Build the final action.** Let GitHub Actions choose the action and produce the arguments it intends to execute. - **Check the exact action with Gate.** Send tool_name and the final payload immediately before the side effect. - **Follow one of four outcomes.** Continue, wait, revise, or stop. You do not need the advanced features to get this basic path working. ## Minimal setup A request is not an approval. Posting a decision request to Gate does not authorize the next deployment step. The job must receive an executable decision before the production command runs. ## Handle the decision | Outcome | Gate status | What GitHub Actions should do | | --- | --- | --- | | Continue | allow or approved | Execute the exact proposed action. If signed proof is required, validate it first. | | Wait | pending_review | Store thread_id and resume that exact review later. | | Revise | changes_requested | Return reviewer feedback to the part of the runtime that can revise the proposal. | | Stop | reject or rejected | Do not execute. Replan, fall back, or end the action. | Unknown or failed decision = stop. Fail closed if Gate cannot be reached, returns an unknown state, or required approval proof is missing or invalid. ## Platform notes - Keep cloud credentials, artifacts, scripts, and deployment tooling in the CI runner. - Persist thread_id between jobs when review can outlive one runner. - For long reviews, split request and continuation rather than holding a runner open. Advanced: review threads, revisions, proof, and audit task_id is your grouping ID. thread_id identifies the exact Gate review and should be persisted whenever work can pause. For changes_requested , revise on the same review thread using the revision event contract. For high-impact actions that require signed proof, validate the returned approval token before execution. Log execution success or failure when you need complete audit evidence. For long reviews, use the platform's durable continuation mechanism instead of keeping a process, workflow, or runner open. Advanced runtime patterns Full Gate API Exact decision states --- # Stacksona for Google ADK Source: https://docs.stacksona.com/integrations/google-adk Markdown: https://docs.stacksona.com/integrations/google-adk.md Wrap governed ADK tool execution with Gate while session state and agent reasoning remain in ADK. Code runtime Wrap governed ADK tool execution with Gate while session state and agent reasoning remain in ADK. Where Gate goes ## In a tool wrapper, callback, or sidecar that controls the actual action. Keep the platform's normal reasoning and orchestration. Gate only the exact action at the last safe point before execution. ADK agent selects tool → Wrapper checks Gate → Execute or return to session ## Start here - **Build the final action.** Let Google ADK choose the action and produce the arguments it intends to execute. - **Check the exact action with Gate.** Send tool_name and the final payload immediately before the side effect. - **Follow one of four outcomes.** Continue, wait, revise, or stop. You do not need the advanced features to get this basic path working. ## Minimal setup Store thread_id in session or durable task state when review can pause the action. Reviewer feedback should return to the agent/planning path for revision instead of being treated as execution approval. ## Handle the decision | Outcome | Gate status | What Google ADK should do | | --- | --- | --- | | Continue | allow or approved | Execute the exact proposed action. If signed proof is required, validate it first. | | Wait | pending_review | Store thread_id and resume that exact review later. | | Revise | changes_requested | Return reviewer feedback to the part of the runtime that can revise the proposal. | | Stop | reject or rejected | Do not execute. Replan, fall back, or end the action. | Unknown or failed decision = stop. Fail closed if Gate cannot be reached, returns an unknown state, or required approval proof is missing or invalid. ## Platform notes - ADK keeps session context, reasoning, and tool selection. - Gate owns policy, human review, approval proof, and audit evidence. - Use a wrapper or sidecar when the platform direct tool path cannot be intercepted safely. Advanced: review threads, revisions, proof, and audit task_id is your grouping ID. thread_id identifies the exact Gate review and should be persisted whenever work can pause. For changes_requested , revise on the same review thread using the revision event contract. For high-impact actions that require signed proof, validate the returned approval token before execution. Log execution success or failure when you need complete audit evidence. For long reviews, use the platform's durable continuation mechanism instead of keeping a process, workflow, or runner open. Advanced runtime patterns Full Gate API Exact decision states --- # Pick the shape first. Then pick your platform. Source: https://docs.stacksona.com/integrations Markdown: https://docs.stacksona.com/integrations.md Choose one of three Stacksona integration shapes, then open the guide for the platform you already use. Integration Hub Stacksona does not require a different architecture for every framework. Most integrations fit one of three shapes. [1 · Code runtime Wrap a function or tool The runtime chooses an action. Your wrapper checks it with Gate before calling the real function. Node, OpenAI Agents, LangGraph, CrewAI, LlamaIndex, Google ADK](node-typescript/index.html) [2 · Workflow platform Put Gate before the action step The workflow or agent chooses a branch. Gate sits immediately before the node or module that changes the outside world. n8n, Zapier, Make, Dify, Copilot Studio](n8n/index.html) [3 · Tool / proxy boundary Wrap the executable tool Gate is enforced in the tool server, proxy, shared service, or operations boundary before execution. MCP, REST wrappers, Salesforce services, GitHub Actions](mcp/index.html) Same behavior in every shape Continue on allow or valid approved . Wait on pending_review . Revise on changes_requested . Stop on reject or rejected . ## Code runtimes and agent frameworks [### Node / TypeScript Direct runtime wrapper and minimal helper.](node-typescript/index.html)[### OpenAI Agents SDK Wrap function-tool execution.](openai-agents/index.html)[### LangGraph Gate the governed tool node.](langgraph/index.html)[### CrewAI Wrap side-effecting crew tools.](crewai/index.html)[### LlamaIndex Gate the action adapter or workflow tool.](llamaindex/index.html)[### Google ADK Wrap tool execution or callback.](google-adk/index.html) ## Workflow platforms [### n8n Stacksona node immediately before governed actions.](n8n/index.html)[### Zapier Evaluate Action before the app action.](zapier-agents/index.html)[### Make HTTP Gate module before the target module.](make/index.html)[### Dify Gate action service or HTTP node before execution.](dify/index.html)[### Copilot Studio Use a connector, flow, or service wrapper.](copilot-studio/index.html) ## Tool, service, and operations boundaries [### MCP Enforce Gate before forwarding the real tool call.](mcp/index.html)[### Custom REST Universal HTTP execution wrapper.](custom-rest/index.html)[### Salesforce Agentforce Gate Apex, Flow, or service mutations.](salesforce-agentforce/index.html)[### GitHub Actions Gate the exact deployment or production operation.](github-actions/index.html) Advanced behavior shared by all platforms Persist thread_id for exact review resume. Use the same thread for requested-change revisions. Validate signed approval proof before high-impact execution when required. For long reviews, use the platform's durable continuation mechanism rather than keeping a process open. Runtime patterns Full API reference --- # Stacksona for LangGraph Source: https://docs.stacksona.com/integrations/langgraph Markdown: https://docs.stacksona.com/integrations/langgraph.md Put Gate in the governed tool-execution node while LangGraph keeps planning, routing, checkpoints, and state. Code runtime Put Gate in the governed tool-execution node while LangGraph keeps planning, routing, checkpoints, and state. Where Gate goes ## In the node that actually executes the side-effecting tool. Keep the platform's normal reasoning and orchestration. Gate only the exact action at the last safe point before execution. Planner routes tool → Governed tool node checks Gate → Execute, interrupt, revise, or route back ## Start here - **Build the final action.** Let LangGraph choose the action and produce the arguments it intends to execute. - **Check the exact action with Gate.** Send tool_name and the final payload immediately before the side effect. - **Follow one of four outcomes.** Continue, wait, revise, or stop. You do not need the advanced features to get this basic path working. ## Minimal setup | Graph state | Store | | --- | --- | | Proposed action | tool_name and final arguments | | Review pause | thread_id | | Requested change | Reviewer feedback and revised proposal | ## Handle the decision | Outcome | Gate status | What LangGraph should do | | --- | --- | --- | | Continue | allow or approved | Execute the exact proposed action. If signed proof is required, validate it first. | | Wait | pending_review | Store thread_id and resume that exact review later. | | Revise | changes_requested | Return reviewer feedback to the part of the runtime that can revise the proposal. | | Stop | reject or rejected | Do not execute. Replan, fall back, or end the action. | Unknown or failed decision = stop. Fail closed if Gate cannot be reached, returns an unknown state, or required approval proof is missing or invalid. ## Platform notes - Use LangGraph checkpoint/interrupt behavior for human-review pauses. - Route changes_requested back to planning or revision, not to execution. - Make the side-effect node reachable only after an executable Gate outcome. Advanced: review threads, revisions, proof, and audit task_id is your grouping ID. thread_id identifies the exact Gate review and should be persisted whenever work can pause. For changes_requested , revise on the same review thread using the revision event contract. For high-impact actions that require signed proof, validate the returned approval token before execution. Log execution success or failure when you need complete audit evidence. For long reviews, use the platform's durable continuation mechanism instead of keeping a process, workflow, or runner open. Advanced runtime patterns Full Gate API Exact decision states --- # Stacksona for LlamaIndex Source: https://docs.stacksona.com/integrations/llamaindex Markdown: https://docs.stacksona.com/integrations/llamaindex.md Gate the action adapter or workflow tool that performs a real side effect while LlamaIndex keeps reasoning and workflow context. Code runtime Gate the action adapter or workflow tool that performs a real side effect while LlamaIndex keeps reasoning and workflow context. Where Gate goes ## Inside the tool/action adapter immediately before it calls the real external service. Keep the platform's normal reasoning and orchestration. Gate only the exact action at the last safe point before execution. Agent/workflow chooses action → Adapter checks Gate → Execute or emit wait/revision event ## Start here - **Build the final action.** Let LlamaIndex choose the action and produce the arguments it intends to execute. - **Check the exact action with Gate.** Send tool_name and the final payload immediately before the side effect. - **Follow one of four outcomes.** Continue, wait, revise, or stop. You do not need the advanced features to get this basic path working. ## Minimal setup Store the proposed tool, arguments, decision, and thread_id in workflow context. A pending review can emit a wait event; requested changes can emit a revision event back to the planner. ## Handle the decision | Outcome | Gate status | What LlamaIndex should do | | --- | --- | --- | | Continue | allow or approved | Execute the exact proposed action. If signed proof is required, validate it first. | | Wait | pending_review | Store thread_id and resume that exact review later. | | Revise | changes_requested | Return reviewer feedback to the part of the runtime that can revise the proposal. | | Stop | reject or rejected | Do not execute. Replan, fall back, or end the action. | Unknown or failed decision = stop. Fail closed if Gate cannot be reached, returns an unknown state, or required approval proof is missing or invalid. ## Platform notes - Keep retrieval, reasoning, context, and event flow in LlamaIndex. - Use workflow context to resume the exact reviewed action. - Do not let a raw mutation tool bypass the governed adapter. Advanced: review threads, revisions, proof, and audit task_id is your grouping ID. thread_id identifies the exact Gate review and should be persisted whenever work can pause. For changes_requested , revise on the same review thread using the revision event contract. For high-impact actions that require signed proof, validate the returned approval token before execution. Log execution success or failure when you need complete audit evidence. For long reviews, use the platform's durable continuation mechanism instead of keeping a process, workflow, or runner open. Advanced runtime patterns Full Gate API Exact decision states --- # Stacksona for Make Source: https://docs.stacksona.com/integrations/make Markdown: https://docs.stacksona.com/integrations/make.md Place an HTTP Gate module in the governed route immediately before the module that performs the real action. Workflow platform Place an HTTP Gate module in the governed route immediately before the module that performs the real action. Where Gate goes ## Inside the route that owns the target API or app side effect. Keep the platform's normal reasoning and orchestration. Gate only the exact action at the last safe point before execution. Scenario/router chooses route → Gate HTTP module checks it → Target module executes or route stops ## Start here - **Build the final action.** Let Make choose the action and produce the arguments it intends to execute. - **Check the exact action with Gate.** Send tool_name and the final payload immediately before the side effect. - **Follow one of four outcomes.** Continue, wait, revise, or stop. You do not need the advanced features to get this basic path working. ## Minimal setup Map the final action values first, then send those exact values to Gate. Only the executable outcome should reach the target module. ## Handle the decision | Outcome | Gate status | What Make should do | | --- | --- | --- | | Continue | allow or approved | Execute the exact proposed action. If signed proof is required, validate it first. | | Wait | pending_review | Store thread_id and resume that exact review later. | | Revise | changes_requested | Return reviewer feedback to the part of the runtime that can revise the proposal. | | Stop | reject or rejected | Do not execute. Replan, fall back, or end the action. | Unknown or failed decision = stop. Fail closed if Gate cannot be reached, returns an unknown state, or required approval proof is missing or invalid. ## Platform notes - Keep scenario routing, mapping, and app credentials in Make. - Use a separate continuation scenario or webhook for long human reviews. - Send requested changes back through the mapping or AI revision path. Advanced: review threads, revisions, proof, and audit task_id is your grouping ID. thread_id identifies the exact Gate review and should be persisted whenever work can pause. For changes_requested , revise on the same review thread using the revision event contract. For high-impact actions that require signed proof, validate the returned approval token before execution. Log execution success or failure when you need complete audit evidence. For long reviews, use the platform's durable continuation mechanism instead of keeping a process, workflow, or runner open. Advanced runtime patterns Full Gate API Exact decision states --- # Stacksona for MCP Source: https://docs.stacksona.com/integrations/mcp Markdown: https://docs.stacksona.com/integrations/mcp.md Enforce Gate in the MCP tool boundary before the real domain tool is forwarded or executed. Tool / proxy Enforce Gate in the MCP tool boundary before the real domain tool is forwarded or executed. Where Gate goes ## In a governed MCP proxy, server wrapper, or bridge that owns access to the real side-effecting tool. Keep the platform's normal reasoning and orchestration. Gate only the exact action at the last safe point before execution. MCP client selects tool → Governed wrapper checks Gate → Wrapper forwards or refuses call ## Start here - **Build the final action.** Let MCP choose the action and produce the arguments it intends to execute. - **Check the exact action with Gate.** Send tool_name and the final payload immediately before the side effect. - **Follow one of four outcomes.** Continue, wait, revise, or stop. You do not need the advanced features to get this basic path working. ## Minimal setup The Stacksona MCP server exposes governance helpers including request_decision , request_decision_and_poll , get_decision , validate_approval_token , and log_event . Important enforcement rule If the client can still call the raw domain tool directly, asking it to call Stacksona first is guidance, not a hard boundary. Put Gate in the wrapper that actually controls forwarding to the real tool. ## Handle the decision | Outcome | Gate status | What MCP should do | | --- | --- | --- | | Continue | allow or approved | Execute the exact proposed action. If signed proof is required, validate it first. | | Wait | pending_review | Store thread_id and resume that exact review later. | | Revise | changes_requested | Return reviewer feedback to the part of the runtime that can revise the proposal. | | Stop | reject or rejected | Do not execute. Replan, fall back, or end the action. | Unknown or failed decision = stop. Fail closed if Gate cannot be reached, returns an unknown state, or required approval proof is missing or invalid. ## Platform notes - Let the MCP client keep normal tool discovery and reasoning. - Use Stacksona MCP tools for orchestration, but enforce sensitive actions in the executable tool wrapper. - Persist exact review threads outside the client session when reviews can outlive the session. Advanced: review threads, revisions, proof, and audit task_id is your grouping ID. thread_id identifies the exact Gate review and should be persisted whenever work can pause. For changes_requested , revise on the same review thread using the revision event contract. For high-impact actions that require signed proof, validate the returned approval token before execution. Log execution success or failure when you need complete audit evidence. For long reviews, use the platform's durable continuation mechanism instead of keeping a process, workflow, or runner open. Advanced runtime patterns Full Gate API Exact decision states --- # Stacksona for n8n Source: https://docs.stacksona.com/integrations/n8n Markdown: https://docs.stacksona.com/integrations/n8n.md Keep the workflow flexible and put Stacksona immediately before the node that performs the governed action. Workflow platform Keep the workflow flexible and put Stacksona immediately before the node that performs the governed action. Where Gate goes ## Inside each governed branch, directly before the side-effect node or inside the reusable sub-workflow that owns execution. Keep the platform's normal reasoning and orchestration. Gate only the exact action at the last safe point before execution. AI Agent / router chooses action → Stacksona node checks it → Target node executes or workflow branches ## Start here - **Build the final action.** Let n8n choose the action and produce the arguments it intends to execute. - **Check the exact action with Gate.** Send tool_name and the final payload immediately before the side effect. - **Follow one of four outcomes.** Continue, wait, revise, or stop. You do not need the advanced features to get this basic path working. ## Minimal setup | Stacksona operation | Use it for | | --- | --- | | Request Decision | Check an action and branch from the result. | | Request Decision and Wait | Convenient short human-review waits. | | Get Decision | Resume an action when you already have its thread. | | Validate Approval Token | Validate signed proof before high-impact execution. | | Log Event | Add execution outcome evidence. | ## Handle the decision | Outcome | Gate status | What n8n should do | | --- | --- | --- | | Continue | allow or approved | Execute the exact proposed action. If signed proof is required, validate it first. | | Wait | pending_review | Store thread_id and resume that exact review later. | | Revise | changes_requested | Return reviewer feedback to the part of the runtime that can revise the proposal. | | Stop | reject or rejected | Do not execute. Replan, fall back, or end the action. | Unknown or failed decision = stop. Fail closed if Gate cannot be reached, returns an unknown state, or required approval proof is missing or invalid. ## Platform notes - The AI Agent, Switch, or router can keep choosing actions normally. - Put Gate immediately before Gmail, CRM, payment, database, HTTP, or other side-effect nodes. - For long reviews, store thread_id and resume through a webhook or later workflow instead of keeping one execution open. Advanced: review threads, revisions, proof, and audit task_id is your grouping ID. thread_id identifies the exact Gate review and should be persisted whenever work can pause. For changes_requested , revise on the same review thread using the revision event contract. For high-impact actions that require signed proof, validate the returned approval token before execution. Log execution success or failure when you need complete audit evidence. For long reviews, use the platform's durable continuation mechanism instead of keeping a process, workflow, or runner open. Advanced runtime patterns Full Gate API Exact decision states --- # Stacksona for Node / TypeScript Source: https://docs.stacksona.com/integrations/node-typescript Markdown: https://docs.stacksona.com/integrations/node-typescript.md Wrap your tool function with Stacksona Gate immediately before the real side effect. Code runtime Wrap your tool function with Stacksona Gate immediately before the real side effect. Where Gate goes ## Inside the function or tool-execution wrapper you control. Keep the platform's normal reasoning and orchestration. Gate only the exact action at the last safe point before execution. Agent chooses tool → Gate checks exact args → Function executes or returns to runtime ## Start here - **Build the final action.** Let Node / TypeScript choose the action and produce the arguments it intends to execute. - **Check the exact action with Gate.** Send tool_name and the final payload immediately before the side effect. - **Follow one of four outcomes.** Continue, wait, revise, or stop. You do not need the advanced features to get this basic path working. ## Minimal setup ``` async function runGoverned(taskId, toolName, args) { const decision = await gate( \`/api/agent/tasks/${encodeURIComponent(taskId)}/requests\`, { tool_name: toolName, payload: args } ); if (decision.status === 'allow') return executeTool(toolName, args); if (decision.status === 'pending_review') return { waitFor: decision.thread_id }; if (decision.status === 'changes_requested') return { revise: decision }; if (decision.status === 'approved') return executeAfterProofCheck(decision, toolName, args); return { stop: decision }; } ``` Optional next step For dynamic tool catalogs, POST /api/agent/tools/resolve can supply governed names, descriptions, and input schemas. Treat that as optional discovery, not a prerequisite for the first integration. ## Handle the decision | Outcome | Gate status | What Node / TypeScript should do | | --- | --- | --- | | Continue | allow or approved | Execute the exact proposed action. If signed proof is required, validate it first. | | Wait | pending_review | Store thread_id and resume that exact review later. | | Revise | changes_requested | Return reviewer feedback to the part of the runtime that can revise the proposal. | | Stop | reject or rejected | Do not execute. Replan, fall back, or end the action. | Unknown or failed decision = stop. Fail closed if Gate cannot be reached, returns an unknown state, or required approval proof is missing or invalid. ## Platform notes - Keep model/provider credentials and service credentials in your runtime. - Validate model-generated tool arguments before the Gate request. - Do not expose a second ungoverned execution path for the same sensitive tool. Advanced: review threads, revisions, proof, and audit task_id is your grouping ID. thread_id identifies the exact Gate review and should be persisted whenever work can pause. For changes_requested , revise on the same review thread using the revision event contract. For high-impact actions that require signed proof, validate the returned approval token before execution. Log execution success or failure when you need complete audit evidence. For long reviews, use the platform's durable continuation mechanism instead of keeping a process, workflow, or runner open. Advanced runtime patterns Full Gate API Exact decision states --- # Stacksona for OpenAI Agents SDK Source: https://docs.stacksona.com/integrations/openai-agents Markdown: https://docs.stacksona.com/integrations/openai-agents.md Wrap each governed function tool so Gate checks the exact selected function arguments before the function executes. Code runtime Wrap each governed function tool so Gate checks the exact selected function arguments before the function executes. Where Gate goes ## Inside the function-tool implementation or a shared execution wrapper used by governed tools. Keep the platform's normal reasoning and orchestration. Gate only the exact action at the last safe point before execution. Agent selects function → Function wrapper checks Gate → Function executes or returns control ## Start here - **Build the final action.** Let OpenAI Agents SDK choose the action and produce the arguments it intends to execute. - **Check the exact action with Gate.** Send tool_name and the final payload immediately before the side effect. - **Follow one of four outcomes.** Continue, wait, revise, or stop. You do not need the advanced features to get this basic path working. ## Minimal setup Expose the governed wrapper as the callable tool. The wrapper receives the model-selected arguments, validates them, sends the exact proposal to Gate, and only then calls the real implementation. ## Handle the decision | Outcome | Gate status | What OpenAI Agents SDK should do | | --- | --- | --- | | Continue | allow or approved | Execute the exact proposed action. If signed proof is required, validate it first. | | Wait | pending_review | Store thread_id and resume that exact review later. | | Revise | changes_requested | Return reviewer feedback to the part of the runtime that can revise the proposal. | | Stop | reject or rejected | Do not execute. Replan, fall back, or end the action. | Unknown or failed decision = stop. Fail closed if Gate cannot be reached, returns an unknown state, or required approval proof is missing or invalid. ## Platform notes - Keep agent reasoning, provider credentials, and function execution in your application. - Do not model Gate as a separate optional tool that the agent may skip. - Store thread_id in session or job state when review can pause the run. Advanced: review threads, revisions, proof, and audit task_id is your grouping ID. thread_id identifies the exact Gate review and should be persisted whenever work can pause. For changes_requested , revise on the same review thread using the revision event contract. For high-impact actions that require signed proof, validate the returned approval token before execution. Log execution success or failure when you need complete audit evidence. For long reviews, use the platform's durable continuation mechanism instead of keeping a process, workflow, or runner open. Advanced runtime patterns Full Gate API Exact decision states --- # Stacksona for Salesforce Agentforce Source: https://docs.stacksona.com/integrations/salesforce-agentforce Markdown: https://docs.stacksona.com/integrations/salesforce-agentforce.md Gate the Apex, Flow, or service boundary that performs a governed CRM or external mutation. Tool / proxy Gate the Apex, Flow, or service boundary that performs a governed CRM or external mutation. Where Gate goes ## Inside the Apex callout, Flow action, or service wrapper immediately before mutation. Keep the platform's normal reasoning and orchestration. Gate only the exact action at the last safe point before execution. Agentforce chooses action → Apex/Flow wrapper checks Gate → Mutation executes or action returns ## Start here - **Build the final action.** Let Salesforce Agentforce choose the action and produce the arguments it intends to execute. - **Check the exact action with Gate.** Send tool_name and the final payload immediately before the side effect. - **Follow one of four outcomes.** Continue, wait, revise, or stop. You do not need the advanced features to get this basic path working. ## Minimal setup Expose the governed action wrapper to the agent instead of exposing a parallel raw mutation action. The wrapper can include record context and proposed field changes for the reviewer. ## Handle the decision | Outcome | Gate status | What Salesforce Agentforce should do | | --- | --- | --- | | Continue | allow or approved | Execute the exact proposed action. If signed proof is required, validate it first. | | Wait | pending_review | Store thread_id and resume that exact review later. | | Revise | changes_requested | Return reviewer feedback to the part of the runtime that can revise the proposal. | | Stop | reject or rejected | Do not execute. Replan, fall back, or end the action. | Unknown or failed decision = stop. Fail closed if Gate cannot be reached, returns an unknown state, or required approval proof is missing or invalid. ## Platform notes - Keep CRM context, reasoning, and action selection in Salesforce. - Store thread_id in Flow, Apex, job, or external runtime state for review resume. - Requested changes should return revised fields or action parameters on the same review thread. Advanced: review threads, revisions, proof, and audit task_id is your grouping ID. thread_id identifies the exact Gate review and should be persisted whenever work can pause. For changes_requested , revise on the same review thread using the revision event contract. For high-impact actions that require signed proof, validate the returned approval token before execution. Log execution success or failure when you need complete audit evidence. For long reviews, use the platform's durable continuation mechanism instead of keeping a process, workflow, or runner open. Advanced runtime patterns Full Gate API Exact decision states --- # Stacksona for Zapier Source: https://docs.stacksona.com/integrations/zapier-agents Markdown: https://docs.stacksona.com/integrations/zapier-agents.md Use Evaluate Action immediately before the app action, then resume the exact review thread when human review is required. Workflow platform Use Evaluate Action immediately before the app action, then resume the exact review thread when human review is required. Where Gate goes ## Between the agent or Zap decision and the real app action. Keep the platform's normal reasoning and orchestration. Gate only the exact action at the last safe point before execution. Agent/Zap chooses action → Evaluate Action checks Gate → App action executes or Zap waits ## Start here - **Build the final action.** Let Zapier choose the action and produce the arguments it intends to execute. - **Check the exact action with Gate.** Send tool_name and the final payload immediately before the side effect. - **Follow one of four outcomes.** Continue, wait, revise, or stop. You do not need the advanced features to get this basic path working. ## Minimal setup | Stacksona Zapier surface | Use | | --- | --- | | Evaluate Action | Check the exact proposed action. | | Decision Completed | Discover completed review work. | | Find Decision | Fetch the current decision by exact thread_id . | | Log Task Event | Add execution and task evidence. | ## Handle the decision | Outcome | Gate status | What Zapier should do | | --- | --- | --- | | Continue | allow or approved | Execute the exact proposed action. If signed proof is required, validate it first. | | Wait | pending_review | Store thread_id and resume that exact review later. | | Revise | changes_requested | Return reviewer feedback to the part of the runtime that can revise the proposal. | | Stop | reject or rejected | Do not execute. Replan, fall back, or end the action. | Unknown or failed decision = stop. Fail closed if Gate cannot be reached, returns an unknown state, or required approval proof is missing or invalid. ## Platform notes - Use thread_id for the exact review; task_id may group multiple checks. - Do not continue the app action while the decision is still pending. - Requested changes should return to the step that can revise the proposed action. Advanced: review threads, revisions, proof, and audit task_id is your grouping ID. thread_id identifies the exact Gate review and should be persisted whenever work can pause. For changes_requested , revise on the same review thread using the revision event contract. For high-impact actions that require signed proof, validate the returned approval token before execution. Log execution success or failure when you need complete audit evidence. For long reviews, use the platform's durable continuation mechanism instead of keeping a process, workflow, or runner open. Advanced runtime patterns Full Gate API Exact decision states --- # @stacksona/agent-tools Source: https://docs.stacksona.com/packages/agent-tools Markdown: https://docs.stacksona.com/packages/agent-tools.md Deterministic utility tools for agents, available through CLI, TypeScript imports, request files, MCP mode, and native imports for event context and stable task identifiers. Live package Deterministic utility tools for agents, available through CLI, TypeScript imports, request files, MCP mode, and native imports for event context and stable task identifiers. ## Fast path: deterministic helper tools - **Install or run with npx.** npm install -g @stacksona/agent-tools - **Call one utility.** Use tools for risk checks, policy evaluation, hashing, schema validation, table validation, URL checks, redaction, and proof envelopes. - **Feed outputs into approval context.** Use deterministic tool output as reviewer context before a Stacksona decision request. ## Package | Field | Value | | --- | --- | | Name | @stacksona/agent-tools | | Version documented | 1.0.3 | | Runtime | Node.js 18 or later | | Binary | stacksona-agent-tools | | Use when | You want deterministic tool outputs, explanations, hashes, redacted proofs, and replay-friendly audit context. | ``` npm install -g @stacksona/agent-tools npx @stacksona/agent-tools list ``` ## Native package usage Use @stacksona/agent-tools directly from your agent runtime when you want deterministic helper output without shelling out to the CLI. Native imports are useful for building Stacksona event payloads, producing replay-friendly proof context, and generating stable task IDs before you call Gate. - Events: format or enrich task.started , step.completed , revision, and tool-call context before sending it to /api/agent/tasks/{taskID}/events . - Task IDs: derive unique task identifiers from workflow inputs, action fingerprints, hashes, slugs, timestamps, or your own deterministic naming rules. - Approval context: include risk checks, policy results, redacted payloads, hashes, and request inspections in the decision request summary or payload. ``` import { callTool } from '@stacksona/agent-tools'; const fingerprint = await callTool('action.fingerprint', { action: { type: 'refund', amount: 2500, currency: 'usd', customer_id: 'cus_123' }, }); const taskSlug = await callTool('text.slugify', { text: \`refund-${fingerprint.hash}\` }); const taskId = \`task-${taskSlug.slug}\`; ``` ## Run as MCP server ``` stacksona-agent-tools mcp ``` ``` { "mcpServers": { "stacksona-agent-tools": { "command": "stacksona-agent-tools", "args": ["mcp"] } } } ``` ## Tool categories | Category | Tools | | --- | --- | | Calculation and security | calculator.evaluate , password.policy_check , security.hash , security.hmac | | Proof and data | proof.create , proof.verify , json.format , json.diff , schema.validate , JSON path tools | | Text and output quality | text.redact_sensitive , text.extract , text.slugify , output.check_constraints , template.render | | Risk and decision support | risk.requires_approval , action.fingerprint , http.request_inspect , time.window_check , policy tools, URL tools, table tools | | Files, images, provenance | file.checksum , file.inspect , image.metadata , image.annotate_boxes , ocr.extract_text , provenance.c2pa_check | ## Examples ``` stacksona-agent-tools call action.fingerprint '{"action":{"type":"refund","amount":2500,"currency":"usd","customer_id":"cus_123"}}' stacksona-agent-tools call http.request_inspect '{"method":"POST","url":"https://api.stripe.com/v1/refunds","headers":{"Authorization":"Bearer sk_live_redacted"},"body":{"charge":"ch_123","amount":2500}}' stacksona-agent-tools call policy.evaluate '{"facts":{"action":"refund","amount":250},"rules":[{"id":"refund_threshold","if":{"action":"refund","amount":{"gte":100}},"then":{"requires_approval":true,"reason":"refund_above_threshold"}}]}' ``` --- # @stacksona/mcp-server Source: https://docs.stacksona.com/packages/mcp-server Markdown: https://docs.stacksona.com/packages/mcp-server.md MCP server for Stacksona Gate approvals, decision polling, audit logging, signed token validation, and revision events. Live package MCP server for Stacksona Gate approvals, decision polling, audit logging, signed token validation, and revision events. ## Fast path: expose approval tools - **Install globally.** npm install -g @stacksona/mcp-server - **Set env vars.** Provide STACKSONA_GATE_URL and STACKSONA_API_KEY . - **Add to your MCP client.** The client can request decisions, poll decisions, validate approval tokens, and log events. Use your own Gate URL and agent key STACKSONA_GATE_URL is the Gate endpoint from your Stacksona workspace or deployment. STACKSONA_API_KEY is the sg_ agent key for the agent making requests. ## Package | Field | Value | | --- | --- | | Name | @stacksona/mcp-server | | Version documented | 0.2.3 | | Runtime | Node.js 18 or later | | Binary | stacksona-mcp-server | | Use when | You want MCP-compatible clients to request approvals or log audit events through Stacksona. | ``` npm install -g @stacksona/mcp-server ``` ## Run ``` STACKSONA_GATE_URL=https://{gate-id}.stacksona.cloud STACKSONA_API_KEY=sg_your_api_key stacksona-mcp-server ``` ## Claude Desktop config ``` { "mcpServers": { "stacksona": { "command": "stacksona-mcp-server", "env": { "STACKSONA_GATE_URL": "https://{gate-id}.stacksona.cloud", "STACKSONA_API_KEY": "sg_your_api_key" } } } } ``` ## Available MCP tools | Tool | Purpose | | --- | --- | | stacksona_log_event | Log an agent timeline event to Stacksona Gate. | | stacksona_request_decision | Request approval before an agent takes a gated action. | | stacksona_request_decision_and_poll | Request a decision and wait for approval or rejection. | | stacksona_get_decision | Fetch current decision status by thread or task. | | stacksona_validate_approval_token | Validate signed one-time approval tokens. | | stacksona_send_revision | Update a pending review thread with a revised request. | --- # n8n-nodes-stacksona Source: https://docs.stacksona.com/packages/n8n-node Markdown: https://docs.stacksona.com/packages/n8n-node.md n8n community node for Stacksona Gate approvals, audit events, decision polling, signed token validation, and approval waiting. Live package n8n community node for Stacksona Gate approvals, audit events, decision polling, signed token validation, and approval waiting. ## Fast path: n8n install - **Install community node.** Settings, Community Nodes, Install, n8n-nodes-stacksona . - **Add credentials.** Use your Gate URL and sg_ API key. - **Use before the risky node.** Request approval before email, CRM, refund, HTTP, database, or message nodes execute. ## Package | Field | Value | | --- | --- | | Name | n8n-nodes-stacksona | | Version documented | 0.1.1 | | Runtime | n8n with community nodes enabled | | Credentials | Stacksona Gate API | | Use when | You want a native n8n node for Stacksona Gate. | ## Install in n8n - **Open n8n settings.** Go to Settings, then Community Nodes. - **Install package.** Enter n8n-nodes-stacksona . - **Create credentials.** Add your Gate URL and Stacksona Agent API key starting with sg_ . - **Add the node.** Search for Stacksona Gate in the n8n node picker. ## Operations | Operation | Purpose | | --- | --- | | Log Event | Record workflow and agent activity. | | Request Decision | Create an approval request before a gated action. | | Get Decision | Check the current status of a decision. | | Validate Approval Token | Validate a signed one-time approval token. | | Request Decision and Wait | Request a decision and wait for final approval or rejection. | --- # @stacksona/sdk Source: https://docs.stacksona.com/packages/sdk Markdown: https://docs.stacksona.com/packages/sdk.md TypeScript and JavaScript SDK for Stacksona Gate approvals, audit events, polling, signed token validation, revision events, and gated action execution. Live package TypeScript and JavaScript SDK for Stacksona Gate approvals, audit events, polling, signed token validation, revision events, and gated action execution. ## Fast path: install and gate an action - **Install.** npm install @stacksona/sdk - **Create a client.** Read STACKSONA_GATE_URL and STACKSONA_API_KEY from environment variables. - **Call Stacksona before execution.** Run the action only when the returned status is allow or approved . Use your own Gate URL and agent key STACKSONA_GATE_URL is the Gate endpoint from your Stacksona workspace or deployment. STACKSONA_API_KEY is the sg_ agent key for the agent making requests. ## Package | Field | Value | | --- | --- | | Name | @stacksona/sdk | | Version documented | 0.2.0 | | Runtime | Node.js 18 or later | | Main export | StacksonaGateClient | | Use when | You control a Node.js or TypeScript agent, backend, worker, or sidecar. | ``` npm install @stacksona/sdk ``` ## Environment ``` STACKSONA_GATE_URL=https://{gate-id}.stacksona.cloud STACKSONA_API_KEY=sg_your_api_key ``` ## Run a gated action ``` const { decision, executed, result } = await gate.runGatedAction( { taskId: 'task-refund-8821', workflowName: 'Customer Support', taskLabel: 'Refund request for order #8821', toolName: 'issue_refund', subject: 'Issue refund of $500 to customer cus_99', riskLevel: 'high', summary: ['Customer requested refund', 'Order has no tracking movement'], payload: { amount: 500, currency: 'usd', customer_id: 'cus_99' }, }, async () => issueRefund({ amount: 500, currency: 'usd', customerId: 'cus_99' }), { validateSignedApprovalToken: true }, ); if (!executed) { console.log(\`Action did not run: ${decision.status}\`); } ``` ## Main methods | Method | Purpose | | --- | --- | | logEvent(input) | Send task, workflow, or agent timeline context to Stacksona Gate. | | logRevision(input) | Send a revision event to a pending review thread after reviewer feedback. | | requestDecision(input) | Ask Gate to allow, reject, or create a review thread for a gated action. | | getDecision(query) | Fetch decision status by thread_id or task_id . | | pollDecision(query, options) | Poll until a pending decision becomes approved or rejected. | | requestDecisionAndPoll(input, options) | Create a decision request and wait automatically when review is required. | | validateApprovalToken(input) | Validate a signed one-time approval token before execution. | | runGatedAction(input, action, options) | Execute the supplied function only after Gate allows or approves it. | ## Revision events Use revisions when a reviewer asks the agent to modify a pending request instead of opening a new thread. ``` await gate.logRevision({ taskId: 'task-refund-8821', threadId: 'THR-XXXXXXXX', revisionId: 'rev-002', workflowName: 'Customer Support', taskLabel: 'Refund request for order #8821', toolName: 'issue_refund', subject: 'Approve conditional refund for customer cus_99', preview: 'Refund releases only after return-label scan.', riskLevel: 'high', summary: ['Reviewer requested a conditional refund'], requestPayload: { amount: 500, currency: 'usd', release_condition: 'return_label_scanned', }, }); ``` --- # Runtime Integration Patterns Source: https://docs.stacksona.com/patterns Markdown: https://docs.stacksona.com/patterns.md Use Stacksona Gate as a lightweight wrapper around a flexible agent runtime instead of hard-coding every workflow path. Patterns Build fewer rigid workflows. Give the runtime its available tools, then wrap each governed execution boundary with Stacksona Gate. The core pattern ## One runtime node instead of a long chain of fixed steps The runtime receives the request, context, SOP, and available tools. It chooses the next action from the current state. Stacksona does not dictate the workflow. It governs the selected action immediately before execution. Request + context → Runtime chooses next tool → Gate checks exact call → Execute or replan The same wrapper works whether the runtime takes two steps or twenty. ## Who owns what | Runtime | Stacksona Gate | | --- | --- | | Reasoning and planning | Tool contracts | | Model and provider credentials | Policy and rule checks | | Executable tool functions | Human review | | Argument validation | Decision delivery | | Retries and business logic | Signed approval validation | | Execution and replanning | Audit evidence | ## The five-part wrapper - **Resolve contracts.** Fetch the names, descriptions, and input_schema for the governed tools this runtime may use. - **Choose the next tool.** The runtime reasons over the request, prior results, and available contracts. - **Validate arguments locally.** Your runtime validates the model-generated arguments against the resolved schema. - **Gate at the last safe moment.** POST the exact tool_name and payload immediately before the real tool executes. - **Continue from the decision.** Execute on allow/approved, wait on review, revise on feedback, and replan or stop on rejection. ## Why resolve tool contracts first Gate can return the same registered tool names, descriptions, and JSON input schemas that are governed by policy. That gives the runtime a clean capability surface without moving the tool implementation or service credential into Gate. ``` POST /api/agent/tools/resolve { "tools": ["issue_refund", "send_email", "update_crm"] } ``` ## Gate only the final proposed call The runtime can reason, retrieve, plan, and prepare freely. The governance check belongs directly before the action leaves your system or mutates important state. ``` POST /api/agent/tasks/order-1042/requests { "tool_name": "issue_refund", "payload": { "amount": 389.99, "currency": "usd" } } ``` tool_name is the only required request field. Add workflow, subject, risk, summary, preview, or image context when it helps policy or reviewers. ## Human review is a runtime state, not a separate workflow | Status | Meaning in the runtime loop | | --- | --- | | allow | Execute now. | | pending_review | Pause this tool call and wait on its thread_id . | | changes_requested | Use reviewer feedback to revise the same proposal thread. | | approved | Execute after required proof validation. | | reject / rejected | Do not execute. Replan or stop. | ## Task IDs group work, thread IDs identify reviews A runtime can reuse one task_id across multiple checks and review threads. Persist the exact Gate-generated thread_id for polling, revisions, and correlation with one human-review request. ## Log what actually happened After execution, write evidence such as tool.execution.completed or tool.execution.failed . Ordinary event names are open-ended, so your application can log its own evidence vocabulary without adding a new workflow system. ## Where this pattern fits [Node and TypeScript](/integrations/node-typescript/index.html)[Custom REST](/integrations/custom-rest/index.html)[n8n](/integrations/n8n/index.html)[Zapier](/integrations/zapier-agents/index.html)[MCP](/integrations/mcp/index.html)[OpenAI Agents](/integrations/openai-agents/index.html)[LangGraph](/integrations/langgraph/index.html) Fail closed at the wrapper Unknown states, API errors, timeouts, and missing required signed approval proof must never fall through to execution. --- # Approve customer email before it runs Source: https://docs.stacksona.com/playbooks/customer-email-approval Markdown: https://docs.stacksona.com/playbooks/customer-email-approval.md Use this pattern when an agent is about to send a customer-facing email, reply, or outbound message that a person should review first. Workflow Playbook Use this pattern when an agent is about to send a customer-facing email, reply, or outbound message that a person should review first. ## When to use this Use this pattern when an agent is about to send a customer-facing email, reply, or outbound message that a person should review first. ## Where Stacksona fits Place Stacksona after the agent drafts the message and before the email send step. ## What the reviewer should see - recipient - subject - draft body - customer or account - ticket or conversation context - reason the agent wants to send - risk or review reason - any policy threshold or escalation reason ## Minimum fields to send - agent_id - workflow_id - tool_name: send_email - action_type: customer_email - recipient - subject - body_preview or draft_body - customer_id or account_id - reason - reviewer_group, if known - callback_url, if using async review ## Example request ``` { "agent_id": "support-agent-01", "workflow_id": "ticket-reply-flow", "tool_name": "send_email", "action_type": "customer_email", "recipient": "customer@example.com", "subject": "Update on your support request", "draft_body": "Hi Jordan, we reviewed your ticket and can replace the item today.", "customer_id": "cus_1042", "reason": "Agent drafted a customer-facing reply for a shipping issue.", "reviewer_group": "support-leads", "callback_url": "https://app.example.com/stacksona/callback" } ``` ## How to branch after the decision | Status | Behavior | | --- | --- | | allowed or approved | Send the email. | | pending_review | Pause, poll, or wait for callback. | | rejected | Do not send. | | expired or error | Do not send by default. | ## What to log after execution - decision_id - message_id or provider id - sent_at - final recipient - final subject - execution_status ## Common mistakes - sending before the decision is approved - showing reviewers only a summary without the actual draft - not logging the final send result - retrying a send after rejection ## Related integrations [n8n](/integrations/n8n/index.html)[Node and TypeScript](/integrations/node-typescript/index.html)[Custom REST](/integrations/custom-rest/index.html)[LangGraph](/integrations/langgraph/index.html)[MCP Clients](/integrations/mcp/index.html)[Patterns](/patterns/index.html)[Decision Statuses](/reference/decision-statuses/index.html) --- # Workflow Playbooks Source: https://docs.stacksona.com/playbooks Markdown: https://docs.stacksona.com/playbooks.md Start with the action your agent is about to take. Each playbook shows where to add Stacksona before the action runs, what to show the reviewer, and what to log after the decision. Workflow Playbooks Start with the action your agent is about to take. Each playbook shows where to add Stacksona before the action runs, what to show the reviewer, and what to log after the decision. ## Choose the action [### Customer email approval Playbook Review the recipient, subject, draft body, customer context, and reason before the message is sent.](/playbooks/customer-email-approval/) [### Refund approval Playbook Review the amount, customer, order, refund reason, and policy threshold before money moves.](/playbooks/refund-approval/) [### Production API approval Playbook Review the endpoint, method, affected system, payload summary, and rollback plan before the API call runs.](/playbooks/production-api-approval/) ## Where Stacksona fits Add Stacksona after the agent has prepared the action and before the tool, API, workflow, or job runs. ## Common branch behavior | Status | Workflow behavior | | --- | --- | | allowed | Run the action. | | approved | Run the action. | | pending_review | Wait, poll, or pause for reviewer decision. | | rejected | Do not run the action. | | expired | Do not run the action unless your policy explicitly allows a fallback. | | error | Fail closed for sensitive actions. | ## Related references [Patterns](/patterns/index.html)[Gate API Reference](/reference/api-contract/index.html)[Decision Statuses](/reference/decision-statuses/index.html)[Security](/reference/security/index.html)[Integration Hub](/integrations/index.html)[Templates](/templates/index.html) --- # Approve production API calls before they run Source: https://docs.stacksona.com/playbooks/production-api-approval Markdown: https://docs.stacksona.com/playbooks/production-api-approval.md Use this pattern when an agent is about to call a production API, trigger a job, send a webhook, mutate a database record, or touch an internal system. Workflow Playbook Use this pattern when an agent is about to call a production API, trigger a job, send a webhook, mutate a database record, or touch an internal system. ## When to use this Use this pattern when an agent is about to call a production API, trigger a job, send a webhook, mutate a database record, or touch an internal system. ## Where Stacksona fits Place Stacksona immediately before the production call. The agent should prepare the request, ask Gate for a decision, and only run the call when the decision allows it. ## What the reviewer should see - endpoint - method - affected system - payload summary - full payload or safe redacted payload - expected impact - rollback plan - reason the agent wants to call the API - risk or review reason ## Minimum fields to send - agent_id - workflow_id - tool_name: call_production_api - action_type: production_api - method - endpoint - affected_system - payload_summary - rollback_plan - reason - callback_url, if using async review ## Example request ``` { "agent_id": "ops-agent-01", "workflow_id": "production-api-review", "tool_name": "call_production_api", "action_type": "production_api", "method": "POST", "endpoint": "https://api.internal.example.com/accounts/cus_99/recalculate", "affected_system": "billing-ledger", "payload_summary": "Recalculate account balance after support adjustment.", "rollback_plan": "Run ledger_restore with request_id if the recalculation is incorrect.", "reason": "Agent detected a mismatch between CRM balance and billing ledger.", "callback_url": "https://app.example.com/stacksona/api-callback" } ``` ## How to branch after the decision | Status | Behavior | | --- | --- | | allowed or approved | Call the API. | | pending_review | Pause, poll, or wait for callback. | | rejected | Do not call the API. | | expired or error | Fail closed by default. | ## What to log after execution - decision_id - endpoint - method - provider request id or internal request id - response status - execution_status - executed_at - rollback_id if applicable ## Common mistakes - hiding the payload from reviewers - approving without showing affected system - not logging the API response result - failing open on timeout ## Related integrations [Custom REST](/integrations/custom-rest/index.html)[Node and TypeScript](/integrations/node-typescript/index.html)[MCP Clients](/integrations/mcp/index.html)[LangGraph](/integrations/langgraph/index.html)[GitHub Actions](/integrations/github-actions/index.html)[Patterns](/patterns/index.html)[Gate API Reference](/reference/api-contract/index.html)[Security](/reference/security/index.html) --- # Approve refunds before they run Source: https://docs.stacksona.com/playbooks/refund-approval Markdown: https://docs.stacksona.com/playbooks/refund-approval.md Use this pattern when an agent is about to issue a refund, credit, adjustment, or billing change that a person should review first. Workflow Playbook Use this pattern when an agent is about to issue a refund, credit, adjustment, or billing change that a person should review first. ## When to use this Use this pattern when an agent is about to issue a refund, credit, adjustment, or billing change that a person should review first. ## Where Stacksona fits Place Stacksona after the agent has prepared the refund request and before the payment, billing, or commerce API is called. ## What the reviewer should see - amount - currency - customer - order or invoice - refund reason - policy threshold - prior refund history if available - agent recommendation - consequence of approval ## Minimum fields to send - agent_id - workflow_id - tool_name: issue_refund - action_type: refund - amount - currency - customer_id - order_id or invoice_id - reason - policy_threshold - callback_url, if using async review ## Example request ``` { "agent_id": "billing-agent-01", "workflow_id": "refund-review-flow", "tool_name": "issue_refund", "action_type": "refund", "amount": 500, "currency": "usd", "customer_id": "cus_99", "order_id": "ord_8821", "reason": "Carrier shows no movement after 14 days.", "policy_threshold": "manual_review_required_over_100_usd", "callback_url": "https://app.example.com/stacksona/refund-callback" } ``` ## How to branch after the decision | Status | Behavior | | --- | --- | | allowed or approved | Issue the refund. | | pending_review | Pause, poll, or wait for callback. | | rejected | Do not issue the refund. | | expired or error | Fail closed and do not issue the refund. | ## What to log after execution - decision_id - refund_id - payment provider id - amount - currency - execution_status - executed_at ## Common mistakes - issuing the refund before validation - omitting the amount or customer history from reviewer view - not validating signed approval for high-impact refunds - retrying after a rejected decision ## Related integrations [Node and TypeScript](/integrations/node-typescript/index.html)[Custom REST](/integrations/custom-rest/index.html)[LangGraph](/integrations/langgraph/index.html)[n8n](/integrations/n8n/index.html)[Security](/reference/security/index.html)[Decision Statuses](/reference/decision-statuses/index.html) --- # Gate Agent API Reference Source: https://docs.stacksona.com/reference/api-contract Markdown: https://docs.stacksona.com/reference/api-contract.md Complete Stacksona Gate Agent API reference for runtime tool contracts, policy checks, human review, decisions, signed approvals, events, revisions, webhooks, limits, and errors. Standard docs Your runtime owns reasoning and execution. Gate exposes six authenticated endpoints that wrap governed tool execution with contracts, policy, review, decisions, signed approval validation, and audit evidence. Authentication Use your own Gate installation as STACKSONA_GATE_URL and the agent's sg_ key as a Bearer token. JSON requests use Content-Type: application/json . Runtime model ## Gate wraps execution, it does not run the tools Keep provider keys, service credentials, executable functions, retries, and business logic in your runtime. Resolve contracts earlier if useful, but evaluate the exact final tool arguments immediately before execution. Resolve contracts → Runtime selects tool → Gate evaluates call → Execute, wait, revise, or replan ## Endpoint overview | Method | Path | Purpose | | --- | --- | --- | | POST | /api/agent/tools/resolve | Resolve governed tool contracts for the runtime. | | POST | /api/agent/tasks/{taskID}/events | Append runtime evidence or a guarded revision event. | | POST | /api/agent/tasks/{taskID}/requests | Evaluate the exact proposed tool call. | | GET | /api/agent/decisions | Read one current review decision by thread or task. | | GET | /api/agent/decisions/list | Discover pending or completed review references. | | POST | /api/agent/approvals/validate | Validate and consume a one-time signed approval token. | ## Runtime quick start ``` # 1. Resolve governed contracts curl -sS -X POST "$STACKSONA_GATE_URL/api/agent/tools/resolve" \ -H "Authorization: Bearer $STACKSONA_API_KEY" \ -H "Content-Type: application/json" \ -d '{"tools":["issue_refund","send_email"]}' # 2. Gate the exact proposed tool call curl -sS -X POST "$STACKSONA_GATE_URL/api/agent/tasks/order-1042/requests" \ -H "Authorization: Bearer $STACKSONA_API_KEY" \ -H "Content-Type: application/json" \ -d '{"tool_name":"issue_refund","payload":{"amount":389.99,"currency":"usd"}}' # 3. If pending_review, poll the exact returned thread curl -sS "$STACKSONA_GATE_URL/api/agent/decisions?thread_id=THR-A1B2C3D4" \ -H "Authorization: Bearer $STACKSONA_API_KEY" ``` ## 1. Resolve tool contracts POST /api/agent/tools/resolve Resolve registered tool contracts so the runtime can reason over the same names, descriptions, and input schemas configured in Gate. | Field | Required | Behavior | | --- | --- | --- | | tools | Yes | Array of 1 to 100 non-empty tool names. Exact duplicates are collapsed. Whitespace-only names are rejected. | ``` { "tools": ["issue_refund", "send_email"] } ``` ``` { "tools": [ { "name": "issue_refund", "description": "Issue a customer refund", "input_schema": { "type": "object", "required": ["amount"], "properties": {"amount": {"type": "number"}} } } ], "unregistered": ["send_email"] } ``` Runtime responsibility Validate model-generated arguments against input_schema in your runtime. Gate returns the schema but does not perform arbitrary JSON Schema validation on /requests . The request body is limited to 16 KiB, unknown top-level fields are rejected, and the body must contain exactly one JSON object. A body over the current 16 KiB cap surfaces as HTTP 400 . ## 2. Log an event POST /api/agent/tasks/{taskID}/events Append evidence to a runtime task. Ordinary event names are open-ended. The revision. prefix is the one namespace that changes request handling. | Field | Required | Description | | --- | --- | --- | | event_type | Yes | Any non-empty event name. Use an application-owned namespace for custom evidence. | | event_summary | Yes | Human-readable evidence summary. | | payload | No | Structured event evidence object. | | images | No | Base64 evidence images when attachments are enabled. | ``` { "event_type": "tool.execution.completed", "event_summary": "Refund executed", "payload": {"provider_id": "rf_123"} } ``` Success is 201 Created with no JSON body. ## Event contract ### Processed lifecycle names | Event | Meaning | | --- | --- | | task.started / execution.started | Start timestamp markers used by runtime projection logic. | | task.completed / execution.completed | Terminal completed marker. | | task.failed / execution.failed | Terminal failure marker. | | task.cancelled / execution.cancelled | Terminal cancellation marker. | | task.terminated / execution.terminated | Terminal forced-termination marker. | ### Recommended runtime conventions task.request.loaded , task.input.loaded , task.sop.loaded , task.tools.available , tool.execution.completed , and tool.execution.failed . ### Gate-generated names approval.requested , decision.allow , decision.reject , decision.approved , decision.rejected , task.summary , token_issued , token_consumed , and token_rejected . Custom by default Ordinary custom event names are not checked against a fixed enum or reserved-name rejection list. Use your own namespace to avoid confusing application evidence with Gate lifecycle records. ## 3. Request a decision POST /api/agent/tasks/{taskID}/requests Evaluate the exact tool call the runtime is about to execute. tool_name is the only required field. | Field | Required | Default / behavior | | --- | --- | --- | | tool_name | Yes | Exact tool selected by the runtime. | | payload | No | Exact tool arguments. Defaults to {} . | | workflow_name | No | Defaults to agent workflow name, then agent name. | | task_label | No | Defaults to the path taskID . | | subject | No | Defaults to Review {tool_name} . | | preview | No | Short reviewer context. | | risk_level | No | low , medium , high , or critical . Empty or unrecognized values currently normalize to medium . | | summary | No | Review summary items. Defaults to an empty array. | | images | No | Base64 evidence images when attachments are enabled. | ``` { "tool_name": "issue_refund", "payload": { "amount": 389.99, "currency": "usd" } } ``` An unregistered tool request is still gateable. Gate routes it to human review with an unregistered-tool reason. ### Responses | Status | Meaning | | --- | --- | | allow | Automatic policy allow. Execute the proposed call. | | reject | Automatic policy reject. Do not execute. | | pending_review | A human-review thread was created. Persist the returned thread_id . | ``` { "status": "pending_review", "thread_id": "THR-A1B2C3D4", "task_id": "order-1042", "message": "Rule matched: amount upper_limit", "recommended_poll_after_seconds": 15 } ``` ## 4. Get one decision GET /api/agent/decisions | Query | Use | | --- | --- | | thread_id | Preferred. Identifies the exact review request returned by /requests . | | task_id | Reusable grouping ID. Resolves to the newest review thread for the authenticated agent and task. | ### Statuses to handle pending_review , changes_requested , approved , and rejected . ``` { "status": "changes_requested", "thread_id": "THR-A1B2C3D4", "task_id": "order-1042", "message": "Reduce the amount and resubmit", "modification": { "requested_changes": "Reduce the amount and resubmit", "requested_at": "2026-08-09T17:00:00Z" }, "recommended_poll_after_seconds": 3 } ``` Signed approvals When enabled, the first successful read of an approved decision may additionally include approval_token and token_expires_at . The raw token is delivered once. If signed proof is required by your runtime, a missing token must block execution. ## 5. List decisions GET /api/agent/decisions/list | Parameter | Default | Behavior | | --- | --- | --- | | status | completed | completed returns approved/rejected. pending returns needs-review/escalated threads as pending_review . | | limit | 25 | Maximum 100. Results are scoped to the authenticated agent and ordered newest first. | ``` { "decisions": [ { "thread_id": "THR-A1B2C3D4", "task_id": "order-1042", "status": "approved", "updated_at": "2026-08-09T17:00:00Z" } ] } ``` This endpoint is token-safe discovery. Listing a completed decision does not reveal or consume the one-time signed approval token. Fetch the exact decision by thread_id when the runtime is ready to continue. ## 6. Validate a signed approval POST /api/agent/approvals/validate | Field | Required | Description | | --- | --- | --- | | task_id | Yes | Task ID associated with the approval. | | signature | Yes | Raw one-time approval token returned by an approved decision. | ``` { "valid": true } ``` ``` { "valid": false, "reason": "invalid" } ``` Failure reasons include invalid , expired , and used . Tokens are single-use, expiry-bound, agent/context-bound, and invalidated by agent API-key rotation. Important HTTP behavior Token validation failures, including invalid, expired, used, malformed, or missing inputs, are currently represented in the JSON body and can return HTTP 200 . Always inspect valid . ## Requested changes and revisions When a reviewer requests changes, polling returns changes_requested . Keep the same review thread and POST a guarded revision event. ``` { "event_type": "revision.order-1042.THR-A1B2C3D4", "event_summary": "Revised after reviewer feedback", "payload": { "revision": { "revision_id": "rev-002", "tool_name": "issue_refund", "subject": "Review issue_refund", "request_payload": {"amount": 250} } } } ``` | Revision field | Required | Behavior | | --- | --- | --- | | revision_id | Yes | Must be unique within the thread. | | tool_name | Yes | Updated proposed tool. | | subject | Yes | Updated reviewer-facing proposal subject. | | request_payload | Yes | Revised tool arguments reevaluated by rules. | | workflow_name , task_label , preview , risk_level , summary | No | May update review context. Existing values are retained when omitted. | A revision is accepted only for the same agent, task, and thread while the thread is pending, and only after reviewer change-request feedback newer than the latest proposal. Duplicate, stale, or no-longer-pending revisions return 409 . A revision that passes policy remains pending for reviewer confirmation; a revision that evaluates to reject may terminate as rejected. ## Decision webhooks When webhook delivery is configured, Gate POSTs completed human decisions to the configured HTTPS endpoint. ``` { "thread_id": "THR-A1B2C3D4", "task_id": "order-1042", "decision": "approved", "message": "Approved", "tenant_id": "tenant-uuid", "workflow_name": "Customer Support", "task_label": "Refund review" } ``` ### Verify the signature ``` X-Guard-Signature: sha256= HMAC-SHA256(webhook_secret, exact_raw_request_body) ``` Gate attempts delivery immediately, then retries after 1 second and 3 seconds. Any HTTP status below 300 is treated as success. Webhook destinations must use HTTPS; localhost, loopback, common private ranges, link-local destinations, and unsafe redirect targets are rejected. ## Identifiers | Identifier | Owner | Use | | --- | --- | --- | | taskID / task_id | Your runtime | Groups events and one or more decision requests. Reuse is supported. Use a stable URL-safe path-segment value. | | thread_id | Gate | Identifies one exact human-review request. Prefer for polling, revisions, and correlation. | | revision_id | Your runtime | Unique identifier for one submitted revision inside a thread. | There is no live 36-character task-ID contract on this API surface. Avoid path-breaking characters such as / , ? , and # . ## Operational limits | Area | Current behavior | | --- | --- | | Agent rate limit | Enforced per agent from tenant API settings. Exceeded requests return 429 . | | Tool resolve body | 16 KiB maximum. Overflow currently returns 400 . | | Tool resolve count | 1 to 100 tool names. | | Stored tool input schema | Tool ingestion caps configured input schemas at 64 KiB. | | Decision listing | Default 25 rows, maximum 100. | | Images | Limited by installation/tenant attachment configuration and available storage quota. | | Rule checks / decision threads | Plan entitlements may impose hard caps. Exceeded hard caps can return 402 . | ## HTTP errors | Status | Meaning | | --- | --- | | 400 | Malformed JSON, missing required input, invalid query values, rule-evaluation input errors, malformed revisions, or oversized /tools/resolve body. | | 401 | Missing or invalid Bearer agent API key. | | 402 | Applicable hard usage or entitlement cap reached. | | 403 | Agent API or polling disabled, subscription guard, or unavailable feature. | | 404 | Decision or revision target not found for the requested context. | | 409 | Revision no longer pending, reviewer feedback stale/missing, or revision ID duplicated. | | 413 | Evidence image or attachment/storage limits exceeded. /tools/resolve overflow is the exception and currently reports 400 . | | 429 | Per-agent API rate limit exceeded. | | 500 / 503 | Unexpected server failure or attachment storage unavailable. | Most Agent API errors are plain HTTP error text rather than a universal JSON envelope. Preserve the response body for diagnostics. The signed approval validation endpoint is the important exception: inspect its JSON valid field even when HTTP is 200. Safe runtime rule Fail closed for an unknown decision status. If signed approval proof is required, also fail closed when approved arrives without approval_token . Never execute a governed action merely because an HTTP request succeeded. --- # Cloudflare deployment Source: https://docs.stacksona.com/reference/cloudflare-deployment Markdown: https://docs.stacksona.com/reference/cloudflare-deployment.md Deploy the Stacksona docs site securely and efficiently on Cloudflare Pages as a static-only public documentation site. Reference Deploy the Stacksona docs site as a static, secure, efficient Cloudflare Pages project with no backend, no customer data, and no committed agent keys. Cloudflare Pages Static only Markdown routes ## Deployment model Deploy this site as static files on Cloudflare Pages. It serves public documentation, search metadata, SEO files, and plain Markdown routes. It does not need a Worker Function, database, KV namespace, API proxy, cookie, or customer secret. Keep Gate credentials out of the docs site. Users provide their own STACKSONA_GATE_URL , usually shaped like https://{gate-id}.stacksona.cloud , and their own sg_ agent key inside their private runtime, n8n credentials, CI secret store, or server-side environment. ## Cloudflare Pages settings | Setting | Value | | --- | --- | | Framework preset | None | | Build command | npm run build | | Build output directory | . | | Root directory | Repository root | | Environment variable | DOCS_BASE_URL=https://docs.stacksona.com | ## Security headers The repo includes a Cloudflare Pages _headers file. It applies HSTS, content-type sniffing protection, frame blocking, referrer limits, restrictive browser permissions, cross-origin isolation headers, a static-site CSP, and cache behavior for HTML, assets, Markdown, and discovery files. Why inline scripts are allowed in CSP. The pages include inline JSON-LD structured data for SEO. The site is static and does not accept user-generated content. ## Efficient static serving HTML pages are revalidated. Static assets use short browser caching with stale-while-revalidate. Markdown and LLM files are served inline with public CORS because they contain public docs only. ## Canonical and Markdown routes ``` https://docs.stacksona.com/integrations/n8n https://docs.stacksona.com/integrations/n8n.md https://docs.stacksona.com/reference/api-contract https://docs.stacksona.com/reference/api-contract.md https://docs.stacksona.com/llms.txt https://docs.stacksona.com/llms-full.txt ``` ## Pre-deploy check ``` npm run build ``` The build regenerates Markdown, LLM, sitemap, and robots files, then validates security files, links, Markdown alternates, and secret hygiene. ## Deploy ``` npm run build npx wrangler pages deploy . --project-name stacksona-integrations-docs ``` ## Cloudflare deployment FAQ ### Does this site need Cloudflare Workers? No. The docs site is static and uses Cloudflare Pages headers and redirects only. ### Does the docs repo contain agent keys? No. Agent keys belong in customer runtimes and private platform secret stores, not public docs. ### Can agents fetch Markdown? Yes. Add .md to public docs routes to get plain Markdown. --- # Decision Statuses Source: https://docs.stacksona.com/reference/decision-statuses Markdown: https://docs.stacksona.com/reference/decision-statuses.md Use Stacksona Gate decision statuses to execute, wait, revise, replan, or stop safely. Reference Gate gives the runtime a small decision vocabulary: execute, wait, revise, replan, or stop. ## Execution rule Execute a governed action only on allow or approved . Treat every other state as a control signal, never as permission to execute. ## Status table | Status | Meaning | Runtime behavior | | --- | --- | --- | | allow | Automatic policy allow. | Execute the exact proposed tool call. | | reject | Automatic policy reject. | Do not execute. Replan or stop. | | pending_review | A human-review thread is open. | Persist the returned thread_id , wait, poll, or resume from a callback. | | changes_requested | A reviewer supplied feedback on the current proposal. | Revise the proposed action and send a guarded revision.{taskID}.{threadID} event on the same thread. | | approved | The reviewer approved the current proposal. | Execute only after required signed-approval checks succeed. | | rejected | The reviewer rejected the current proposal. | Do not execute. Replan or stop. | ## Requested changes stay on the same review thread When polling returns changes_requested , use the reviewer message as feedback, produce a revised proposal, and POST a revision event to the same task and thread. Gate reevaluates the revision while preserving the review history. ``` { "event_type": "revision.task-123.THR-A1B2C3D4", "event_summary": "Revised after reviewer feedback", "payload": { "revision": { "revision_id": "rev-002", "tool_name": "issue_refund", "subject": "Review issue_refund", "request_payload": { "amount": 250 } } } } ``` A revision requires a unique revision_id , tool_name , subject , and request_payload . Duplicate, stale, or no-longer-pending revisions return 409 . ## Identifiers | ID | Use | | --- | --- | | task_id | Your runtime-controlled grouping ID. Reuse is supported across multiple decision requests. | | thread_id | Gate-generated identifier for one exact human-review request. Prefer it for polling and revisions. | | revision_id | Your unique identifier for one revision inside a review thread. | ## Recommended branch behavior Fail closed Stop execution on unknown status, API failure, missing required approval proof, invalid or consumed token, or timeout. The HTTP request succeeding is not itself permission to execute. --- # LLM-ready Documentation Source: https://docs.stacksona.com/reference/llm-ready-docs Markdown: https://docs.stacksona.com/reference/llm-ready-docs.md How Stacksona docs expose llms.txt, llms-full.txt, Markdown exports, and copy-for-LLM buttons for AI assistants and coding agents. Reference Use Stacksona documentation with AI assistants, coding agents, and LLM-powered search without scraping noisy navigation or layout code. ## What this site exposes Stacksona docs include human-readable pages, public .md versions of every page, an llms.txt map, a full-documentation export, and copy buttons that package the current page for use in ChatGPT, Claude, Cursor, Copilot, or another coding assistant. | Asset | Path | Use | | --- | --- | --- | | LLM map | /llms.txt | Curated links to the most important Stacksona docs and Markdown exports. | | Full export | /llms-full.txt | One combined Markdown export for agents that need the entire docs context. | | Public Markdown pages | /integrations/n8n.md | Append .md to a clean public page URL to return plain Markdown for agents. | | Markdown archive | /markdown/... | Clean page content without navigation, layout, or script noise, kept as a generated archive. | | Copy page for LLM | Button on every docs page | Copies a compact Markdown version of the current page. | | Copy platform brief | Button on integration pages | Copies the current platform guide with usage context and first-call guidance. | ## Markdown URL pattern For public docs pages, use the clean human URL for browsers and add .md for an agent-readable Markdown response. | Human URL | Markdown URL | | --- | --- | | https://docs.stacksona.com/integrations/n8n | https://docs.stacksona.com/integrations/n8n.md | | https://docs.stacksona.com/integrations/custom-rest | https://docs.stacksona.com/integrations/custom-rest.md | | https://docs.stacksona.com/reference/api-contract | https://docs.stacksona.com/reference/api-contract.md | | https://docs.stacksona.com/packages/mcp-server | https://docs.stacksona.com/packages/mcp-server.md | Each HTML page also includes a rel="alternate" Markdown link in the page head so crawlers and agents can discover the plain-text version automatically. ## How to use with an AI assistant - **Open the platform page.** Choose n8n, Node, MCP, REST, or a platform recipe. - **Click Copy page for LLM.** The copied text includes the page title, URL, description, key steps, tables, and code examples. - **Paste into your coding assistant.** Ask it to adapt the Stacksona approval flow to your actual workflow, Gate URL, and sg_ agent key. Do not paste real secrets into an LLM. Use placeholders like STACKSONA_GATE_URL and STACKSONA_API_KEY . Hosted Gate URLs usually look like https://{gate-id}.stacksona.cloud , and the agent key starts with sg_ . ## Recommended prompt ``` Use this Stacksona documentation as the source of truth. Build an approval gate before the risky agent action. Use my own STACKSONA_GATE_URL and sg_ agent key as environment variables. Execute the action only when Stacksona returns allow or approved. Fail closed for rejected, pending, expired, blocked, invalid token, or API error states. ``` ## SEO and AI discovery assets The site includes page titles, meta descriptions, canonical URLs, Open Graph metadata, structured data, a sitemap, robots file, Markdown exports, and LLM-focused discovery files. These help search engines and AI systems find the right Stacksona integration page for platform-specific approval questions. --- # Security Source: https://docs.stacksona.com/reference/security Markdown: https://docs.stacksona.com/reference/security.md Security guidance for runtime tool execution, Gate API keys, signed approvals, webhook verification, and fail-closed agent workflows. Reference Keep execution credentials in the runtime. Let Gate govern whether a proposed tool call may cross the execution boundary. ## Security boundary Your runtime owns execution. Provider keys, database credentials, tool functions, retries, and business logic stay in your application. Gate receives the proposed tool name, arguments, and the evidence you intentionally send for policy and review. ## Key handling | Practice | Guidance | | --- | --- | | Use server-side secrets | Store the sg_ agent key in environment variables, platform credentials, or a secrets manager. | | Never expose keys to browsers | Agent API calls belong in the runtime, backend, worker, or trusted automation environment. | | Separate environments | Use different Gate URLs and agent keys for development, staging, and production. | | Rotate keys deliberately | Rotating an agent key invalidates signed approval tokens bound to the prior key context. | ## Signed approval tokens When signed approvals are enabled, an approved decision may deliver a one-time approval_token . Gate stores the raw token only for delivery and retains a hash/binding record for validation. | Property | Behavior | | --- | --- | | Single use | Validation consumes the token so it cannot authorize execution twice. | | Expiry bound | Expired tokens return {"valid":false,"reason":"expired"} . | | Context bound | The approval is bound to tenant, agent, tool, exact review thread, current API-key hash, and expiry. | | Delivered once | The raw token may appear only on the first successful approved-decision read. | | Reusable task IDs | Validation uses the exact token binding, so later review threads under the same task ID do not invalidate an older still-valid token. | Required means required If your runtime requires signed approval proof, an approved status without a token is not executable. Fail closed. ## Validate before execution ``` POST /api/agent/approvals/validate Authorization: Bearer sg_... Content-Type: application/json { "task_id": "task-123", "signature": "APPROVAL_TOKEN" } ``` Token failures such as invalid, expired, used, malformed, or missing inputs can be represented inside an HTTP 200 JSON response. Always inspect valid . Never treat a 2xx status by itself as approval. ## Webhook verification Decision webhooks are separate from Agent API authentication. Verify X-Guard-Signature against the exact raw request body with HMAC-SHA256. ``` X-Guard-Signature: sha256= HMAC-SHA256(webhook_secret, exact_raw_request_body) ``` Webhook destinations must use HTTPS. Gate rejects localhost, loopback, common private ranges, link-local destinations, and unsafe redirect targets. ## Data minimization Send enough context for policy and review, but avoid secrets, raw credentials, or full private documents when a summary, diff, selected fields, or fingerprint is enough. Tool execution does not require Gate to hold the external service credential. ## Fail closed at the wrapper Execution rule The runtime should execute only on allow or a valid approved result. Unknown statuses, API errors, missing required proof, invalid tokens, and timeouts must not fall through to tool execution. --- # Workflow Templates Source: https://docs.stacksona.com/templates Markdown: https://docs.stacksona.com/templates.md Reusable Stacksona workflow templates for n8n and other platforms. Templates Reusable Stacksona workflow templates for n8n and other platforms. ## Template library | Template | Platforms | Purpose | | --- | --- | --- | | AI Email Approval | n8n, Zapier, Make, custom | Approve AI-generated emails before send. | | CRM Update Approval | n8n, Salesforce, HubSpot, Make | Approve customer or account mutations. | | Refund Approval | n8n, custom, Make, GitHub Actions for ops scripts | Approve payment provider refund actions. | | Support Reply Approval | n8n, Dify, Zendesk, Copilot Studio | Approve customer-facing support responses. | | Production API Approval | Node, n8n, Make, custom REST | Approve external API calls in production. | | Deployment Approval | GitHub Actions, Node, custom CI | Approve deploys, releases, and migrations. | | Data Deletion Approval | Node, Salesforce, n8n, custom REST | Approve destructive data operations. | | Reviewer Revision Flow | SDK, MCP server, n8n | Allow reviewer feedback to revise a pending request. | ## Common approval workflows Use these templates when you need to add approvals to any workflow before a risky action executes. Each template follows the same Stacksona pattern: prepare the action, request a decision, pause for human approval when policy requires it, validate the decision, then log what happened. - Stop an AI agent before it sends an email: gate the email-send tool or node and execute only after approval. - Audit agent actions before execution: store the proposed action, reviewer context, decision status, and final execution event. - Add policy checks before an AI tool call: route risky actions to review based on tool name, payload, environment, recipient, amount, or data sensitivity. ## Standard request fields ``` { "workflow_name": "Customer Support", "task_label": "Refund request for order #8821", "tool_name": "issue_refund", "subject": "Issue a $500 refund to customer cus_99", "preview": "Agent proposes a refund because shipment has no tracking movement.", "risk_level": "high", "summary": [ "Customer requested refund", "Order placed 14 days ago", "No tracking movement found" ], "payload": { "amount": 500, "currency": "usd", "customer_id": "cus_99" } } ```