@assembly-js/app-foundation 0.6.4 → 0.6.6

package/CHANGELOG.md

@@ -19,6 +19,13 @@ A patch release never changes what an app's build requires; a minor release may
 not by hand; see `changes/README.md`. CI fails a PR that changes a check script without a
 `bump: minor` change file.
 
+## 0.6.6
+- [guidance] The build agent ends a chat turn by describing what changed instead of reporting its type-check, build, or the screens it didn't open, and knows the platform builds the app after every turn. It still claims "fixed" or "working" only for what it exercised, and talks about verification when asked or when fixing a reported bug.
+
+## 0.6.5
+- [guidance] The `assembly-storage` skill says the `assembly` option of `detectPdfFields` is only an opt-in flag. The `assembly-ai` skill and the `assembly.fetch()` prose now call the AI proxy on the installer client (`getInstallerAssembly()`, gated by `await getAssembly()` first) instead of the viewer's client.
+- [behavior] `detectPdfFields` now runs its AI step on the installer client, and degrades to a warning when there is no verified viewer. `options.assembly` is deprecated and ignored; passing it still opts in to the AI step.
+
 ## 0.6.4
 - [behavior] An app's sandbox now sends its sandbox grant when minting an app bearer, so the platform can tell its calls from the deployed app's.
 

package/CLAUDE.md

@@ -684,17 +684,17 @@ export PATH="$HOME/.bun/bin:$PATH" && bun add <extra-package>
 
 ### Inner verification loop — type-check, don't full-build
 
-Use `bunx tsc --noEmit` to verify your changes while iterating. It runs in 2–3s and gives you the full, untruncated type errors. Reserve `bun run build` (~15–20s for a full Next build) for the **final** check at the end of the task, not after every edit. Running `bun run build` between trivial edits adds ~15s of dead time per cycle.
+Use `bunx tsc --noEmit` to check changes while iterating (2–3s, full type errors). After every chat turn that changes app code, the platform runs the type-check and a full build and sends failures back for you to fix, so skip `bun run build` unless the task asks for a build or you changed `lib/schema.ts` and need the new tables now.
 
 ```bash
 # Inner loop — after edits, every few changes:
 export PATH="$HOME/.bun/bin:$PATH" && bunx tsc --noEmit
 
-# Final check — once, at the end of the task:
+# Full build — only when the task asks for one:
 export PATH="$HOME/.bun/bin:$PATH" && bun run build
 ```
 
-If `tsc --noEmit` is clean and the task says "verify the build", run `bun run build` once and move on — don't loop on it.
+When the task says "verify the build", run `bun run build` once.
 
 `bun run build` also validates `.assembly/app.json` (it runs the manifest validator first) and **fails** if the manifest is malformed or a key is misplaced — most commonly a surface like `notification` written at the top level instead of under `surfaces`. If the build stops with a `.assembly/app.json is invalid` error, fix the manifest as the message instructs — every surface belongs under the `surfaces` key. Run `bun run validate:manifest` to check it on its own.
 
