@framers/agentos-ext-image-search 1.0.0

package/README.md

@@ -0,0 +1,35 @@
+# Image Search Extension for AgentOS
+
+Unified stock photo search across Pexels, Unsplash, and Pixabay with automatic provider fallback.
+
+## Installation
+
+```bash
+npm install @framers/agentos-ext-image-search
+```
+
+## Configuration
+
+Set one or more API keys:
+
+```bash
+PEXELS_API_KEY=your-key
+UNSPLASH_ACCESS_KEY=your-key
+PIXABAY_API_KEY=your-key
+```
+
+## Tool: image_search
+
+**Input:**
+- `query` (string, required) -- Search query
+- `provider` (string: pexels/unsplash/pixabay/auto, default: auto) -- Image provider
+- `limit` (number, 1-10, default: 3) -- Number of results
+- `orientation` (string: landscape/portrait/square) -- Image orientation
+
+**Output:** Array of images with `url`, `thumbnailUrl`, `photographer`, `attribution`.
+
+Auto mode tries providers in order: Pexels -> Unsplash -> Pixabay.
+
+## License
+
+MIT - Frame.dev

package/dist/index.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Image Search Extension Pack — stock photo search from Pexels, Unsplash, Pixabay.
+ */
+import { ImageSearchTool } from './tools/imageSearch.js';
+export interface ImageSearchExtensionOptions {
+    pexelsApiKey?: string;
+    unsplashApiKey?: string;
+    pixabayApiKey?: string;
+    priority?: number;
+}
+export declare function createExtensionPack(context: any): {
+    name: string;
+    version: string;
+    descriptors: {
+        id: string;
+        kind: "tool";
+        priority: number;
+        payload: ImageSearchTool;
+    }[];
+    onActivate: () => Promise<any>;
+    onDeactivate: () => Promise<any>;
+};
+export { ImageSearchTool };
+export type { ImageSearchInput, ImageSearchOutput, SearchImage } from './tools/imageSearch.js';
+export default createExtensionPack;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAEzD,MAAM,WAAW,2BAA2B;IAC1C,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,GAAG;;;;;;;;;;;EAiB/C;AAED,OAAO,EAAE,eAAe,EAAE,CAAC;AAC3B,YAAY,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAC/F,eAAe,mBAAmB,CAAC"}

package/dist/index.js

@@ -0,0 +1,24 @@
+/**
+ * Image Search Extension Pack — stock photo search from Pexels, Unsplash, Pixabay.
+ */
+import { ImageSearchTool } from './tools/imageSearch.js';
+export function createExtensionPack(context) {
+    const options = (context.options || {});
+    const tool = new ImageSearchTool({
+        pexels: options.pexelsApiKey || context.getSecret?.('pexels.apiKey') || process.env.PEXELS_API_KEY,
+        unsplash: options.unsplashApiKey || context.getSecret?.('unsplash.apiKey') || process.env.UNSPLASH_ACCESS_KEY,
+        pixabay: options.pixabayApiKey || context.getSecret?.('pixabay.apiKey') || process.env.PIXABAY_API_KEY,
+    });
+    return {
+        name: '@framers/agentos-ext-image-search',
+        version: '1.0.0',
+        descriptors: [
+            { id: 'imageSearch', kind: 'tool', priority: options.priority || 50, payload: tool },
+        ],
+        onActivate: async () => context.logger?.info('Image Search Extension activated'),
+        onDeactivate: async () => context.logger?.info('Image Search Extension deactivated'),
+    };
+}
+export { ImageSearchTool };
+export default createExtensionPack;
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AASzD,MAAM,UAAU,mBAAmB,CAAC,OAAY;IAC9C,MAAM,OAAO,GAAG,CAAC,OAAO,CAAC,OAAO,IAAI,EAAE,CAAgC,CAAC;IACvE,MAAM,IAAI,GAAG,IAAI,eAAe,CAAC;QAC/B,MAAM,EAAE,OAAO,CAAC,YAAY,IAAI,OAAO,CAAC,SAAS,EAAE,CAAC,eAAe,CAAC,IAAI,OAAO,CAAC,GAAG,CAAC,cAAc;QAClG,QAAQ,EAAE,OAAO,CAAC,cAAc,IAAI,OAAO,CAAC,SAAS,EAAE,CAAC,iBAAiB,CAAC,IAAI,OAAO,CAAC,GAAG,CAAC,mBAAmB;QAC7G,OAAO,EAAE,OAAO,CAAC,aAAa,IAAI,OAAO,CAAC,SAAS,EAAE,CAAC,gBAAgB,CAAC,IAAI,OAAO,CAAC,GAAG,CAAC,eAAe;KACvG,CAAC,CAAC;IAEH,OAAO;QACL,IAAI,EAAE,mCAAmC;QACzC,OAAO,EAAE,OAAO;QAChB,WAAW,EAAE;YACX,EAAE,EAAE,EAAE,aAAa,EAAE,IAAI,EAAE,MAAe,EAAE,QAAQ,EAAE,OAAO,CAAC,QAAQ,IAAI,EAAE,EAAE,OAAO,EAAE,IAAI,EAAE;SAC9F;QACD,UAAU,EAAE,KAAK,IAAI,EAAE,CAAC,OAAO,CAAC,MAAM,EAAE,IAAI,CAAC,kCAAkC,CAAC;QAChF,YAAY,EAAE,KAAK,IAAI,EAAE,CAAC,OAAO,CAAC,MAAM,EAAE,IAAI,CAAC,oCAAoC,CAAC;KACrF,CAAC;AACJ,CAAC;AAED,OAAO,EAAE,eAAe,EAAE,CAAC;AAE3B,eAAe,mBAAmB,CAAC"}

