infaira-canvas 0.1.10 → 0.2.0

package/README.md

@@ -11,6 +11,13 @@ CLI toolkit for building and publishing widgets for the **InfAIra Canvas (ICan)*
 1. **Scaffold** a new widget project with all required files
 2. **Upload** a built widget bundle to an ICan portal
 
+Widgets scaffolded with this CLI can call:
+
+- **ICan native actions** — `icanContext.executeAction('Buildings', 'List', { siteId })`
+- **Mythos workflow actions** — `icanContext.executeAction('mythos:Inventory', 'UpdateStock', { sku, qty })`
+
+The only difference at the call site is the `mythos:` prefix on the model name. The ICan backend handles routing (set `MYTHOS_BASE_URL` on the backend to enable). See **section 2a** of the bundled `ICan-Widget-Development-Guide.md` for the full Mythos integration walkthrough.
+
 ---
 
 ## Installation

package/dist/commands/init.js

@@ -294,14 +294,35 @@ export interface IActionOptions {
   executeImmediately?: boolean;
 }
 
+/** A Mythos action published and callable from this widget. Returned by
+ *  IContextProvider.listMythosActions. Invoke one via
+ *  executeAction('mythos:' + model_name, action_name, params). */
+export interface IMythosAction {
+  model_id: string;
+  model_name: string;
+  action_id: string;
+  action_name: string;
+  description?: string;
+  capability?: string;
+}
+
 export interface IContextProvider {
   environment: 'dev' | 'prod';
   orchUrl?: string;
   userKey: string;
   root: string;
   scriptFiles?: string[];
+  /** Invoke a model action.
+   *  - executeAction('Buildings', 'List', { siteId })      → ICan native
+   *  - executeAction('mythos:Inventory', 'UpdateStock', p) → Mythos engine
+   *  The 'mythos:' prefix is the only difference at the call site; the
+   *  ICan backend routes the call appropriately. */
   executeAction(model: string, action: string, parameters: unknown, options?: IActionOptions): Promise<unknown>;
   executeService(app: string, service: string, parameters: unknown, options?: IActionOptions): Promise<unknown>;
+  /** List Mythos actions callable via executeAction('mythos:...', ...).
+   *  Optional — present only when MYTHOS_BASE_URL is configured on the ICan
+   *  backend. Treat absence as "Mythos integration disabled". */
+  listMythosActions?(): Promise<IMythosAction[]>;
   fireEvent(eventId: string): Promise<void>;
   hasAppRole(app: string, role: string): boolean;
   themeName?: string;

package/package.json

@@ -1,13 +1,15 @@
 {
   "name": "infaira-canvas",
-  "version": "0.1.10",
-  "description": "InfAIra Canvas CLI — Widget development toolkit for InfAIra Canvas",
+  "version": "0.2.0",
+  "description": "InfAIra Canvas CLI — scaffold widgets that talk to ICan and Mythos.",
   "keywords": [
     "infaira",
     "ican",
+    "mythos",
     "widget",
     "cli",
-    "scaffold"
+    "scaffold",
+    "workflow"
   ],
   "homepage": "https://infaira.co",
   "license": "MIT",

package/templates/ICan-Widget-Development-Guide.md

@@ -38,7 +38,8 @@ In the portal, `icanContext` is always defined — the widget is never mounted u
 | `language` | `string` | Active language code, e.g. `'en'` |
 | `themeName` | `string \| undefined` | e.g. `'Dark'`, `'Glass Light'` |
 | `themeType` | `'Dark' \| 'Light' \| 'Glass-Dark' \| 'Glass-Light' \| undefined` | Structured theme type for chart colours |
-| `executeAction` | `(model, action, params?, options?) => Promise<unknown>` | Call an Orch model |
+| `executeAction` | `(model, action, params?, options?) => Promise<unknown>` | Call an action. ICan native by default; prefix `model` with `mythos:` to route to the Mythos engine instead. |
+| `listMythosActions` | `() => Promise<IMythosAction[]> \| undefined` | List Mythos actions callable from this widget. Present only when the ICan backend has `MYTHOS_BASE_URL` configured. |
 | `fireEvent` | `(eventId) => Promise<void>` | Trigger a portal event |
 | `hasAppRole` | `(app, role) => boolean` | Check if the user has a role |
 | `$L` | `(code, params?) => string` | Translate a localisation key |
@@ -73,6 +74,59 @@ The dev harness always sets `environment: 'dev'`. The portal always sets `enviro
 
 ---
 
+## 2a. Calling Mythos actions — the `mythos:` prefix
+
+ICan widgets can invoke actions running in the Mythos workflow engine through the exact same `executeAction` call, just by prefixing the `model` argument with `mythos:`. The host backend inspects the prefix and routes the request to the Mythos engine via the shared JWT.
+
+```tsx
+// 1. Discover what's available (call once at mount and cache)
+const actions = await icanContext.listMythosActions?.();
+// → [{ model_id, model_name: 'Inventory', action_id, action_name: 'UpdateStock', description }]
+
+// 2. Invoke a Mythos action — only the `mythos:` prefix differs from a
+//    native ICan call
+const result = await icanContext.executeAction(
+  'mythos:Inventory',     // <- the prefix is what triggers Mythos routing
+  'UpdateStock',
+  { sku: 'ABC-123', qty: 5 },
+);
+// → { run_id: '...', status: 'ok', output?: {...} }
+```
+
+### When to use Mythos vs native
+
+| Use Mythos when… | Use native ICan when… |
+|---|---|
+| The logic is a multi-step workflow with branches, retries, or external calls | The call is a direct read/write to a backing service (Locations, Assets, etc.) |
+| You want the call recorded in Mythos's execution log + debugger | You don't need step-level tracing |
+| Multiple widgets need to call the same business operation | The operation is widget-local |
+| You want to publish the same logic over a REST endpoint too | The widget owns the orchestration |
+
+### Failure modes to handle
+
+`executeAction('mythos:...')` can reject with:
+
+- **`mythos integration not configured`** — the ICan backend doesn't have `MYTHOS_BASE_URL` set. Surface this to the user and fall back gracefully.
+- **`mythos model "X" not found or not published`** — the action either doesn't exist or isn't toggled `published: true` in Mythos.
+- **HTTP / network errors** — same as any `executeAction` call.
+
+`listMythosActions` is also `undefined` when integration is disabled — so guard with `?.()`.
+
+```tsx
+const handleRun = async () => {
+  try {
+    const r = await icanContext.executeAction('mythos:Inventory', 'UpdateStock', { sku, qty });
+    setResult(r);
+  } catch (e) {
+    setError(e instanceof Error ? e.message : 'Failed');
+  }
+};
+```
+
+A working reference widget lives at `Widgets/ICan widgets/mythosdemo/` — pick an action, fill params, run, render the response.
+
+---
+
 ## 3. Widget settings panel — `IWidgetPropConfig`
 
 Widgets can expose a settings form in the portal. Users open it by clicking the ⚙ button on a widget cell in edit mode. You define the fields in `registerWidget`:

package/templates/ICan-Widget-Theming-Guide.md

@@ -594,7 +594,10 @@ interface IContextProvider {
   orchUrl?:     string;
   apiKey?:      string;
 
-  // Fetch data from Orch
+  // Invoke an action. Prefix model with `mythos:` to route to the Mythos
+  // workflow engine instead of the default ICan native pipeline:
+  //   executeAction('Buildings', 'List', { siteId })            → ICan native
+  //   executeAction('mythos:Inventory', 'UpdateStock', { ... }) → Mythos engine
   executeAction(
     model: string,
     action: string,
@@ -602,6 +605,16 @@ interface IContextProvider {
     options?: IActionOptions
   ): Promise<unknown>;
 
+  // List Mythos actions callable via executeAction('mythos:...', ...).
+  // Optional — present only when MYTHOS_BASE_URL is set on the ICan backend.
+  listMythosActions?(): Promise<Array<{
+    model_id: string;
+    model_name: string;
+    action_id: string;
+    action_name: string;
+    description?: string;
+  }>>;
+
   executeService(
     app: string,
     service: string,

package/templates/ican.d.ts

@@ -701,17 +701,51 @@ declare module "ican/context" {
       email?: string;
       roles?: string[];
     };
-    /** Invoke a registered model action on this dashboard. */
+    /**
+     * Invoke a model action on this dashboard.
+     *
+     * Routing happens server-side by inspecting `model`:
+     *   - `executeAction('Buildings', 'List', { siteId })`
+     *       → ICan native action (existing Orch pipeline).
+     *   - `executeAction('mythos:Inventory', 'UpdateStock', { sku, qty })`
+     *       → routed to the Mythos engine via the `mythos:` prefix. Resolves
+     *         to the published Mythos action with that (model_name, action_name)
+     *         and POSTs to `/api/models/{id}/actions/{id}/run`.
+     *
+     * Both call shapes return a Promise that resolves to the action's output
+     * envelope. For Mythos, the envelope is `{ run_id, status, output? }`.
+     */
     executeAction(
       model: string,
       action: string,
       params?: Record<string, unknown>
     ): Promise<unknown>;
+    /**
+     * List every Mythos action published and callable from this widget.
+     * Optional — present only when the ICan backend has MYTHOS_BASE_URL set.
+     * Widgets that build action pickers (settings panels, etc.) call this
+     * once at mount and cache the result themselves.
+     */
+    listMythosActions?: () => Promise<IMythosAction[]>;
     /** Resolve a relative ICan backend path against the portal base URL. */
     resolveUrl(path: string): string;
     /** Logging helper namespaced to this widget instance. */
     log(level: "info" | "warn" | "error", ...args: unknown[]): void;
   }
+
+  /**
+   * A single Mythos action published as callable from a widget. Returned by
+   * `icanContext.listMythosActions()`. To invoke one, call
+   * `icanContext.executeAction('mythos:' + model_name, action_name, params)`.
+   */
+  export interface IMythosAction {
+    model_id: string;
+    model_name: string;
+    action_id: string;
+    action_name: string;
+    description?: string;
+    capability?: string;
+  }
 }
 
 // ─── Global runtime declarations ─────────────────────────────────────────────

package/templates/index.html

@@ -1419,13 +1419,30 @@
       orchUrl: localStorage.getItem(LS_ORCH_URL) || '',
       apiKey:  localStorage.getItem(LS_API_KEY)  || '',
       executeAction: function (model, action, params) {
-        console.log('[ICan Dev] executeAction:', model, action, params);
+        // Mythos-routed calls use the `mythos:<ModelName>` prefix in production.
+        // In the dev harness we just log them distinctively so authors can see
+        // whether their widget is targeting ICan native or Mythos.
+        var isMythos = typeof model === 'string' && model.toLowerCase().indexOf('mythos:') === 0;
+        console.log('[ICan Dev]' + (isMythos ? ' [Mythos]' : '') + ' executeAction:', model, action, params);
+        if (isMythos) {
+          // Mock the Mythos response envelope: { run_id, status, output }.
+          return Promise.resolve({ run_id: 'dev-' + Date.now(), status: 'ok', output: {} });
+        }
         return Promise.resolve([]);
       },
       executeService: function (app, service, params) {
         console.log('[ICan Dev] executeService:', app, service, params);
         return Promise.resolve(null);
       },
+      listMythosActions: function () {
+        // Dev stub — returns a couple of synthetic actions so widgets that
+        // populate dropdowns from discovery don't render empty.
+        console.log('[ICan Dev] listMythosActions');
+        return Promise.resolve([
+          { model_id: 'dev-model-1', model_name: 'Inventory',  action_id: 'dev-action-1', action_name: 'UpdateStock', description: 'Dev stub' },
+          { model_id: 'dev-model-2', model_name: 'Buildings', action_id: 'dev-action-2', action_name: 'List',         description: 'Dev stub' },
+        ]);
+      },
       fireEvent: function (id) {
         console.log('[ICan Dev] fireEvent:', id);
         return Promise.resolve();

package/templates/ui.html

@@ -1123,13 +1123,25 @@
       orchUrl:        localStorage.getItem(LS_ORCH_URL) || '',
       apiKey:         localStorage.getItem(LS_API_KEY)  || '',
       executeAction:  function (model, action, params) {
-        console.log('[ICan Dev] executeAction:', model, action, params);
+        // Mythos-routed calls use the `mythos:<ModelName>` prefix.
+        var isMythos = typeof model === 'string' && model.toLowerCase().indexOf('mythos:') === 0;
+        console.log('[ICan Dev]' + (isMythos ? ' [Mythos]' : '') + ' executeAction:', model, action, params);
+        if (isMythos) {
+          return Promise.resolve({ run_id: 'dev-' + Date.now(), status: 'ok', output: {} });
+        }
         return Promise.resolve([]);
       },
       executeService: function (app, service, params) {
         console.log('[ICan Dev] executeService:', app, service, params);
         return Promise.resolve(null);
       },
+      listMythosActions: function () {
+        console.log('[ICan Dev] listMythosActions');
+        return Promise.resolve([
+          { model_id: 'dev-model-1', model_name: 'Inventory',  action_id: 'dev-action-1', action_name: 'UpdateStock', description: 'Dev stub' },
+          { model_id: 'dev-model-2', model_name: 'Buildings', action_id: 'dev-action-2', action_name: 'List',         description: 'Dev stub' },
+        ]);
+      },
       fireEvent:      function (id) {
         console.log('[ICan Dev] fireEvent:', id);
         return Promise.resolve();