agentful 0.1.0

package/assets/tools/imagegen.ts

@@ -0,0 +1,360 @@
+import { tool } from "@opencode-ai/plugin"
+import * as fs from "fs"
+import * as path from "path"
+import * as crypto from "crypto"
+
+/**
+ * imagegen — generate a project-owned image asset via the LLM Gateway.
+ *
+ * The gateway (POST /v1/images/generations) owns provider/model resolution,
+ * data-residency enforcement (air claim), key handling and usage tracking.
+ * This tool only validates the output path, calls the gateway with the
+ * session token, writes the bytes into the workspace and reports the
+ * relative path. The workspace file is the source of truth — no base64 in
+ * the tool output, no attachments (keeps WebSocket events and chat
+ * persistence small).
+ */
+
+const GATEWAY_URL = (process.env.LLM_GATEWAY_URL || "").replace(/\/+$/, "")
+const SESSION_TOKEN = process.env.SESSION_TOKEN || ""
+const MAX_PER_SESSION = intEnv("IMAGEGEN_MAX_PER_SESSION", 3)
+const MAX_IMAGE_BYTES = intEnv("IMAGEGEN_MAX_BYTES", 8 * 1024 * 1024)
+const REQUEST_TIMEOUT_MS = intEnv("IMAGEGEN_TIMEOUT_MS", 120_000)
+const MAX_PROMPT_CHARS = 2_000
+
+const ALLOWED_EXTENSIONS: Record<string, string> = {
+  ".png": "image/png",
+  ".webp": "image/webp",
+  ".jpg": "image/jpeg",
+  ".jpeg": "image/jpeg",
+}
+
+const SIZE_BY_ASPECT: Record<string, string> = {
+  "1:1": "1024x1024",
+  "4:3": "1408x1056",
+  "3:2": "1536x1024",
+  "16:9": "1792x1024",
+  "9:16": "1024x1792",
+  "21:9": "2016x864",
+}
+
+function intEnv(name: string, fallback: number): number {
+  const raw = Number(process.env[name])
+  return Number.isFinite(raw) && raw > 0 ? Math.floor(raw) : fallback
+}
+
+function slugify(text: string): string {
+  const slug = text
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .slice(0, 48)
+  return slug || "image"
+}
+
+/**
+ * Resolve and validate the output path. The model-supplied value is
+ * untrusted input: reject anything that is absolute, traverses out of the
+ * workspace, targets hidden/config/tooling paths or a non-image extension.
+ * Symlink escapes are caught by realpath-checking the deepest existing
+ * ancestor before any directory is created.
+ */
+function resolveOutputPath(
+  workspaceRoot: string,
+  requested: string | undefined,
+  defaultRelPath: string,
+  extension: string
+): { absPath: string; relPath: string } {
+  const rel = (requested || defaultRelPath).trim()
+
+  if (!rel) throw new Error("outputPath is empty")
+  if (path.isAbsolute(rel)) {
+    throw new Error(`outputPath must be relative to the project root: ${rel}`)
+  }
+
+  const normalized = path.normalize(rel)
+  const segments = normalized.split(path.sep)
+  if (segments.some((seg) => seg === "..")) {
+    throw new Error(`outputPath must not traverse outside the project: ${rel}`)
+  }
+  if (segments.some((seg) => seg.startsWith("."))) {
+    throw new Error(`outputPath must not target hidden or config paths: ${rel}`)
+  }
+  if (segments.includes("node_modules")) {
+    throw new Error(`outputPath must not target node_modules: ${rel}`)
+  }
+
+  const ext = path.extname(normalized).toLowerCase()
+  if (!(ext in ALLOWED_EXTENSIONS)) {
+    throw new Error(
+      `outputPath must end in ${Object.keys(ALLOWED_EXTENSIONS).join("/")}: ${rel}`
+    )
+  }
+  if (ext !== extension && !(ext === ".jpeg" && extension === ".jpg")) {
+    throw new Error(
+      `outputPath extension ${ext} does not match requested format ${extension}`
+    )
+  }
+
+  const rootResolved = fs.realpathSync(workspaceRoot)
+  const absPath = path.resolve(rootResolved, normalized)
+  if (!absPath.startsWith(rootResolved + path.sep)) {
+    throw new Error(`outputPath resolves outside the project: ${rel}`)
+  }
+
+  // Symlink containment: realpath the deepest existing ancestor and require
+  // it to still be inside the workspace before creating any directories.
+  let ancestor = path.dirname(absPath)
+  while (!fs.existsSync(ancestor)) ancestor = path.dirname(ancestor)
+  const ancestorReal = fs.realpathSync(ancestor)
+  if (
+    ancestorReal !== rootResolved &&
+    !ancestorReal.startsWith(rootResolved + path.sep)
+  ) {
+    throw new Error(`outputPath resolves outside the project: ${rel}`)
+  }
+
+  return { absPath, relPath: path.relative(rootResolved, absPath) }
+}
+
+/**
+ * public/ and static/ are only served from the site root by bundlers
+ * (Vite/Next/Astro/SvelteKit/Nuxt). A vanilla HTML project has no build
+ * step — there public/ is just a folder and must be referenced by its real
+ * relative path (prod finding 2026-07-10: /landscape.png 404'd in a vanilla
+ * project because the hint assumed framework semantics).
+ */
+function isBundlerProject(workspaceRoot: string): boolean {
+  const markers = [
+    "package.json",
+    "vite.config.js", "vite.config.ts", "vite.config.mjs",
+    "astro.config.mjs", "astro.config.ts",
+    "next.config.js", "next.config.ts", "next.config.mjs",
+    "svelte.config.js", "nuxt.config.ts",
+  ]
+  return markers.some((marker) => fs.existsSync(path.join(workspaceRoot, marker)))
+}
+
+function defaultAssetDir(workspaceRoot: string): string {
+  if (isBundlerProject(workspaceRoot)) {
+    if (fs.existsSync(path.join(workspaceRoot, "static"))) return "static/generated"
+    return "public/generated"
+  }
+  return "assets/generated"
+}
+
+function sessionCountFile(sessionID: string): string {
+  const safe = sessionID.replace(/[^a-zA-Z0-9_-]/g, "_")
+  return path.join("/tmp", `imagegen-count-${safe}`)
+}
+
+function readSessionCount(sessionID: string): number {
+  try {
+    return parseInt(fs.readFileSync(sessionCountFile(sessionID), "utf8"), 10) || 0
+  } catch {
+    return 0
+  }
+}
+
+function writeSessionCount(sessionID: string, count: number): void {
+  try {
+    fs.writeFileSync(sessionCountFile(sessionID), String(count))
+  } catch {
+    // Counter is best-effort; generation itself already succeeded.
+  }
+}
+
+export default tool({
+  description:
+    "Generate an image asset (hero, illustration, texture, product mockup) and save it into the project. " +
+    "Returns the saved project path. Vanilla projects must resolve that path relative to the consuming " +
+    "HTML/CSS/JS file; bundler public/static assets get a site-root URL. " +
+    "Do not use for real people, real venues, logos or brand assets.",
+  args: {
+    prompt: tool.schema
+      .string()
+      .describe("Detailed visual description of the image to generate"),
+    outputPath: tool.schema
+      .string()
+      .optional()
+      .describe(
+        "Relative output path inside the project, e.g. public/generated/hero.webp. " +
+          "Extension must match format. Defaults to a generated path."
+      ),
+    purpose: tool.schema
+      .enum(["hero", "card", "background", "icon", "texture", "product", "illustration"])
+      .optional()
+      .describe("What the image is used for (influences default naming)"),
+    aspectRatio: tool.schema
+      .enum(["1:1", "4:3", "3:2", "16:9", "9:16", "21:9"])
+      .optional()
+      .describe("Aspect ratio of the image (default 3:2)"),
+    format: tool.schema
+      .enum(["png", "webp", "jpeg"])
+      .optional()
+      .describe("Output format (default webp; use png for transparency)"),
+    transparent: tool.schema
+      .boolean()
+      .optional()
+      .describe("Request a transparent background (png/webp only)"),
+  },
+  async execute(args, context) {
+    if (!GATEWAY_URL || !SESSION_TOKEN) {
+      throw new Error(
+        "Image generation is not configured for this session (no gateway credentials). " +
+          "Use CSS/SVG placeholders instead."
+      )
+    }
+
+    const prompt = (args.prompt || "").trim()
+    if (!prompt) throw new Error("prompt must not be empty")
+    if (prompt.length > MAX_PROMPT_CHARS) {
+      throw new Error(`prompt too long (${prompt.length} > ${MAX_PROMPT_CHARS} chars)`)
+    }
+
+    const used = readSessionCount(context.sessionID)
+    if (used >= MAX_PER_SESSION) {
+      throw new Error(
+        `Image limit reached for this run (${MAX_PER_SESSION}). ` +
+          "Reuse already generated assets or CSS/SVG placeholders."
+      )
+    }
+
+    const format = args.format || "webp"
+    if (args.transparent && format === "jpeg") {
+      throw new Error("transparent backgrounds require png or webp format")
+    }
+    const extension = format === "jpeg" ? ".jpg" : `.${format}`
+    const size = SIZE_BY_ASPECT[args.aspectRatio || "3:2"]
+
+    const workspaceRoot = context.directory
+    const hash = crypto.createHash("sha1").update(prompt).digest("hex").slice(0, 8)
+    const baseName = slugify(args.purpose ? `${args.purpose}-${prompt}` : prompt)
+    const defaultRelPath = path.join(
+      defaultAssetDir(workspaceRoot),
+      `${baseName}-${hash}${extension}`
+    )
+    const { absPath, relPath } = resolveOutputPath(
+      workspaceRoot,
+      args.outputPath,
+      defaultRelPath,
+      extension
+    )
+
+    const startedAt = Date.now()
+    let response: Response
+    try {
+      response = await fetch(`${GATEWAY_URL}/v1/images/generations`, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          Authorization: `Bearer ${SESSION_TOKEN}`,
+        },
+        body: JSON.stringify({
+          model: process.env.IMAGE_MODEL || "auto",
+          prompt,
+          size,
+          response_format: "b64_json",
+          output_format: format,
+          ...(args.transparent ? { background: "transparent" } : {}),
+        }),
+        signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+      })
+    } catch (error) {
+      throw new Error(`Image generation request failed: ${error}`)
+    }
+
+    if (!response.ok) {
+      let message = `${response.status}`
+      try {
+        const body = (await response.json()) as {
+          error?: { message?: string } | string
+        }
+        const err = body?.error
+        message =
+          typeof err === "string" ? err : err?.message || JSON.stringify(body).slice(0, 300)
+      } catch {
+        // keep status-only message
+      }
+      throw new Error(`Image generation failed: ${message}`)
+    }
+
+    const result = (await response.json()) as {
+      data?: Array<{ b64_json?: string }>
+      model?: string
+      provider?: string
+      mime?: string
+    }
+    const b64 = result.data?.[0]?.b64_json
+    if (!b64) {
+      throw new Error("Image generation returned no image data")
+    }
+
+    const bytes = Buffer.from(b64, "base64")
+    if (bytes.length === 0) {
+      throw new Error("Image generation returned empty image data")
+    }
+    if (bytes.length > MAX_IMAGE_BYTES) {
+      throw new Error(
+        `Generated image too large (${bytes.length} bytes > ${MAX_IMAGE_BYTES})`
+      )
+    }
+
+    // Providers do not always honor the requested format (e.g. Gemini always
+    // returns PNG). The gateway reports the actual mime; keep the file
+    // extension truthful by swapping it within the image-extension allowlist.
+    let finalAbsPath = absPath
+    let finalRelPath = relPath
+    let finalMime = ALLOWED_EXTENSIONS[extension]
+    const reportedMime = result.mime
+    if (reportedMime && reportedMime !== finalMime) {
+      const actualExt = Object.keys(ALLOWED_EXTENSIONS).find(
+        (candidate) => ALLOWED_EXTENSIONS[candidate] === reportedMime && candidate !== ".jpeg"
+      )
+      if (actualExt) {
+        finalAbsPath = absPath.slice(0, -path.extname(absPath).length) + actualExt
+        finalRelPath = relPath.slice(0, -path.extname(relPath).length) + actualExt
+        finalMime = reportedMime
+      }
+    }
+
+    fs.mkdirSync(path.dirname(finalAbsPath), { recursive: true })
+    fs.writeFileSync(finalAbsPath, bytes)
+    writeSessionCount(context.sessionID, used + 1)
+
+    // Bundler projects serve public/ and static/ from the site root. Vanilla
+    // projects are served as-is, so there is no single drop-in URL: CSS URLs
+    // resolve from the stylesheet while HTML URLs resolve from the document.
+    const isBundler = isBundlerProject(workspaceRoot)
+    const publicUrl = isBundler
+      ? finalRelPath.replace(/^(public|static)\//, "/").replace(/^(?!\/)/, "/")
+      : null
+    const durationMs = Date.now() - startedAt
+    const remaining = MAX_PER_SESSION - used - 1
+    const referenceGuidance = isBundler
+      ? `Reference it as ${publicUrl} in the app.`
+      :
+        `This is a project-root path, not a drop-in URL. ` +
+        `From a root HTML document use ./${finalRelPath}; from css/style.css use ../${finalRelPath}. ` +
+        `For any other consuming file, compute the URL relative to that file.`
+
+    return {
+      title: "Generated image",
+      output:
+        `Generated image at ${finalRelPath} (${bytes.length} bytes, ${size}). ` +
+        `${referenceGuidance} ` +
+        `${remaining} image generation(s) left in this run.`,
+      metadata: {
+        path: finalRelPath,
+        projectPath: finalRelPath,
+        publicUrl,
+        mime: finalMime,
+        size,
+        bytes: bytes.length,
+        provider: result.provider,
+        model: result.model,
+        durationMs,
+      },
+    }
+  },
+})