package/dist/tools/imageSearch.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Image Search Tool — unified stock photo search across Pexels, Unsplash, Pixabay.
+ */
+import type { ITool, ToolExecutionContext, ToolExecutionResult, JSONSchemaObject } from '../../../../../../agentos/src/core/tools/ITool.js';
+export interface ImageSearchInput {
+    query: string;
+    provider?: 'pexels' | 'unsplash' | 'pixabay' | 'auto';
+    limit?: number;
+    orientation?: 'landscape' | 'portrait' | 'square';
+}
+export interface SearchImage {
+    id: string;
+    provider: string;
+    url: string;
+    thumbnailUrl: string;
+    width: number;
+    height: number;
+    photographer?: string;
+    description?: string;
+    attribution: string;
+}
+export interface ImageSearchOutput {
+    query: string;
+    provider: string;
+    images: SearchImage[];
+    totalResults: number;
+}
+export declare class ImageSearchTool implements ITool<ImageSearchInput, ImageSearchOutput> {
+    readonly id = "image-search-v1";
+    readonly name = "image_search";
+    readonly displayName = "Image Search";
+    readonly description: string;
+    readonly category = "media";
+    readonly version = "1.0.0";
+    readonly hasSideEffects = false;
+    readonly inputSchema: JSONSchemaObject;
+    readonly requiredCapabilities: string[];
+    private pexelsKey;
+    private unsplashKey;
+    private pixabayKey;
+    constructor(keys?: {
+        pexels?: string;
+        unsplash?: string;
+        pixabay?: string;
+    });
+    execute(args: ImageSearchInput, _context: ToolExecutionContext): Promise<ToolExecutionResult<ImageSearchOutput>>;
+    private searchPexels;
+    private searchUnsplash;
+    private searchPixabay;
+}
+//# sourceMappingURL=imageSearch.d.ts.map

