@pikku/assistant-ui 0.12.1 → 0.12.3

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # @pikku/assistant-ui
 
+## 0.12.3
+
+### Patch Changes
+
+- f85c234: Add unified credential system with per-user OAuth and AI agent pre-flight checks
+
+  - Unified CredentialService with lazy loading per user via pikkuUserId
+  - wire.getCredential() for typed single credential lookup
+  - MissingCredentialError with structured payload for client-side connect flows
+  - Console UI: Global/Users credential tabs, per-user OAuth connect/revoke
+  - AI agent pre-flight check: detects missing OAuth credentials from addon metadata, shows "Connect your accounts" prompt before chat
+  - CLI codegen: generates credentialsMeta per addon package for runtime lookup
+  - Vercel AI runner: catches MissingCredentialError as runtime fallback
+
+## 0.12.2
+
+### Patch Changes
+
+- cc4a8e0: Show friendly error messages in agent chat instead of silently failing with a loading spinner
+
 ## 0.12.1
 
 ### Patch Changes

package/dist/cjs/index.d.ts

@@ -1,4 +1,4 @@
 export { usePikkuAgentRuntime, usePikkuAgentNonStreamingRuntime, PikkuApprovalContext, usePikkuApproval, convertDbMessages, isDeniedResult, resolvePikkuToolStatus, } from './use-pikku-agent-runtime.js';
-export type { PikkuAgentRuntimeOptions, PendingApproval, PikkuApprovalContextValue, PikkuToolStatusType, PikkuToolStatus, } from './use-pikku-agent-runtime.js';
+export type { PikkuAgentRuntimeOptions, PendingApproval, PikkuApprovalContextValue, PikkuToolStatusType, PikkuToolStatus, MissingCredentialPayload, } from './use-pikku-agent-runtime.js';
 export { PikkuAgentChat } from './pikku-agent-chat.js';
 export type { PikkuAgentChatProps } from './pikku-agent-chat.js';

package/dist/cjs/pikku-agent-chat.d.ts

@@ -7,5 +7,7 @@ export interface PikkuAgentChatProps extends PikkuAgentRuntimeOptions {
      */
     hideToolCalls?: boolean | string[];
     dark?: boolean;
+    /** Max width of the chat content area. Defaults to 768. Set to 'none' for full width. */
+    maxWidth?: number | 'none';
 }
 export declare function PikkuAgentChat(props: PikkuAgentChatProps): import("react/jsx-runtime").JSX.Element;

package/dist/cjs/pikku-agent-chat.js