@@ -713,9 +713,9 @@ If `tsc --noEmit` is clean and the task says "verify the build", run `bun run bu
 
 `tsc --noEmit` and `bun run build` prove the code compiles and the static checks pass. Neither renders a page, so both stay green while a page 500s for every visitor — a function passed into a client component, a browser-only import in server code, a field the sample record happened to have. A query against the sandbox database or an SDK call shows the data is there, not that the page reading it renders.
 
-You cannot open the app as a signed-in client or team member, and you cannot see the published app or its logs. The builder preview is the user's own signed-in session, so the one runtime signal you have is the dev-server log (`assembly-dev-server-logs`): after changing a page or route, read it for new errors before calling the change done, and when nothing has requested the changed screen yet, ask the user to open it in the preview.
+You cannot open the app as a signed-in client or team member, and you cannot see the published app or its logs. The builder preview is the user's own signed-in session, so the one runtime signal you have is the dev-server log (`assembly-dev-server-logs`): after changing a page or route, read it and fix any new errors before calling the change done. Mention it only if something is wrong.
 
-Close every turn, and answer every "does it work" or "is it safe to publish", by naming the checks that ran in those terms and the screens you could not open — which page, as which kind of user — so the user opens them. Say this unprompted, every time, not only when the prompt asks for a manual check. Say "fixed", "working", or "good to publish" only for behaviour you exercised; otherwise say what you checked and what is still unseen.
+Close a turn by describing what changed, in product terms — no tool or command names, no list of what you did not open or run. A limitation the user will hit is worth one line ("test cases still reset on reload; I can move them into the database"). Speak about verification only when the user asks whether something works or is safe to publish, or the turn fixes a bug they reported; then say in product terms what you exercised, or whether you reproduced the bug and saw it gone. Say "fixed", "working", or "good to publish" only for behaviour you exercised.
 
 When the user reports that the published app errors, do not blame a cold start, caching, or a stale tab without evidence. Ask for the page, who was signed in, and the exact error text or code; reproduce it in the sandbox — the same screen in the preview or the same request against the dev server — and read the dev-server log. If you cannot reproduce it, say so and ask for those details rather than asking the user to reload.
 
@@ -1260,9 +1260,11 @@ Convention-breakers to know up front:
 
 ### `assembly.fetch()` — for non-SDK endpoints
 
-The SDK exposes a generic `fetch(path, init?)` method for calling Assembly API endpoints that aren't in the generated SDK methods (e.g. the AI proxy). It prepends the base URL and injects auth headers (`Authorization: Bearer` from the `getAssembly()` client, plus `X-Assembly-SDK-Version`) automatically — never `X-API-Key` on data calls — returning a standard `Response`:
+The SDK exposes a generic `fetch(path, init?)` method for calling Assembly API endpoints that aren't in the generated SDK methods (e.g. the AI proxy). It prepends the base URL and injects auth headers (`Authorization: Bearer` from the client you call it on, plus `X-Assembly-SDK-Version`) automatically — never `X-API-Key` on data calls — returning a standard `Response`. The AI proxy is app-owned, so call it on the installer client (`getInstallerAssembly()`, server-side only), gated by `await getAssembly()` first because that throws without a verified viewer:
 
 ```ts
