@botpress/adk-cli 1.19.0-beta.3 → 1.19.0-beta.5

package/{assets/ui-dist/assets/index-DfjXY3Oo.js → dist/index-a3ZL0_Jr-q145h35p.js}

@@ -1,4 +1,4 @@
-import{r as a,W as R}from"./index-CSTz-oTK.js";function oe(e,t){(t==null||t>e.length)&&(t=e.length);for(var r=0,n=Array(t);r<t;r++)n[r]=e[r];return n}function me(e){if(Array.isArray(e))return e}function be(e,t,r){return(t=Se(t))in e?Object.defineProperty(e,t,{value:r,enumerable:!0,configurable:!0,writable:!0}):e[t]=r,e}function ye(e,t){var r=e==null?null:typeof Symbol<"u"&&e[Symbol.iterator]||e["@@iterator"];if(r!=null){var n,o,i,c,s=[],f=!0,p=!1;try{if(i=(r=r.call(e)).next,t!==0)for(;!(f=(n=i.call(r)).done)&&(s.push(n.value),s.length!==t);f=!0);}catch(j){p=!0,o=j}finally{try{if(!f&&r.return!=null&&(c=r.return(),Object(c)!==c))return}finally{if(p)throw o}}return s}}function we(){throw new TypeError(`Invalid attempt to destructure non-iterable instance.
+import{r as a,W as R}from"./index-B3b7PPgV.js";function oe(e,t){(t==null||t>e.length)&&(t=e.length);for(var r=0,n=Array(t);r<t;r++)n[r]=e[r];return n}function me(e){if(Array.isArray(e))return e}function be(e,t,r){return(t=Se(t))in e?Object.defineProperty(e,t,{value:r,enumerable:!0,configurable:!0,writable:!0}):e[t]=r,e}function ye(e,t){var r=e==null?null:typeof Symbol<"u"&&e[Symbol.iterator]||e["@@iterator"];if(r!=null){var n,o,i,c,s=[],f=!0,p=!1;try{if(i=(r=r.call(e)).next,t!==0)for(;!(f=(n=i.call(r)).done)&&(s.push(n.value),s.length!==t);f=!0);}catch(j){p=!0,o=j}finally{try{if(!f&&r.return!=null&&(c=r.return(),Object(c)!==c))return}finally{if(p)throw o}}return s}}function we(){throw new TypeError(`Invalid attempt to destructure non-iterable instance.
 In order to be iterable, non-array objects must have a [Symbol.iterator]() method.`)}function ie(e,t){var r=Object.keys(e);if(Object.getOwnPropertySymbols){var n=Object.getOwnPropertySymbols(e);t&&(n=n.filter(function(o){return Object.getOwnPropertyDescriptor(e,o).enumerable})),r.push.apply(r,n)}return r}function ae(e){for(var t=1;t<arguments.length;t++){var r=arguments[t]!=null?arguments[t]:{};t%2?ie(Object(r),!0).forEach(function(n){be(e,n,r[n])}):Object.getOwnPropertyDescriptors?Object.defineProperties(e,Object.getOwnPropertyDescriptors(r)):ie(Object(r)).forEach(function(n){Object.defineProperty(e,n,Object.getOwnPropertyDescriptor(r,n))})}return e}function Oe(e,t){if(e==null)return{};var r,n,o=je(e,t);if(Object.getOwnPropertySymbols){var i=Object.getOwnPropertySymbols(e);for(n=0;n<i.length;n++)r=i[n],t.indexOf(r)===-1&&{}.propertyIsEnumerable.call(e,r)&&(o[r]=e[r])}return o}function je(e,t){if(e==null)return{};var r={};for(var n in e)if({}.hasOwnProperty.call(e,n)){if(t.indexOf(n)!==-1)continue;r[n]=e[n]}return r}function Me(e,t){return me(e)||ye(e,t)||Ee(e,t)||we()}function Pe(e,t){if(typeof e!="object"||!e)return e;var r=e[Symbol.toPrimitive];if(r!==void 0){var n=r.call(e,t);if(typeof n!="object")return n;throw new TypeError("@@toPrimitive must return a primitive value.")}return(t==="string"?String:Number)(e)}function Se(e){var t=Pe(e,"string");return typeof t=="symbol"?t:t+""}function Ee(e,t){if(e){if(typeof e=="string")return oe(e,t);var r={}.toString.call(e).slice(8,-1);return r==="Object"&&e.constructor&&(r=e.constructor.name),r==="Map"||r==="Set"?Array.from(e):r==="Arguments"||/^(?:Ui|I)nt(?:8|16|32)(?:Clamped)?Array$/.test(r)?oe(e,t):void 0}}function Re(e,t,r){return t in e?Object.defineProperty(e,t,{value:r,enumerable:!0,configurable:!0,writable:!0}):e[t]=r,e}function ue(e,t){var r=Object.keys(e);if(Object.getOwnPropertySymbols){var n=Object.getOwnPropertySymbols(e);t&&(n=n.filter(function(o){return Object.getOwnPropertyDescriptor(e,o).enumerable})),r.push.apply(r,n)}return r}function ce(e){for(var t=1;t<arguments.length;t++){var r=arguments[t]!=null?arguments[t]:{};t%2?ue(Object(r),!0).forEach(function(n){Re(e,n,r[n])}):Object.getOwnPropertyDescriptors?Object.defineProperties(e,Object.getOwnPropertyDescriptors(r)):ue(Object(r)).forEach(function(n){Object.defineProperty(e,n,Object.getOwnPropertyDescriptor(r,n))})}return e}function Ie(){for(var e=arguments.length,t=new Array(e),r=0;r<e;r++)t[r]=arguments[r];return function(n){return t.reduceRight(function(o,i){return i(o)},n)}}function A(e){return function t(){for(var r=this,n=arguments.length,o=new Array(n),i=0;i<n;i++)o[i]=arguments[i];return o.length>=e.length?e.apply(this,o):function(){for(var c=arguments.length,s=new Array(c),f=0;f<c;f++)s[f]=arguments[f];return t.apply(r,[].concat(o,s))}}}function U(e){return{}.toString.call(e).includes("Object")}function Te(e){return!Object.keys(e).length}function D(e){return typeof e=="function"}function Ce(e,t){return Object.prototype.hasOwnProperty.call(e,t)}function Le(e,t){return U(t)||P("changeType"),Object.keys(t).some(function(r){return!Ce(e,r)})&&P("changeField"),t}function Ae(e){D(e)||P("selectorType")}function $e(e){D(e)||U(e)||P("handlerType"),U(e)&&Object.values(e).some(function(t){return!D(t)})&&P("handlersType")}function De(e){e||P("initialIsRequired"),U(e)||P("initialType"),Te(e)&&P("initialContent")}function Ve(e,t){throw new Error(e[t]||e.default)}var xe={initialIsRequired:"initial state is required",initialType:"initial state should be an object",initialContent:"initial state shouldn't be an empty object",handlerType:"handler should be an object or a function",handlersType:"all handlers should be a functions",selectorType:"selector should be a function",changeType:"provided value of changes should be an object",changeField:'it seams you want to change a field in the state which is not specified in the "initial" state',default:"an unknown error accured in `state-local` package"},P=A(Ve)(xe),q={changes:Le,selector:Ae,handler:$e,initial:De};function Ne(e){var t=arguments.length>1&&arguments[1]!==void 0?arguments[1]:{};q.initial(e),q.handler(t);var r={current:e},n=A(Ue)(r,t),o=A(ze)(r),i=A(q.changes)(e),c=A(qe)(r);function s(){var p=arguments.length>0&&arguments[0]!==void 0?arguments[0]:function(j){return j};return q.selector(p),p(r.current)}function f(p){Ie(n,o,i,c)(p)}return[s,f]}function qe(e,t){return D(t)?t(e.current):t}function ze(e,t){return e.current=ce(ce({},e.current),t),t}function Ue(e,t,r){return D(t)?t(e.current):Object.keys(r).forEach(function(n){var o;return(o=t[n])===null||o===void 0?void 0:o.call(t,e.current[n])}),r}var Fe={create:Ne},We={paths:{vs:"https://cdn.jsdelivr.net/npm/monaco-editor@0.55.1/min/vs"}};function He(e){return function t(){for(var r=this,n=arguments.length,o=new Array(n),i=0;i<n;i++)o[i]=arguments[i];return o.length>=e.length?e.apply(this,o):function(){for(var c=arguments.length,s=new Array(c),f=0;f<c;f++)s[f]=arguments[f];return t.apply(r,[].concat(o,s))}}}function _e(e){return{}.toString.call(e).includes("Object")}function Be(e){return e||le("configIsRequired"),_e(e)||le("configType"),e.urls?(Ke(),{paths:{vs:e.urls.monacoBase}}):e}function Ke(){console.warn(se.deprecation)}function Ge(e,t){throw new Error(e[t]||e.default)}var se={configIsRequired:"the configuration object is required",configType:"the configuration object should be an object",default:"an unknown error accured in `@monaco-editor/loader` package",deprecation:`Deprecation warning!
     You are using deprecated way of configuration.
 
@@ -9,4 +9,4 @@ In order to be iterable, non-array objects must have a [Symbol.iterator]() metho
 
     For more please check the link https://github.com/suren-atoyan/monaco-loader#config
   `},le=He(Ge)(se),Ye={config:Be},Je=function(){for(var t=arguments.length,r=new Array(t),n=0;n<t;n++)r[n]=arguments[n];return function(o){return r.reduceRight(function(i,c){return c(i)},o)}};function fe(e,t){return Object.keys(t).forEach(function(r){t[r]instanceof Object&&e[r]&&Object.assign(t[r],fe(e[r],t[r]))}),ae(ae({},e),t)}var Qe={type:"cancelation",msg:"operation is manually canceled"};function Z(e){var t=!1,r=new Promise(function(n,o){e.then(function(i){return t?o(Qe):n(i)}),e.catch(o)});return r.cancel=function(){return t=!0},r}var Xe=["monaco"],Ze=Fe.create({config:We,isInitialized:!1,resolve:null,reject:null,monaco:null}),de=Me(Ze,2),V=de[0],W=de[1];function ke(e){var t=Ye.config(e),r=t.monaco,n=Oe(t,Xe);W(function(o){return{config:fe(o.config,n),monaco:r}})}function et(){var e=V(function(t){var r=t.monaco,n=t.isInitialized,o=t.resolve;return{monaco:r,isInitialized:n,resolve:o}});if(!e.isInitialized){if(W({isInitialized:!0}),e.monaco)return e.resolve(e.monaco),Z(k);if(window.monaco&&window.monaco.editor)return pe(window.monaco),e.resolve(window.monaco),Z(k);Je(tt,nt)(ot)}return Z(k)}function tt(e){return document.body.appendChild(e)}function rt(e){var t=document.createElement("script");return e&&(t.src=e),t}function nt(e){var t=V(function(n){var o=n.config,i=n.reject;return{config:o,reject:i}}),r=rt("".concat(t.config.paths.vs,"/loader.js"));return r.onload=function(){return e()},r.onerror=t.reject,r}function ot(){var e=V(function(r){var n=r.config,o=r.resolve,i=r.reject;return{config:n,resolve:o,reject:i}}),t=window.require;t.config(e.config),t(["vs/editor/editor.main"],function(r){var n=r.m||r;pe(n),e.resolve(n)},function(r){e.reject(r)})}function pe(e){V().monaco||W({monaco:e})}function it(){return V(function(e){var t=e.monaco;return t})}var k=new Promise(function(e,t){return W({resolve:e,reject:t})}),F={config:ke,init:et,__getMonacoInstance:it},at={wrapper:{display:"flex",position:"relative",textAlign:"initial"},fullWidth:{width:"100%"},hide:{display:"none"}},ee=at,ut={container:{display:"flex",height:"100%",width:"100%",justifyContent:"center",alignItems:"center"}},ct=ut;function lt({children:e}){return R.createElement("div",{style:ct.container},e)}var st=lt,ft=st;function dt({width:e,height:t,isEditorReady:r,loading:n,_ref:o,className:i,wrapperProps:c}){return R.createElement("section",{style:{...ee.wrapper,width:e,height:t},...c},!r&&R.createElement(ft,null,n),R.createElement("div",{ref:o,style:{...ee.fullWidth,...!r&&ee.hide},className:i}))}var pt=dt,ge=a.memo(pt);function gt(e){a.useEffect(e,[])}var te=gt;function ht(e,t,r=!0){let n=a.useRef(!0);a.useEffect(n.current||!r?()=>{n.current=!1}:e,t)}var w=ht;function $(){}function E(e,t,r,n){return vt(e,n)||mt(e,t,r,n)}function vt(e,t){return e.editor.getModel(he(e,t))}function mt(e,t,r,n){return e.editor.createModel(t,r,n?he(e,n):void 0)}function he(e,t){return e.Uri.parse(t)}function bt({original:e,modified:t,language:r,originalLanguage:n,modifiedLanguage:o,originalModelPath:i,modifiedModelPath:c,keepCurrentOriginalModel:s=!1,keepCurrentModifiedModel:f=!1,theme:p="light",loading:j="Loading...",options:O={},height:H="100%",width:_="100%",className:B,wrapperProps:K={},beforeMount:G=$,onMount:Y=$}){let[y,I]=a.useState(!1),[T,g]=a.useState(!0),h=a.useRef(null),d=a.useRef(null),C=a.useRef(null),m=a.useRef(Y),u=a.useRef(G),S=a.useRef(!1);te(()=>{let l=F.init();return l.then(v=>(d.current=v)&&g(!1)).catch(v=>v?.type!=="cancelation"&&console.error("Monaco initialization: error:",v)),()=>h.current?L():l.cancel()}),w(()=>{if(h.current&&d.current){let l=h.current.getOriginalEditor(),v=E(d.current,e||"",n||r||"text",i||"");v!==l.getModel()&&l.setModel(v)}},[i],y),w(()=>{if(h.current&&d.current){let l=h.current.getModifiedEditor(),v=E(d.current,t||"",o||r||"text",c||"");v!==l.getModel()&&l.setModel(v)}},[c],y),w(()=>{let l=h.current.getModifiedEditor();l.getOption(d.current.editor.EditorOption.readOnly)?l.setValue(t||""):t!==l.getValue()&&(l.executeEdits("",[{range:l.getModel().getFullModelRange(),text:t||"",forceMoveMarkers:!0}]),l.pushUndoStop())},[t],y),w(()=>{h.current?.getModel()?.original.setValue(e||"")},[e],y),w(()=>{let{original:l,modified:v}=h.current.getModel();d.current.editor.setModelLanguage(l,n||r||"text"),d.current.editor.setModelLanguage(v,o||r||"text")},[r,n,o],y),w(()=>{d.current?.editor.setTheme(p)},[p],y),w(()=>{h.current?.updateOptions(O)},[O],y);let x=a.useCallback(()=>{if(!d.current)return;u.current(d.current);let l=E(d.current,e||"",n||r||"text",i||""),v=E(d.current,t||"",o||r||"text",c||"");h.current?.setModel({original:l,modified:v})},[r,t,o,e,n,i,c]),N=a.useCallback(()=>{!S.current&&C.current&&(h.current=d.current.editor.createDiffEditor(C.current,{automaticLayout:!0,...O}),x(),d.current?.editor.setTheme(p),I(!0),S.current=!0)},[O,p,x]);a.useEffect(()=>{y&&m.current(h.current,d.current)},[y]),a.useEffect(()=>{!T&&!y&&N()},[T,y,N]);function L(){let l=h.current?.getModel();s||l?.original?.dispose(),f||l?.modified?.dispose(),h.current?.dispose()}return R.createElement(ge,{width:_,height:H,isEditorReady:y,loading:j,_ref:C,className:B,wrapperProps:K})}var yt=bt,Rt=a.memo(yt);function wt(){let[e,t]=a.useState(F.__getMonacoInstance());return te(()=>{let r;return e||(r=F.init(),r.then(n=>{t(n)})),()=>r?.cancel()}),e}var It=wt;function Ot(e){let t=a.useRef();return a.useEffect(()=>{t.current=e},[e]),t.current}var jt=Ot,z=new Map;function Mt({defaultValue:e,defaultLanguage:t,defaultPath:r,value:n,language:o,path:i,theme:c="light",line:s,loading:f="Loading...",options:p={},overrideServices:j={},saveViewState:O=!0,keepCurrentModel:H=!1,width:_="100%",height:B="100%",className:K,wrapperProps:G={},beforeMount:Y=$,onMount:y=$,onChange:I,onValidate:T=$}){let[g,h]=a.useState(!1),[d,C]=a.useState(!0),m=a.useRef(null),u=a.useRef(null),S=a.useRef(null),x=a.useRef(y),N=a.useRef(Y),L=a.useRef(),l=a.useRef(n),v=jt(i),re=a.useRef(!1),J=a.useRef(!1);te(()=>{let b=F.init();return b.then(M=>(m.current=M)&&C(!1)).catch(M=>M?.type!=="cancelation"&&console.error("Monaco initialization: error:",M)),()=>u.current?ve():b.cancel()}),w(()=>{let b=E(m.current,e||n||"",t||o||"",i||r||"");b!==u.current?.getModel()&&(O&&z.set(v,u.current?.saveViewState()),u.current?.setModel(b),O&&u.current?.restoreViewState(z.get(i)))},[i],g),w(()=>{u.current?.updateOptions(p)},[p],g),w(()=>{!u.current||n===void 0||(u.current.getOption(m.current.editor.EditorOption.readOnly)?u.current.setValue(n):n!==u.current.getValue()&&(J.current=!0,u.current.executeEdits("",[{range:u.current.getModel().getFullModelRange(),text:n,forceMoveMarkers:!0}]),u.current.pushUndoStop(),J.current=!1))},[n],g),w(()=>{let b=u.current?.getModel();b&&o&&m.current?.editor.setModelLanguage(b,o)},[o],g),w(()=>{s!==void 0&&u.current?.revealLine(s)},[s],g),w(()=>{m.current?.editor.setTheme(c)},[c],g);let ne=a.useCallback(()=>{if(!(!S.current||!m.current)&&!re.current){N.current(m.current);let b=i||r,M=E(m.current,n||e||"",t||o||"",b||"");u.current=m.current?.editor.create(S.current,{model:M,automaticLayout:!0,...p},j),O&&u.current.restoreViewState(z.get(b)),m.current.editor.setTheme(c),s!==void 0&&u.current.revealLine(s),h(!0),re.current=!0}},[e,t,r,n,o,i,p,j,O,c,s]);a.useEffect(()=>{g&&x.current(u.current,m.current)},[g]),a.useEffect(()=>{!d&&!g&&ne()},[d,g,ne]),l.current=n,a.useEffect(()=>{g&&I&&(L.current?.dispose(),L.current=u.current?.onDidChangeModelContent(b=>{J.current||I(u.current.getValue(),b)}))},[g,I]),a.useEffect(()=>{if(g){let b=m.current.editor.onDidChangeMarkers(M=>{let Q=u.current.getModel()?.uri;if(Q&&M.find(X=>X.path===Q.path)){let X=m.current.editor.getModelMarkers({resource:Q});T?.(X)}});return()=>{b?.dispose()}}return()=>{}},[g,T]);function ve(){L.current?.dispose(),H?O&&z.set(i,u.current.saveViewState()):u.current.getModel()?.dispose(),u.current.dispose()}return R.createElement(ge,{width:_,height:B,isEditorReady:g,loading:f,_ref:S,className:K,wrapperProps:G})}var Pt=Mt,St=a.memo(Pt),Tt=St;export{Rt as DiffEditor,St as Editor,Tt as default,F as loader,It as useMonaco};
-//# sourceMappingURL=index-DfjXY3Oo.js.map
+//# sourceMappingURL=index-a3ZL0_Jr.js.map

package/dist/integration-actions-xang7tma.md

@@ -0,0 +1,659 @@
+# Integration Actions
+
+Call actions from installed integrations using a simple, type-safe API.
+
+## Quick Start
+
+```typescript
+import { actions } from "@botpress/runtime";
+
+// Call integration action
+const { items } = await actions.linear.issueList({
+  first: 10,
+  filter: { state: { name: { eq: "In Progress" } } }
+});
+```
+
+## Overview
+
+Integration actions allow you to call functionality from installed integrations (Slack, Linear, GitHub, etc.) using a unified, type-safe API. Each integration exposes actions that map to its capabilities.
+
+**Pattern:**
+```typescript
+await actions.{integration}.{actionName}(params);
+```
+
+**Available in:**
+- Actions
+- Tools
+- Workflows
+- Conversations
+- Triggers
+
+## Installation
+
+Before using integration actions, add the integration to your project:
+
+```bash
+# Add integration
+adk integrations add slack@2.5.5
+
+# Or with custom alias
+adk integrations add linear@2.0.0 --alias my-linear
+
+# Start dev to configure
+adk dev
+```
+
+Then configure the integration in the Dev Console at `localhost:3001` or via `adk integrations configure`.
+
+## Basic Usage
+
+### Importing Actions
+
+```typescript
+import { actions } from "@botpress/runtime";
+```
+
+### Calling Actions
+
+```typescript
+// Slack - Send message
+await actions.slack.sendMessage({
+  channel: "#general",
+  text: "Hello from bot!"
+});
+
+// Linear - List issues
+const { items } = await actions.linear.issueList({
+  first: 10,
+  filter: { state: { name: { eq: "In Progress" } } }
+});
+
+// GitHub - Create issue
+await actions.github.createIssue({
+  owner: "myorg",
+  repo: "myrepo",
+  title: "Bug report",
+  body: "Issue description"
+});
+```
+
+### Alternative: Bracket Notation
+
+Use bracket notation when integration names contain special characters or when accessing them dynamically:
+
+```typescript
+// Useful for dynamic integration names
+const integrationName = "intercom";
+await actions[integrationName].getConversation({
+  intercomConversationId: "conv_123"
+});
+
+// Or when the integration name has special characters
+await actions["my-integration"].someAction({
+  param: "value"
+});
+```
+
+### Type Safety
+
+All integration actions are fully typed with TypeScript:
+
+```typescript
+type LinearIssue = Awaited<ReturnType<typeof actions.linear.getIssue>>;
+
+// TypeScript knows the exact shape of the result
+const issue = await actions.linear.getIssue({ id: "ISS-123" });
+// issue.title, issue.description, issue.state, etc. are all typed
+```
+
+## Converting to AI Tools
+
+Integration actions can be converted to AI-callable tools using `.asTool()`:
+
+```typescript
+await execute({
+  instructions: "Help the user browse the web",
+  tools: [
+    // Convert integration action to tool
+    actions.browser.captureScreenshot.asTool(),
+
+    // Mix with custom tools
+    customSearchTool,
+  ]
+});
+```
+
+**How it works:**
+- The action's input/output schemas become the tool's parameters
+- The action's description (if any) helps the AI understand when to use it
+- The AI can call the tool during autonomous execution
+
+## Common Integration Actions
+
+### Slack Integration
+
+```typescript
+// Send message
+await actions.slack.sendMessage({
+  channel: "#general",
+  text: "Hello!",
+  blocks: [
+    {
+      type: "section",
+      text: { type: "mrkdwn", text: "*Hello* from bot!" }
+    }
+  ]
+});
+
+// Add reaction
+await actions.slack.addReaction({
+  channel: "C123456",
+  timestamp: "1234567890.123456",
+  name: "thumbsup"
+});
+
+// Upload file
+await actions.slack.uploadFile({
+  channels: ["#general"],
+  file: fileBuffer,
+  filename: "report.pdf",
+  title: "Monthly Report"
+});
+```
+
+### Linear Integration
+
+```typescript
+// List issues with filters
+const { items, meta } = await actions.linear.issueList({
+  first: 50,
+  filter: {
+    state: { name: { eq: "In Progress" } },
+    assignee: { email: { eq: "user@example.com" } }
+  },
+  orderBy: { createdAt: "desc" }
+});
+
+// Get specific issue
+const issue = await actions.linear.getIssue({
+  id: "ISS-123"
+});
+
+// Create issue
+await actions.linear.issueCreate({
+  teamId: "team_123",
+  title: "New feature request",
+  description: "Detailed description",
+  priority: 1,
+  assigneeId: "user_456"
+});
+
+// Update issue
+await actions.linear.issueUpdate({
+  id: "ISS-123",
+  stateId: "state_done"
+});
+```
+
+### Browser Integration
+
+```typescript
+// Browse pages (web scraping)
+const { results } = await actions.browser.browsePages({
+  urls: ["https://docs.example.com"],
+  extractType: "markdown",
+  maxPages: 10
+});
+
+// Web search
+const output = await actions.browser.webSearch({
+  query: "Botpress ADK documentation",
+  maxResults: 5
+});
+
+// Capture screenshot
+const screenshot = await actions.browser.captureScreenshot({
+  url: "https://example.com",
+  fullPage: true,
+  format: "png"
+});
+```
+
+### GitHub Integration
+
+```typescript
+// Create issue
+await actions.github.createIssue({
+  owner: "myorg",
+  repo: "myrepo",
+  title: "Bug: Login not working",
+  body: "Steps to reproduce:\n1. ...",
+  labels: ["bug", "priority-high"]
+});
+
+// Get repository
+const repo = await actions.github.getRepository({
+  owner: "myorg",
+  repo: "myrepo"
+});
+
+// Create pull request
+await actions.github.createPullRequest({
+  owner: "myorg",
+  repo: "myrepo",
+  title: "Fix login issue",
+  head: "feature-branch",
+  base: "main",
+  body: "This PR fixes the login issue"
+});
+```
+
+### Discord Integration
+
+```typescript
+// Send message
+await actions.discord.sendMessage({
+  channelId: "123456789",
+  content: "Hello from bot!",
+  embeds: [
+    {
+      title: "Notification",
+      description: "Your task is complete",
+      color: 0x00ff00
+    }
+  ]
+});
+
+// Add reaction
+await actions.discord.addReaction({
+  channelId: "123456789",
+  messageId: "987654321",
+  emoji: "✅"
+});
+```
+
+### WhatsApp Integration
+
+```typescript
+// Send text message
+await actions.whatsapp.sendMessage({
+  to: "+1234567890",
+  type: "text",
+  text: { body: "Hello from bot!" }
+});
+
+// Send template message
+await actions.whatsapp.sendTemplate({
+  to: "+1234567890",
+  template: {
+    name: "order_confirmation",
+    language: { code: "en" },
+    components: [
+      {
+        type: "body",
+        parameters: [{ type: "text", text: "12345" }]
+      }
+    ]
+  }
+});
+```
+
+### Intercom Integration
+
+```typescript
+// Send admin message with attachments
+await actions.intercom.sendAdminMessage({
+  adminId: "admin_123",
+  intercomConversationId: "conv_456",
+  messageType: "comment",
+  body: "Thank you for contacting us!",
+  attachment_urls: ["https://example.com/image.png"]
+});
+
+// Close/open conversation
+await actions.intercom.closeConversation({
+  intercomConversationId: "conv_456",
+  adminId: "admin_123"
+});
+
+// Manage tags
+await actions.intercom.updateConversationTags({
+  intercomConversationId: "conv_456",
+  adminId: "admin_123",
+  tagsToAdd: ["priority"],
+  tagsToRemove: ["pending"]
+});
+```
+
+## Advanced: Building Custom Integration Actions
+
+> **Note**: This section is for integration developers building custom integrations. If you're building a bot and using existing integrations (Slack, Linear, etc.), you can skip this section.
+
+When building a custom integration, you define actions that bot developers can call via `actions.{yourIntegration}.{actionName}()`.
+
+### Integration Action Structure
+
+Here's how integration actions are implemented (example from Intercom integration):
+
+```typescript
+// In integrations/intercom/src/actions/send-admin-message.ts
+import { RuntimeError } from "@botpress/client";
+import * as bp from "../../.botpress";
+
+export const sendAdminMessage: bp.IntegrationProps["actions"]["sendAdminMessage"] =
+  async ({ input }) => {
+    const url = new URL(
+      `https://api.intercom.io/conversations/${input.intercomConversationId}/reply`
+    );
+
+    const requestBody: Record<string, unknown> = {
+      message_type: input.messageType ?? "comment",
+      type: "admin",
+      body: input.body,
+      admin_id: input.adminId,
+    };
+
+    // Add optional parameters
+    if (input.attachment_urls && input.attachment_urls.length > 0) {
+      requestBody.attachment_urls = input.attachment_urls;
+    }
+
+    // Call external API
+    const response = await fetch(url.toString(), {
+      method: "POST",
+      headers: {
+        Authorization: `Bearer ${bp.secrets.TOKEN}`,
+        "Intercom-Version": "2.14",
+        "Content-Type": "application/json",
+      },
+      body: JSON.stringify(requestBody),
+    });
+
+    // Error handling
+    if (!response.ok) {
+      const errorText = await response.text();
+      throw new RuntimeError(
+        `Failed to send admin message: ${response.status} - ${errorText}`
+      );
+    }
+
+    return await response.json();
+  };
+```
+
+### Integration Action Definition
+
+Actions are defined in the integration's definition file:
+
+```typescript
+// In integrations/intercom/integration.definition.ts
+import { Integration, z } from "@botpress/sdk";
+
+export default new Integration({
+  actions: {
+    sendAdminMessage: {
+      title: "Send Admin Message",
+      description: "Send a message as an admin with optional attachments",
+      input: {
+        schema: z.object({
+          adminId: z.string(),
+          intercomConversationId: z.string(),
+          body: z.string(),
+          messageType: z.enum(["comment", "note"]).optional(),
+          attachment_urls: z.array(z.string().url()).max(10).optional(),
+        }),
+      },
+      output: {
+        schema: z.object({
+          id: z.string(),
+          body: z.string(),
+          createdAt: z.string(),
+        }),
+      },
+    },
+    // ... more actions
+  },
+});
+```
+
+### Key Integration Action Patterns
+
+1. **Use RuntimeError for failures** - Provides better error context to bot developers
+2. **Validate external API responses** - Always check `response.ok` and handle errors
+3. **Transform external data** - Map external API schemas to your action output schema
+4. **Use bp.secrets for credentials** - Never hardcode tokens or API keys
+5. **Handle optional parameters** - Check before adding to request body
+6. **Type external API responses** - Use TypeScript types from SDK if available
+
+## Using Integration Actions
+
+### Composing Actions
+
+```typescript
+// In a workflow step
+await step("sync-to-slack", async () => {
+  // Get data from Linear
+  const { items } = await actions.linear.issueList({
+    first: 10,
+    filter: { state: { name: { eq: "Done" } } }
+  });
+
+  // Send to Slack
+  for (const issue of items) {
+    await actions.slack.sendMessage({
+      channel: "#updates",
+      text: `✅ Completed: ${issue.title}`
+    });
+  }
+});
+```
+
+### Using in Workflows
+
+```typescript
+export const SyncLinearWorkflow = new Workflow({
+  name: "syncLinear",
+  async handler({ step }) {
+    // Step 1: Fetch from Linear
+    const issues = await step("fetch-issues", async () => {
+      const { items } = await actions.linear.issueList({
+        first: 50,
+        orderBy: { updatedAt: "desc" }
+      });
+      return items;
+    });
+
+    // Step 2: Process and update
+    await step("update-database", async () => {
+      for (const issue of issues) {
+        await updateDatabase(issue);
+      }
+    });
+  }
+});
+```
+
+### Using in Tools
+
+```typescript
+import { Autonomous, z } from "@botpress/runtime";
+
+export const searchWebTool = new Autonomous.Tool({
+  name: "searchWeb",
+  description: "Search the web for information",
+  input: z.object({
+    query: z.string().describe("Search query")
+  }),
+  output: z.string(),
+  handler: async ({ query }) => {
+    const results = await actions.browser.webSearch({
+      query,
+      maxResults: 5
+    });
+
+    return results
+      .map((r, i) => `${i + 1}. ${r.title}\n${r.snippet}`)
+      .join("\n\n");
+  }
+});
+```
+
+## Type Inference
+
+TypeScript automatically infers types from integration actions:
+
+```typescript
+// Infer return type
+type SearchResult = Awaited<ReturnType<typeof actions.browser.webSearch>>;
+// SearchResult is { title: string; url: string; snippet: string }[]
+
+// Infer parameter type
+type IssueListParams = Parameters<typeof actions.linear.issueList>[0];
+// IssueListParams is { first?: number; filter?: {...}; ... }
+
+// Use in function signatures
+async function processIssues(
+  params: Parameters<typeof actions.linear.issueList>[0]
+) {
+  const { items } = await actions.linear.issueList(params);
+  // ...
+}
+```
+
+## Bot Actions vs Integration Actions
+
+The `actions` proxy handles both:
+
+**Bot Actions** (from `src/actions/*.ts`):
+```typescript
+// Direct access to your bot's actions
+await actions.myCustomAction({ param: "value" });
+```
+
+**Integration Actions** (from installed integrations):
+```typescript
+// Nested under integration name
+await actions.slack.sendMessage({ channel: "#general", text: "Hi" });
+```
+
+The actions proxy automatically determines whether you're calling a bot action (top-level) or an integration action (nested under integration name).
+
+## Troubleshooting
+
+### Integration Not Found
+
+```typescript
+// Error: Could not find integration "slack" and action "sendMessage"
+```
+
+**Solutions:**
+1. Add integration: `adk integrations add slack@2.5.5`
+2. Enable: `adk integrations enable slack`
+3. Configure credentials in Dev Console (localhost:3001) or via `adk integrations configure`
+4. Restart dev server: `adk dev`
+
+### Action Not Found
+
+```typescript
+// Error: Action "nonexistentAction" not found in integration "slack"
+```
+
+**Solutions:**
+1. Check integration documentation for available actions
+2. Verify integration version supports the action
+3. Check for typos in action name
+
+### Type Errors
+
+```typescript
+// Error: Property 'wrongParam' does not exist on type ...
+```
+
+**Solutions:**
+1. Check IntelliSense for correct parameter names
+2. Verify integration version matches your usage
+3. Run `adk dev` to regenerate types
+
+### Authentication Errors
+
+```typescript
+// Error: Integration not authenticated
+```
+
+**Solutions:**
+1. Configure credentials in Dev Console (localhost:3001 during dev)
+2. Set credentials via `adk integrations configure <alias> --set key=value`
+3. Check environment variables are set
+4. Verify API keys/tokens are valid
+
+## Best Practices
+
+### 1. Handle Errors Gracefully
+
+```typescript
+try {
+  await actions.slack.sendMessage({ channel: "#general", text: "Hi" });
+} catch (error) {
+  console.error("Failed to send Slack message:", error);
+  // Fallback or retry logic
+}
+```
+
+### 2. Use Type Inference
+
+```typescript
+// ✅ Good - Let TypeScript infer types
+const issue = await actions.linear.getIssue({ id: "ISS-123" });
+
+// ❌ Bad - Manual typing (can get out of sync)
+const issue: { id: string; title: string } = await actions.linear.getIssue(...);
+```
+
+### 3. Check Integration Availability
+
+```typescript
+// For optional integrations
+const slack = adk.project.integrations.get("slack");
+if (slack) {
+  await actions.slack.sendMessage(...);
+} else {
+  console.log("Slack not configured, skipping notification");
+}
+```
+
+### 4. Batch When Possible
+
+```typescript
+// ✅ Good - Parallel requests
+await Promise.all([
+  actions.slack.sendMessage({ channel: "#team1", text: "Update" }),
+  actions.slack.sendMessage({ channel: "#team2", text: "Update" })
+]);
+
+// ❌ Bad - Sequential (slower)
+await actions.slack.sendMessage({ channel: "#team1", text: "Update" });
+await actions.slack.sendMessage({ channel: "#team2", text: "Update" });
+```
+
+### 5. Use .asTool() for AI
+
+```typescript
+// Make integration actions available to AI
+await execute({
+  instructions: "Help the user",
+  tools: [
+    actions.linear.issueCreate.asTool(),
+    actions.slack.sendMessage.asTool(),
+  ]
+});
+```
+
+## See Also
+
+- **[Agent Configuration](./agent-config.md)** - Installing and configuring integrations
+- **[Actions](./actions.md)** - Creating custom actions
+- **[Tools](./tools.md)** - Creating AI-callable tools
+- **[Workflows](./workflows.md)** - Using actions in workflows
+- **[Context API](./context-api.md)** - Accessing integrations via context