@@ -34,6 +34,8 @@ const lightColors = {
     successColor: '#2e7d32',
     errorBg: '#ffebee',
     errorColor: '#c62828',
+    warningBg: '#fff3e0',
+    warningColor: '#e65100',
 };
 const darkColors = {
     bg: 'transparent',
@@ -52,6 +54,8 @@ const darkColors = {
     successColor: '#00e68a',
     errorBg: 'rgba(220, 38, 38, 0.1)',
     errorColor: '#f87171',
+    warningBg: 'rgba(245, 158, 11, 0.1)',
+    warningColor: '#fbbf24',
 };
 const ColorsContext = (0, react_1.createContext)(lightColors);
 const HideToolCallsContext = (0, react_1.createContext)(undefined);
@@ -170,7 +174,13 @@ const ToolCallDisplay = ({ toolCallId, toolName, args, result, status, addResult
                             borderRadius: 3,
                             background: colors.errorBg,
                             color: colors.errorColor,
-                        }, children: "error" })), status.type === 'denied' && ((0, jsx_runtime_1.jsx)("span", { style: {
+                        }, children: "error" })), status.type === 'missing-credential' && ((0, jsx_runtime_1.jsx)("span", { style: {
+                            fontSize: 11,
+                            padding: '1px 5px',
+                            borderRadius: 3,
+                            background: colors.warningBg,
+                            color: colors.warningColor,
+                        }, children: "credential required" })), status.type === 'denied' && ((0, jsx_runtime_1.jsx)("span", { style: {
                             fontSize: 11,
                             padding: '1px 5px',
                             borderRadius: 3,
@@ -295,7 +305,7 @@ const PikkuComposer = ({ disabled, }) => {
                         }, children: "\u25B6" })] }) }) }));
 };
 function PikkuAgentChat(props) {
-    const { emptyMessage, hideToolCalls, dark } = props, runtimeOptions = __rest(props, ["emptyMessage", "hideToolCalls", "dark"]);
+    const { emptyMessage, hideToolCalls, dark, maxWidth = 768 } = props, runtimeOptions = __rest(props, ["emptyMessage", "hideToolCalls", "dark", "maxWidth"]);
     const { runtime, isAwaitingApproval, pendingApprovals, handleApproval } = (0, use_pikku_agent_runtime_js_1.usePikkuAgentRuntime)(runtimeOptions);
     const colors = dark ? darkColors : lightColors;
     return ((0, jsx_runtime_1.jsx)(ColorsContext.Provider, { value: colors, children: (0, jsx_runtime_1.jsx)(use_pikku_agent_runtime_js_1.PikkuApprovalContext.Provider, { value: { pendingApprovals, handleApproval }, children: (0, jsx_runtime_1.jsx)(HideToolCallsContext.Provider, { value: hideToolCalls, children: (0, jsx_runtime_1.jsx)(react_2.AssistantRuntimeProvider, { runtime: runtime, children: (0, jsx_runtime_1.jsx)("div", { style: {
@@ -313,7 +323,7 @@ function PikkuAgentChat(props) {
                                         minHeight: 0,
                                         overflowY: 'auto',
                                     }, children: (0, jsx_runtime_1.jsxs)("div", { style: {
-                                            maxWidth: 768,
+                                            maxWidth: maxWidth === 'none' ? undefined : maxWidth,
                                             margin: '0 auto',
                                             padding: 16,
                                             display: 'flex',
@@ -332,5 +342,5 @@ function PikkuAgentChat(props) {
                                                         : 'Start a new conversation.') }) }), (0, jsx_runtime_1.jsx)(react_2.ThreadPrimitive.Messages, { components: {
                                                     UserMessage,
                                                     AssistantMessage,
-                                                } })] }) }), (0, jsx_runtime_1.jsx)("div", { style: { maxWidth: 768, margin: '0 auto', width: '100%', padding: '0 16px' }, children: (0, jsx_runtime_1.jsx)(PikkuComposer, { disabled: isAwaitingApproval }) })] }) }) }) }) }) }));
+                                                } })] }) }), (0, jsx_runtime_1.jsx)("div", { style: { maxWidth: maxWidth === 'none' ? undefined : maxWidth, margin: '0 auto', width: '100%', padding: '0 16px' }, children: (0, jsx_runtime_1.jsx)(PikkuComposer, { disabled: isAwaitingApproval }) })] }) }) }) }) }) }));
 }

package/dist/cjs/use-pikku-agent-runtime.d.ts

