@assembly-js/app-foundation 0.6.1 → 0.6.2

package/CHANGELOG.md

@@ -19,6 +19,9 @@ 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.2
+- [guidance] The build agent now returns a failed AI call as `{ ok: false, message }` with the proxy's error instead of throwing, and saves a chat's question and answer together only once the answer has arrived.
+
 ## 0.6.1
 - [fix] The client-call scan no longer reports a `fetch` to the AI proxy (`POST /v1/ai/openai/...`) as breaking: the platform now admits a client bearer on that route. Nothing in the app changes.
 

package/CLAUDE.md

@@ -1490,6 +1490,7 @@ Use `AssemblyBridge.header.*` for breadcrumbs, CTAs, and actions menu. See `.cla
 - ❌ Don't include `companyId` (or any other unchanged field) in `updateClient.requestBody` "for completeness". Each field in `requestBody` is treated as a write — passing `companyId` triggers a company-reassignment path that clients can't perform, and the whole update fails. Pass ONLY the fields the user is actually changing.
 - ❌ Don't hardcode mutation error messages like "Failed to save preference". Read `error` from the response body and surface it to the user.
 - ❌ Don't `throw new Error` with a sentence the user should read from a server action. Production redacts that throw, so the toast shows a generic React error and the response is HTTP 500. Return `{ ok: false, message }` and toast `message`. Let `TokenInvalidError` and unexpected failures throw. See `assembly-action-results`.
+- ❌ Don't let a failed AI call throw out of a server action, and don't create a conversation or message row before the answer exists. Check `response.ok`, return `{ ok: false, message }` with the proxy's error so the UI can show it with a retry, and write the question and the answer together in one `db.batch` once the answer has arrived. See "Conversations" in `assembly-ai`.
 - ❌ Don't `Promise.all` a list-sized write fan-out (one `createNotification` / `markNotificationRead` / update per recipient or record). Writes cap at 5 concurrent per token; firing a whole list 429s and silently drops the overflow. Use `sendThrottled` from `@assembly-js/app-foundation/server`. A fixed handful of calls is the only exception. See "Write rate limit" above.
 - ❌ Don't re-notify a still-true condition from a cron. Mark a recipient sent only after `createNotification` succeeds, and clear that record when the condition ends unless the alert is once per billing period; keep those successful outcomes until the period resets, even if usage dips below the threshold. See "Recurring conditions" in `assembly-notifications`.
 - ❌ Don't use title case — see "Labels, copy, and dropdowns" above.

package/package.json

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

package/skills/assembly-ai/SKILL.md

@@ -28,9 +28,17 @@ export async function chatCompletion(messages: Array<{ role: string; content: st
       stream: options?.stream || false,
     }),
   });
-  if (!response.ok) throw new Error(`AI request failed: ${response.status}`);
   return response;
 }
+
+// The proxy refuses with { error: string }; an OpenAI error passes through as { error: { message } }.
+export async function aiErrorMessage(response: Response): Promise<string> {
+  const body = await response.json().catch(() => null);
+  const error = body?.error;
+  if (typeof error === 'string') return error;
+  if (typeof error?.message === 'string') return error.message;
+  return `AI request failed (${response.status})`;
+}
 ```
 
 `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.
@@ -44,18 +52,34 @@ Expose an AI call to the client as a server action — its arguments are type-ch
 ```typescript
 // app/actions/summarize.ts
 'use server';
-import { chatCompletion } from '@/lib/ai';
+import { aiErrorMessage, chatCompletion } from '@/lib/ai';
+
+export type SummarizeResult = { ok: true; text: string } | { ok: false; message: string };
 
