@isomorph.ai/app-sdk 1.4.2 → 1.5.0

package/README.md

@@ -0,0 +1,63 @@
+# Isomorph app SDK: M1 server AI and browser reads
+
+Use upstream `ai@7.0.118` and `@ai-sdk/openai@4.0.78` directly in actions. The platform supplies the gateway connection and approved aliases; no model wrapper is needed. Never import the provider setup into frontend code.
+
+```ts
+// actions/summarise.ts
+import { generateText, tool, jsonSchema, stepCountIs } from 'ai';
+import { createOpenAI } from '@ai-sdk/openai';
+import { createClient } from '@isomorph.ai/app-sdk';
+
+export default async function summarise() {
+  const gateway = createOpenAI({
+    baseURL: process.env.OPENAI_BASE_URL,
+    apiKey: process.env.OPENAI_API_KEY,
+  });
+  const isomorph = createClient();
+  const result = await generateText({
+    model: gateway.chat(process.env.ISOMORPH_AI_GENERATION_MODEL_ALIAS!),
+    prompt: 'Summarise the approved channel.',
+    stopWhen: stepCountIs(5),
+    tools: {
+      readChannel: tool({
+        description: 'Read the approved team channel.',
+        inputSchema: jsonSchema<Record<string, never>>({ type: 'object', properties: {}, additionalProperties: false }),
+        execute: () => isomorph.integrations.execute('company-slack', {
+          operation: 'slack.channel.history', resource: 'APP_APPROVED_CHANNEL', input: { limit: 10 },
+        }),
+      }),
+    },
+  });
+  return { text: result.text };
+}
+```
+
+Replace the connection/resource with the app's existing approved integration. Tools inherit the invoking person's signed identity. Expose read operations only; existing SDK write methods are not M1 agent tools.
+
+For images call `generateImage({model: gateway.image(process.env.ISOMORPH_AI_IMAGE_MODEL_ALIAS!), prompt: 'A blue notebook'})`. Editing uses `prompt: {text: 'Make it red', images: [inputBytes]}` only when `isomorph ai models` advertises edit. Reuse app files upload/signed reads for authorized input and output storage; respect existing transfer/action limits and never return credentials.
+
+## Browser read tools
+
+Install optional peers `ai` and `playwright-core@1.58.2`. Locally run `npx playwright-core install chromium --only-shell`; V2 packages Chromium in the existing app image. An existing system executable can be supplied as executablePath.
+
+```ts
+import { createBrowserTools } from '@isomorph.ai/app-sdk/dist/browser.js';
+// Inside an action with its context:
+const browser = await createBrowserTools({
+  pages: ['https://example.com/'],
+  signal: context.signal,
+});
+try {
+  // Add browser.tools to generateText's tools; keep stopWhen: stepCountIs(5).
+} finally {
+  await browser.close();
+}
+```
+
+App code declares exact HTTPS pages and named click/fill selectors reviewed for reads. Tools provide navigate, observe, control, scroll, screenshot and close. Observations are untrusted webpage content. One isolated page per run, one active run per process, 50 actions, five minutes, ten-second operations, bounded text/screenshots. Private destinations, undeclared navigation, downloads, popups, WebSockets, service workers and non-GET/HEAD requests are blocked. GET-only filtering cannot infer website business semantics: never declare URLs/controls that perform external writes. Chromium's sandbox remains enabled; unsupported sandbox environments fail clearly.
+
+## Running and rollout
+
+`isomorph dev` uses canned server-model fixtures. `dev --real` supplies an approved development connection to the action process. Hosted actions resolve their exact ACTIVE version key. The current V2 PLAN is published after LIVE; before key activation, an AI action fails and later actions retry. LIVE alone is not AI acceptance.
+
+Requires compatible SDK/CLI/toolkit publication, gateway protocol fixes, governance connection routes and V2 packaging/version wiring. No deployment is claimed here. Real model/file authorization and hosted Chromium sandbox checks remain release acceptance. Search, company skills, integration/browser writes, video, audio, STT, TTS and realtime audio are deferred.