@suknna/pixelforge 0.1.0

package/dist/errors.js

@@ -0,0 +1,75 @@
+export class PixelForgeError extends Error {
+    category;
+    retryable;
+    statusCode;
+    provider;
+    constructor(input) {
+        super(input.message);
+        this.name = "PixelForgeError";
+        this.category = input.category;
+        this.retryable = input.retryable;
+        if (input.statusCode !== undefined)
+            this.statusCode = input.statusCode;
+        if (input.provider !== undefined)
+            this.provider = input.provider;
+    }
+}
+export function classifyHttpStatus(statusCode, provider) {
+    if (statusCode === 429) {
+        return new PixelForgeError(withProvider({
+            category: "rate-limit",
+            message: "Provider rate limit exceeded.",
+            retryable: true,
+            statusCode,
+        }, provider));
+    }
+    if (statusCode >= 500) {
+        return new PixelForgeError(withProvider({
+            category: "server",
+            message: "Provider server error.",
+            retryable: true,
+            statusCode,
+        }, provider));
+    }
+    if (statusCode === 401 || statusCode === 403) {
+        return new PixelForgeError(withProvider({
+            category: "auth",
+            message: "Provider authentication or authorization failed.",
+            retryable: false,
+            statusCode,
+        }, provider));
+    }
+    return new PixelForgeError(withProvider({
+        category: "bad-request",
+        message: "Provider rejected the request.",
+        retryable: false,
+        statusCode,
+    }, provider));
+}
+export function networkError(message, provider) {
+    return new PixelForgeError(withProvider({ category: "network", message, retryable: true }, provider));
+}
+export function timeoutError(provider) {
+    return new PixelForgeError(withProvider({ category: "timeout", message: "Provider request timed out.", retryable: true }, provider));
+}
+export function moderationError(message, provider) {
+    return new PixelForgeError(withProvider({ category: "moderation", message, retryable: false }, provider));
+}
+export function configurationError(message) {
+    return new PixelForgeError({ category: "configuration", message, retryable: false });
+}
+export function filesystemError(message) {
+    return new PixelForgeError({ category: "filesystem", message, retryable: false });
+}
+export function toPixelForgeError(error, provider) {
+    if (error instanceof PixelForgeError)
+        return error;
+    if (error instanceof DOMException && error.name === "AbortError")
+        return timeoutError(provider);
+    if (error instanceof Error)
+        return networkError(error.message, provider);
+    return networkError("Unknown provider failure.", provider);
+}
+function withProvider(input, provider) {
+    return provider === undefined ? input : { ...input, provider };
+}

package/dist/image-input.d.ts

@@ -0,0 +1,9 @@
+export type LoadedImage = {
+    bytes: Uint8Array;
+    mimeType: string;
+    fileName: string;
+};
+export declare function loadLocalImage(filePath: string): Promise<LoadedImage>;
+export declare function toDataUri(image: LoadedImage): string;
+export declare function mimeTypeFromPath(filePath: string): string;
+export declare function blobFromImage(image: LoadedImage): Blob;

package/dist/image-input.js

@@ -0,0 +1,28 @@
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import { filesystemError } from "./errors.js";
+export async function loadLocalImage(filePath) {
+    const mimeType = mimeTypeFromPath(filePath);
+    const bytes = await readFile(filePath).catch((error) => {
+        throw filesystemError(`Cannot read base image: ${error instanceof Error ? error.message : String(error)}`);
+    });
+    return { bytes, mimeType, fileName: path.basename(filePath) };
+}
+export function toDataUri(image) {
+    return `data:${image.mimeType};base64,${Buffer.from(image.bytes).toString("base64")}`;
+}
+export function mimeTypeFromPath(filePath) {
+    const extension = path.extname(filePath).toLowerCase();
+    if (extension === ".png")
+        return "image/png";
+    if (extension === ".jpg" || extension === ".jpeg")
+        return "image/jpeg";
+    if (extension === ".webp")
+        return "image/webp";
+    throw filesystemError("Base image must be a PNG, JPEG, or WebP file.");
+}
+export function blobFromImage(image) {
+    const arrayBuffer = new ArrayBuffer(image.bytes.byteLength);
+    new Uint8Array(arrayBuffer).set(image.bytes);
+    return new Blob([arrayBuffer], { type: image.mimeType });
+}

package/dist/index.d.ts

