@onereach/idw-apps 0.1.2-beta.6.0

package/skills/idw-app-development/SKILL.md

@@ -0,0 +1,458 @@
+---
+name: idw-app-development
+description: Use when building IDW-compatible MCP Apps, generic IDW Web apps, or adapting apps to @onereach/idw-apps, including widget state, lazy auth, IDW actions, agent context, RWC boundaries, and OpenAI/standard MCP compatibility.
+---
+
+# IDW App Development
+
+Use this skill when creating an app that will run inside IDW through `@onereach/idw-apps`. This covers MCP Apps and generic IDW Web apps. Keep the app protocol close to MCP Apps; do not invent a custom bridge unless the package already exposes it.
+
+For full API details, read the package `README.md`. This skill captures the implementation decisions and app-building defaults.
+
+## One Skill Or Many
+
+Use this single skill for now. MCP Apps and IDW Web apps share the same app primitives:
+
+- durable widget state
+- optional lazy `orToken`
+- optional host actions
+- optional agent/model context updates
+- app/backend-owned authoritative data
+
+“IDW Web app” means the app is not backed by an MCP server or tool resource. It
+still uses `createIdwApp()` and the MCP Apps handshake as the universal IDW app
+protocol; only its business-data backend differs.
+
+Split into separate skills only if one app type grows a truly different build workflow.
+
+## Choose The App Type
+
+| App type | Use when | Main differences |
+| --- | --- | --- |
+| MCP App | An MCP server exposes an interactive UI resource or URL. | Prefer standard MCP Apps APIs for tools/resources/prompts. Use IDW additions only when the app needs IDW widget state, IDW actions, lazy auth, or agent context. |
+| Standard external MCP App | The user brings an external MCP server/app built directly with `@modelcontextprotocol/ext-apps`. | It must work in IDW without importing `@onereach/idw-apps/app`. Do not require IDW-only messages for basic MCP behavior. |
+| IDW Web app | A hosted IDW user app embedded or opened by IDW, often with its own backend. | Same protocol regardless of where IDW renders it. Request `orToken` lazily when the app needs IDW/API auth. Store only restore hints in widget state. Use `surface` only as a layout/context hint. |
+| RWC app | Existing Rich Web Chat app/skill. | Treat as separate unless the user explicitly asks to migrate it. RWC continues using `pageData`/`orToken` because its backend expects data through its UI. |
+
+## Preferred App Import
+
+For new IDW-aware apps, import from `@onereach/idw-apps/app`:
+
+```ts
+import { createIdwApp } from '@onereach/idw-apps/app';
+```
+
+IDW app authors should not need to install `@modelcontextprotocol/ext-apps` separately. The IDW `App` extends the MCP Apps `App`, so standard MCP methods remain available.
+
+External MCP apps built directly with `@modelcontextprotocol/ext-apps` should still work with the IDW host, but they will not have the `window.idw.app` helpers unless they include this package or an equivalent bootstrap.
+
+Treat current OpenAI Apps SDK apps as standard MCP Apps when they use the MCP
+Apps bridge. Do not assume IDW implements the complete ChatGPT-only
+`window.openai` runtime. IDW currently aliases widget state only; feature-detect
+any optional `window.openai` methods and keep core behavior on MCP Apps.
+
+New IDW apps should not call `installIdwAppApi()` directly. It is reserved for
+custom bootstraps and legacy integrations.
+
+## Choose The API By Direction
+
+| Intent | API |
+| --- | --- |
+| App calls its MCP server | `app.callServerTool()` |
+| IDW host/agent calls a live app tool | app `onlisttools` / `oncalltool`; host `listAppTools()` / `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()` |
+
+Do not invent another action channel for app-provided tools.
+
+## Basic IDW App Skeleton
+
+```ts
+import { createIdwApp } from '@onereach/idw-apps/app';
+
+const app = createIdwApp({
+  appInfo: {
+    name: 'My IDW App',
+    version: '1.0.0',
+  },
+});
+
+app.ontoolinput = ({ arguments: args }) => {
+  // Standard MCP Apps tool input notification from the host/model turn.
+};
+
+app.ontoolresult = (result) => {
+  // The latest tool result (especially structuredContent) is authoritative
+  // business data. Store it and render from it.
+};
+
+app.state.subscribeWidgetState((state) => {
+  // Apply only route, selected ID, active tab, or another restore/view hint.
+});
+
+await app.connect();
+
+const widgetState = app.state.getWidgetState();
+const hostContext = app.getHostContext();
+const hostCapabilities = app.getHostCapabilities();
+```
+
+`capabilities` is optional. Add `capabilities.tools` only when the app itself
+exposes MCP-style tools to the host.
+
+Use `app.dispose()` when the app is being torn down by your framework.
+
+## Widget State
+
+Widget state is durable UI restoration state owned by the host. It is not the app's authoritative data store.
+
+The host stores widget state for the durable app instance, not for a single tool call. On the next app render or reload, it can arrive before or after the MCP tool result, and there may be no saved widget state at all. Connect immediately and render authoritative tool results without waiting for state.
+
+Use these names in new code:
+
+```ts
+app.state.getWidgetState();
+app.state.setWidgetState({ route: '/lessons/lesson-3', selectedLessonId: 'lesson-3' });
+app.state.subscribeWidgetState((state) => {
+  // sync local UI
+});
+```
+
+Use `whenWidgetStateReady()` only after `app.connect()` when a restore hint is specifically needed. It resolves on a host reply or the fallback timeout; it is not a startup prerequisite.
+
+Deprecated aliases may exist for compatibility: `getState`, `setState`, `whenStateReady`, `subscribeState`. Do not use them in new apps.
+
+`setWidgetState(state)` replaces the whole widget-state object. Keep it JSON-serializable, small, and non-sensitive.
+
+Good widget state:
+
+```ts
+{
+  route: '/lessons/lesson-3/remediation',
+  selectedLessonId: 'lesson-3',
+  activeTab: 'quiz',
+  draftId: 'draft-abc',
+  currentStep: 2
+}
+```
+
+Bad widget state:
+
+```ts
+{
+  orToken: '...',
+  fullApiResponse: {},
+  entireUserProfile: {},
+  largeDataset: [],
+  lastToolResult: {}
+}
+```
+
+For apps with their own backend, widget state should contain restore hints such as IDs/routes/tabs. On reload, use those hints to fetch authoritative data from the app backend.
+
+For small apps without a backend, such as a simple game, it is acceptable to store full lightweight local state if it is small, non-sensitive, and JSON-serializable.
+
+Do not block UI on persistence. The host updates local state immediately and persists asynchronously.
+
+Avoid writing every tiny transient interaction. Persist restore-critical changes such as route, selected IDs, active tab, draft ID, current workflow step, or compact local state for small backend-less apps.
+
+## Rendering And State Ownership
+
+Keep these layers separate:
+
+- **Tool result** — authoritative business state. A tool that renders or updates the app should return the complete current business snapshot in `structuredContent`; every new result replaces the previous snapshot.
+- **Widget state** — lightweight UI/restore hint. Reapply it on top of the latest business snapshot only when it is still valid.
+- **Local component state** — ephemeral rendering details.
+
+Tool-result and widget-state messages have no guaranteed relative order. A new app must work when the first render has only tool input/result and no widget state. On a reload, it may render a persisted tool result first and receive `{ sessionId, route }` later.
+
+If a restore hint causes a backend fetch, keep that request from overwriting a newer tool-result snapshot. Use your framework's normal cancellation or request-generation pattern when both can race.
+
+## Backend Data
+
+Use this split:
+
+- IDW widget state: lightweight restore checkpoint.
+- App backend/session: authoritative business or game data.
+- Agent context: selected model-visible activity/context only.
+- IDW auth token: requested lazily as a user identity token and never persisted in widget state.
+
+When restoring:
+
+1. Register tool-result and widget-state handlers.
+2. Call `app.connect()` immediately.
+3. Render every authoritative tool result as it arrives.
+4. Apply widget state as a route/selection/session hint whenever it arrives.
+5. If the hint needs backend hydration, request auth only if needed and fetch without replacing a newer tool result.
+
+## Lazy Auth
+
+The only current token type is `orToken`. It is a user identity token issued for
+one web app session. It lets the embedded app call IDW/platform APIs as the
+current user, subject to the platform's normal authorization. Request it only
+when needed:
+
+```ts
+const auth = await app.getAuthToken();
+
+// Use auth.token for app/API calls that require IDW identity.
+```
+
+The host must opt in with `auth.allowTokenRequest: true`. If it uses
+`allowedActions`, it must also include `getAuthToken` (or its configured token
+action name). Otherwise `getAuthToken` returns a normal MCP-style error result.
+
+The host may provide a static `auth.orToken` or an async
+`auth.getOrToken(runtimeContext)` provider. The provider is called lazily for
+each actual host token-action request and receives the current runtime context;
+it is never exposed through MCP host context. App-side `getAuthToken()` still
+caches normal requests, while `forceRefresh: true` sends another host request.
+
+`app.getAuthToken()` caches the in-memory token for the current app instance, so
+calling `app.validateAccess()` and then making app API requests, or doing those
+in the opposite order, does not require duplicate host token requests. Use
+`forceRefresh: true` only when the product explicitly needs a new session token.
+
+The package does not verify `orToken` and should treat it as opaque. Verification belongs to IDW/platform APIs or the app backend using the platform's normal server-side authorization flow.
+
+Do not put tokens into widget state, model/agent context, logs, URLs, or localStorage unless the product explicitly requires and reviews it.
+
+## Web App Access Validation
+
+For Web Apps/skills replacing `idw-skill`, validate access from the app after
+the MCP Apps handshake:
+
+```ts
+await app.connect();
+
+const { skill, user } = await app.validateAccess({
+  url: window.location.href,
+});
+```
+
+`validateAccess()` keeps the old app-side request model: it reads
+`hostContext.idw.idwId` and `hostContext.idw.auth.apiBaseUrl`, requests a lazy
+`orToken` through the cached `app.getAuthToken()` helper, then calls:
+
+```text
+POST {apiBaseUrl}/idw/{idwId}/skills/access
+```
+
+The host must provide `idwId`, `auth.apiBaseUrl`, `auth.allowTokenRequest: true`,
+and, when `allowedActions` is set, the configured token action name. Do not use
+host-mediated `callIdwAction()` access checks when the product requires the app
+to perform this request itself.
+
+## MCP Server Tools And Resources
+
+Use standard MCP Apps methods for MCP server capabilities:
+
+- `callServerTool()` for MCP server tools.
+- resource/prompt list and read APIs for MCP resources/prompts.
+- `updateModelContext()` for standard MCP model context updates.
+
+Use IDW methods only for IDW-specific behavior:
+
+- `callIdwAction()` for host/platform actions.
+- `updateAgentContext()` as a semantic IDW alias for `updateModelContext()`.
+- widget-state helpers for durable UI restoration.
+
+If an MCP app needs external scripts, styles, or assets, define UI CSP metadata on the app resource, not on the tool. Include the needed asset origins in the resource UI CSP. Do not assume arbitrary external asset origins will be allowed.
+
+For local development, localhost app/resource URLs can be valid if the host environment is configured to allow them.
+
+## App-Provided Agent Tools
+
+An app can expose standard MCP tools for IDW to make available to the agent.
+Use this for either UI actions (`openRequest`, `selectTab`) or app/API actions
+(`listTasks`, `createTask`); the app owns the tool implementation.
+
+This is the reverse of `callServerTool()`:
+
+- `callServerTool()` is app → MCP server.
+- `onlisttools` / `oncalltool` is IDW host/agent → app.
+
+Declare tool capability and register handlers before connecting:
+
+```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 },
+  };
+};
+
+await app.connect();
+```
+
+Tool descriptions, input schemas, output, and annotations are part of the
+agent-facing contract. Keep them concise and accurate. Mark read-only tools
+with `readOnlyHint`; provide honest destructive/idempotency annotations for
+side effects. The IDW host decides whether a declared tool is agent-visible or
+requires confirmation.
+
+App-provided tools run in the live iframe. For a backend capability that must
+work when the app is not mounted, expose it as a durable MCP or backend tool
+instead. Do not put raw backend URLs, credentials, or authorization policy in
+the tool manifest; use the app's normal backend/auth flow inside the handler.
+
+## IDW Host Actions
+
+Use `callIdwAction()` for host-defined platform actions:
+
+```ts
+const result = await app.callIdwAction({
+  name: 'openSkill',
+  arguments: {
+    slug: 'generate-image',
+  },
+});
+
+if (result.isError) {
+  // Show a local app error state if useful.
+}
+```
+
+Action names are host-defined strings. Do not assume built-in actions other than `getAuthToken`.
+
+The host may pass `allowedActions`. If an action is not allowed, including
+`getAuthToken`, the app receives `CallToolResult.isError = true`.
+
+For MCP server tools, do not use `callIdwAction`; use `callServerTool`.
+
+## Agent Context
+
+Use `updateAgentContext()` when the app knows something useful for the IDW agent's future reasoning:
+
+```ts
+await app.updateAgentContext({
+  content: [{
+    type: 'text',
+    text: 'User selected lesson 3 and opened quiz remediation.',
+  }],
+  structuredContent: {
+    selectedLessonId: 'lesson-3',
+    currentView: 'quiz-remediation',
+  },
+});
+```
+
+Rules:
+
+- It accepts the same payload shape as MCP Apps `updateModelContext()`.
+- Keep it concise and relevant to the agent.
+- Do not use it for monitoring telemetry or debug logs.
+- Do not include secrets, auth tokens, private backend payloads, or large data.
+- Use `sendLog()` / logging APIs for debug or diagnostic events.
+
+## Host Context
+
+The host may include a compact IDW block in MCP host context:
+
+```ts
+const hostContext = app.getHostContext();
+const idw = hostContext.idw as {
+  idwId?: string;
+  surface?: string;
+  appInstanceId?: string;
+  auth?: {
+    apiBaseUrl?: string;
+    orToken?: string;
+  };
+  allowedActions?: string[];
+} | undefined;
+```
+
+By default, `auth.orToken` is omitted. Prefer lazy `getAuthToken`.
+
+Use `surface` to adjust layout, not to fork the app protocol.
+
+## OpenAI Compatibility
+
+`@onereach/idw-apps/app` provides a minimal OpenAI widget-state compatibility shim:
+
+```ts
+window.openai?.widgetState;
+window.openai?.setWidgetState?.({ route: '/details' });
+```
+
+This mirrors/delegates to IDW widget state. It is not a full OpenAI Apps SDK implementation.
+
+Apps built for OpenAI Apps SDK may need adaptation unless they only depend on compatible widget-state behavior and standard MCP Apps behavior. Prefer the explicit IDW APIs for new IDW apps.
+
+## IDW Web Apps (Not MCP-Server-Backed)
+
+For IDW Web apps:
+
+- Use the same `createIdwApp()` skeleton above; Web Apps do not use a separate app class.
+- They still use the standard MCP Apps transport/handshake as the universal IDW
+  app protocol; “non-MCP” refers only to the absence of an MCP server backend.
+- Omit `capabilities` unless the Web App exposes app-side MCP tools.
+- Use the same widget-state and lazy-auth rules.
+- Use `app.validateAccess()` after `app.connect()` when replacing old
+  `idw-skill` Web Skill access checks.
+- Treat `surface` as a layout hint.
+- Resolve business/session data from the app backend.
+- Request `app.getAuthToken()` only when the app needs IDW/API identity.
+- Use `callIdwAction` for host actions, not for app-backend business operations.
+- Use `updateAgentContext` only for concise model-visible app activity.
+
+If the app is cross-origin and does not bundle `@onereach/idw-apps/app` or receive an equivalent bootstrap, the host cannot reliably add `window.idw.app` after the page has loaded.
+
+## Security And Privacy
+
+- Feature-detect optional APIs before using them when building portable apps.
+- Never persist or expose tokens in widget state or agent context.
+- Do not leak `chatId`, backend URLs, token values, or private API payloads into model-visible context unless explicitly required.
+- Avoid storing PII in widget state; store IDs and reload data from the backend.
+- Validate and sanitize user-controlled values before rendering.
+- Treat host action failures as normal app errors, not crashes.
+- Keep app state JSON-serializable so it can cross `postMessage` and persist cleanly.
+
+## Build Checklist
+
+Before finishing an app:
+
+- The app uses `createIdwApp()` and connects immediately after registering handlers.
+- The app renders from tool results even when no widget state exists.
+- Widget state is applied only as a view/restore overlay and never replaces business data.
+- Stateful reload works from `getWidgetState()` or `subscribeWidgetState()` without blocking the initial MCP render.
+- `setWidgetState()` is called only for lightweight restore-critical state.
+- Backend-backed data reloads from the app/backend using IDs from widget state.
+- Auth is requested lazily with `getAuthToken` only when needed.
+- MCP server operations use `callServerTool`, not `callIdwAction`.
+- Agent-callable app tools use `capabilities.tools`, `onlisttools`, and `oncalltool`.
+- IDW host/platform operations use `callIdwAction`.
+- Agent context is concise, non-secret, and useful to the model.
+- The app behaves reasonably on its target surface.
+- Standard external MCP compatibility is not broken by IDW-specific assumptions.