package/dist/tools/imageSearch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"imageSearch.d.ts","sourceRoot":"","sources":["../../src/tools/imageSearch.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,oBAAoB,EAAE,mBAAmB,EAAE,gBAAgB,EAAE,MAAM,mDAAmD,CAAC;AAE5I,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,QAAQ,GAAG,UAAU,GAAG,SAAS,GAAG,MAAM,CAAC;IACtD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,WAAW,GAAG,UAAU,GAAG,QAAQ,CAAC;CACnD;AAED,MAAM,WAAW,WAAW;IAC1B,EAAE,EAAE,MAAM,CAAC;IACX,QAAQ,EAAE,MAAM,CAAC;IACjB,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,EAAE,MAAM,CAAC;IACrB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,iBAAiB;IAChC,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,WAAW,EAAE,CAAC;IACtB,YAAY,EAAE,MAAM,CAAC;CACtB;AAED,qBAAa,eAAgB,YAAW,KAAK,CAAC,gBAAgB,EAAE,iBAAiB,CAAC;IAChF,QAAQ,CAAC,EAAE,qBAAqB;IAChC,QAAQ,CAAC,IAAI,kBAAkB;IAC/B,QAAQ,CAAC,WAAW,kBAAkB;IACtC,QAAQ,CAAC,WAAW,SAE4C;IAChE,QAAQ,CAAC,QAAQ,WAAW;IAC5B,QAAQ,CAAC,OAAO,WAAW;IAC3B,QAAQ,CAAC,cAAc,SAAS;IAEhC,QAAQ,CAAC,WAAW,EAAE,gBAAgB,CASpC;IAEF,QAAQ,CAAC,oBAAoB,WAA+B;IAE5D,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,WAAW,CAAS;IAC5B,OAAO,CAAC,UAAU,CAAS;gBAEf,IAAI,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE;IAMrE,OAAO,CACX,IAAI,EAAE,gBAAgB,EACtB,QAAQ,EAAE,oBAAoB,GAC7B,OAAO,CAAC,mBAAmB,CAAC,iBAAiB,CAAC,CAAC;YAyBpC,YAAY;YAqBZ,cAAc;YAqBd,aAAa;CAqB5B"}

package/dist/tools/imageSearch.js