@@ -0,0 +1,11 @@
+import type { Plugin } from "@opencode-ai/plugin";
+/**
+ * PixelForge opencode plugin entry point.
+ *
+ * On startup it loads and validates `~/.config/opencode/pixelforge.json`,
+ * creates a process-local job registry, and registers the three image
+ * generation tools. Config validation failures surface here so a misconfigured
+ * plugin fails fast at load time rather than at first tool call.
+ */
+export declare const PixelForgePlugin: Plugin;
+export default PixelForgePlugin;

package/dist/index.js

@@ -0,0 +1,42 @@
+import { loadPixelForgeConfig } from "./config.js";
+import { JobRegistry } from "./jobs.js";
+import { createPixelForgeTools } from "./tools.js";
+/**
+ * PixelForge opencode plugin entry point.
+ *
+ * On startup it loads and validates `~/.config/opencode/pixelforge.json`,
+ * creates a process-local job registry, and registers the three image
+ * generation tools. Config validation failures surface here so a misconfigured
+ * plugin fails fast at load time rather than at first tool call.
+ */
+export const PixelForgePlugin = async ({ client }) => {
+    const config = await loadPixelForgeConfig();
+    const jobs = new JobRegistry();
+    // Adapt the opencode SDK client to PixelForge's minimal NotificationClient
+    // boundary. Keeping this translation here means the runner and notifier never
+    // depend on the full SDK surface — only on the two calls they actually use.
+    const notificationClient = {
+        tui: {
+            async showToast(input) {
+                await client.tui.showToast({
+                    body: { title: input.title, message: input.message, variant: "success" },
+                });
+            },
+        },
+        session: {
+            async prompt(input) {
+                await client.session.prompt({
+                    path: { id: input.sessionID },
+                    body: {
+                        noReply: input.noReply ?? false,
+                        parts: [{ type: "text", text: input.message }],
+                    },
+                });
+            },
+        },
+    };
+    return {
+        tool: createPixelForgeTools({ config, jobs, client: notificationClient }),
+    };
+};
+export default PixelForgePlugin;

package/dist/jobs.d.ts

@@ -0,0 +1,28 @@
+import type { ImageJob, JobKind, ProviderError, ProviderName, PublicJobStatus } from "./types.js";
+/**
+ * In-memory registry of background image generation jobs.
+ *
+ * The registry is the single source of truth for job state. It deliberately
+ * exposes a model-safe projection (`publicStatus`) that never leaks the
+ * internal `profile` name — models only ever learn the resolved `provider`.
+ */
+export declare class JobRegistry {
+    private readonly jobs;
+    create(input: {
+        kind: JobKind;
+        prompt: string;
+        outputPath: string;
+        baseImagePath?: string;
+    }): ImageJob;
+    get(jobId: string): ImageJob | undefined;
+    startAttempt(jobId: string, provider: ProviderName): void;
+    failAttempt(jobId: string, error: ProviderError): void;
+    succeed(jobId: string, input: {
+        provider: ProviderName;
+        mimeType: string;
+        byteLength: number;
+    }): void;
+    fail(jobId: string, error: ProviderError): void;
+    publicStatus(jobId: string): PublicJobStatus | undefined;
+    private require;
+}

package/dist/jobs.js

