@pikku/assistant-ui 0.12.5 → 0.12.6

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @pikku/assistant-ui
 
+## 0.12.6
+
+### Patch Changes
+
+- f4f7046: feat(assistant-ui): export useFileAttachment hook, modelSupportsVision, PendingFile, UploadAttachmentFn, and INLINE_SIZE_LIMIT
+
 ## 0.12.5
 
 ### Patch Changes

package/dist/cjs/index.d.ts

@@ -2,3 +2,6 @@ export { usePikkuAgentRuntime, usePikkuAgentNonStreamingRuntime, PikkuApprovalCo
 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';
+export { useFileAttachment, INLINE_SIZE_LIMIT } from './use-file-attachment.js';
+export type { PendingFile, UploadAttachmentFn } from './use-file-attachment.js';
+export { modelSupportsVision } from './model-capabilities.js';

package/dist/cjs/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.PikkuAgentChat = exports.resolvePikkuToolStatus = exports.isDeniedResult = exports.convertDbMessages = exports.usePikkuApproval = exports.PikkuApprovalContext = exports.usePikkuAgentNonStreamingRuntime = exports.usePikkuAgentRuntime = void 0;
+exports.modelSupportsVision = exports.INLINE_SIZE_LIMIT = exports.useFileAttachment = exports.PikkuAgentChat = exports.resolvePikkuToolStatus = exports.isDeniedResult = exports.convertDbMessages = exports.usePikkuApproval = exports.PikkuApprovalContext = exports.usePikkuAgentNonStreamingRuntime = exports.usePikkuAgentRuntime = void 0;
 var use_pikku_agent_runtime_js_1 = require("./use-pikku-agent-runtime.js");
 Object.defineProperty(exports, "usePikkuAgentRuntime", { enumerable: true, get: function () { return use_pikku_agent_runtime_js_1.usePikkuAgentRuntime; } });
 Object.defineProperty(exports, "usePikkuAgentNonStreamingRuntime", { enumerable: true, get: function () { return use_pikku_agent_runtime_js_1.usePikkuAgentNonStreamingRuntime; } });
@@ -11,3 +11,8 @@ Object.defineProperty(exports, "isDeniedResult", { enumerable: true, get: functi
 Object.defineProperty(exports, "resolvePikkuToolStatus", { enumerable: true, get: function () { return use_pikku_agent_runtime_js_1.resolvePikkuToolStatus; } });
 var pikku_agent_chat_js_1 = require("./pikku-agent-chat.js");
 Object.defineProperty(exports, "PikkuAgentChat", { enumerable: true, get: function () { return pikku_agent_chat_js_1.PikkuAgentChat; } });
+var use_file_attachment_js_1 = require("./use-file-attachment.js");
+Object.defineProperty(exports, "useFileAttachment", { enumerable: true, get: function () { return use_file_attachment_js_1.useFileAttachment; } });
+Object.defineProperty(exports, "INLINE_SIZE_LIMIT", { enumerable: true, get: function () { return use_file_attachment_js_1.INLINE_SIZE_LIMIT; } });
+var model_capabilities_js_1 = require("./model-capabilities.js");
+Object.defineProperty(exports, "modelSupportsVision", { enumerable: true, get: function () { return model_capabilities_js_1.modelSupportsVision; } });

package/dist/cjs/model-capabilities.d.ts

@@ -0,0 +1 @@
+export declare function modelSupportsVision(modelID: string): boolean;

package/dist/cjs/model-capabilities.js

@@ -0,0 +1,16 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.modelSupportsVision = modelSupportsVision;
+const MODEL_VISION_SUPPORT = new Set([
+    'claude-sonnet-4-5',
+    'claude-opus-4-1',
+    'gpt-4o-mini',
+    'gpt-5',
+    'gpt-5-mini',
+    'gpt-5-codex',
+    'gemini-2.5-pro',
+    'gemini-2.5-flash',
+]);
+function modelSupportsVision(modelID) {
+    return MODEL_VISION_SUPPORT.has(modelID);
+}

package/dist/cjs/use-file-attachment.d.ts

@@ -0,0 +1,26 @@
+export type PendingFile = {
+    id: string;
+    name: string;
+    mimeType: string;
+    previewUrl: string;
+    contentUrl: string;
+    isImage: boolean;
+};
+export type UploadAttachmentFn = (args: {
+    contentType: string;
+    sizeBytes: number;
+}) => Promise<{
+    uploadUrl: string;
+    signedReadUrl: string;
+    uploadMethod?: string;
+}>;
+export declare const INLINE_SIZE_LIMIT: number;
+export declare function useFileAttachment(upload: UploadAttachmentFn): {
+    pendingFiles: PendingFile[];
+    uploading: boolean;
+    uploadError: string | null;
+    fileInputRef: import("react").RefObject<HTMLInputElement | null>;
+    handleFileChange: (e: React.ChangeEvent<HTMLInputElement>) => Promise<void>;
+    removeFile: (id: string) => void;
+    clearFiles: () => void;
+};

package/dist/cjs/use-file-attachment.js

@@ -0,0 +1,99 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.INLINE_SIZE_LIMIT = void 0;
+exports.useFileAttachment = useFileAttachment;
+const react_1 = require("react");
+exports.INLINE_SIZE_LIMIT = 1 * 1024 * 1024;
+function useFileAttachment(upload) {
+    const [pendingFiles, setPendingFiles] = (0, react_1.useState)([]);
+    const [uploading, setUploading] = (0, react_1.useState)(false);
+    const [uploadError, setUploadError] = (0, react_1.useState)(null);
+    const fileInputRef = (0, react_1.useRef)(null);
+    const handleFileChange = (0, react_1.useCallback)((e) => __awaiter(this, void 0, void 0, function* () {
+        var _a;
+        const files = Array.from((_a = e.target.files) !== null && _a !== void 0 ? _a : []);
+        e.target.value = '';
+        if (!files.length)
+            return;
+        setUploading(true);
+        setUploadError(null);
+        try {
+            for (const file of files) {
+                const previewUrl = URL.createObjectURL(file);
+                let contentUrl;
+                if (file.type.startsWith('image/') &&
+                    file.size <= exports.INLINE_SIZE_LIMIT) {
+                    contentUrl = yield new Promise((resolve, reject) => {
+                        const reader = new FileReader();
+                        reader.onload = (ev) => resolve(ev.target.result);
+                        reader.onerror = reject;
+                        reader.readAsDataURL(file);
+                    });
+                }
+                else {
+                    const { uploadUrl, signedReadUrl, uploadMethod } = yield upload({
+                        contentType: file.type,
+                        sizeBytes: file.size,
+                    });
+                    const resp = yield fetch(uploadUrl, {
+                        method: uploadMethod !== null && uploadMethod !== void 0 ? uploadMethod : 'PUT',
+                        body: file,
+                        headers: { 'Content-Type': file.type },
+                    });
+                    if (!resp.ok)
+                        throw new Error(`Upload failed (${resp.status})`);
+                    contentUrl = signedReadUrl;
+                }
+                setPendingFiles((prev) => [
+                    ...prev,
+                    {
+                        id: `file_${Date.now().toString(36)}`,
+                        name: file.name,
+                        mimeType: file.type,
+                        previewUrl,
+                        contentUrl,
+                        isImage: file.type.startsWith('image/'),
+                    },
+                ]);
+            }
+        }
+        catch (err) {
+            setUploadError(err instanceof Error ? err.message : 'Upload failed');
+        }
+        finally {
+            setUploading(false);
+        }
+    }), [upload]);
+    const removeFile = (0, react_1.useCallback)((id) => {
+        setPendingFiles((prev) => {
+            const f = prev.find((x) => x.id === id);
+            if (f)
+                URL.revokeObjectURL(f.previewUrl);
+            return prev.filter((x) => x.id !== id);
+        });
+    }, []);
+    const clearFiles = (0, react_1.useCallback)(() => {
+        setPendingFiles((prev) => {
+            prev.forEach((f) => URL.revokeObjectURL(f.previewUrl));
+            return [];
+        });
+    }, []);
+    return {
+        pendingFiles,
+        uploading,
+        uploadError,
+        fileInputRef,
+        handleFileChange,
+        removeFile,
+        clearFiles,
+    };
+}

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

@@ -10,6 +10,10 @@ export interface PikkuAgentRuntimeOptions {
     headers?: Record<string, string>;
     model?: string;
     temperature?: number;
+    /** Structured context injected into the agent's system instructions.
+     *  Provide upfront state (e.g. current org/project/branch/deployment IDs)
+     *  so the agent can call tools without asking the user. */
+    context?: string;
 }
 export interface PendingApproval {
     toolCallId: string;

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

@@ -379,14 +379,7 @@ function createPikkuStreamingAdapter(optionsRef, pendingApprovalsRef, approvalDe
                     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,
-                        }),
+                        body: JSON.stringify(Object.assign({ agentName: opts.agentName, message: messageText, threadId: opts.threadId, resourceId: opts.resourceId, model: opts.model, temperature: opts.temperature }, (opts.context ? { context: opts.context } : {}))),
                         signal: abortSignal,
                         credentials: opts.credentials,
                     }));