@@ -0,0 +1,131 @@
+/**
+ * Image Search Tool — unified stock photo search across Pexels, Unsplash, Pixabay.
+ */
+export class ImageSearchTool {
+    id = 'image-search-v1';
+    name = 'image_search';
+    displayName = 'Image Search';
+    description = 'Search for stock photos from Pexels, Unsplash, or Pixabay. ' +
+        'Returns image URLs with attribution for embedding in posts.';
+    category = 'media';
+    version = '1.0.0';
+    hasSideEffects = false;
+    inputSchema = {
+        type: 'object',
+        properties: {
+            query: { type: 'string', description: 'Image search query.' },
+            provider: { type: 'string', enum: ['pexels', 'unsplash', 'pixabay', 'auto'], default: 'auto' },
+            limit: { type: 'integer', minimum: 1, maximum: 10, default: 3 },
+            orientation: { type: 'string', enum: ['landscape', 'portrait', 'square'] },
+        },
+        required: ['query'],
+    };
+    requiredCapabilities = ['capability:media_search'];
+    pexelsKey;
+    unsplashKey;
+    pixabayKey;
+    constructor(keys) {
+        this.pexelsKey = keys?.pexels || process.env.PEXELS_API_KEY || '';
+        this.unsplashKey = keys?.unsplash || process.env.UNSPLASH_ACCESS_KEY || '';
+        this.pixabayKey = keys?.pixabay || process.env.PIXABAY_API_KEY || '';
+    }
+    async execute(args, _context) {
+        const provider = args.provider || 'auto';
+        const limit = args.limit || 3;
+        let selected;
+        if (provider === 'auto') {
+            if (this.pexelsKey)
+                selected = 'pexels';
+            else if (this.unsplashKey)
+                selected = 'unsplash';
+            else if (this.pixabayKey)
+                selected = 'pixabay';
+            else
+                return { success: false, error: 'No image API keys configured.' };
+        }
+        else {
+            selected = provider;
+        }
+        try {
+            switch (selected) {
+                case 'pexels': return await this.searchPexels(args.query, limit, args.orientation);
+                case 'unsplash': return await this.searchUnsplash(args.query, limit, args.orientation);
+                case 'pixabay': return await this.searchPixabay(args.query, limit, args.orientation);
+            }
+        }
+        catch (err) {
+            return { success: false, error: `Image search failed: ${err.message}` };
+        }
+    }
+    async searchPexels(query, limit, orientation) {
+        if (!this.pexelsKey)
+            return { success: false, error: 'PEXELS_API_KEY not set.' };
+        const params = new URLSearchParams({ query, per_page: String(limit) });
+        if (orientation)
+            params.set('orientation', orientation);
+        const res = await fetch(`https://api.pexels.com/v1/search?${params}`, { headers: { Authorization: this.pexelsKey } });
+        if (!res.ok)
+            return { success: false, error: `Pexels: ${res.status}` };
+        const data = await res.json();
+        return {
+            success: true,
+            output: {
+                query, provider: 'pexels', totalResults: data.total_results || 0,
+                images: (data.photos || []).map((p) => ({
+                    id: String(p.id), provider: 'pexels', url: p.src?.large || p.src?.original,
+                    thumbnailUrl: p.src?.medium, width: p.width, height: p.height,
+                    photographer: p.photographer, description: p.alt || '',
+                    attribution: `Photo by ${p.photographer} on Pexels`,
+                })),
+            },
+        };
+    }
+    async searchUnsplash(query, limit, orientation) {
+        if (!this.unsplashKey)
+            return { success: false, error: 'UNSPLASH_ACCESS_KEY not set.' };
+        const params = new URLSearchParams({ query, per_page: String(limit) });
+        if (orientation)
+            params.set('orientation', orientation);
+        const res = await fetch(`https://api.unsplash.com/search/photos?${params}`, { headers: { Authorization: `Client-ID ${this.unsplashKey}` } });
+        if (!res.ok)
+            return { success: false, error: `Unsplash: ${res.status}` };
+        const data = await res.json();
+        return {
+            success: true,
+            output: {
+                query, provider: 'unsplash', totalResults: data.total || 0,
+                images: (data.results || []).map((p) => ({
+                    id: p.id, provider: 'unsplash', url: p.urls?.regular, thumbnailUrl: p.urls?.small,
+                    width: p.width, height: p.height, photographer: p.user?.name,
+                    description: p.description || p.alt_description || '',
+                    attribution: `Photo by ${p.user?.name} on Unsplash`,
+                })),
+            },
+        };
+    }
+    async searchPixabay(query, limit, orientation) {
+        if (!this.pixabayKey)
+            return { success: false, error: 'PIXABAY_API_KEY not set.' };
+        // Pixabay requires per_page 3–200
+        const params = new URLSearchParams({ key: this.pixabayKey, q: query, per_page: String(Math.max(3, limit)), safesearch: 'true' });
+        if (orientation && orientation !== 'square')
+            params.set('orientation', orientation);
+        const res = await fetch(`https://pixabay.com/api/?${params}`);
+        if (!res.ok)
+            return { success: false, error: `Pixabay: ${res.status}` };
+        const data = await res.json();
+        return {
+            success: true,
+            output: {
+                query, provider: 'pixabay', totalResults: data.totalHits || 0,
+                images: (data.hits || []).map((h) => ({
+                    id: String(h.id), provider: 'pixabay', url: h.largeImageURL || h.webformatURL,
+                    thumbnailUrl: h.previewURL, width: h.imageWidth, height: h.imageHeight,
+                    photographer: h.user, description: h.tags || '',
+                    attribution: `Image by ${h.user} on Pixabay`,
+                })),
+            },
+        };
+    }
+}
+//# sourceMappingURL=imageSearch.js.map

package/dist/tools/imageSearch.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"imageSearch.js","sourceRoot":"","sources":["../../src/tools/imageSearch.ts"],"names":[],"mappings":"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"}

package/manifest.json