@@ -0,0 +1,107 @@
+import { randomUUID } from "node:crypto";
+/**
+ * In-memory registry of background image generation jobs.
+ *
+ * The registry is the single source of truth for job state. It deliberately
+ * exposes a model-safe projection (`publicStatus`) that never leaks the
+ * internal `profile` name — models only ever learn the resolved `provider`.
+ */
+export class JobRegistry {
+    jobs = new Map();
+    create(input) {
+        const now = new Date().toISOString();
+        const job = {
+            id: `pf_${randomUUID()}`,
+            kind: input.kind,
+            status: "queued",
+            prompt: input.prompt,
+            outputPath: input.outputPath,
+            // exactOptionalPropertyTypes: only set baseImagePath when actually provided.
+            ...(input.baseImagePath !== undefined ? { baseImagePath: input.baseImagePath } : {}),
+            attempts: [],
+            createdAt: now,
+            updatedAt: now,
+        };
+        this.jobs.set(job.id, job);
+        return job;
+    }
+    get(jobId) {
+        return this.jobs.get(jobId);
+    }
+    startAttempt(jobId, provider) {
+        const job = this.require(jobId);
+        job.status = "running";
+        job.provider = provider;
+        job.updatedAt = new Date().toISOString();
+        job.attempts.push({ provider, startedAt: job.updatedAt });
+    }
+    failAttempt(jobId, error) {
+        const job = this.require(jobId);
+        const attempt = job.attempts.at(-1);
+        if (attempt) {
+            attempt.finishedAt = new Date().toISOString();
+            attempt.error = error;
+        }
+        job.error = error;
+        job.updatedAt = new Date().toISOString();
+    }
+    succeed(jobId, input) {
+        const job = this.require(jobId);
+        const now = new Date().toISOString();
+        const attempt = job.attempts.at(-1);
+        if (attempt)
+            attempt.finishedAt = now;
+        job.status = "succeeded";
+        job.provider = input.provider;
+        job.mimeType = input.mimeType;
+        job.byteLength = input.byteLength;
+        job.updatedAt = now;
+        job.completedAt = now;
+    }
+    fail(jobId, error) {
+        const job = this.require(jobId);
+        const now = new Date().toISOString();
+        const attempt = job.attempts.at(-1);
+        if (attempt && !attempt.finishedAt) {
+            attempt.finishedAt = now;
+            attempt.error = error;
+        }
+        job.status = "failed";
+        job.error = error;
+        job.updatedAt = now;
+        job.completedAt = now;
+    }
+    publicStatus(jobId) {
+        const job = this.jobs.get(jobId);
+        if (!job)
+            return undefined;
+        return {
+            jobId: job.id,
+            status: job.status,
+            outputPath: job.outputPath,
+            ...(job.baseImagePath !== undefined ? { baseImagePath: job.baseImagePath } : {}),
+            ...(job.provider !== undefined ? { provider: job.provider } : {}),
+            ...(job.mimeType !== undefined ? { mimeType: job.mimeType } : {}),
+            ...(job.byteLength !== undefined ? { byteLength: job.byteLength } : {}),
+            ...(job.error !== undefined
+                ? {
+                    error: {
+                        category: job.error.category,
+                        message: job.error.message,
+                        retryable: job.error.retryable,
+                        ...(job.error.statusCode !== undefined ? { statusCode: job.error.statusCode } : {}),
+                    },
+                }
+                : {}),
+            createdAt: job.createdAt,
+            updatedAt: job.updatedAt,
+            ...(job.completedAt !== undefined ? { completedAt: job.completedAt } : {}),
+        };
+    }
+    require(jobId) {
+        const job = this.jobs.get(jobId);
+        if (!job)
+            throw new Error(`Unknown PixelForge job '${jobId}'.`);
+        return job;
+    }
+}

package/dist/notifications.d.ts

@@ -0,0 +1,30 @@
+import type { PublicJobStatus } from "./types.js";
+/**
+ * Minimal structural view of the opencode plugin client that PixelForge needs.
+ *
+ * Both members are optional: in tests and in headless `opencode serve` there
+ * may be no TUI to toast and no session to prompt. Notifications are best-effort
+ * enhancements — the reliable result channel is the check-job tool.
+ */
+export type NotificationClient = {
+    tui?: {
+        showToast?: (input: {
+            title: string;
+            message: string;
+        }) => Promise<void> | void;
+    };
+    session?: {
+        prompt?: (input: {
+            sessionID: string;
+            message: string;
+            noReply?: boolean;
+        }) => Promise<void> | void;
+    };
+};
+export declare function notifyJobCompleted(input: {
+    client: NotificationClient;
+    sessionID?: string;
+    status: PublicJobStatus;
+    tui: boolean;
+    sessionMessage: boolean;
+}): Promise<void>;

package/dist/notifications.js

@@ -0,0 +1,15 @@
+export async function notifyJobCompleted(input) {
+    if (input.tui && input.client.tui?.showToast) {
+        await input.client.tui.showToast({
+            title: "PixelForge image ready",
+            message: `${input.status.provider ?? "unknown provider"} wrote ${input.status.outputPath}`,
+        });
+    }
+    if (input.sessionMessage && input.sessionID && input.client.session?.prompt) {
+        await input.client.session.prompt({
+            sessionID: input.sessionID,
+            noReply: true,
+            message: `PixelForge image job ${input.status.jobId} ${input.status.status}: ${input.status.outputPath}`,
+        });
+    }
+}

package/dist/path-safety.d.ts

@@ -0,0 +1,3 @@
+export declare function resolveWorkspacePath(inputPath: string, directory: string, worktree?: string): string;
+export declare function assertCanWriteOutput(filePath: string, overwrite: boolean): Promise<void>;
+export declare function writeFileAtomic(filePath: string, bytes: Uint8Array): Promise<number>;