@@ -17,6 +17,10 @@ export interface PendingApproval {
     args: unknown;
     reason?: string;
     runId: string;
+    type?: 'approval-request' | 'credential-request';
+    credentialName?: string;
+    credentialType?: 'oauth2' | 'apikey';
+    connectUrl?: string;
 }
 export interface PikkuApprovalContextValue {
     pendingApprovals: PendingApproval[];
@@ -25,9 +29,18 @@ export interface PikkuApprovalContextValue {
 export declare const PikkuApprovalContext: import("react").Context<PikkuApprovalContextValue>;
 export declare const usePikkuApproval: () => PikkuApprovalContextValue;
 export declare function isDeniedResult(result: unknown): boolean;
-export type PikkuToolStatusType = 'running' | 'requires-action' | 'completed' | 'denied' | 'error';
+export type PikkuToolStatusType = 'running' | 'requires-action' | 'completed' | 'denied' | 'error' | 'missing-credential';
+export type MissingCredentialPayload = {
+    error: 'missing_credential';
+    credentialName: string;
+    credentialType: 'oauth2' | 'apikey';
+    connectUrl?: string;
+};
 export type PikkuToolStatus = {
-    type: PikkuToolStatusType;
+    type: Exclude<PikkuToolStatusType, 'missing-credential'>;
+} | {
+    type: 'missing-credential';
+    payload: MissingCredentialPayload;
 };
 export declare function resolvePikkuToolStatus(status: {
     type: string;

package/dist/cjs/use-pikku-agent-runtime.js

@@ -129,6 +129,19 @@ function processStream(reader, text, toolCalls, yieldContent, onFinish) {
                             args: event.args,
                             reason: event.reason,
                             runId: event.runId,
+                            type: 'approval-request',
+                        });
+                        break;
+                    case 'credential-request':
+                        pendingApprovals.push({
+                            toolCallId: event.toolCallId,
+                            toolName: event.toolName,
+                            args: event.args,
+                            runId: event.runId,
+                            type: 'credential-request',
+                            credentialName: event.credentialName,
+                            credentialType: event.credentialType,
+                            connectUrl: event.connectUrl,
                         });
                         break;
                     case 'error':
@@ -162,6 +175,22 @@ function isDeniedResult(result) {
         return false;
     }
 }
+function isMissingCredentialResult(result) {
+    if (typeof result === 'object' &&
+        result &&
+        result.error === 'missing_credential') {
+        return result;
+    }
+    if (typeof result === 'string') {
+        try {
+            const parsed = JSON.parse(result);
+            if ((parsed === null || parsed === void 0 ? void 0 : parsed.error) === 'missing_credential')
+                return parsed;
+        }
+        catch (_a) { }
+    }
+    return null;
+}
 function resolvePikkuToolStatus(status, result) {
     if (status.type === 'running')
         return { type: 'running' };
@@ -169,6 +198,9 @@ function resolvePikkuToolStatus(status, result) {
         return { type: 'requires-action' };
     if (isDeniedResult(result))
         return { type: 'denied' };
+    const missingCred = isMissingCredentialResult(result);
+    if (missingCred)
+        return { type: 'missing-credential', payload: missingCred };
     if (typeof result === 'string' && result.startsWith('Error:'))
         return { type: 'error' };
     return { type: 'completed' };
@@ -295,22 +327,56 @@ function createPikkuStreamingAdapter(optionsRef, pendingApprovalsRef, approvalDe
                         }
                     }
                 }
-                const response = yield __await(fetch(`${opts.api}/${opts.agentName}/stream`, {
-                    method: 'POST',
-                    headers: Object.assign({ 'Content-Type': 'application/json' }, opts.headers),
-                    body: JSON.stringify({
-                        agentName: opts.agentName,
-                        message: messageText,
-                        threadId: opts.threadId,
-                        resourceId: opts.resourceId,
-                        model: opts.model,
-                        temperature: opts.temperature,
-                    }),
-                    signal: abortSignal,
-                    credentials: opts.credentials,
-                }));
+                let response;
+                try {
+                    response = yield __await(fetch(`${opts.api}/${opts.agentName}/stream`, {
+                        method: 'POST',
+                        headers: Object.assign({ 'Content-Type': 'application/json' }, opts.headers),
+                        body: JSON.stringify({
+                            agentName: opts.agentName,
+                            message: messageText,
+                            threadId: opts.threadId,
+                            resourceId: opts.resourceId,
+                            model: opts.model,
+                            temperature: opts.temperature,
+                        }),
+                        signal: abortSignal,
+                        credentials: opts.credentials,
+                    }));
+                }
+                catch (e) {
+                    const msg = (e === null || e === void 0 ? void 0 : e.message) || 'Unknown error';
+                    let errorText = 'Failed to connect to the agent.';
+                    if (msg.includes('Failed to fetch') ||
+                        msg.includes('NetworkError') ||
+                        msg.includes('CORS')) {
+                        errorText =
+                            'Unable to reach the agent server. The deployment may be down or the URL may be incorrect.';
+                    }
+                    else if (msg.includes('abort')) {
+                        return yield __await(void 0);
+                    }
+                    yield yield __await({ content: [{ type: 'text', text: `⚠️ ${errorText}` }] });
+                    return yield __await(void 0);
+                }
                 if (!response.ok || !response.body) {
-                    throw new Error(`Agent stream failed: ${response.status}`);
+                    let errorText = `Request failed (${response.status}).`;
+                    if (response.status === 401 || response.status === 403) {
+                        errorText = 'Authentication error.';
+                    }
+                    else if (response.status === 404) {
+                        errorText =
+                            'Agent not found — the agent may not be configured for this project.';
+                    }
+                    else if (response.status === 502 || response.status === 503) {
+                        errorText =
+                            'The agent server is currently unavailable. Try again in a moment.';
+                    }
+                    else if (response.status === 429) {
+                        errorText = 'Rate limited — too many requests. Please wait a moment.';
+                    }
+                    yield yield __await({ content: [{ type: 'text', text: `⚠️ ${errorText}` }] });
+                    return yield __await(void 0);
                 }
                 const text = { value: '' };
                 const toolCalls = [];

package/dist/esm/index.d.ts

@@ -1,4 +1,4 @@
 export { usePikkuAgentRuntime, usePikkuAgentNonStreamingRuntime, PikkuApprovalContext, usePikkuApproval, convertDbMessages, isDeniedResult, resolvePikkuToolStatus, } from './use-pikku-agent-runtime.js';
-export type { PikkuAgentRuntimeOptions, PendingApproval, PikkuApprovalContextValue, PikkuToolStatusType, PikkuToolStatus, } from './use-pikku-agent-runtime.js';
+export type { PikkuAgentRuntimeOptions, PendingApproval, PikkuApprovalContextValue, PikkuToolStatusType, PikkuToolStatus, MissingCredentialPayload, } from './use-pikku-agent-runtime.js';
 export { PikkuAgentChat } from './pikku-agent-chat.js';
 export type { PikkuAgentChatProps } from './pikku-agent-chat.js';

package/dist/esm/pikku-agent-chat.d.ts

@@ -7,5 +7,7 @@ export interface PikkuAgentChatProps extends PikkuAgentRuntimeOptions {
      */
     hideToolCalls?: boolean | string[];
     dark?: boolean;
+    /** Max width of the chat content area. Defaults to 768. Set to 'none' for full width. */
+    maxWidth?: number | 'none';
 }
 export declare function PikkuAgentChat(props: PikkuAgentChatProps): import("react/jsx-runtime").JSX.Element;

package/dist/esm/pikku-agent-chat.js

@@ -20,6 +20,8 @@ const lightColors = {
     successColor: '#2e7d32',
     errorBg: '#ffebee',
     errorColor: '#c62828',
+    warningBg: '#fff3e0',
+    warningColor: '#e65100',
 };
 const darkColors = {
     bg: 'transparent',
@@ -38,6 +40,8 @@ const darkColors = {
     successColor: '#00e68a',
     errorBg: 'rgba(220, 38, 38, 0.1)',
     errorColor: '#f87171',
+    warningBg: 'rgba(245, 158, 11, 0.1)',
+    warningColor: '#fbbf24',
 };
 const ColorsContext = createContext(lightColors);
 const HideToolCallsContext = createContext(undefined);
@@ -156,7 +160,13 @@ const ToolCallDisplay = ({ toolCallId, toolName, args, result, status, addResult
                             borderRadius: 3,
                             background: colors.errorBg,
                             color: colors.errorColor,
-                        }, children: "error" })), status.type === 'denied' && (_jsx("span", { style: {
+                        }, children: "error" })), status.type === 'missing-credential' && (_jsx("span", { style: {
+                            fontSize: 11,
+                            padding: '1px 5px',
+                            borderRadius: 3,
+                            background: colors.warningBg,
+                            color: colors.warningColor,
+                        }, children: "credential required" })), status.type === 'denied' && (_jsx("span", { style: {
                             fontSize: 11,
                             padding: '1px 5px',
                             borderRadius: 3,
@@ -290,7 +300,7 @@ const PikkuComposer = ({ disabled, }) => {
                         }, children: "\u25B6" })] }) }) }));
 };
 export function PikkuAgentChat(props) {
-    const { emptyMessage, hideToolCalls, dark, ...runtimeOptions } = props;
+    const { emptyMessage, hideToolCalls, dark, maxWidth = 768, ...runtimeOptions } = props;
     const { runtime, isAwaitingApproval, pendingApprovals, handleApproval } = usePikkuAgentRuntime(runtimeOptions);
     const colors = dark ? darkColors : lightColors;
     return (_jsx(ColorsContext.Provider, { value: colors, children: _jsx(PikkuApprovalContext.Provider, { value: { pendingApprovals, handleApproval }, children: _jsx(HideToolCallsContext.Provider, { value: hideToolCalls, children: _jsx(AssistantRuntimeProvider, { runtime: runtime, children: _jsx("div", { style: {
@@ -308,7 +318,7 @@ export function PikkuAgentChat(props) {
                                         minHeight: 0,
                                         overflowY: 'auto',
                                     }, children: _jsxs("div", { style: {
-                                            maxWidth: 768,
+                                            maxWidth: maxWidth === 'none' ? undefined : maxWidth,
                                             margin: '0 auto',
                                             padding: 16,
                                             display: 'flex',
@@ -328,5 +338,5 @@ export function PikkuAgentChat(props) {
                                                             : 'Start a new conversation.') }) }), _jsx(ThreadPrimitive.Messages, { components: {
                                                     UserMessage,
                                                     AssistantMessage,
-                                                } })] }) }), _jsx("div", { style: { maxWidth: 768, margin: '0 auto', width: '100%', padding: '0 16px' }, children: _jsx(PikkuComposer, { disabled: isAwaitingApproval }) })] }) }) }) }) }) }));
+                                                } })] }) }), _jsx("div", { style: { maxWidth: maxWidth === 'none' ? undefined : maxWidth, margin: '0 auto', width: '100%', padding: '0 16px' }, children: _jsx(PikkuComposer, { disabled: isAwaitingApproval }) })] }) }) }) }) }) }));
 }