@@ -729,14 +722,7 @@ function createPikkuNonStreamingAdapter(optionsRef, pendingApprovalsRef, approva
                 const response = yield __await(fetch(`${opts.api}/${opts.agentName}`, {
                     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,
-                    }),
+                    body: JSON.stringify(Object.assign({ agentName: opts.agentName, message: messageText, threadId: opts.threadId, resourceId: opts.resourceId, model: opts.model, temperature: opts.temperature }, (opts.context ? { context: opts.context } : {}))),
                     signal: abortSignal,
                     credentials: opts.credentials,
                 }));

package/dist/esm/index.d.ts

@@ -2,3 +2,6 @@ export { usePikkuAgentRuntime, usePikkuAgentNonStreamingRuntime, PikkuApprovalCo
 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';
+export { useFileAttachment, INLINE_SIZE_LIMIT } from './use-file-attachment.js';
+export type { PendingFile, UploadAttachmentFn } from './use-file-attachment.js';
+export { modelSupportsVision } from './model-capabilities.js';

package/dist/esm/index.js

@@ -1,2 +1,4 @@
 export { usePikkuAgentRuntime, usePikkuAgentNonStreamingRuntime, PikkuApprovalContext, usePikkuApproval, convertDbMessages, isDeniedResult, resolvePikkuToolStatus, } from './use-pikku-agent-runtime.js';
 export { PikkuAgentChat } from './pikku-agent-chat.js';
+export { useFileAttachment, INLINE_SIZE_LIMIT } from './use-file-attachment.js';
+export { modelSupportsVision } from './model-capabilities.js';

package/dist/esm/model-capabilities.d.ts

@@ -0,0 +1 @@
+export declare function modelSupportsVision(modelID: string): boolean;

package/dist/esm/model-capabilities.js

@@ -0,0 +1,13 @@
+const MODEL_VISION_SUPPORT = new Set([
+    'claude-sonnet-4-5',
+    'claude-opus-4-1',
+    'gpt-4o-mini',
+    'gpt-5',
+    'gpt-5-mini',
+    'gpt-5-codex',
+    'gemini-2.5-pro',
+    'gemini-2.5-flash',
+]);
+export function modelSupportsVision(modelID) {
+    return MODEL_VISION_SUPPORT.has(modelID);
+}

package/dist/esm/use-file-attachment.d.ts

@@ -0,0 +1,26 @@
+export type PendingFile = {
+    id: string;
+    name: string;
+    mimeType: string;
+    previewUrl: string;
+    contentUrl: string;
+    isImage: boolean;
+};
+export type UploadAttachmentFn = (args: {
+    contentType: string;
+    sizeBytes: number;
+}) => Promise<{
+    uploadUrl: string;
+    signedReadUrl: string;
+    uploadMethod?: string;
+}>;
+export declare const INLINE_SIZE_LIMIT: number;
+export declare function useFileAttachment(upload: UploadAttachmentFn): {
+    pendingFiles: PendingFile[];
+    uploading: boolean;
+    uploadError: string | null;
+    fileInputRef: import("react").RefObject<HTMLInputElement | null>;
+    handleFileChange: (e: React.ChangeEvent<HTMLInputElement>) => Promise<void>;
+    removeFile: (id: string) => void;
+    clearFiles: () => void;
+};

package/dist/esm/use-file-attachment.js

@@ -0,0 +1,85 @@
+import { useState, useCallback, useRef } from 'react';
+export const INLINE_SIZE_LIMIT = 1 * 1024 * 1024;
+export function useFileAttachment(upload) {
+    const [pendingFiles, setPendingFiles] = useState([]);
+    const [uploading, setUploading] = useState(false);
+    const [uploadError, setUploadError] = useState(null);
+    const fileInputRef = useRef(null);
+    const handleFileChange = useCallback(async (e) => {
+        const files = Array.from(e.target.files ?? []);
+        e.target.value = '';
+        if (!files.length)
+            return;
+        setUploading(true);
+        setUploadError(null);
+        try {
+            for (const file of files) {
+                const previewUrl = URL.createObjectURL(file);
+                let contentUrl;
+                if (file.type.startsWith('image/') &&
+                    file.size <= INLINE_SIZE_LIMIT) {
+                    contentUrl = await new Promise((resolve, reject) => {
+                        const reader = new FileReader();
+                        reader.onload = (ev) => resolve(ev.target.result);
+                        reader.onerror = reject;
+                        reader.readAsDataURL(file);
+                    });
+                }
+                else {
+                    const { uploadUrl, signedReadUrl, uploadMethod } = await upload({
+                        contentType: file.type,
+                        sizeBytes: file.size,
+                    });
+                    const resp = await fetch(uploadUrl, {
+                        method: uploadMethod ?? 'PUT',
+                        body: file,
+                        headers: { 'Content-Type': file.type },
+                    });
+                    if (!resp.ok)
+                        throw new Error(`Upload failed (${resp.status})`);
+                    contentUrl = signedReadUrl;
+                }
+                setPendingFiles((prev) => [
+                    ...prev,
+                    {
+                        id: `file_${Date.now().toString(36)}`,
+                        name: file.name,
+                        mimeType: file.type,
+                        previewUrl,
+                        contentUrl,
+                        isImage: file.type.startsWith('image/'),
+                    },
+                ]);
+            }
+        }
+        catch (err) {
+            setUploadError(err instanceof Error ? err.message : 'Upload failed');
+        }
+        finally {
+            setUploading(false);
+        }
+    }, [upload]);
+    const removeFile = useCallback((id) => {
+        setPendingFiles((prev) => {
+            const f = prev.find((x) => x.id === id);
+            if (f)
+                URL.revokeObjectURL(f.previewUrl);
+            return prev.filter((x) => x.id !== id);
+        });
+    }, []);
+    const clearFiles = useCallback(() => {
+        setPendingFiles((prev) => {
+            prev.forEach((f) => URL.revokeObjectURL(f.previewUrl));
+            return [];
+        });
+    }, []);
+    return {
+        pendingFiles,
+        uploading,
+        uploadError,
+        fileInputRef,
+        handleFileChange,
+        removeFile,
+        clearFiles,
+    };
+}

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

@@ -10,6 +10,10 @@ export interface PikkuAgentRuntimeOptions {
     headers?: Record<string, string>;
     model?: string;
     temperature?: number;
+    /** Structured context injected into the agent's system instructions.
+     *  Provide upfront state (e.g. current org/project/branch/deployment IDs)
+     *  so the agent can call tools without asking the user. */
+    context?: string;
 }
 export interface PendingApproval {
     toolCallId: string;

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

@@ -334,6 +334,7 @@ function createPikkuStreamingAdapter(optionsRef, pendingApprovalsRef, approvalDe
                         resourceId: opts.resourceId,
                         model: opts.model,
                         temperature: opts.temperature,
+                        ...(opts.context ? { context: opts.context } : {}),
                     }),
                     signal: abortSignal,
                     credentials: opts.credentials,
@@ -688,6 +689,7 @@ function createPikkuNonStreamingAdapter(optionsRef, pendingApprovalsRef, approva
                     resourceId: opts.resourceId,
                     model: opts.model,
                     temperature: opts.temperature,
+                    ...(opts.context ? { context: opts.context } : {}),
                 }),
                 signal: abortSignal,
                 credentials: opts.credentials,