@@ -0,0 +1,22 @@
+{
+  "$schema": "https://agentos.sh/schemas/extension-manifest-v1.json",
+  "id": "com.framers.media.image-search",
+  "name": "Image Search Extension",
+  "version": "1.0.0",
+  "description": "Search for stock photos from Pexels, Unsplash, and Pixabay with automatic fallback",
+  "author": { "name": "Frame.dev" },
+  "license": "MIT",
+  "keywords": ["images", "photos", "pexels", "unsplash", "pixabay", "stock"],
+  "agentosVersion": "^2.0.0",
+  "categories": ["media"],
+  "extensions": [
+    { "kind": "tool", "id": "imageSearch", "displayName": "Image Search", "entry": "./src/tools/imageSearch.ts" }
+  ],
+  "configuration": {
+    "properties": {
+      "pexels.apiKey": { "type": "string", "secret": true },
+      "unsplash.apiKey": { "type": "string", "secret": true },
+      "pixabay.apiKey": { "type": "string", "secret": true }
+    }
+  }
+}

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@framers/agentos-ext-image-search",
+  "version": "1.0.0",
+  "description": "Unified stock photo search across Pexels, Unsplash, and Pixabay for AgentOS",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": { "import": "./dist/index.js", "types": "./dist/index.d.ts" },
+    "./manifest.json": "./manifest.json",
+    "./package.json": "./package.json"
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "lint": "eslint src --ext .ts",
+    "typecheck": "tsc --noEmit",
+    "clean": "rimraf dist"
+  },
+  "keywords": ["agentos", "extension", "image", "search", "pexels", "unsplash", "pixabay", "media"],
+  "author": { "name": "Framers AI", "email": "team@frame.dev", "url": "https://frame.dev" },
+  "contributors": [{ "name": "Johnny Dunn", "email": "johnnyfived@protonmail.com", "url": "https://github.com/jddunn" }],
+  "license": "MIT",
+  "repository": { "type": "git", "url": "https://github.com/framersai/agentos-extensions.git", "directory": "registry/curated/media/image-search" },
+  "publishConfig": { "access": "public" },
+  "peerDependencies": { "@framers/agentos": "^0.1.0" },
+  "devDependencies": {
+    "@framers/agentos": "^0.1.0",
+    "@types/node": "^20.12.12",
+    "@vitest/coverage-v8": "^1.6.0",
+    "rimraf": "^5.0.7",
+    "typescript": "^5.4.5",
+    "vitest": "^1.6.0"
+  }
+}

package/src/index.ts

@@ -0,0 +1,35 @@
+/**
+ * Image Search Extension Pack — stock photo search from Pexels, Unsplash, Pixabay.
+ */
+
+import { ImageSearchTool } from './tools/imageSearch.js';
+
+export interface ImageSearchExtensionOptions {
+  pexelsApiKey?: string;
+  unsplashApiKey?: string;
+  pixabayApiKey?: string;
+  priority?: number;
+}
+
+export function createExtensionPack(context: any) {
+  const options = (context.options || {}) as ImageSearchExtensionOptions;
+  const tool = new ImageSearchTool({
+    pexels: options.pexelsApiKey || context.getSecret?.('pexels.apiKey') || process.env.PEXELS_API_KEY,
+    unsplash: options.unsplashApiKey || context.getSecret?.('unsplash.apiKey') || process.env.UNSPLASH_ACCESS_KEY,
+    pixabay: options.pixabayApiKey || context.getSecret?.('pixabay.apiKey') || process.env.PIXABAY_API_KEY,
+  });
+
+  return {
+    name: '@framers/agentos-ext-image-search',
+    version: '1.0.0',
+    descriptors: [
+      { id: 'imageSearch', kind: 'tool' as const, priority: options.priority || 50, payload: tool },
+    ],
+    onActivate: async () => context.logger?.info('Image Search Extension activated'),
+    onDeactivate: async () => context.logger?.info('Image Search Extension deactivated'),
+  };
+}
+
+export { ImageSearchTool };
+export type { ImageSearchInput, ImageSearchOutput, SearchImage } from './tools/imageSearch.js';
+export default createExtensionPack;

package/src/tools/imageSearch.ts

