@onereach/idw-apps 0.1.2-beta.6.0

package/README.md

@@ -0,0 +1,411 @@
+# @onereach/idw-apps
+
+IDW adapter around [`@modelcontextprotocol/ext-apps`](https://www.npmjs.com/package/@modelcontextprotocol/ext-apps) for hosting **MCP Apps** and embedded IDW web apps (Web Skills, feed widgets, sidebar apps), plus a small iframe-facing IDW/OpenAI-compatible **widget-state** API.
+
+This is a thin wrapper, not a replacement or a new framework:
+
+- All standard MCP Apps behavior is preserved (tool input/result notifications, app tool calls, server tool calls, server resource/prompt discovery, resource reads, messages, downloads, open-link, logging, size changes, display-mode requests, teardown requests, and model-context updates).
+- On top of that it adds an **IDW app channel** (`window.idw.app`) for durable state and host actions, plus an optional **OpenAI Apps SDK compatibility shim** (`window.openai`).
+- IDW app methods intentionally mirror MCP Apps semantics: `callIdwAction()` feels like `callServerTool()`, and `updateAgentContext()` feels like `updateModelContext()`.
+- It is **framework-agnostic** — no Vue/React. State persistence happens through caller callbacks, never direct store/backend imports.
+
+External apps built directly with `@modelcontextprotocol/ext-apps` work with the
+host bridge. They use the standard MCP Apps JSON-RPC transport and do not need
+`@onereach/idw-apps/app`. The IDW channel is additive and ignored by standard
+MCP apps.
+
+Current OpenAI Apps SDK apps that use the
+[standard MCP Apps bridge](https://developers.openai.com/apps-sdk/mcp-apps-in-chatgpt#host-bridge)
+have the same compatibility. ChatGPT-only `window.openai` extensions are a separate layer:
+IDW currently provides only the documented widget-state aliases, not the full
+ChatGPT component runtime (`callTool`, file APIs, modals, checkout, and other
+host-specific extensions). Build portable app behavior on MCP Apps and
+feature-detect optional `window.openai` methods.
+
+> **Module format:** ESM-only with `bundler` module resolution (required to consume `@modelcontextprotocol/ext-apps`' `exports` map). Both consumers — the IDW host (Vite) and in-iframe apps — are bundled, so this is a deliberate deviation from the CJS+ESM packages in this repo.
+
+## Install
+
+```bash
+pnpm add @onereach/idw-apps
+```
+
+`@onereach/idw-apps` owns the underlying MCP Apps SDK dependency. IDW app authors do not
+install or import `@modelcontextprotocol/ext-apps` directly.
+
+## Two entry points
+
+| Import | Runs in | Purpose |
+|--------|---------|---------|
+| `@onereach/idw-apps` | Host (idw-ui) | `createIdwAppBridge` — wrap `AppBridge` for one app iframe |
+| `@onereach/idw-apps/app` | Inside the app iframe | `App` / `createIdwApp` — standard MCP App plus IDW state/actions |
+
+## Host side
+
+```ts
+import { createIdwAppBridge } from '@onereach/idw-apps';
+
+const bridge = createIdwAppBridge({
+  iframe,
+  idwId,
+  chatId,
+  hostKey,                // durable app-instance identity
+  surface: 'app-sidebar', // web-app | feed-widget | app-sidebar | chat-inline | fullscreen
+  appInstanceId: hostKey,
+  auth: {
+    getOrToken: (ctx) => issueOrTokenForApp(ctx),
+    apiBaseUrl: IDW_API_URL,
+    allowTokenRequest: true, // enables lazy callIdwAction({ name: 'getAuthToken' })
+  },
+  // Include getAuthToken here when an allowlist is present and lazy auth is enabled.
+  allowedActions: ['openSkill', 'startConversation', 'getAuthToken'],
+  artifactId,             // optional: current MCP-backed runtime tool call
+  toolCallId,             // optional: current MCP-backed tool call id
+  initialState,           // durable widget/view state previously loaded from your DB
+  onStateChange: (state) => persistWidgetState(chatId, hostKey, state), // may be async
+  onIdwAction: (params, ctx) => handleIdwAction(params, ctx),
+  onCallTool: (params, ctx) => chatApi.callMcpAppTool(ctx.chatId!, ctx.artifactId!, params),
+  onListResources: (params, ctx) => chatApi.listMcpAppResources(ctx.chatId!, ctx.artifactId!, params),
+  onListResourceTemplates: (params, ctx) => chatApi.listMcpAppResourceTemplates(ctx.chatId!, ctx.artifactId!, params),
+  onListPrompts: (params, ctx) => chatApi.listMcpAppPrompts(ctx.chatId!, ctx.artifactId!, params),
+  onReadResource: (params, ctx) => chatApi.readMcpAppResource(ctx.chatId!, ctx.artifactId!, params),
+  onMessage: (params, ctx) => enqueueAppMessage(ctx.chatId!, ctx.hostKey!, params),
+  onDownloadFile: (params, ctx) => downloadFromApp(ctx.hostKey!, params),
+  // Keep the original MCP payload: it may be structured-only, in which case
+  // `text` is an empty string.
+  onUpdateModelContext: (text, params) => queueAppContext(hostKey, { text, params }),
+});
+
+await bridge.connect();
+
+// New agent turn on the same app — no reconnect, no iframe reload:
+await bridge.updateRuntimeContext({
+  artifactId: next.tool_call_id,
+  toolCallId: next.tool_call_id,
+  toolInput: next.tool_args,
+  toolResult: next.tool_result,
+});
+
+// on unmount
+await bridge.disconnect();
+```
+
+### Returned API
+
+- `connect()` / `disconnect()`
+- `updateRuntimeContext({ artifactId, toolCallId, toolInput, toolResult })` — update runtime identity without recreating the bridge
+- `sendToolInput(args, toolCallId?)` / `sendToolResult(result, toolCallId?)` — stale `toolCallId` values are ignored
+- `listAppTools()` / `callAppTool(params, options?)` — discover and invoke standard MCP tools supplied by the connected iframe app
+- `getAppCapabilities()` — inspect capabilities declared by the initialized app before discovering optional features such as app tools
+- `sendToolCancelled(reason?)`
+- `sendToolListChanged()` / `sendResourceListChanged()` / `sendPromptListChanged()`
+- `setHostContext(context)` — update standard MCP Apps host context while preserving `hostContext.idw`
+- `getWidgetState()` / `setWidgetState(state)`
+- IDW host context is sent through MCP host context under `hostContext.idw`:
+  `{ idwId, surface, appInstanceId, auth: { apiBaseUrl }, allowedActions }`.
+  `auth.orToken` is omitted by default.
+
+For advanced host integrations, `@onereach/idw-apps` also exports:
+
+- `McpAppBridge` — the low-level upstream MCP Apps host bridge
+- `McpAppBridgePostMessageTransport`
+
+Use `createIdwAppBridge` for IDW chat apps unless you explicitly need to build
+your own host lifecycle/state adapter.
+
+`onOpenIdwApp` and `openIdwAppToolName` remain available only as deprecated
+migration hooks for the legacy `open_idw_app` convention. New integrations
+should use standard MCP tools.
+
+### Host persistence contract
+
+`onStateChange` is the only persistence hook. When an app calls
+`window.idw.app.setWidgetState(state)` or `window.openai.setWidgetState(state)`, the
+host wrapper updates its in-memory state immediately and then invokes
+`onStateChange(state)`. Store that value in your DB using the durable `hostKey`
+(usually scoped by `chatId` and user/session). On the next reload, load that DB
+value first and pass it back as `initialState`.
+
+The package does not import your DB/client/store directly.
+
+### Artifact / runtime split
+
+- `hostKey` identifies the durable app instance — one bridge, one iframe.
+- `artifactId` / `toolCallId` identify the current runtime tool call and may change over the bridge's lifetime.
+- `updateRuntimeContext` updates them **without** recreating `AppBridge` or reloading the iframe, so widget UI state survives new turns.
+- Generic Web Apps can omit runtime tool-call identity and MCP proxy callbacks entirely.
+
+### App-provided tools
+
+An iframe app can expose standard MCP tools for the host or agent to call. After
+the app initializes, discover and invoke those tools through the bridge:
+
+```ts
+if (bridge.getAppCapabilities()?.tools) {
+  const appTools = await bridge.listAppTools();
+
+  const result = await bridge.callAppTool({
+    name: 'listTasks',
+    arguments: {},
+  }, {
+    timeout: 10_000,
+  });
+}
+```
+
+`callAppTool()` is host → app. It is distinct from `onCallTool` and
+`app.callServerTool()`, which are app → MCP-server operations. It delegates to
+the standard MCP Apps `tools/list` and `tools/call` protocol; the package adds
+no IDW-specific action messages.
+
+App-provided tools exist only while their iframe is connected. IDW UI/API is
+responsible for deciding which tools become agent-visible, namespacing them by
+app instance, applying product policy/confirmation, and routing an agent call
+to the live bridge. A backend capability that must work without the iframe
+mounted should be a server/backend tool instead.
+
+Use the following direction map when choosing an API:
+
+| Intent | API |
+| --- | --- |
+| App calls its MCP server | `app.callServerTool()` |
+| IDW host/agent calls a live app tool | `bridge.listAppTools()` / `bridge.callAppTool()` |
+| App requests an IDW host/platform action | `app.callIdwAction()` |
+| App gives concise context to the agent | `app.updateAgentContext()` |
+| App saves a lightweight restore hint | `app.state.setWidgetState()` |
+
+## App side (inside the iframe)
+
+```ts
+import { createIdwApp } from '@onereach/idw-apps/app';
+
+const app = createIdwApp({
+  appInfo: {
+    name: 'Hangman',
+    version: '1.0.0',
+  },
+});
+
+app.ontoolinput = ({ arguments: args }) => {
+  // Standard MCP Apps tool input notification.
+};
+
+app.ontoolresult = (result) => {
+  // Store/render the latest authoritative business snapshot from
+  // result.structuredContent.
+};
+
+app.state.subscribeWidgetState((state) => {
+  // Reapply only a lightweight view/restore hint such as a route or selected ID.
+});
+
+await app.connect(); // Connect immediately so tool input/results can arrive.
+
+const hostCapabilities = app.getHostCapabilities();
+const hostContext = app.getHostContext();
+
+const access = await app.validateAccess({
+  url: window.location.href,
+});
+
+app.state.getWidgetState();                 // -> latest widget state known to the app
+app.state.setWidgetState({ tab: 'chart' }); // replaces the whole widget-state object
+app.state.subscribeWidgetState((state) => {
+  // React to local or host-pushed state changes.
+});
+
+await app.callIdwAction({
+  name: 'openSkill',
+  arguments: {
+    skillId: 'training',
+  },
+});
+
+const auth = await app.getAuthToken();
+// auth.token is an OR user identity token for this web app session.
+
+await app.updateAgentContext({
+  content: [{
+    type: 'text',
+    text: 'User selected lesson 3 and opened quiz remediation.',
+  }],
+  structuredContent: {
+    selectedLessonId: 'lesson-3',
+    currentView: 'quiz-remediation',
+  },
+});
+
+// OpenAI compatibility shim (aliases only):
+window.openai.widgetState;
+window.openai.setWidgetState({ tab: 'chart' });
+```
+
+For advanced cases, `@onereach/idw-apps/app` also exports:
+
+- `App` / `IdwApp` — IDW's subclass of the standard MCP Apps `App`
+- `PostMessageTransport`
+- `installIdwAppApi` — state-only installer, only for custom bootstraps or legacy integrations
+
+New apps should use `createIdwApp()` rather than calling `installIdwAppApi()` directly.
+
+The iframe API is available only to apps that install this entry point, or to
+HTML resources where the IDW API injects an equivalent bootstrap while proxying
+the resource. A cross-origin app loaded by URL cannot be modified by the host
+after it has loaded.
+
+### App-provided tools
+
+Apps can expose standard MCP tools that the host may make available to the
+agent. This works for UI actions (`openRequest`) and app/backend actions
+(`listTasks`) alike; the app owns the implementation.
+
+```ts
+const app = createIdwApp({
+  appInfo: {
+    name: 'Tasks',
+    version: '1.0.0',
+  },
+  capabilities: {
+    tools: {},
+  },
+});
+
+app.onlisttools = async () => ({
+  tools: [{
+    name: 'listTasks',
+    description: 'List tasks visible to the current user.',
+    inputSchema: {
+      type: 'object',
+      properties: {},
+    },
+    annotations: {
+      readOnlyHint: true,
+    },
+  }],
+});
+
+app.oncalltool = async ({ name, arguments: args }) => {
+  if (name !== 'listTasks') {
+    return { content: [], isError: true };
+  }
+
+  const tasks = await appBackend.listTasks(args);
+  return {
+    content: [{ type: 'text', text: `Found ${tasks.length} tasks.` }],
+    structuredContent: { tasks },
+  };
+};
+```
+
+Register `onlisttools` and `oncalltool` before `app.connect()`. Use accurate
+descriptions and JSON Schema, return MCP `CallToolResult` values, and set tool
+annotations such as `readOnlyHint` or `destructiveHint` honestly. The host—not
+the app—decides whether a declared tool is agent-visible or needs confirmation.
+
+### MCP-backed and Web Apps
+
+An IDW Web App is an app that is not backed by an MCP server/resource. It still
+uses the same MCP Apps transport and `createIdwApp()` initialization handshake
+as an MCP-backed app; only its business-data source differs.
+
+- A generic Web App normally omits `capabilities`. Add `capabilities.tools` only
+  when the app itself exposes MCP-style tools to the host/agent.
+- Use `callServerTool()` and server resource APIs only when the host is proxying
+  an MCP server for this app. Otherwise use the app's own backend for business
+  APIs and `callIdwAction()` only for IDW host/platform actions.
+- Use `app.validateAccess()` after `app.connect()` when the app needs to verify
+  the current user can access the Web App/skill. The host must provide `idwId`,
+  `auth.apiBaseUrl`, and lazy token access.
+- The host bridge may omit `artifactId`, `toolCallId`, and MCP proxy callbacks
+  for a Web App.
+
+### Business data and widget state
+
+- Tool input/result uses standard MCP Apps notifications. A tool that renders or
+  updates an app should return the complete current business-data snapshot in
+  `structuredContent`. Treat that latest tool result as authoritative and
+  re-render from it.
+- Widget state is only a lightweight UI/restore overlay: route, selected ID,
+  active tab, draft ID, current step, or an opaque backend `sessionId`.
+- Tool results and widget-state messages are independent. Either can arrive
+  first, and widget state can be absent on an app's first render. Register both
+  handlers and call `app.connect()` immediately; do not wait for widget state
+  before connecting or rendering the initial tool result.
+- When a new tool result arrives, replace business data with that snapshot and
+  reapply only still-valid UI state. Never merge widget state into business data.
+- If a restore hint starts a backend fetch, do not let that older fetch overwrite
+  a newer tool-result snapshot.
+
+### Widget-state semantics
+
+- `stateOptions.initialState` is an iframe-local fallback before the host replies.
+  It is useful for custom integrations but is not the durable host snapshot; new
+  apps normally leave it unset.
+- `setWidgetState(state)` **replaces** the whole widget-state object and updates local state immediately; the host persists asynchronously via `onStateChange` (the iframe never blocks on persistence).
+- `whenWidgetStateReady()` is an optional signal for code that needs a restore hint
+  after `app.connect()`. It resolves on a host reply or the fallback timeout; it
+  is never a prerequisite for MCP initialization or first render.
+- `getWidgetState()` returns the latest widget state known to the wrapper.
+- `subscribeWidgetState(listener)` observes both local `setWidgetState` calls and host-pushed widget-state changes.
+- `getState()`, `setState()`, `whenStateReady()`, and `subscribeState()` remain as deprecated aliases for existing apps.
+- Widget state must be **JSON-serializable** and is **lightweight widget/view state only** — never store tool results or authoritative business data as widget state.
+
+### IDW actions and agent context
+
+- `callIdwAction({ name, arguments })` requests a host/platform action. It returns a standard MCP `CallToolResult`; errors use `isError: true`.
+- Hosts may pass `allowedActions`. When set, every IDW action—including the
+  configured auth-token action—must be included or it is rejected.
+- Action names are host-defined strings. This package does not hardcode `openSkill`, `startConversation`, `close`, or other product actions.
+- `getAuthToken` is the built-in lazy auth action. It only returns a token when
+  the host passes `auth.allowTokenRequest: true` and, when an allowlist is set,
+  includes that action; otherwise it returns `isError: true`.
+- Hosts can pass `auth.getOrToken(runtimeContext)` to retrieve or generate a
+  fresh token for every actual token-action request. The provider receives the
+  current live runtime context, takes precedence over `auth.orToken`, and is not
+  called during bridge creation or connection. The host bridge does not cache
+  provider results.
+- `app.getAuthToken()` is the preferred app-side helper. It requests the OR user
+  identity token lazily and reuses the in-memory token for the current web app
+  session, so `validateAccess()` and later app API calls do not need duplicate
+  token requests. Use `forceRefresh: true` only when the host/app explicitly
+  needs to replace the session token.
+- `validateAccess({ url })` is an app-side helper for IDW Web apps/skills. It
+  reads `hostContext.idw.idwId` and `hostContext.idw.auth.apiBaseUrl`, requests
+  the same cached `orToken` used by `app.getAuthToken()`, then calls
+  `POST /idw/:idwId/skills/access` from the app. Call it after `app.connect()`.
+- `updateAgentContext(params)` is a semantic alias for MCP Apps `updateModelContext(params)`. It does not add a custom payload shape.
+- The host callback receives both flattened text and the original MCP params.
+  Preserve the original params: a useful update can be structured-only and have
+  no text to flatten.
+- Use `updateAgentContext()` only for app-reported context the IDW agent should understand in future turns. Use `sendLog()` for debug/telemetry.
+- Auth currently supports only `orToken`; it is a user identity token issued for
+  one web app session. The app wrapper caches it in memory for the app instance.
+  The host may provide a static `auth.orToken` or generate one lazily with
+  `auth.getOrToken`; the package itself does not mint, refresh, or persist tokens.
+
+### OpenAI compatibility
+
+- `window.openai.widgetState` mirrors the latest IDW widget state.
+- `window.openai.setWidgetState(state)` delegates to `window.idw.app.setWidgetState(state)`.
+- Existing `window.openai` fields are preserved; the shim only adds/replaces `widgetState` and `setWidgetState`, then restores previous values on `dispose()`.
+- These are compatibility shims only, not a full OpenAI Apps SDK, and should only be exposed inside MCP app iframes.
+- Apps that depend only on ChatGPT-specific `window.openai` methods are not
+  automatically portable to IDW. Their core transport should use MCP Apps;
+  optional ChatGPT extensions must be feature-detected.
+
+## Security
+
+- Every inbound state message is validated against the target iframe's `contentWindow` (host) / the host window (app) before it is trusted.
+- Every inbound action message uses the same iframe source validation and optional action allowlist before caller code runs.
+- Standard MCP Apps traffic stays on the upstream `PostMessageTransport`; the
+  IDW channel ignores MCP JSON-RPC frames and sends host-initiated IDW state
+  messages only after the iframe has opted into the IDW channel.
+- IDW/OpenAI APIs are only present in iframes that call `installIdwAppApi`.
+- Tool calls and resource reads are routed through your callbacks, so they keep going through the backend's existing authorization checks.
+- The IDW side channel validates the iframe window and binds a non-opaque app origin when the bridge is created. Sandboxed opaque-origin/srcdoc apps require wildcard targeting, so only enable token access for app resources and configuration the host already trusts.
+- `orToken` is not exposed through host context by default. Prefer lazy token access via `callIdwAction({ name: 'getAuthToken' })` with `auth.allowTokenRequest: true`; also allowlist that action when `allowedActions` is set. `auth.getOrToken` and its resolved values are never serialized into host context. Use `auth.exposeInHostContext: true` only for trusted legacy apps that need eager injection of a static `auth.orToken`; it never invokes the provider.
+- Do not leak `chatId`, auth tokens, or backend URLs into model context unless explicitly required.
+
+## Non-goals
+
+Does not replace `@modelcontextprotocol/ext-apps`, does not add custom IDW aliases for MCP tool calls/resource reads (those stay on the standard MCP bridge), does not mint auth tokens, does not migrate RWC/pageData integrations, and does not make the OpenAI Apps SDK the primary abstraction.

package/dist/app/createIdwApp.d.ts

@@ -0,0 +1,104 @@
+import { App as McpApp, PostMessageTransport } from '@modelcontextprotocol/ext-apps';
+import type { IdwActionParams, IdwActionResult } from '../types';
+import { type IdwActionCallOptions, type InstalledIdwAppApi, type InstallIdwAppApiOptions } from './installIdwAppApi';
+export type IdwAppInfo = ConstructorParameters<typeof McpApp>[0];
+export type IdwAppCapabilities = ConstructorParameters<typeof McpApp>[1];
+export type IdwAppOptions = ConstructorParameters<typeof McpApp>[2];
+export type IdwAgentContextParams = Parameters<McpApp['updateModelContext']>[0];
+export type IdwStateOptions = InstallIdwAppApiOptions;
+export interface IdwAuthToken {
+    token: string;
+    tokenType: 'or-token';
+    apiBaseUrl?: string;
+}
+export interface GetAuthTokenOptions extends IdwActionCallOptions {
+    /** Lazy auth-token action name. Defaults to `getAuthToken`. */
+    tokenActionName?: string;
+    /** Request a new token instead of reusing the in-memory app-session token. */
+    forceRefresh?: boolean;
+}
+export interface ValidateAccessParams {
+    /** App URL checked by the IDW API. Defaults to `window.location.href`. */
+    url?: string;
+}
+export interface ValidateAccessOptions extends GetAuthTokenOptions {
+    /** Fetch implementation override for tests or custom runtimes. */
+    fetch?: typeof fetch;
+}
+export interface SkillData {
+    slug: string;
+    id: string;
+    name: string;
+    description: string;
+    created_at: string;
+    meta: {
+        skill: {
+            advanced: boolean;
+            disabled: boolean;
+            editable: boolean;
+            docUrl?: string;
+        };
+        chat?: {
+            id: string;
+            url: string;
+            web?: boolean;
+        };
+    };
+}
+export interface ValidateAccessResult {
+    skill: SkillData;
+    user?: {
+        role: string;
+        userId?: string;
+        email?: string;
+        accountId?: string;
+        idwId?: string;
+        contactId?: string;
+    };
+}
+export interface CreateIdwAppOptions {
+    /** App identity sent through the standard MCP Apps initialize handshake. */
+    appInfo: IdwAppInfo;
+    /** Standard MCP Apps capabilities declared by the iframe app. */
+    capabilities?: IdwAppCapabilities;
+    /** Standard MCP Apps options, forwarded to `@modelcontextprotocol/ext-apps` App. */
+    appOptions?: IdwAppOptions;
+    /** IDW/OpenAI-compatible widget-state options. */
+    stateOptions?: IdwStateOptions;
+}
+/**
+ * IDW's app-side MCP App class.
+ *
+ * This extends the standard `@modelcontextprotocol/ext-apps` `App` class, so it
+ * still performs the normal MCP Apps initialize handshake and exposes
+ * `getHostCapabilities()`, `getHostContext()`, `callServerTool()`, etc. IDW adds
+ * widget state, host/platform actions, and a semantic agent-context alias. The
+ * state API installs `window.idw.app` and the optional `window.openai`
+ * compatibility shim.
+ */
+export declare class IdwApp extends McpApp {
+    readonly state: InstalledIdwAppApi;
+    private authToken?;
+    private authTokenRequest?;
+    constructor(appInfo: IdwAppInfo, capabilities?: IdwAppCapabilities, appOptions?: IdwAppOptions, stateOptions?: IdwStateOptions);
+    /** Request an IDW host/platform action. Mirrors MCP `callServerTool()`. */
+    callIdwAction(params: IdwActionParams, options?: IdwActionCallOptions): Promise<IdwActionResult>;
+    /** Semantic IDW alias for MCP Apps `updateModelContext()`. */
+    updateAgentContext(params: IdwAgentContextParams, options?: Parameters<McpApp['updateModelContext']>[1]): ReturnType<McpApp['updateModelContext']>;
+    /** Return the OR user identity token for this app session, requesting it lazily once. */
+    getAuthToken(options?: GetAuthTokenOptions): Promise<IdwAuthToken>;
+    /**
+     * Validate that the current user can access this IDW Web app/skill.
+     *
+     * This intentionally keeps the old app-side `idw-skill` behavior: the app
+     * requests a lazy OR token, then calls the IDW API itself. Call after
+     * `connect()`, because it depends on MCP host context.
+     */
+    validateAccess(params?: ValidateAccessParams, options?: ValidateAccessOptions): Promise<ValidateAccessResult>;
+    /** Remove IDW globals and close the underlying MCP App transport. */
+    dispose(): Promise<void>;
+}
+/** Create an IDW app-side MCP App with widget-state support installed. */
+export declare function createIdwApp(options: CreateIdwAppOptions): IdwApp;
+export { PostMessageTransport };
+//# sourceMappingURL=createIdwApp.d.ts.map

package/dist/app/createIdwApp.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"createIdwApp.d.ts","sourceRoot":"","sources":["../../src/app/createIdwApp.ts"],"names":[],"mappings":"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"}

package/dist/app/createIdwApp.js

@@ -0,0 +1,151 @@
+import { App as McpApp, PostMessageTransport, } from '@modelcontextprotocol/ext-apps';
+import { installIdwAppApi, } from './installIdwAppApi';
+const DEFAULT_AUTH_TOKEN_ACTION = 'getAuthToken';
+function isRecord(value) {
+    return typeof value === 'object' && value !== null;
+}
+function currentUrl(url) {
+    const resolved = url ?? globalThis.window?.location?.href;
+    if (!resolved) {
+        throw new Error('IdwApp.validateAccess: url is required outside a browser window');
+    }
+    return resolved;
+}
+function validateAccessUrl(apiBaseUrl, idwId) {
+    const base = apiBaseUrl.endsWith('/') ? apiBaseUrl : `${apiBaseUrl}/`;
+    return new URL(`idw/${encodeURIComponent(idwId)}/skills/access`, base).toString();
+}
+function extractAuthToken(result, apiBaseUrl) {
+    const structuredContent = result.structuredContent;
+    if (!isRecord(structuredContent) || typeof structuredContent.token !== 'string') {
+        throw new Error('IdwApp.getAuthToken: getAuthToken did not return a token');
+    }
+    if (structuredContent.tokenType !== undefined
+        && structuredContent.tokenType !== 'or-token') {
+        throw new Error('IdwApp.getAuthToken: getAuthToken returned an unsupported token type');
+    }
+    return {
+        token: structuredContent.token,
+        tokenType: 'or-token',
+        apiBaseUrl: typeof structuredContent.apiBaseUrl === 'string'
+            ? structuredContent.apiBaseUrl
+            : apiBaseUrl,
+    };
+}
+function extractToolError(result) {
+    const content = result.content;
+    if (Array.isArray(content)) {
+        const text = content
+            .map((block) => (isRecord(block) && typeof block.text === 'string' ? block.text : ''))
+            .filter(Boolean)
+            .join('\n');
+        if (text) {
+            return text;
+        }
+    }
+    return 'Auth token access failed';
+}
+/**
+ * IDW's app-side MCP App class.
+ *
+ * This extends the standard `@modelcontextprotocol/ext-apps` `App` class, so it
+ * still performs the normal MCP Apps initialize handshake and exposes
+ * `getHostCapabilities()`, `getHostContext()`, `callServerTool()`, etc. IDW adds
+ * widget state, host/platform actions, and a semantic agent-context alias. The
+ * state API installs `window.idw.app` and the optional `window.openai`
+ * compatibility shim.
+ */
+export class IdwApp extends McpApp {
+    constructor(appInfo, capabilities, appOptions, stateOptions) {
+        super(appInfo, capabilities, appOptions);
+        this.state = installIdwAppApi(stateOptions);
+        this.onteardown = async () => ({});
+    }
+    /** Request an IDW host/platform action. Mirrors MCP `callServerTool()`. */
+    callIdwAction(params, options) {
+        return this.state.callIdwAction(params, options);
+    }
+    /** Semantic IDW alias for MCP Apps `updateModelContext()`. */
+    updateAgentContext(params, options) {
+        return this.updateModelContext(params, options);
+    }
+    /** Return the OR user identity token for this app session, requesting it lazily once. */
+    getAuthToken(options = {}) {
+        if (!options.forceRefresh && this.authToken) {
+            return Promise.resolve(this.authToken);
+        }
+        if (!options.forceRefresh && this.authTokenRequest) {
+            return this.authTokenRequest;
+        }
+        const hostContext = this.getHostContext();
+        const apiBaseUrl = hostContext?.idw?.auth?.apiBaseUrl;
+        const request = this.callIdwAction({
+            name: options.tokenActionName ?? DEFAULT_AUTH_TOKEN_ACTION,
+        }, {
+            timeout: options.timeout,
+        }).then((tokenResult) => {
+            if (tokenResult.isError) {
+                throw new Error(`IdwApp.getAuthToken: ${extractToolError(tokenResult)}`);
+            }
+            const token = extractAuthToken(tokenResult, apiBaseUrl);
+            this.authToken = token;
+            return token;
+        }).finally(() => {
+            if (this.authTokenRequest === request) {
+                this.authTokenRequest = undefined;
+            }
+        });
+        this.authTokenRequest = request;
+        return request;
+    }
+    /**
+     * Validate that the current user can access this IDW Web app/skill.
+     *
+     * This intentionally keeps the old app-side `idw-skill` behavior: the app
+     * requests a lazy OR token, then calls the IDW API itself. Call after
+     * `connect()`, because it depends on MCP host context.
+     */
+    async validateAccess(params = {}, options = {}) {
+        const hostContext = this.getHostContext();
+        const idw = hostContext?.idw;
+        const apiBaseUrl = idw?.auth?.apiBaseUrl;
+        const idwId = idw?.idwId;
+        if (!apiBaseUrl) {
+            throw new Error('IdwApp.validateAccess: host context is missing idw.auth.apiBaseUrl');
+        }
+        if (!idwId) {
+            throw new Error('IdwApp.validateAccess: host context is missing idw.idwId');
+        }
+        const fetchFn = options.fetch ?? globalThis.fetch;
+        if (typeof fetchFn !== 'function') {
+            throw new Error('IdwApp.validateAccess: fetch is unavailable');
+        }
+        const auth = await this.getAuthToken(options);
+        const endpoint = validateAccessUrl(apiBaseUrl, idwId);
+        const response = await fetchFn(endpoint, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json;charset=UTF-8',
+                ortoken: auth.token,
+            },
+            body: JSON.stringify({
+                url: currentUrl(params.url),
+            }),
+        });
+        if (!response.ok) {
+            throw new Error(`IdwApp.validateAccess: request failed [POST ${endpoint}] - ${response.status} ${response.statusText}`);
+        }
+        return response.json();
+    }
+    /** Remove IDW globals and close the underlying MCP App transport. */
+    async dispose() {
+        this.state.dispose();
+        await this.close();
+    }
+}
+/** Create an IDW app-side MCP App with widget-state support installed. */
+export function createIdwApp(options) {
+    return new IdwApp(options.appInfo, options.capabilities, options.appOptions, options.stateOptions);
+}
+export { PostMessageTransport };
+//# sourceMappingURL=createIdwApp.js.map