-export async function summarize(text: string): Promise<string> {
+export async function summarize(text: string): Promise<SummarizeResult> {
   const response = await chatCompletion([
     { role: 'user', content: `Summarize the following:\n\n${text}` },
   ]);
+  if (!response.ok) return { ok: false, message: await aiErrorMessage(response) };
   const data = await response.json();
-  return data.choices[0].message.content;
+  return { ok: true, text: data.choices[0].message.content };
 }
 ```
 
-From a client component: `const summary = await callAction(() => summarize(text), { idempotent: true });` — the call writes nothing, so it is safe to re-run after a bearer renewal.
+A failed AI call is an expected outcome, not a crash: the workspace runs out of quota (429 "AI quota exceeded for this workspace"), the proxy refuses the path (403), or OpenAI is down or slow (502/504). Check `response.ok` after every AI call and return the proxy's message as `{ ok: false, message }` (see `assembly-action-results`). Never throw it: production redacts a thrown server-action error, so the user sees a generic error and the response is HTTP 500.
+
+From a client component:
+
+```tsx
+const result = await callAction(() => summarize(text), { idempotent: true });
+if (!result.ok) {
+  setError(result.message); // show it next to a Retry button
+  return;
+}
+setSummary(result.text);
+```
+
+The call writes nothing, so `idempotent: true` is safe to re-run after a bearer renewal.
 
 ## Vision (image inputs)
 
@@ -78,8 +102,7 @@ export async function analyzeImage(base64DataUrl: string, prompt: string) {
       stream: false,
     }),
   });
-  if (!response.ok) throw new Error(`AI request failed: ${response.status}`);
-  return response;
+  return response; // the caller checks response.ok, as in summarize above
 }
 ```
 
@@ -113,8 +136,7 @@ export async function transcribeAudio(file: File) {
     method: 'POST',
     body,
   });
-  if (!response.ok) throw new Error(`AI request failed: ${response.status}`);
-  return response;
+  return response; // the caller checks response.ok, as in summarize above
 }
 ```
 
@@ -134,19 +156,56 @@ For chat or long-form generation, pass `stream: true` and forward the SSE stream
 export async function POST(request: NextRequest) {
   const { messages } = await request.json();
   const response = await chatCompletion(messages, { stream: true });
+  if (!response.ok) {
+    return NextResponse.json({ error: await aiErrorMessage(response) }, { status: response.status });
+  }
   return new Response(response.body, {
     headers: { 'Content-Type': 'text/event-stream', 'Cache-Control': 'no-cache' },
   });
 }
 ```
 
-The proxy forwards OpenAI's SSE stream directly. Parse `data:` lines on the client as usual.
+The proxy forwards OpenAI's SSE stream directly. Parse `data:` lines on the client as usual. A refusal arrives before the stream starts, so check `res.ok` on the client and show `error` from the JSON body.
 
 `assembly.fetch()` returns a standard `Response`, so `response.body` is a `ReadableStream` you can pipe directly.
 
 ## Quota
 
-Usage is metered against the workspace's monthly AI quota. Do not implement your own rate limiting — Assembly handles this automatically. If the quota is exceeded, the proxy returns HTTP 429.
+Usage is metered against the workspace's monthly AI quota. Do not implement your own rate limiting — Assembly handles this automatically. If the quota is exceeded, the proxy returns HTTP 429 with `{ error: "AI quota exceeded for this workspace" }`. Show that message; don't replace it with "Something went wrong".
+
+## Conversations: persist the question and answer together
+
+A chat feature (an assistant, a Q&A thread) must never leave a conversation with a question and no answer, or a titled conversation with no messages. Call the model first. Write the user turn and the assistant turn in one atomic write, and only after the answer has arrived. If the AI call fails, write nothing and return `{ ok: false, message }`. The UI then shows the message with a Retry button that sends the same question again.
+
+```typescript
+// app/actions/chat.ts
+'use server';
+
+export type SendQuestionResult =
+  | { ok: true; conversationId: string; answer: string }
+  | { ok: false; message: string };
+
+export async function sendQuestion(conversationId: string | null, question: string): Promise<SendQuestionResult> {
+  const history = conversationId ? await loadMessages(conversationId) : [];
+  const response = await chatCompletion([...history, { role: 'user', content: question }]);
+  if (!response.ok) return { ok: false, message: await aiErrorMessage(response) };
+  const answer = (await response.json()).choices[0].message.content;
+
+  const id = conversationId ?? crypto.randomUUID();
+  await db.batch([
+    ...(conversationId ? [] : [db.insert(conversations).values({ id, title: question.slice(0, 80) })]),
+    db.insert(messages).values([
+      { conversationId: id, role: 'user', content: question },
+      { conversationId: id, role: 'assistant', content: answer },
+    ]),
+  ]);
+  return { ok: true, conversationId: id, answer };
+}
+```
+
+`db.batch` commits the conversation row and both messages together or not at all (see `assembly-db-transactions`). Keep the question in client state until the action returns, so the chat shows it while the answer loads and Retry can resend it. This action writes, so call it without `{ idempotent: true }`.
+
+When streaming, write the rows when the stream completes, not when it starts: collect the streamed text, then save the conversation and both turns in one `db.batch` from the stream's final step. A stream that errors or is cancelled saves nothing.
 
 ## What NOT to do