package/dist/tsconfig.cjs.tsbuildinfo

@@ -1 +1 @@
-{"root":["../src/index.ts","../src/use-pikku-agent-runtime.ts","../src/pikku-agent-chat.tsx"],"version":"5.9.3"}
+{"root":["../src/index.ts","../src/model-capabilities.ts","../src/use-file-attachment.ts","../src/use-pikku-agent-runtime.ts","../src/pikku-agent-chat.tsx"],"version":"5.9.3"}

package/dist/tsconfig.tsbuildinfo

@@ -1 +1 @@
-{"root":["../src/index.ts","../src/use-pikku-agent-runtime.ts","../src/pikku-agent-chat.tsx"],"version":"5.9.3"}
+{"root":["../src/index.ts","../src/model-capabilities.ts","../src/use-file-attachment.ts","../src/use-pikku-agent-runtime.ts","../src/pikku-agent-chat.tsx"],"version":"5.9.3"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pikku/assistant-ui",
-  "version": "0.12.5",
+  "version": "0.12.6",
   "author": "yasser.fadl@gmail.com",
   "license": "MIT",
   "type": "module",
@@ -20,7 +20,7 @@
     "prepublishOnly": "yarn build"
   },
   "dependencies": {
-    "@assistant-ui/react": "^0.12.12",
+    "@assistant-ui/react": "^0.12.12 || ^0.14.0",
     "react-markdown": "^10.1.0"
   },
   "peerDependencies": {

package/src/index.ts

@@ -17,3 +17,6 @@ export type {
 } from './use-pikku-agent-runtime.js'
 export { PikkuAgentChat } from './pikku-agent-chat.js'
 export type { PikkuAgentChatProps } from './pikku-agent-chat.js'
+export { useFileAttachment, INLINE_SIZE_LIMIT } from './use-file-attachment.js'
+export type { PendingFile, UploadAttachmentFn } from './use-file-attachment.js'
+export { modelSupportsVision } from './model-capabilities.js'

package/src/model-capabilities.ts

@@ -0,0 +1,14 @@
+const MODEL_VISION_SUPPORT = new Set([
+  'claude-sonnet-4-5',
+  'claude-opus-4-1',
+  'gpt-4o-mini',
+  'gpt-5',
+  'gpt-5-mini',
+  'gpt-5-codex',
+  'gemini-2.5-pro',
+  'gemini-2.5-flash',
+])
+
+export function modelSupportsVision(modelID: string): boolean {
+  return MODEL_VISION_SUPPORT.has(modelID)
+}

package/src/use-file-attachment.ts

@@ -0,0 +1,110 @@
+import { useState, useCallback, useRef } from 'react'
+
+export type PendingFile = {
+  id: string
+  name: string
+  mimeType: string
+  previewUrl: string
+  contentUrl: string
+  isImage: boolean
+}
+
+export type UploadAttachmentFn = (args: {
+  contentType: string
+  sizeBytes: number
+}) => Promise<{
+  uploadUrl: string
+  signedReadUrl: string
+  uploadMethod?: string
+}>
+
+export const INLINE_SIZE_LIMIT = 1 * 1024 * 1024
+
+export function useFileAttachment(upload: UploadAttachmentFn) {
+  const [pendingFiles, setPendingFiles] = useState<PendingFile[]>([])
+  const [uploading, setUploading] = useState(false)
+  const [uploadError, setUploadError] = useState<string | null>(null)
+  const fileInputRef = useRef<HTMLInputElement>(null)
+
+  const handleFileChange = useCallback(
+    async (e: React.ChangeEvent<HTMLInputElement>) => {
+      const files = Array.from(e.target.files ?? [])
+      e.target.value = ''
+      if (!files.length) return
+      setUploading(true)
+      setUploadError(null)
+      try {
+        for (const file of files) {
+          const previewUrl = URL.createObjectURL(file)
+          let contentUrl: string
+
+          if (
+            file.type.startsWith('image/') &&
+            file.size <= INLINE_SIZE_LIMIT
+          ) {
+            contentUrl = await new Promise<string>((resolve, reject) => {
+              const reader = new FileReader()
+              reader.onload = (ev) => resolve(ev.target!.result as string)
+              reader.onerror = reject
+              reader.readAsDataURL(file)
+            })
+          } else {
+            const { uploadUrl, signedReadUrl, uploadMethod } = await upload({
+              contentType: file.type,
+              sizeBytes: file.size,
+            })
+            const resp = await fetch(uploadUrl, {
+              method: uploadMethod ?? 'PUT',
+              body: file,
+              headers: { 'Content-Type': file.type },
+            })
+            if (!resp.ok) throw new Error(`Upload failed (${resp.status})`)
+            contentUrl = signedReadUrl
+          }
+
+          setPendingFiles((prev) => [
+            ...prev,
+            {
+              id: `file_${Date.now().toString(36)}`,
+              name: file.name,
+              mimeType: file.type,
+              previewUrl,
+              contentUrl,
+              isImage: file.type.startsWith('image/'),
+            },
+          ])
+        }
+      } catch (err) {
+        setUploadError(err instanceof Error ? err.message : 'Upload failed')
+      } finally {
+        setUploading(false)
+      }
+    },
+    [upload]
+  )
+
+  const removeFile = useCallback((id: string) => {
+    setPendingFiles((prev) => {
+      const f = prev.find((x) => x.id === id)
+      if (f) URL.revokeObjectURL(f.previewUrl)
+      return prev.filter((x) => x.id !== id)
+    })
+  }, [])
+
+  const clearFiles = useCallback(() => {
+    setPendingFiles((prev) => {
+      prev.forEach((f) => URL.revokeObjectURL(f.previewUrl))
+      return []
+    })
+  }, [])
+
+  return {
+    pendingFiles,
+    uploading,
+    uploadError,
+    fileInputRef,
+    handleFileChange,
+    removeFile,
+    clearFiles,
+  }
+}

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

@@ -23,6 +23,10 @@ export interface PikkuAgentRuntimeOptions {
   headers?: Record<string, string>
   model?: string
   temperature?: number
+  /** Structured context injected into the agent's system instructions.
+   *  Provide upfront state (e.g. current org/project/branch/deployment IDs)
+   *  so the agent can call tools without asking the user. */
+  context?: string
 }
 
 export interface PendingApproval {
@@ -486,6 +490,7 @@ function createPikkuStreamingAdapter(
             resourceId: opts.resourceId,
             model: opts.model,
             temperature: opts.temperature,
+            ...(opts.context ? { context: opts.context } : {}),
           }),
           signal: abortSignal,
           credentials: opts.credentials,
@@ -948,6 +953,7 @@ function createPikkuNonStreamingAdapter(
           resourceId: opts.resourceId,
           model: opts.model,
           temperature: opts.temperature,
+          ...(opts.context ? { context: opts.context } : {}),
         }),
         signal: abortSignal,
         credentials: opts.credentials,