package/assets/tools/node_modules/@opencode-ai/plugin/dist/example.d.ts

@@ -0,0 +1,2 @@
+import { Plugin } from "./index.js";
+export declare const ExamplePlugin: Plugin;

package/assets/tools/node_modules/@opencode-ai/plugin/dist/example.js

@@ -0,0 +1,16 @@
+import { tool } from "./tool.js";
+export const ExamplePlugin = async (ctx) => {
+    return {
+        tool: {
+            mytool: tool({
+                description: "This is a custom tool",
+                args: {
+                    foo: tool.schema.string().describe("foo"),
+                },
+                async execute(args) {
+                    return `Hello ${args.foo}!`;
+                },
+            }),
+        },
+    };
+};

package/assets/tools/node_modules/@opencode-ai/plugin/dist/index.d.ts

@@ -0,0 +1,267 @@
+import type { Event, createOpencodeClient, Project, Model, Provider, Permission, UserMessage, Message, Part, Auth, Config as SDKConfig } from "@opencode-ai/sdk";
+import type { Provider as ProviderV2, Model as ModelV2 } from "@opencode-ai/sdk/v2";
+import type { BunShell } from "./shell.js";
+import { type ToolDefinition } from "./tool.js";
+export * from "./tool.js";
+export type ProviderContext = {
+    source: "env" | "config" | "custom" | "api";
+    info: Provider;
+    options: Record<string, any>;
+};
+export type PluginInput = {
+    client: ReturnType<typeof createOpencodeClient>;
+    project: Project;
+    directory: string;
+    worktree: string;
+    serverUrl: URL;
+    $: BunShell;
+};
+export type PluginOptions = Record<string, unknown>;
+export type Config = Omit<SDKConfig, "plugin"> & {
+    plugin?: Array<string | [string, PluginOptions]>;
+};
+export type Plugin = (input: PluginInput, options?: PluginOptions) => Promise<Hooks>;
+export type PluginModule = {
+    id?: string;
+    server: Plugin;
+    tui?: never;
+};
+type Rule = {
+    key: string;
+    op: "eq" | "neq";
+    value: string;
+};
+export type AuthHook = {
+    provider: string;
+    loader?: (auth: () => Promise<Auth>, provider: Provider) => Promise<Record<string, any>>;
+    methods: ({
+        type: "oauth";
+        label: string;
+        prompts?: Array<{
+            type: "text";
+            key: string;
+            message: string;
+            placeholder?: string;
+            validate?: (value: string) => string | undefined;
+            /** @deprecated Use `when` instead */
+            condition?: (inputs: Record<string, string>) => boolean;
+            when?: Rule;
+        } | {
+            type: "select";
+            key: string;
+            message: string;
+            options: Array<{
+                label: string;
+                value: string;
+                hint?: string;
+            }>;
+            /** @deprecated Use `when` instead */
+            condition?: (inputs: Record<string, string>) => boolean;
+            when?: Rule;
+        }>;
+        authorize(inputs?: Record<string, string>): Promise<AuthOAuthResult>;
+    } | {
+        type: "api";
+        label: string;
+        prompts?: Array<{
+            type: "text";
+            key: string;
+            message: string;
+            placeholder?: string;
+            validate?: (value: string) => string | undefined;
+            /** @deprecated Use `when` instead */
+            condition?: (inputs: Record<string, string>) => boolean;
+            when?: Rule;
+        } | {
+            type: "select";
+            key: string;
+            message: string;
+            options: Array<{
+                label: string;
+                value: string;
+                hint?: string;
+            }>;
+            /** @deprecated Use `when` instead */
+            condition?: (inputs: Record<string, string>) => boolean;
+            when?: Rule;
+        }>;
+        authorize?(inputs?: Record<string, string>): Promise<{
+            type: "success";
+            key: string;
+            provider?: string;
+        } | {
+            type: "failed";
+        }>;
+    })[];
+};
+export type AuthOAuthResult = {
+    url: string;
+    instructions: string;
+} & ({
+    method: "auto";
+    callback(): Promise<({
+        type: "success";
+        provider?: string;
+    } & ({
+        refresh: string;
+        access: string;
+        expires: number;
+        accountId?: string;
+        enterpriseUrl?: string;
+    } | {
+        key: string;
+    })) | {
+        type: "failed";
+    }>;
+} | {
+    method: "code";
+    callback(code: string): Promise<({
+        type: "success";
+        provider?: string;
+    } & ({
+        refresh: string;
+        access: string;
+        expires: number;
+        accountId?: string;
+        enterpriseUrl?: string;
+    } | {
+        key: string;
+    })) | {
+        type: "failed";
+    }>;
+});
+export type ProviderHookContext = {
+    auth?: Auth;
+};
+export type ProviderHook = {
+    id: string;
+    models?: (provider: ProviderV2, ctx: ProviderHookContext) => Promise<Record<string, ModelV2>>;
+};
+/** @deprecated Use AuthOAuthResult instead. */
+export type AuthOuathResult = AuthOAuthResult;
+export interface Hooks {
+    event?: (input: {
+        event: Event;
+    }) => Promise<void>;
+    config?: (input: Config) => Promise<void>;
+    tool?: {
+        [key: string]: ToolDefinition;
+    };
+    auth?: AuthHook;
+    provider?: ProviderHook;
+    /**
+     * Called when a new message is received
+     */
+    "chat.message"?: (input: {
+        sessionID: string;
+        agent?: string;
+        model?: {
+            providerID: string;
+            modelID: string;
+        };
+        messageID?: string;
+        variant?: string;
+    }, output: {
+        message: UserMessage;
+        parts: Part[];
+    }) => Promise<void>;
+    /**
+     * Modify parameters sent to LLM
+     */
+    "chat.params"?: (input: {
+        sessionID: string;
+        agent: string;
+        model: Model;
+        provider: ProviderContext;
+        message: UserMessage;
+    }, output: {
+        temperature: number;
+        topP: number;
+        topK: number;
+        options: Record<string, any>;
+    }) => Promise<void>;
+    "chat.headers"?: (input: {
+        sessionID: string;
+        agent: string;
+        model: Model;
+        provider: ProviderContext;
+        message: UserMessage;
+    }, output: {
+        headers: Record<string, string>;
+    }) => Promise<void>;
+    "permission.ask"?: (input: Permission, output: {
+        status: "ask" | "deny" | "allow";
+    }) => Promise<void>;
+    "command.execute.before"?: (input: {
+        command: string;
+        sessionID: string;
+        arguments: string;
+    }, output: {
+        parts: Part[];
+    }) => Promise<void>;
+    "tool.execute.before"?: (input: {
+        tool: string;
+        sessionID: string;
+        callID: string;
+    }, output: {
+        args: any;
+    }) => Promise<void>;
+    "shell.env"?: (input: {
+        cwd: string;
+        sessionID?: string;
+        callID?: string;
+    }, output: {
+        env: Record<string, string>;
+    }) => Promise<void>;
+    "tool.execute.after"?: (input: {
+        tool: string;
+        sessionID: string;
+        callID: string;
+        args: any;
+    }, output: {
+        title: string;
+        output: string;
+        metadata: any;
+    }) => Promise<void>;
+    "experimental.chat.messages.transform"?: (input: {}, output: {
+        messages: {
+            info: Message;
+            parts: Part[];
+        }[];
+    }) => Promise<void>;
+    "experimental.chat.system.transform"?: (input: {
+        sessionID?: string;
+        model: Model;
+    }, output: {
+        system: string[];
+    }) => Promise<void>;
+    /**
+     * Called before session compaction starts. Allows plugins to customize
+     * the compaction prompt.
+     *
+     * - `context`: Additional context strings appended to the default prompt
+     * - `prompt`: If set, replaces the default compaction prompt entirely
+     */
+    "experimental.session.compacting"?: (input: {
+        sessionID: string;
+    }, output: {
+        context: string[];
+        prompt?: string;
+    }) => Promise<void>;
+    "experimental.text.complete"?: (input: {
+        sessionID: string;
+        messageID: string;
+        partID: string;
+    }, output: {
+        text: string;
+    }) => Promise<void>;
+    /**
+     * Modify tool definitions (description and parameters) sent to LLM
+     */
+    "tool.definition"?: (input: {
+        toolID: string;
+    }, output: {
+        description: string;
+        parameters: any;
+    }) => Promise<void>;
+}

package/assets/tools/node_modules/@opencode-ai/plugin/dist/index.js

@@ -0,0 +1 @@
+export * from "./tool.js";