@@ -0,0 +1,158 @@
+/**
+ * Image Search Tool — unified stock photo search across Pexels, Unsplash, Pixabay.
+ */
+
+import type { ITool, ToolExecutionContext, ToolExecutionResult, JSONSchemaObject } from '../../../../../../agentos/src/core/tools/ITool.js';
+
+export interface ImageSearchInput {
+  query: string;
+  provider?: 'pexels' | 'unsplash' | 'pixabay' | 'auto';
+  limit?: number;
+  orientation?: 'landscape' | 'portrait' | 'square';
+}
+
+export interface SearchImage {
+  id: string;
+  provider: string;
+  url: string;
+  thumbnailUrl: string;
+  width: number;
+  height: number;
+  photographer?: string;
+  description?: string;
+  attribution: string;
+}
+
+export interface ImageSearchOutput {
+  query: string;
+  provider: string;
+  images: SearchImage[];
+  totalResults: number;
+}
+
+export class ImageSearchTool implements ITool<ImageSearchInput, ImageSearchOutput> {
+  readonly id = 'image-search-v1';
+  readonly name = 'image_search';
+  readonly displayName = 'Image Search';
+  readonly description =
+    'Search for stock photos from Pexels, Unsplash, or Pixabay. ' +
+    'Returns image URLs with attribution for embedding in posts.';
+  readonly category = 'media';
+  readonly version = '1.0.0';
+  readonly hasSideEffects = false;
+
+  readonly inputSchema: JSONSchemaObject = {
+    type: 'object',
+    properties: {
+      query: { type: 'string', description: 'Image search query.' },
+      provider: { type: 'string', enum: ['pexels', 'unsplash', 'pixabay', 'auto'], default: 'auto' },
+      limit: { type: 'integer', minimum: 1, maximum: 10, default: 3 },
+      orientation: { type: 'string', enum: ['landscape', 'portrait', 'square'] },
+    },
+    required: ['query'],
+  };
+
+  readonly requiredCapabilities = ['capability:media_search'];
+
+  private pexelsKey: string;
+  private unsplashKey: string;
+  private pixabayKey: string;
+
+  constructor(keys?: { pexels?: string; unsplash?: string; pixabay?: string }) {
+    this.pexelsKey = keys?.pexels || process.env.PEXELS_API_KEY || '';
+    this.unsplashKey = keys?.unsplash || process.env.UNSPLASH_ACCESS_KEY || '';
+    this.pixabayKey = keys?.pixabay || process.env.PIXABAY_API_KEY || '';
+  }
+
+  async execute(
+    args: ImageSearchInput,
+    _context: ToolExecutionContext,
+  ): Promise<ToolExecutionResult<ImageSearchOutput>> {
+    const provider = args.provider || 'auto';
+    const limit = args.limit || 3;
+
+    let selected: 'pexels' | 'unsplash' | 'pixabay';
+    if (provider === 'auto') {
+      if (this.pexelsKey) selected = 'pexels';
+      else if (this.unsplashKey) selected = 'unsplash';
+      else if (this.pixabayKey) selected = 'pixabay';
+      else return { success: false, error: 'No image API keys configured.' };
+    } else {
+      selected = provider;
+    }
+
+    try {
+      switch (selected) {
+        case 'pexels': return await this.searchPexels(args.query, limit, args.orientation);
+        case 'unsplash': return await this.searchUnsplash(args.query, limit, args.orientation);
+        case 'pixabay': return await this.searchPixabay(args.query, limit, args.orientation);
+      }
+    } catch (err: any) {
+      return { success: false, error: `Image search failed: ${err.message}` };
+    }
+  }
+
+  private async searchPexels(query: string, limit: number, orientation?: string): Promise<ToolExecutionResult<ImageSearchOutput>> {
+    if (!this.pexelsKey) return { success: false, error: 'PEXELS_API_KEY not set.' };
+    const params = new URLSearchParams({ query, per_page: String(limit) });
+    if (orientation) params.set('orientation', orientation);
+    const res = await fetch(`https://api.pexels.com/v1/search?${params}`, { headers: { Authorization: this.pexelsKey } });
+    if (!res.ok) return { success: false, error: `Pexels: ${res.status}` };
+    const data = await res.json();
+    return {
+      success: true,
+      output: {
+        query, provider: 'pexels', totalResults: data.total_results || 0,
+        images: (data.photos || []).map((p: any) => ({
+          id: String(p.id), provider: 'pexels', url: p.src?.large || p.src?.original,
+          thumbnailUrl: p.src?.medium, width: p.width, height: p.height,
+          photographer: p.photographer, description: p.alt || '',
+          attribution: `Photo by ${p.photographer} on Pexels`,
+        })),
+      },
+    };
+  }
+
+  private async searchUnsplash(query: string, limit: number, orientation?: string): Promise<ToolExecutionResult<ImageSearchOutput>> {
+    if (!this.unsplashKey) return { success: false, error: 'UNSPLASH_ACCESS_KEY not set.' };
+    const params = new URLSearchParams({ query, per_page: String(limit) });
+    if (orientation) params.set('orientation', orientation);
+    const res = await fetch(`https://api.unsplash.com/search/photos?${params}`, { headers: { Authorization: `Client-ID ${this.unsplashKey}` } });
+    if (!res.ok) return { success: false, error: `Unsplash: ${res.status}` };
+    const data = await res.json();
+    return {
+      success: true,
+      output: {
+        query, provider: 'unsplash', totalResults: data.total || 0,
+        images: (data.results || []).map((p: any) => ({
+          id: p.id, provider: 'unsplash', url: p.urls?.regular, thumbnailUrl: p.urls?.small,
+          width: p.width, height: p.height, photographer: p.user?.name,
+          description: p.description || p.alt_description || '',
+          attribution: `Photo by ${p.user?.name} on Unsplash`,
+        })),
+      },
+    };
+  }
+
+  private async searchPixabay(query: string, limit: number, orientation?: string): Promise<ToolExecutionResult<ImageSearchOutput>> {
+    if (!this.pixabayKey) return { success: false, error: 'PIXABAY_API_KEY not set.' };
+    // Pixabay requires per_page 3–200
+    const params = new URLSearchParams({ key: this.pixabayKey, q: query, per_page: String(Math.max(3, limit)), safesearch: 'true' });
+    if (orientation && orientation !== 'square') params.set('orientation', orientation);
+    const res = await fetch(`https://pixabay.com/api/?${params}`);
+    if (!res.ok) return { success: false, error: `Pixabay: ${res.status}` };
+    const data = await res.json();
+    return {
+      success: true,
+      output: {
+        query, provider: 'pixabay', totalResults: data.totalHits || 0,
+        images: (data.hits || []).map((h: any) => ({
+          id: String(h.id), provider: 'pixabay', url: h.largeImageURL || h.webformatURL,
+          thumbnailUrl: h.previewURL, width: h.imageWidth, height: h.imageHeight,
+          photographer: h.user, description: h.tags || '',
+          attribution: `Image by ${h.user} on Pixabay`,
+        })),
+      },
+    };
+  }
+}