package/dist/path-safety.js

@@ -0,0 +1,26 @@
+import { mkdir, rename, stat, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { filesystemError } from "./errors.js";
+export function resolveWorkspacePath(inputPath, directory, worktree) {
+    if (!inputPath || inputPath.includes("\0"))
+        throw filesystemError("Path must be a non-empty file path.");
+    const root = path.resolve(worktree || directory);
+    const resolved = path.isAbsolute(inputPath) ? path.resolve(inputPath) : path.resolve(directory, inputPath);
+    const relative = path.relative(root, resolved);
+    if (relative.startsWith("..") || path.isAbsolute(relative)) {
+        throw filesystemError("Path must stay inside the current workspace.");
+    }
+    return resolved;
+}
+export async function assertCanWriteOutput(filePath, overwrite) {
+    const existing = await stat(filePath).catch(() => undefined);
+    if (existing && !overwrite)
+        throw filesystemError("Output file already exists and overwrite is false.");
+}
+export async function writeFileAtomic(filePath, bytes) {
+    await mkdir(path.dirname(filePath), { recursive: true });
+    const tempPath = `${filePath}.pixelforge-${process.pid}-${Date.now()}.tmp`;
+    await writeFile(tempPath, bytes);
+    await rename(tempPath, filePath);
+    return bytes.byteLength;
+}

package/dist/runner.d.ts

@@ -0,0 +1,16 @@
+import { JobRegistry } from "./jobs.js";
+import { type NotificationClient } from "./notifications.js";
+import type { ImageJob, PixelForgeConfig } from "./types.js";
+/**
+ * Everything a background job needs to execute: validated config, the shared
+ * job registry, and the notification client. `sessionID` is optional because
+ * not every invocation path has an active session to message.
+ */
+export type RunnerContext = {
+    config: PixelForgeConfig;
+    jobs: JobRegistry;
+    client: NotificationClient;
+    sessionID?: string;
+};
+export declare function startTextToImageJob(context: RunnerContext, job: ImageJob, overwrite: boolean): void;
+export declare function startImageToImageJob(context: RunnerContext, job: ImageJob, overwrite: boolean, strength?: number): void;

package/dist/runner.js

@@ -0,0 +1,88 @@
+import { createAdapter } from "./adapters/index.js";
+import { PixelForgeError, toPixelForgeError } from "./errors.js";
+import { notifyJobCompleted } from "./notifications.js";
+import { assertCanWriteOutput, writeFileAtomic } from "./path-safety.js";
+export function startTextToImageJob(context, job, overwrite) {
+    void runJob(context, job, overwrite, async (adapter, signal) => adapter.generateImage({ prompt: job.prompt, signal }));
+}
+export function startImageToImageJob(context, job, overwrite, strength) {
+    void runJob(context, job, overwrite, async (adapter, signal) => {
+        if (!job.baseImagePath)
+            throw new Error("Image-to-image job is missing baseImagePath.");
+        return adapter.generateImageFromImage({
+            baseImagePath: job.baseImagePath,
+            prompt: job.prompt,
+            ...(strength !== undefined ? { strength } : {}),
+            signal,
+        });
+    });
+}
+/**
+ * Core background execution loop.
+ *
+ * Tries the default profile first, then each explicit fallback in order. Only
+ * retryable errors (network/timeout/429/5xx) advance to the next profile; every
+ * other failure is fail-closed and stops the job immediately. Output is written
+ * atomically before the job is marked succeeded, so a visible file always means
+ * a completed job.
+ */
+async function runJob(context, job, overwrite, execute) {
+    try {
+        await assertCanWriteOutput(job.outputPath, overwrite);
+        const profileNames = orderedProfiles(context.config);
+        let lastError;
+        for (const profileName of profileNames) {
+            const profile = context.config.profiles[profileName];
+            if (!profile)
+                continue;
+            const adapter = createAdapter(profile);
+            const controller = new AbortController();
+            const timeout = setTimeout(() => controller.abort(), profile.timeoutMs);
+            context.jobs.startAttempt(job.id, profile.provider);
+            try {
+                const result = await execute(adapter, controller.signal);
+                clearTimeout(timeout);
+                const byteLength = await writeFileAtomic(job.outputPath, result.bytes);
+                context.jobs.succeed(job.id, {
+                    provider: result.provider,
+                    mimeType: result.mimeType,
+                    byteLength,
+                });
+                const status = context.jobs.publicStatus(job.id);
+                if (status) {
+                    await notifyJobCompleted({
+                        client: context.client,
+                        ...(context.sessionID !== undefined ? { sessionID: context.sessionID } : {}),
+                        status,
+                        tui: context.config.notifications.tui,
+                        sessionMessage: context.config.notifications.sessionMessage,
+                    });
+                }
+                return;
+            }
+            catch (error) {
+                clearTimeout(timeout);
+                const classified = toPixelForgeError(error, profile.provider);
+                lastError = classified;
+                context.jobs.failAttempt(job.id, classified);
+                if (!classified.retryable) {
+                    context.jobs.fail(job.id, classified);
+                    return;
+                }
+            }
+        }
+        context.jobs.fail(job.id, lastError ??
+            new PixelForgeError({
+                category: "provider",
+                message: "No provider profiles were available.",
+                retryable: false,
+            }));
+    }
+    catch (error) {
+        context.jobs.fail(job.id, toPixelForgeError(error));
+    }
+}
+/** Default profile first, then explicit fallbacks, de-duplicated, order preserved. */
+function orderedProfiles(config) {
+    return [...new Set([config.defaultProfile, ...config.fallbackProfiles])];
+}

package/dist/tools.d.ts

@@ -0,0 +1,49 @@
+import { type RunnerContext } from "./runner.js";
+/**
+ * Builds the three opencode tools backed by a shared runner context.
+ *
+ * The model-facing surface never mentions the internal `profile` concept: the
+ * only provider value returned is the resolved default provider name, which is
+ * informational. Provider/fallback selection stays entirely inside config.
+ */
+export declare function createPixelForgeTools(context: RunnerContext): {
+    pixelforge_generate_image: {
+        description: string;
+        args: {
+            prompt: import("zod").ZodString;
+            outputPath: import("zod").ZodString;
+            overwrite: import("zod").ZodBoolean;
+        };
+        execute(args: {
+            prompt: string;
+            outputPath: string;
+            overwrite: boolean;
+        }, context: import("@opencode-ai/plugin").ToolContext): Promise<import("@opencode-ai/plugin").ToolResult>;
+    };
+    pixelforge_generate_image_from_image: {
+        description: string;
+        args: {
+            baseImagePath: import("zod").ZodString;
+            prompt: import("zod").ZodString;
+            outputPath: import("zod").ZodString;
+            strength: import("zod").ZodOptional<import("zod").ZodNumber>;
+            overwrite: import("zod").ZodBoolean;
+        };
+        execute(args: {
+            baseImagePath: string;
+            prompt: string;
+            outputPath: string;
+            overwrite: boolean;
+            strength?: number | undefined;
+        }, context: import("@opencode-ai/plugin").ToolContext): Promise<import("@opencode-ai/plugin").ToolResult>;
+    };
+    pixelforge_check_image_job: {
+        description: string;
+        args: {
+            jobId: import("zod").ZodString;
+        };
+        execute(args: {
+            jobId: string;
+        }, context: import("@opencode-ai/plugin").ToolContext): Promise<import("@opencode-ai/plugin").ToolResult>;
+    };
+};

package/dist/tools.js

@@ -0,0 +1,112 @@
+import { tool } from "@opencode-ai/plugin";
+import { resolveWorkspacePath } from "./path-safety.js";
+import { startImageToImageJob, startTextToImageJob } from "./runner.js";
+const GENERATE_IMAGE_DESCRIPTION = "Generate an image from a text prompt and write it to a requested file path in the current workspace. Provide a complete visual prompt and an explicit output path. This tool starts image generation in the background and returns a jobId immediately; the image file may not exist yet when the tool returns.";
+const GENERATE_IMAGE_FROM_IMAGE_DESCRIPTION = "Generate a new image from an existing base image and a text prompt, then write the result to a requested file path in the current workspace. Provide the base image path, a complete visual prompt describing the desired generated result, and an explicit output path. This tool starts image generation in the background and returns a jobId immediately; the output image file may not exist yet when the tool returns.";
+const CHECK_IMAGE_JOB_DESCRIPTION = "Check the status of a PixelForge image generation job by jobId. The response reports queued, running, succeeded, or failed. When the status is succeeded, the response includes the final file path, MIME type, byte size, elapsed time, and the provider that produced the image. When the status is failed, the response includes the explicit error reason. This tool only reports job state.";
+const STARTED_MESSAGE = "Image generation started in the background. Use pixelforge_check_image_job with this jobId to inspect completion.";
+/**
+ * Builds the three opencode tools backed by a shared runner context.
+ *
+ * The model-facing surface never mentions the internal `profile` concept: the
+ * only provider value returned is the resolved default provider name, which is
+ * informational. Provider/fallback selection stays entirely inside config.
+ */
+export function createPixelForgeTools(context) {
+    const defaultProvider = resolveDefaultProvider(context);
+    return {
+        pixelforge_generate_image: tool({
+            description: GENERATE_IMAGE_DESCRIPTION,
+            args: {
+                prompt: tool.schema.string().min(1).describe("Detailed text prompt describing the image to generate."),
+                outputPath: tool.schema
+                    .string()
+                    .min(1)
+                    .describe("File path where the generated image should be written. Relative paths are resolved from the current session directory."),
+                overwrite: tool.schema.boolean().describe("Whether to overwrite the output file if it already exists."),
+            },
+            async execute(args, opencodeContext) {
+                const outputPath = resolveWorkspacePath(args.outputPath, opencodeContext.directory, opencodeContext.worktree);
+                const job = context.jobs.create({ kind: "text-to-image", prompt: args.prompt, outputPath });
+                startTextToImageJob({ ...context, sessionID: opencodeContext.sessionID }, job, args.overwrite);
+                return JSON.stringify({
+                    jobId: job.id,
+                    status: "queued",
+                    outputPath: args.outputPath,
+                    provider: defaultProvider,
+                    message: STARTED_MESSAGE,
+                });
+            },
+        }),
+        pixelforge_generate_image_from_image: tool({
+            description: GENERATE_IMAGE_FROM_IMAGE_DESCRIPTION,
+            args: {
+                baseImagePath: tool.schema
+                    .string()
+                    .min(1)
+                    .describe("Path to the local base image to use as visual input. Relative paths are resolved from the current session directory."),
+                prompt: tool.schema
+                    .string()
+                    .min(1)
+                    .describe("Detailed text prompt describing how to generate the new image from the base image."),
+                outputPath: tool.schema
+                    .string()
+                    .min(1)
+                    .describe("File path where the generated image should be written. Relative paths are resolved from the current session directory."),
+                strength: tool.schema
+                    .number()
+                    .min(0)
+                    .max(1)
+                    .optional()
+                    .describe("How strongly the generated result may diverge from the base image, from 0 to 1."),
+                overwrite: tool.schema.boolean().describe("Whether to overwrite the output file if it already exists."),
+            },
+            async execute(args, opencodeContext) {
+                const baseImagePath = resolveWorkspacePath(args.baseImagePath, opencodeContext.directory, opencodeContext.worktree);
+                const outputPath = resolveWorkspacePath(args.outputPath, opencodeContext.directory, opencodeContext.worktree);
+                const job = context.jobs.create({
+                    kind: "image-to-image",
+                    prompt: args.prompt,
+                    baseImagePath,
+                    outputPath,
+                });
+                startImageToImageJob({ ...context, sessionID: opencodeContext.sessionID }, job, args.overwrite, args.strength);
+                return JSON.stringify({
+                    jobId: job.id,
+                    status: "queued",
+                    baseImagePath: args.baseImagePath,
+                    outputPath: args.outputPath,
+                    provider: defaultProvider,
+                    message: STARTED_MESSAGE,
+                });
+            },
+        }),
+        pixelforge_check_image_job: tool({
+            description: CHECK_IMAGE_JOB_DESCRIPTION,
+            args: {
+                jobId: tool.schema
+                    .string()
+                    .min(1)
+                    .describe("PixelForge image generation job ID returned by a generation tool."),
+            },
+            async execute(args) {
+                const status = context.jobs.publicStatus(args.jobId);
+                if (!status) {
+                    return JSON.stringify({
+                        jobId: args.jobId,
+                        status: "failed",
+                        error: { category: "configuration", message: "Unknown PixelForge job ID.", retryable: false },
+                    });
+                }
+                return JSON.stringify(status);
+            },
+        }),
+    };
+}
+/** Resolves the default profile's provider name for informational tool output. */
+function resolveDefaultProvider(context) {
+    const profile = context.config.profiles[context.config.defaultProfile];
+    if (!profile)
+        throw new Error(`Default profile '${context.config.defaultProfile}' is missing from resolved config.`);
+    return profile.provider;
+}