+await getAssembly(); // the gate: throws without a verified viewer
+const assembly = await getInstallerAssembly();
 const response = await assembly.fetch('/v1/ai/openai/chat/completions', {
   method: 'POST',
   body: JSON.stringify({ model: 'gpt-4o-mini', messages }),
@@ -1508,7 +1510,7 @@ Use `AssemblyBridge.header.*` for breadcrumbs, CTAs, and actions menu. See `.cla
 - ❌ Don't import a native or browser-only library into server code without the serverless setup — `bun run build` passes but the deployed route crashes at request time. Decide the layer first per "Server runs in serverless Node" above.
 - ❌ Don't preview a PDF (or any file) in an `<iframe>`, `<embed>` or `<object>` — the portal frame is sandboxed and Chrome won't run its PDF viewer inside it, so the preview renders blank while the build passes. Open the pre-signed URL in a new tab (`assembly-storage` Pattern A) or render pages to a canvas client-side with `next/dynamic` + `ssr: false`.
 - ❌ Don't build a PDF-to-form feature on AcroForm fields alone. Call `detectPdfFields` and branch on `method`: `none` and `xfa` need a visible explanation plus a manual add-field path, and `text` fields are suggestions the user must be able to edit before saving. Plenty of real forms are Word exports, scans or XFA, so an AcroForm-only app tells those users their form is empty.
-- ❌ Don't call a change verified, working, or safe to publish because `tsc --noEmit` and `bun run build` passed — name the checks that ran and the signed-in screens left unopened. See "What a passing build proves" above.
+- ❌ Don't call a change verified, working, or safe to publish because `tsc --noEmit` and `bun run build` passed, and don't close a turn with a report of your checks. See "What a passing build proves" above.
 - ❌ Don't pass a function — or an object that holds one, like a question/field config with `visibleWhen`, `validate`, `render`, or `format` callbacks — as a prop from a server component or page into a `'use client'` component. Props cross that boundary as serialized data, so the render throws `Functions cannot be passed directly to Client Components` and the page 500s for every visitor no matter what the record holds. `tsc --noEmit` and `bun run build` both pass. Keep such a config in a shared module the client component imports itself, or express the logic as data (`{ showWhen: { field: 'entityType', equals: 'llc' } }`) and interpret it client-side.
 - ❌ Don't call a function imported from a `'use client'` file from a server component, layout, or server action — e.g. an answer formatter defined in the client component file that the `/n` notification page also renders. The server gets a client reference, not the function, so the render throws and the route 500s for every visitor; `tsc --noEmit` passes. A `'use client'` file should export only components and hooks; put a shared helper in a plain module (`lib/…`) both sides import. `bun run build` fails on this (`check:client-boundary`).
 - ❌ Don't use `Select` or `Combobox` to pick any Assembly person or organization record (clients, internal users, team members, staff, companies). Always use `UserCompanySelector` — in forms, filters, dropdowns, "assign to" controls, everywhere.

package/dist/pdf.d.ts

@@ -44,8 +44,12 @@ export declare class PdfUnreadableError extends Error {
  * Finds the fields a person has to fill in on a PDF form: its AcroForm fields when
  * it has them, otherwise fields read from its text by Assembly AI when `assembly`
  * is given. Throws PdfUnreadableError when the bytes are not a readable PDF.
- * Server side only: the AI step runs through the app's Assembly client.
+ * Server side only: the AI step runs through the installer client.
  */
 export declare function detectPdfFields(data: ArrayBuffer | Uint8Array, options?: {
+    /**
+     * @deprecated The client is ignored: the AI step uses the installer client, since the AI proxy
+     * is app-owned. Kept so existing apps that pass it keep working; its presence still opts in.
+     */
     assembly?: AssemblyAPI;
 }): Promise<PdfFieldDetection>;

package/dist/pdf.js

@@ -1,3 +1,4 @@
+import { getInstallerAssemblyForCaller } from './installer-caller.js';
 // pdf.js rejects a Node Buffer outright, so hand it a plain Uint8Array view.
 function toBytes(data) {
     return data instanceof ArrayBuffer
@@ -98,7 +99,7 @@ const AI_RESPONSE_FORMAT = {
  * Finds the fields a person has to fill in on a PDF form: its AcroForm fields when
  * it has them, otherwise fields read from its text by Assembly AI when `assembly`
  * is given. Throws PdfUnreadableError when the bytes are not a readable PDF.
- * Server side only: the AI step runs through the app's Assembly client.
+ * Server side only: the AI step runs through the installer client.
  */
 export async function detectPdfFields(data, options) {
     const bytes = toBytes(data);
@@ -137,7 +138,7 @@ export async function detectPdfFields(data, options) {
         return { method: 'none', fields: [], pages, text, warnings };
     if (!options?.assembly)
         return { method: 'text', fields: [], pages, text, warnings };
-    const suggested = await suggestFieldsFromText(options.assembly, pageTexts);
+    const suggested = await suggestFieldsFromText(pageTexts);
     return {
         method: 'text',
         fields: suggested.fields,
@@ -247,7 +248,7 @@ async function extractPageTexts(bytes) {
         await pdf.loadingTask.destroy();
     }
 }
-async function suggestFieldsFromText(assembly, pageTexts) {
+async function suggestFieldsFromText(pageTexts) {
     const warnings = [];
     const prompt = pageTexts
         .map((pageText, index) => {
@@ -261,6 +262,9 @@ async function suggestFieldsFromText(assembly, pageTexts) {
         .join('\n\n');
     let suggested;
     try {
+        // Inside the try so a missing verified viewer degrades to a warning like any other AI failure.
+        // Same viewer gate as storage and connectors: an app with token exchange off has no verified viewer here, and that is accepted.
+        const assembly = await getInstallerAssemblyForCaller();
         const response = await assembly.fetch(AI_CHAT_COMPLETIONS_PATH, {
             method: 'POST',
             headers: { 'Content-Type': 'application/json' },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@assembly-js/app-foundation",
-  "version": "0.6.4",
+  "version": "0.6.6",
   "description": "Versioned foundation helpers and build context for Assembly generated apps",
   "type": "module",
   "files": [

package/skills/assembly-ai/SKILL.md

@@ -13,13 +13,15 @@ The proxy mirrors OpenAI's API shape. Call any OpenAI endpoint path via:
 
 ## Setup
 
-Create a helper in `lib/ai.ts` that uses the existing Assembly SDK instance:
+Create a helper in `lib/ai.ts` that calls the proxy on the installer client:
 
 ```typescript
-import { getAssembly } from '@assembly-js/app-foundation/server';
+import { getAssembly, getInstallerAssembly } from '@assembly-js/app-foundation/server';
 
 export async function chatCompletion(messages: Array<{ role: string; content: string }>, options?: { model?: string; stream?: boolean }) {
-  const assembly = await getAssembly();
+  // The AI proxy is app-owned, so it uses the installer client; getAssembly() is the gate, it throws without a verified viewer.
+  await getAssembly();
+  const assembly = await getInstallerAssembly();
   const response = await assembly.fetch('/v1/ai/openai/chat/completions', {
     method: 'POST',
     body: JSON.stringify({
@@ -41,7 +43,9 @@ export async function aiErrorMessage(response: Response): Promise<string> {
 }
 ```
 
-`assembly.fetch()` automatically prepends the base URL and injects auth headers (`Authorization: Bearer` from `getAssembly()`, plus `X-Assembly-SDK-Version`). It never sends `X-API-Key` on data calls. You only provide the path and request body.
+`assembly.fetch()` automatically prepends the base URL and injects auth headers (`Authorization: Bearer` from the installer client, plus `X-Assembly-SDK-Version`). It never sends `X-API-Key` on data calls. You only provide the path and request body.
+
+The AI proxy belongs to the app, not to the person using it, so these calls use the installer client from `getInstallerAssembly()` rather than the viewer's `getAssembly()` client. It is server-side only. Call `await getAssembly()` first: it throws when there is no verified viewer, which keeps the installer's authority from being used by an anonymous caller. Let that throw propagate out of the server action so the bearer renewal can retry it; return `{ ok: false, message }` only for the proxy's own refusals.
 
 ## Server-side only
 
@@ -87,7 +91,9 @@ The proxy supports OpenAI's vision API. Use `gpt-4o` with the multi-part content
 
 ```typescript
 export async function analyzeImage(base64DataUrl: string, prompt: string) {
-  const assembly = await getAssembly();
+  // The AI proxy is app-owned, so it uses the installer client; getAssembly() is the gate, it throws without a verified viewer.
+  await getAssembly();
+  const assembly = await getInstallerAssembly();
   const response = await assembly.fetch('/v1/ai/openai/chat/completions', {
     method: 'POST',
     body: JSON.stringify({
@@ -128,7 +134,9 @@ Transcribe on the server. Post the file as `multipart/form-data` to `/v1/ai/open
 
 ```typescript
 export async function transcribeAudio(file: File) {
-  const assembly = await getAssembly();
+  // The AI proxy is app-owned, so it uses the installer client; getAssembly() is the gate, it throws without a verified viewer.
+  await getAssembly();
+  const assembly = await getInstallerAssembly();
   const body = new FormData();
   body.append('file', file);
   body.append('model', 'gpt-4o-mini-transcribe');

package/skills/assembly-storage/SKILL.md

@@ -168,8 +168,9 @@ free — no second upload.
 ### Detecting form fields in an uploaded PDF
 
 A PDF-to-form feature calls the helper in the processing route and lets `method` decide the UI. Passing
-`assembly` (from `getAssemblyForRequest(request)`) lets a text-only PDF get AI-suggested fields; without
-it, `text` comes back with no fields. A file that is not a PDF throws `PdfUnreadableError`, whose message
+`assembly` (from `getAssemblyForRequest(request)`) opts a text-only PDF in to AI-suggested fields; without
+it, `text` comes back with no fields. The AI step runs on the installer client, so the client you pass is
+only the opt-in flag and is otherwise ignored (the option is deprecated). A file that is not a PDF throws `PdfUnreadableError`, whose message
 is safe to show.
 
 ```typescript