package/test/imageSearch.spec.ts

@@ -0,0 +1,101 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+
+const mockFetch = vi.fn();
+vi.stubGlobal('fetch', mockFetch);
+
+const { ImageSearchTool } = await import('../src/tools/imageSearch.js');
+const { createExtensionPack } = await import('../src/index.js');
+
+describe('ImageSearchTool', () => {
+  let tool: InstanceType<typeof ImageSearchTool>;
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+    tool = new ImageSearchTool({ pexels: 'pexels-key', unsplash: 'unsplash-key', pixabay: 'pixabay-key' });
+  });
+
+  describe('metadata', () => {
+    it('has correct id and name', () => {
+      expect(tool.id).toBe('image-search-v1');
+      expect(tool.name).toBe('image_search');
+    });
+
+    it('has valid input schema', () => {
+      expect(tool.inputSchema.type).toBe('object');
+      expect(tool.inputSchema.required).toContain('query');
+    });
+  });
+
+  describe('execute', () => {
+    const ctx = {} as any;
+
+    it('returns error when no API keys configured', async () => {
+      const noKeyTool = new ImageSearchTool({});
+      const result = await noKeyTool.execute({ query: 'cats' }, ctx);
+      expect(result.success).toBe(false);
+      expect(result.error).toContain('No image API keys');
+    });
+
+    it('auto-selects pexels when available', async () => {
+      mockFetch.mockResolvedValueOnce({
+        ok: true,
+        json: async () => ({
+          total_results: 50,
+          photos: [{ id: 1, src: { large: 'https://pexels.com/1.jpg', medium: 'https://pexels.com/1_m.jpg' }, width: 1920, height: 1080, photographer: 'Test', alt: 'Cat' }],
+        }),
+      });
+
+      const result = await tool.execute({ query: 'cats' }, ctx);
+      expect(result.success).toBe(true);
+      expect(result.output!.provider).toBe('pexels');
+      expect(result.output!.images).toHaveLength(1);
+      expect(mockFetch).toHaveBeenCalledWith(expect.stringContaining('api.pexels.com'), expect.any(Object));
+    });
+
+    it('uses specified provider', async () => {
+      mockFetch.mockResolvedValueOnce({
+        ok: true,
+        json: async () => ({ total: 10, results: [{ id: 'u1', urls: { regular: 'https://unsplash.com/u1.jpg', small: 'https://unsplash.com/u1_s.jpg' }, width: 1920, height: 1080, user: { name: 'Photographer' }, description: 'A cat' }] }),
+      });
+
+      const result = await tool.execute({ query: 'cats', provider: 'unsplash' }, ctx);
+      expect(result.success).toBe(true);
+      expect(result.output!.provider).toBe('unsplash');
+      expect(mockFetch).toHaveBeenCalledWith(expect.stringContaining('api.unsplash.com'), expect.any(Object));
+    });
+
+    it('searches pixabay with clamped per_page', async () => {
+      mockFetch.mockResolvedValueOnce({
+        ok: true,
+        json: async () => ({ totalHits: 20, hits: [{ id: 1, largeImageURL: 'https://pixabay.com/1.jpg', previewURL: 'https://pixabay.com/1_p.jpg', imageWidth: 800, imageHeight: 600, user: 'Test', tags: 'cat' }] }),
+      });
+
+      const result = await tool.execute({ query: 'cats', provider: 'pixabay', limit: 1 }, ctx);
+      expect(result.success).toBe(true);
+      expect(result.output!.provider).toBe('pixabay');
+      // per_page should be clamped to minimum 3
+      expect(mockFetch).toHaveBeenCalledWith(expect.stringContaining('per_page=3'));
+    });
+
+    it('handles API errors', async () => {
+      mockFetch.mockResolvedValueOnce({ ok: false, status: 401 });
+      const result = await tool.execute({ query: 'cats', provider: 'pexels' }, ctx);
+      expect(result.success).toBe(false);
+    });
+
+    it('handles network errors', async () => {
+      mockFetch.mockRejectedValueOnce(new Error('Connection refused'));
+      const result = await tool.execute({ query: 'cats' }, ctx);
+      expect(result.success).toBe(false);
+      expect(result.error).toContain('Connection refused');
+    });
+  });
+});
+
+describe('createExtensionPack', () => {
+  it('creates pack with correct metadata', () => {
+    const pack = createExtensionPack({ options: { pexelsApiKey: 'test' }, logger: { info: vi.fn() } });
+    expect(pack.name).toBe('@framers/agentos-ext-image-search');
+    expect(pack.descriptors).toHaveLength(1);
+  });
+});

package/tsconfig.json

@@ -0,0 +1,22 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "lib": ["ES2022"],
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "noEmitOnError": false,
+    "forceConsistentCasingInFileNames": true,
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "resolveJsonModule": true,
+    "moduleResolution": "Bundler",
+    "types": ["node"]
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist", "test"]
+}

package/vitest.config.ts

@@ -0,0 +1,10 @@
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  test: {
+    globals: true,
+    environment: 'node',
+    include: ['test/**/*.spec.ts'],
+    testTimeout: 10000,
+  },
+});