package/dist/esm/use-pikku-agent-runtime.d.ts

@@ -17,6 +17,10 @@ export interface PendingApproval {
     args: unknown;
     reason?: string;
     runId: string;
+    type?: 'approval-request' | 'credential-request';
+    credentialName?: string;
+    credentialType?: 'oauth2' | 'apikey';
+    connectUrl?: string;
 }
 export interface PikkuApprovalContextValue {
     pendingApprovals: PendingApproval[];
@@ -25,9 +29,18 @@ export interface PikkuApprovalContextValue {
 export declare const PikkuApprovalContext: import("react").Context<PikkuApprovalContextValue>;
 export declare const usePikkuApproval: () => PikkuApprovalContextValue;
 export declare function isDeniedResult(result: unknown): boolean;
-export type PikkuToolStatusType = 'running' | 'requires-action' | 'completed' | 'denied' | 'error';
+export type PikkuToolStatusType = 'running' | 'requires-action' | 'completed' | 'denied' | 'error' | 'missing-credential';
+export type MissingCredentialPayload = {
+    error: 'missing_credential';
+    credentialName: string;
+    credentialType: 'oauth2' | 'apikey';
+    connectUrl?: string;
+};
 export type PikkuToolStatus = {
-    type: PikkuToolStatusType;
+    type: Exclude<PikkuToolStatusType, 'missing-credential'>;
+} | {
+    type: 'missing-credential';
+    payload: MissingCredentialPayload;
 };
 export declare function resolvePikkuToolStatus(status: {
     type: string;

package/dist/esm/use-pikku-agent-runtime.js

@@ -84,6 +84,19 @@ async function processStream(reader, text, toolCalls, yieldContent, onFinish) {
                     args: event.args,
                     reason: event.reason,
                     runId: event.runId,
+                    type: 'approval-request',
+                });
+                break;
+            case 'credential-request':
+                pendingApprovals.push({
+                    toolCallId: event.toolCallId,
+                    toolName: event.toolName,
+                    args: event.args,
+                    runId: event.runId,
+                    type: 'credential-request',
+                    credentialName: event.credentialName,
+                    credentialType: event.credentialType,
+                    connectUrl: event.connectUrl,
                 });
                 break;
             case 'error':
@@ -108,6 +121,22 @@ export function isDeniedResult(result) {
         return false;
     }
 }
+function isMissingCredentialResult(result) {
+    if (typeof result === 'object' &&
+        result &&
+        result.error === 'missing_credential') {
+        return result;
+    }
+    if (typeof result === 'string') {
+        try {
+            const parsed = JSON.parse(result);
+            if (parsed?.error === 'missing_credential')
+                return parsed;
+        }
+        catch { }
+    }
+    return null;
+}
 export function resolvePikkuToolStatus(status, result) {
     if (status.type === 'running')
         return { type: 'running' };
@@ -115,6 +144,9 @@ export function resolvePikkuToolStatus(status, result) {
         return { type: 'requires-action' };
     if (isDeniedResult(result))
         return { type: 'denied' };
+    const missingCred = isMissingCredentialResult(result);
+    if (missingCred)
+        return { type: 'missing-credential', payload: missingCred };
     if (typeof result === 'string' && result.startsWith('Error:'))
         return { type: 'error' };
     return { type: 'completed' };
@@ -243,22 +275,56 @@ function createPikkuStreamingAdapter(optionsRef, pendingApprovalsRef, approvalDe
                     }
                 }
             }
-            const response = await fetch(`${opts.api}/${opts.agentName}/stream`, {
-                method: 'POST',
-                headers: { 'Content-Type': 'application/json', ...opts.headers },
-                body: JSON.stringify({
-                    agentName: opts.agentName,
-                    message: messageText,
-                    threadId: opts.threadId,
-                    resourceId: opts.resourceId,
-                    model: opts.model,
-                    temperature: opts.temperature,
-                }),
-                signal: abortSignal,
-                credentials: opts.credentials,
-            });
+            let response;
+            try {
+                response = await fetch(`${opts.api}/${opts.agentName}/stream`, {
+                    method: 'POST',
+                    headers: { 'Content-Type': 'application/json', ...opts.headers },
+                    body: JSON.stringify({
+                        agentName: opts.agentName,
+                        message: messageText,
+                        threadId: opts.threadId,
+                        resourceId: opts.resourceId,
+                        model: opts.model,
+                        temperature: opts.temperature,
+                    }),
+                    signal: abortSignal,
+                    credentials: opts.credentials,
+                });
+            }
+            catch (e) {
+                const msg = e?.message || 'Unknown error';
+                let errorText = 'Failed to connect to the agent.';
+                if (msg.includes('Failed to fetch') ||
+                    msg.includes('NetworkError') ||
+                    msg.includes('CORS')) {
+                    errorText =
+                        'Unable to reach the agent server. The deployment may be down or the URL may be incorrect.';
+                }
+                else if (msg.includes('abort')) {
+                    return;
+                }
+                yield { content: [{ type: 'text', text: `⚠️ ${errorText}` }] };
+                return;
+            }
             if (!response.ok || !response.body) {
-                throw new Error(`Agent stream failed: ${response.status}`);
+                let errorText = `Request failed (${response.status}).`;
+                if (response.status === 401 || response.status === 403) {
+                    errorText = 'Authentication error.';
+                }
+                else if (response.status === 404) {
+                    errorText =
+                        'Agent not found — the agent may not be configured for this project.';
+                }
+                else if (response.status === 502 || response.status === 503) {
+                    errorText =
+                        'The agent server is currently unavailable. Try again in a moment.';
+                }
+                else if (response.status === 429) {
+                    errorText = 'Rate limited — too many requests. Please wait a moment.';
+                }
+                yield { content: [{ type: 'text', text: `⚠️ ${errorText}` }] };
+                return;
             }
             const text = { value: '' };
             const toolCalls = [];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pikku/assistant-ui",
-  "version": "0.12.1",
+  "version": "0.12.3",
   "author": "yasser.fadl@gmail.com",
   "license": "MIT",
   "type": "module",
@@ -16,7 +16,8 @@
     "tsc": "tsc",
     "build:esm": "tsc -b && echo '{\"type\": \"module\"}' > dist/esm/package.json",
     "build:cjs": "tsc -b tsconfig.cjs.json && echo '{\"type\": \"commonjs\"}' > dist/cjs/package.json",
-    "build": "yarn build:esm && yarn build:cjs"
+    "build": "yarn build:esm && yarn build:cjs",
+    "prepublishOnly": "yarn build"
   },
   "dependencies": {
     "@assistant-ui/react": "^0.12.12",

package/src/index.ts

@@ -13,6 +13,7 @@ export type {
   PikkuApprovalContextValue,
   PikkuToolStatusType,
   PikkuToolStatus,
+  MissingCredentialPayload,
 } from './use-pikku-agent-runtime.js'
 export { PikkuAgentChat } from './pikku-agent-chat.js'
 export type { PikkuAgentChatProps } from './pikku-agent-chat.js'

package/src/pikku-agent-chat.tsx

@@ -23,6 +23,8 @@ export interface PikkuAgentChatProps extends PikkuAgentRuntimeOptions {
    */
   hideToolCalls?: boolean | string[]
   dark?: boolean
+  /** Max width of the chat content area. Defaults to 768. Set to 'none' for full width. */
+  maxWidth?: number | 'none'
 }
 
 interface ChatColors {
@@ -42,6 +44,8 @@ interface ChatColors {
   successColor: string
   errorBg: string
   errorColor: string
+  warningBg: string
+  warningColor: string
 }
 
 const lightColors: ChatColors = {
@@ -61,6 +65,8 @@ const lightColors: ChatColors = {
   successColor: '#2e7d32',
   errorBg: '#ffebee',
   errorColor: '#c62828',
+  warningBg: '#fff3e0',
+  warningColor: '#e65100',
 }
 
 const darkColors: ChatColors = {
@@ -80,6 +86,8 @@ const darkColors: ChatColors = {
   successColor: '#00e68a',
   errorBg: 'rgba(220, 38, 38, 0.1)',
   errorColor: '#f87171',
+  warningBg: 'rgba(245, 158, 11, 0.1)',
+  warningColor: '#fbbf24',
 }
 
 const ColorsContext = createContext<ChatColors>(lightColors)
@@ -284,6 +292,19 @@ const ToolCallDisplay: FunctionComponent<{
             error
           </span>
         )}
+        {status.type === 'missing-credential' && (
+          <span
+            style={{
+              fontSize: 11,
+              padding: '1px 5px',
+              borderRadius: 3,
+              background: colors.warningBg,
+              color: colors.warningColor,
+            }}
+          >
+            credential required
+          </span>
+        )}
         {status.type === 'denied' && (
           <span
             style={{
@@ -571,7 +592,7 @@ const PikkuComposer: FunctionComponent<{ disabled?: boolean }> = ({
 }
 
 export function PikkuAgentChat(props: PikkuAgentChatProps) {
-  const { emptyMessage, hideToolCalls, dark, ...runtimeOptions } = props
+  const { emptyMessage, hideToolCalls, dark, maxWidth = 768, ...runtimeOptions } = props
   const { runtime, isAwaitingApproval, pendingApprovals, handleApproval } =
     usePikkuAgentRuntime(runtimeOptions)
 
@@ -607,7 +628,7 @@ export function PikkuAgentChat(props: PikkuAgentChatProps) {
           >
             <div
               style={{
-                maxWidth: 768,
+                maxWidth: maxWidth === 'none' ? undefined : maxWidth,
                 margin: '0 auto',
                 padding: 16,
                 display: 'flex',
@@ -641,7 +662,7 @@ export function PikkuAgentChat(props: PikkuAgentChatProps) {
               />
             </div>
           </ThreadPrimitive.Viewport>
-          <div style={{ maxWidth: 768, margin: '0 auto', width: '100%', padding: '0 16px' }}>
+          <div style={{ maxWidth: maxWidth === 'none' ? undefined : maxWidth, margin: '0 auto', width: '100%', padding: '0 16px' }}>
             <PikkuComposer disabled={isAwaitingApproval} />
           </div>
         </ThreadPrimitive.Root>

package/src/use-pikku-agent-runtime.ts

@@ -31,6 +31,10 @@ export interface PendingApproval {
   args: unknown
   reason?: string
   runId: string
+  type?: 'approval-request' | 'credential-request'
+  credentialName?: string
+  credentialType?: 'oauth2' | 'apikey'
+  connectUrl?: string
 }
 
 export interface PikkuApprovalContextValue {
@@ -143,6 +147,19 @@ async function processStream(
           args: event.args,
           reason: event.reason,
           runId: event.runId,
+          type: 'approval-request',
+        })
+        break
+      case 'credential-request':
+        pendingApprovals.push({
+          toolCallId: event.toolCallId,
+          toolName: event.toolName,
+          args: event.args,
+          runId: event.runId,
+          type: 'credential-request',
+          credentialName: event.credentialName,
+          credentialType: event.credentialType,
+          connectUrl: event.connectUrl,
         })
         break
       case 'error':
@@ -174,8 +191,37 @@ export type PikkuToolStatusType =
   | 'completed'
   | 'denied'
   | 'error'
+  | 'missing-credential'
 
-export type PikkuToolStatus = { type: PikkuToolStatusType }
+export type MissingCredentialPayload = {
+  error: 'missing_credential'
+  credentialName: string
+  credentialType: 'oauth2' | 'apikey'
+  connectUrl?: string
+}
+
+export type PikkuToolStatus =
+  | { type: Exclude<PikkuToolStatusType, 'missing-credential'> }
+  | { type: 'missing-credential'; payload: MissingCredentialPayload }
+
+function isMissingCredentialResult(
+  result: unknown
+): MissingCredentialPayload | null {
+  if (
+    typeof result === 'object' &&
+    result &&
+    (result as any).error === 'missing_credential'
+  ) {
+    return result as MissingCredentialPayload
+  }
+  if (typeof result === 'string') {
+    try {
+      const parsed = JSON.parse(result)
+      if (parsed?.error === 'missing_credential') return parsed
+    } catch {}
+  }
+  return null
+}
 
 export function resolvePikkuToolStatus(
   status: { type: string },
@@ -184,6 +230,8 @@ export function resolvePikkuToolStatus(
   if (status.type === 'running') return { type: 'running' }
   if (status.type === 'requires-action') return { type: 'requires-action' }
   if (isDeniedResult(result)) return { type: 'denied' }
+  const missingCred = isMissingCredentialResult(result)
+  if (missingCred) return { type: 'missing-credential', payload: missingCred }
   if (typeof result === 'string' && result.startsWith('Error:'))
     return { type: 'error' }
   return { type: 'completed' }
@@ -351,23 +399,54 @@ function createPikkuStreamingAdapter(
         }
       }
 
-      const response = await fetch(`${opts.api}/${opts.agentName}/stream`, {
-        method: 'POST',
-        headers: { 'Content-Type': 'application/json', ...opts.headers },
-        body: JSON.stringify({
-          agentName: opts.agentName,
-          message: messageText,
-          threadId: opts.threadId,
-          resourceId: opts.resourceId,
-          model: opts.model,
-          temperature: opts.temperature,
-        }),
-        signal: abortSignal,
-        credentials: opts.credentials,
-      })
+      let response: Response
+      try {
+        response = await fetch(`${opts.api}/${opts.agentName}/stream`, {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/json', ...opts.headers },
+          body: JSON.stringify({
+            agentName: opts.agentName,
+            message: messageText,
+            threadId: opts.threadId,
+            resourceId: opts.resourceId,
+            model: opts.model,
+            temperature: opts.temperature,
+          }),
+          signal: abortSignal,
+          credentials: opts.credentials,
+        })
+      } catch (e: any) {
+        const msg = e?.message || 'Unknown error'
+        let errorText = 'Failed to connect to the agent.'
+        if (
+          msg.includes('Failed to fetch') ||
+          msg.includes('NetworkError') ||
+          msg.includes('CORS')
+        ) {
+          errorText =
+            'Unable to reach the agent server. The deployment may be down or the URL may be incorrect.'
+        } else if (msg.includes('abort')) {
+          return
+        }
+        yield { content: [{ type: 'text' as const, text: `⚠️ ${errorText}` }] }
+        return
+      }
 
       if (!response.ok || !response.body) {
-        throw new Error(`Agent stream failed: ${response.status}`)
+        let errorText = `Request failed (${response.status}).`
+        if (response.status === 401 || response.status === 403) {
+          errorText = 'Authentication error.'
+        } else if (response.status === 404) {
+          errorText =
+            'Agent not found — the agent may not be configured for this project.'
+        } else if (response.status === 502 || response.status === 503) {
+          errorText =
+            'The agent server is currently unavailable. Try again in a moment.'
+        } else if (response.status === 429) {
+          errorText = 'Rate limited — too many requests. Please wait a moment.'
+        }
+        yield { content: [{ type: 'text' as const, text: `⚠️ ${errorText}` }] }
+        return
       }
 
       const text = { value: '' }