open-multi-agent-kit 0.78.0

package/dist/memory/ontology-model.js

@@ -0,0 +1,131 @@
+/**
+ * Ontology model for OMK project memory.
+ *
+ * Defines core node types, relationship types, project-isolation fields,
+ * and schema helpers used across all graph-backed memory stores.
+ */
+export const ONTOLOGY_SCHEMA_VERSION = 1;
+export const ONTOLOGY_NODE_TYPES = [
+    "Project",
+    "Session",
+    "Run",
+    "Goal",
+    "Criterion",
+    "Evidence",
+    "Decision",
+    "Task",
+    "Risk",
+    "Constraint",
+    "File",
+    "Symbol",
+    "Test",
+    "Command",
+    "Commit",
+    "MCPServer",
+    "Skill",
+    "Provider",
+    "ProviderRoute",
+    "ProviderFallback",
+    "AuditLink",
+];
+export const ONTOLOGY_RELATIONSHIP_TYPES = [
+    "HAS_GOAL",
+    "HAS_RUN",
+    "HAS_CRITERION",
+    "HAS_EVIDENCE",
+    "HAS_DECISION",
+    "HAS_TASK",
+    "DEPENDS_ON",
+    "HAS_RISK",
+    "HAS_FILE",
+    "HAS_SYMBOL",
+    "HAS_TEST",
+    "HAS_COMMAND",
+    "HAS_COMMIT",
+    "USES_MCP",
+    "USES_SKILL",
+    "USES_PROVIDER",
+    "HAS_PROVIDER_ROUTE",
+    "ROUTES_TO",
+    "FALLS_BACK_TO",
+    "HAS_PROVIDER_FALLBACK",
+    "HAS_AUDIT_LINK",
+    "LINKS_TO",
+];
+/**
+ * Create unique constraints for every ontology node type.
+ * Each constraint enforces uniqueness on `(projectId, id)` for the label.
+ */
+export async function createOntologyConstraints(executor, database) {
+    const options = database ? { database } : undefined;
+    for (const nodeType of ONTOLOGY_NODE_TYPES) {
+        const label = `Omk${nodeType}`;
+        const constraintName = `omk_${nodeType.toLowerCase()}_project_id_unique`;
+        await executor.executeQuery(`CREATE CONSTRAINT ${constraintName} IF NOT EXISTS FOR (n:${label}) REQUIRE (n.projectId, n.id) IS UNIQUE`, {}, options);
+    }
+}
+/** Build Kuzu CREATE NODE TABLE / CREATE REL TABLE DDLs from the ontology model. */
+export function buildKuzuOntologySchema() {
+    const baseProps = "id STRING PRIMARY KEY, projectId STRING, workspaceRootHash STRING, schemaVersion INT64, createdAt STRING, updatedAt STRING";
+    const nodeTables = [
+        `CREATE NODE TABLE OmkGoal (${baseProps}, goalId STRING, title STRING, objective STRING, status STRING, riskLevel STRING)`,
+        `CREATE NODE TABLE OmkCriterion (${baseProps}, criterionId STRING, description STRING, requirement STRING, weight INT64)`,
+        `CREATE NODE TABLE OmkEvidence (${baseProps}, evidenceId STRING, passed BOOLEAN, message STRING, checkedAt STRING)`,
+        `CREATE NODE TABLE OmkDecision (${baseProps}, decisionId STRING, description STRING, decidedAt STRING)`,
+        `CREATE NODE TABLE OmkTask (${baseProps}, taskId STRING, description STRING, status STRING, priority STRING)`,
+        `CREATE NODE TABLE OmkRisk (${baseProps}, riskId STRING, description STRING, level STRING)`,
+        `CREATE NODE TABLE OmkConstraint (${baseProps}, constraintId STRING, description STRING)`,
+        `CREATE NODE TABLE OmkFile (${baseProps}, path STRING, description STRING)`,
+        `CREATE NODE TABLE OmkSymbol (${baseProps}, symbolId STRING, name STRING, kind STRING)`,
+        `CREATE NODE TABLE OmkTest (${baseProps}, testId STRING, name STRING, status STRING)`,
+        `CREATE NODE TABLE OmkCommand (${baseProps}, commandId STRING, command STRING, description STRING)`,
+        `CREATE NODE TABLE OmkCommit (${baseProps}, commitId STRING, message STRING, author STRING)`,
+        `CREATE NODE TABLE OmkMCPServer (${baseProps}, name STRING, description STRING)`,
+        `CREATE NODE TABLE OmkSkill (${baseProps}, name STRING, description STRING)`,
+        `CREATE NODE TABLE OmkProvider (${baseProps}, providerId STRING, role STRING, description STRING)`,
+        `CREATE NODE TABLE OmkProviderRoute (${baseProps}, routeId STRING, nodeId STRING, requestedProvider STRING, actualProvider STRING, reason STRING, confidence DOUBLE)`,
+        `CREATE NODE TABLE OmkProviderFallback (${baseProps}, fallbackId STRING, nodeId STRING, fromProvider STRING, toProvider STRING, reason STRING)`,
+        `CREATE NODE TABLE OmkRun (${baseProps}, runId STRING, status STRING, startedAt STRING)`,
+        `CREATE NODE TABLE OmkAuditLink (${baseProps}, linkId STRING, label STRING, target STRING, targetType STRING)`,
+    ];
+    const relTables = [
+        `CREATE REL TABLE HAS_GOAL (FROM OmkProject TO OmkGoal)`,
+        `CREATE REL TABLE HAS_RUN (FROM OmkProject TO OmkRun)`,
+        `CREATE REL TABLE HAS_CRITERION (FROM OmkGoal TO OmkCriterion)`,
+        `CREATE REL TABLE HAS_EVIDENCE (FROM OmkCriterion TO OmkEvidence)`,
+        `CREATE REL TABLE HAS_DECISION (FROM OmkProject TO OmkDecision)`,
+        `CREATE REL TABLE HAS_TASK (FROM OmkProject TO OmkTask)`,
+        `CREATE REL TABLE DEPENDS_ON (FROM OmkTask TO OmkTask)`,
+        `CREATE REL TABLE HAS_RISK (FROM OmkProject TO OmkRisk)`,
+        `CREATE REL TABLE HAS_FILE (FROM OmkProject TO OmkFile)`,
+        `CREATE REL TABLE HAS_SYMBOL (FROM OmkFile TO OmkSymbol)`,
+        `CREATE REL TABLE HAS_TEST (FROM OmkProject TO OmkTest)`,
+        `CREATE REL TABLE HAS_COMMAND (FROM OmkProject TO OmkCommand)`,
+        `CREATE REL TABLE HAS_COMMIT (FROM OmkProject TO OmkCommit)`,
+        `CREATE REL TABLE USES_MCP (FROM OmkProject TO OmkMCPServer)`,
+        `CREATE REL TABLE USES_SKILL (FROM OmkProject TO OmkSkill)`,
+        `CREATE REL TABLE USES_PROVIDER (FROM OmkProject TO OmkProvider)`,
+        `CREATE REL TABLE HAS_PROVIDER_ROUTE (FROM OmkTask TO OmkProviderRoute)`,
+        `CREATE REL TABLE ROUTES_TO (FROM OmkProviderRoute TO OmkProvider)`,
+        `CREATE REL TABLE FALLS_BACK_TO (FROM OmkProviderRoute TO OmkProvider)`,
+        `CREATE REL TABLE HAS_PROVIDER_FALLBACK (FROM OmkTask TO OmkProviderFallback)`,
+        `CREATE REL TABLE HAS_AUDIT_LINK (FROM OmkProject TO OmkAuditLink)`,
+        `CREATE REL TABLE LINKS_TO (FROM OmkAuditLink TO OmkFile)`,
+    ];
+    return { nodeTables, relTables };
+}
+/** Cypher write keywords rejected by the read-only graph query guard. */
+export const MUTATION_KEYWORDS = ["CREATE", "DELETE", "SET", "REMOVE", "MERGE", "DROP"];
+/**
+ * Return true if the provided Cypher query contains write mutations.
+ * Strips line comments and block comments before scanning.
+ */
+export function containsMutation(query) {
+    const normalized = query
+        .replace(/\/\/.*$/gm, "")
+        .replace(/\/\*[\s\S]*?\*\//g, "")
+        .replace(/\s+/g, " ")
+        .trim()
+        .toUpperCase();
+    return MUTATION_KEYWORDS.some((keyword) => normalized.includes(keyword));
+}

package/dist/openai/image-client.d.ts

@@ -0,0 +1,103 @@
+export declare const DEFAULT_OPENAI_IMAGE_MODEL = "gpt-image-2";
+export declare const DEFAULT_OPENAI_IMAGES_BASE_URL = "https://api.openai.com/v1";
+export declare const DEFAULT_OPENAI_API_KEY_ENV = "OPENAI_API_KEY";
+export declare const OPENAI_IMAGE_API_KEY_ACTION = "Use an OpenAI Platform project API key: create it through Platform OAuth, keep any encrypted copy outside the repo, decrypt only locally, run one command with OPENAI_API_KEY=<ephemeral>, then unset the env/temp key. Codex/ChatGPT OAuth tokens are only for login and cannot call the Images API.";
+export type OpenAiImageOperation = "generate" | "edit";
+export type OpenAiImageErrorKind = "auth" | "permission" | "billing" | "rate_limit" | "moderation" | "api" | "network" | "invalid_response";
+export type OpenAiImageFetch = typeof fetch;
+export interface OpenAiImageClientOptions {
+    apiKey: string;
+    fetch?: OpenAiImageFetch;
+    baseUrl?: string;
+    timeoutMs?: number;
+}
+export interface OpenAiImageRequestOptions {
+    model?: string;
+    size?: string;
+    quality?: string;
+    background?: string;
+    outputFormat?: "png" | "jpeg" | "webp";
+    n?: number;
+    user?: string;
+}
+export interface GenerateImageOptions extends OpenAiImageRequestOptions {
+    prompt: string;
+}
+export interface EditImageOptions extends OpenAiImageRequestOptions {
+    prompt: string;
+    imagePaths: string[];
+    maskPath?: string;
+}
+export interface OpenAiImageResult {
+    operation: OpenAiImageOperation;
+    model: string;
+    image: Buffer;
+    mimeType: string;
+    outputFormat: "png" | "jpeg" | "webp";
+    created?: number;
+    usage?: unknown;
+    promptHash: string;
+    promptLength: number;
+    imageCount?: number;
+    maskProvided?: boolean;
+}
+export interface SavedOpenAiImageResult extends OpenAiImageResult {
+    imagePath: string;
+    metadataPath: string;
+    relativeImagePath: string;
+    relativeMetadataPath: string;
+}
+export interface OpenAiImageMetadata {
+    createdAt: string;
+    operation: OpenAiImageOperation;
+    provider: "openai";
+    model: string;
+    output: {
+        path: string;
+        mimeType: string;
+        bytes: number;
+    };
+    request: {
+        promptSha256: string;
+        promptLength: number;
+        size?: string;
+        quality?: string;
+        background?: string;
+        outputFormat: string;
+        n: number;
+        imageCount?: number;
+        maskProvided?: boolean;
+    };
+    response: {
+        created?: number;
+        usage?: unknown;
+    };
+}
+export declare class OpenAiImageError extends Error {
+    readonly kind: OpenAiImageErrorKind;
+    readonly status?: number;
+    readonly action: string;
+    constructor(message: string, options: {
+        kind: OpenAiImageErrorKind;
+        action: string;
+        status?: number;
+    });
+}
+export declare class OpenAiImageClient {
+    private readonly apiKey;
+    private readonly fetchImpl;
+    private readonly baseUrl;
+    private readonly timeoutMs;
+    constructor(options: OpenAiImageClientOptions);
+    generate(options: GenerateImageOptions): Promise<OpenAiImageResult>;
+    edit(options: EditImageOptions): Promise<OpenAiImageResult>;
+    private requestJson;
+    private requestForm;
+    private request;
+    private toImageResult;
+    private downloadImage;
+}
+export declare function resolveOpenAiApiKey(env?: NodeJS.ProcessEnv, envName?: string): string;
+export declare function isOpenAiPlatformApiKey(credential: string): boolean;
+export declare function isLikelyOpenAiOAuthCredential(credential: string): boolean;
+export declare function saveOpenAiImageResult(root: string, result: OpenAiImageResult, options?: OpenAiImageRequestOptions, now?: Date): Promise<SavedOpenAiImageResult>;

package/dist/openai/image-client.js

@@ -0,0 +1,380 @@
+import { createHash } from "crypto";
+import { mkdir, readFile, writeFile } from "fs/promises";
+import { basename, extname, join, relative } from "path";
+import { Blob } from "buffer";
+export const DEFAULT_OPENAI_IMAGE_MODEL = "gpt-image-2";
+export const DEFAULT_OPENAI_IMAGES_BASE_URL = "https://api.openai.com/v1";
+export const DEFAULT_OPENAI_API_KEY_ENV = "OPENAI_API_KEY";
+export const OPENAI_IMAGE_API_KEY_ACTION = "Use an OpenAI Platform project API key: create it through Platform OAuth, keep any encrypted copy outside the repo, decrypt only locally, run one command with OPENAI_API_KEY=<ephemeral>, then unset the env/temp key. Codex/ChatGPT OAuth tokens are only for login and cannot call the Images API.";
+export class OpenAiImageError extends Error {
+    kind;
+    status;
+    action;
+    constructor(message, options) {
+        super(message);
+        this.name = "OpenAiImageError";
+        this.kind = options.kind;
+        this.status = options.status;
+        this.action = options.action;
+    }
+}
+export class OpenAiImageClient {
+    apiKey;
+    fetchImpl;
+    baseUrl;
+    timeoutMs;
+    constructor(options) {
+        this.apiKey = options.apiKey;
+        this.fetchImpl = options.fetch ?? fetch;
+        this.baseUrl = (options.baseUrl ?? DEFAULT_OPENAI_IMAGES_BASE_URL).replace(/\/$/, "");
+        this.timeoutMs = options.timeoutMs ?? 120_000;
+    }
+    async generate(options) {
+        const model = options.model ?? DEFAULT_OPENAI_IMAGE_MODEL;
+        const body = compactRecord({
+            model,
+            prompt: options.prompt,
+            n: options.n ?? 1,
+            size: options.size,
+            quality: options.quality,
+            background: options.background,
+            output_format: options.outputFormat ?? "png",
+            user: options.user,
+        });
+        const response = await this.requestJson("/images/generations", body);
+        return this.toImageResult("generate", response, {
+            model,
+            prompt: options.prompt,
+            outputFormat: options.outputFormat ?? "png",
+        });
+    }
+    async edit(options) {
+        const model = options.model ?? DEFAULT_OPENAI_IMAGE_MODEL;
+        if (options.imagePaths.length === 0) {
+            throw new OpenAiImageError("At least one source image is required for image edits.", {
+                kind: "api",
+                action: "Pass one or more image paths to `omk image edit`.",
+            });
+        }
+        const form = new FormData();
+        form.set("model", model);
+        form.set("prompt", options.prompt);
+        form.set("n", String(options.n ?? 1));
+        form.set("output_format", options.outputFormat ?? "png");
+        appendOptionalFormValue(form, "size", options.size);
+        appendOptionalFormValue(form, "quality", options.quality);
+        appendOptionalFormValue(form, "background", options.background);
+        appendOptionalFormValue(form, "user", options.user);
+        for (const imagePath of options.imagePaths) {
+            const blob = await readImageBlob(imagePath);
+            form.append("image", blob, basename(imagePath));
+        }
+        if (options.maskPath) {
+            const mask = await readImageBlob(options.maskPath);
+            form.set("mask", mask, basename(options.maskPath));
+        }
+        const response = await this.requestForm("/images/edits", form);
+        return this.toImageResult("edit", response, {
+            model,
+            prompt: options.prompt,
+            outputFormat: options.outputFormat ?? "png",
+            imageCount: options.imagePaths.length,
+            maskProvided: Boolean(options.maskPath),
+        });
+    }
+    async requestJson(path, body) {
+        return this.request(path, {
+            method: "POST",
+            headers: {
+                authorization: `Bearer ${this.apiKey}`,
+                "content-type": "application/json",
+            },
+            body: JSON.stringify(body),
+        });
+    }
+    async requestForm(path, body) {
+        return this.request(path, {
+            method: "POST",
+            headers: {
+                authorization: `Bearer ${this.apiKey}`,
+            },
+            body,
+        });
+    }
+    async request(path, init) {
+        const controller = new AbortController();
+        const timeout = setTimeout(() => controller.abort(), this.timeoutMs);
+        try {
+            const response = await this.fetchImpl(`${this.baseUrl}${path}`, {
+                ...init,
+                signal: controller.signal,
+            });
+            const body = await parseResponseBody(response);
+            if (!response.ok) {
+                throw mapOpenAiError(response.status, body);
+            }
+            if (!isRecord(body)) {
+                throw new OpenAiImageError("OpenAI Images API returned a non-object response.", {
+                    kind: "invalid_response",
+                    action: "Retry the request; if it repeats, capture `--json` output and report the response shape without secrets.",
+                });
+            }
+            return body;
+        }
+        catch (error) {
+            if (error instanceof OpenAiImageError)
+                throw error;
+            if (error instanceof Error && error.name === "AbortError") {
+                throw new OpenAiImageError("OpenAI Images API request timed out.", {
+                    kind: "network",
+                    action: "Retry with a smaller image or increase the timeout option when wiring the CLI.",
+                });
+            }
+            const message = error instanceof Error ? error.message : String(error);
+            throw new OpenAiImageError(`OpenAI Images API request failed: ${redactSensitiveText(message)}`, {
+                kind: "network",
+                action: "Check network connectivity and the OpenAI API status page, then retry.",
+            });
+        }
+        finally {
+            clearTimeout(timeout);
+        }
+    }
+    async toImageResult(operation, response, context) {
+        const first = response.data?.[0];
+        if (!first) {
+            throw new OpenAiImageError("OpenAI Images API returned no image data.", {
+                kind: "invalid_response",
+                action: "Retry the request; if it repeats, verify the selected model supports the Images API.",
+            });
+        }
+        const image = first.b64_json
+            ? Buffer.from(first.b64_json, "base64")
+            : first.url
+                ? await this.downloadImage(first.url)
+                : undefined;
+        if (!image || image.length === 0) {
+            throw new OpenAiImageError("OpenAI Images API returned an empty image payload.", {
+                kind: "invalid_response",
+                action: "Retry the request; if it repeats, inspect the model and output format options.",
+            });
+        }
+        const outputFormat = response.output_format ?? context.outputFormat;
+        return {
+            operation,
+            model: context.model,
+            image,
+            mimeType: mimeTypeForOutputFormat(outputFormat),
+            outputFormat,
+            created: response.created,
+            usage: response.usage,
+            promptHash: sha256(context.prompt),
+            promptLength: context.prompt.length,
+            imageCount: context.imageCount,
+            maskProvided: context.maskProvided,
+        };
+    }
+    async downloadImage(url) {
+        const response = await this.fetchImpl(url, { method: "GET", signal: AbortSignal.timeout(this.timeoutMs) });
+        if (!response.ok) {
+            throw new OpenAiImageError(`OpenAI image download failed (${response.status}).`, {
+                kind: "api",
+                status: response.status,
+                action: "Retry the request; generated image URLs can expire quickly.",
+            });
+        }
+        return Buffer.from(await response.arrayBuffer());
+    }
+}
+export function resolveOpenAiApiKey(env = process.env, envName = DEFAULT_OPENAI_API_KEY_ENV) {
+    const credential = env[envName]?.trim();
+    if (!credential) {
+        throw new OpenAiImageError(`OpenAI API key is missing from ${envName}.`, {
+            kind: "auth",
+            action: `${OPENAI_IMAGE_API_KEY_ACTION} Set ${envName} only in the runtime environment for this command; OMK does not store it.`,
+        });
+    }
+    if (!isOpenAiPlatformApiKey(credential)) {
+        const issue = isLikelyOpenAiOAuthCredential(credential)
+            ? "the value looks like a Codex/ChatGPT OAuth or session token"
+            : "the value does not look like an OpenAI Platform API key";
+        throw new OpenAiImageError(`OpenAI Images API requires an OpenAI Platform project API key in ${envName}; ${issue}.`, {
+            kind: "auth",
+            action: OPENAI_IMAGE_API_KEY_ACTION,
+        });
+    }
+    return credential;
+}
+export function isOpenAiPlatformApiKey(credential) {
+    const value = credential.trim();
+    return /^sk-(?:proj-|svcacct-)?[A-Za-z0-9_-]{8,}$/.test(value);
+}
+export function isLikelyOpenAiOAuthCredential(credential) {
+    const value = credential.trim();
+    return /^Bearer\s+/i.test(value)
+        || /^eyJ[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+/.test(value)
+        || /^(?:oauth|acct|codex|chatgpt):/i.test(value)
+        || /^(?:sess|oai)-[A-Za-z0-9_-]+/i.test(value)
+        || /^(?:access|refresh)[_-]?token[:=]/i.test(value);
+}
+export async function saveOpenAiImageResult(root, result, options = {}, now = new Date()) {
+    const dir = join(root, ".omk", "images");
+    await mkdir(dir, { recursive: true });
+    const stem = safeTimestamp(now);
+    const imagePath = join(dir, `${stem}.${result.outputFormat}`);
+    const metadataPath = join(dir, `${stem}.json`);
+    const relativeImagePath = relative(root, imagePath).replace(/\\/g, "/");
+    const relativeMetadataPath = relative(root, metadataPath).replace(/\\/g, "/");
+    await writeFile(imagePath, result.image);
+    const metadata = {
+        createdAt: now.toISOString(),
+        operation: result.operation,
+        provider: "openai",
+        model: result.model,
+        output: {
+            path: relativeImagePath,
+            mimeType: result.mimeType,
+            bytes: result.image.length,
+        },
+        request: {
+            promptSha256: result.promptHash,
+            promptLength: result.promptLength,
+            size: options.size,
+            quality: options.quality,
+            background: options.background,
+            outputFormat: result.outputFormat,
+            n: options.n ?? 1,
+            imageCount: result.imageCount,
+            maskProvided: result.maskProvided,
+        },
+        response: {
+            created: result.created,
+            usage: result.usage,
+        },
+    };
+    await writeFile(metadataPath, `${JSON.stringify(metadata, null, 2)}\n`, "utf-8");
+    return {
+        ...result,
+        imagePath,
+        metadataPath,
+        relativeImagePath,
+        relativeMetadataPath,
+    };
+}
+function appendOptionalFormValue(form, name, value) {
+    if (value !== undefined && value !== "")
+        form.set(name, value);
+}
+async function readImageBlob(filePath) {
+    const bytes = await readFile(filePath);
+    return new Blob([bytes], { type: mimeTypeForPath(filePath) });
+}
+function mimeTypeForPath(filePath) {
+    const ext = extname(filePath).toLowerCase();
+    if (ext === ".jpg" || ext === ".jpeg")
+        return "image/jpeg";
+    if (ext === ".webp")
+        return "image/webp";
+    return "image/png";
+}
+function mimeTypeForOutputFormat(format) {
+    if (format === "jpeg")
+        return "image/jpeg";
+    if (format === "webp")
+        return "image/webp";
+    return "image/png";
+}
+async function parseResponseBody(response) {
+    const text = await response.text();
+    if (!text)
+        return {};
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return text;
+    }
+}
+function mapOpenAiError(status, body) {
+    const message = summarizeOpenAiError(body) || `OpenAI Images API request failed (${status}).`;
+    const lower = message.toLowerCase();
+    if (lower.includes("content_policy") || lower.includes("moderation") || lower.includes("safety")) {
+        return new OpenAiImageError(redactSensitiveText(message), {
+            kind: "moderation",
+            status,
+            action: "Revise the prompt or input image to satisfy OpenAI image safety policy, then retry.",
+        });
+    }
+    if (status === 401) {
+        return new OpenAiImageError(redactSensitiveText(message), {
+            kind: "auth",
+            status,
+            action: `${OPENAI_IMAGE_API_KEY_ACTION} Check the configured API-key environment variable; OMK reads it only from runtime env and never stores it.`,
+        });
+    }
+    if (status === 403) {
+        return new OpenAiImageError(redactSensitiveText(message), {
+            kind: "permission",
+            status,
+            action: "Check project permissions, API tier/model access, organization policy, and whether Images API access is enabled for this key.",
+        });
+    }
+    if (status === 429) {
+        return new OpenAiImageError(redactSensitiveText(message), {
+            kind: lower.includes("quota") || lower.includes("billing") ? "billing" : "rate_limit",
+            status,
+            action: lower.includes("quota") || lower.includes("billing")
+                ? "Check OpenAI billing, project quota, and usage limits before retrying."
+                : "Wait, then retry with lower concurrency or smaller images.",
+        });
+    }
+    if (status === 402 || lower.includes("billing") || lower.includes("insufficient_quota") || lower.includes("quota")) {
+        return new OpenAiImageError(redactSensitiveText(message), {
+            kind: "billing",
+            status,
+            action: "Check OpenAI billing status, project quota, and monthly usage limits, then retry.",
+        });
+    }
+    return new OpenAiImageError(redactSensitiveText(message), {
+        kind: "api",
+        status,
+        action: "Verify prompt, input image constraints, selected model, and output options, then retry.",
+    });
+}
+function summarizeOpenAiError(body) {
+    if (typeof body === "string")
+        return body.slice(0, 800);
+    if (!isRecord(body))
+        return "";
+    const error = body.error;
+    if (isRecord(error)) {
+        const message = typeof error.message === "string" ? error.message : "";
+        const code = typeof error.code === "string" ? error.code : "";
+        const type = typeof error.type === "string" ? error.type : "";
+        return [message, code, type].filter(Boolean).join(" ").slice(0, 800);
+    }
+    const message = typeof body.message === "string" ? body.message : "";
+    return message.slice(0, 800);
+}
+function compactRecord(values) {
+    const entries = Object.entries(values).filter(([, value]) => value !== undefined && value !== "");
+    return Object.fromEntries(entries);
+}
+function safeTimestamp(date) {
+    return date.toISOString().replace(/[:.]/g, "-");
+}
+function sha256(value) {
+    return createHash("sha256").update(value).digest("hex");
+}
+function redactSensitiveText(value) {
+    return value
+        .replace(/sk-[A-Za-z0-9_-]+/g, "[redacted-openai-key]")
+        .replace(/\bBearer\s+[^\s"',;]+/gi, "Bearer [redacted-oauth-token]")
+        .replace(/\beyJ[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+(?:\.[A-Za-z0-9_-]+)?\b/g, "[redacted-oauth-token]")
+        .replace(/\b(?:oauth|acct|codex|chatgpt):[^\s"',;]+/gi, "[redacted-oauth-token]")
+        .replace(/\b(?:sess|oai)-[^\s"',;]+/gi, "[redacted-oauth-token]")
+        .replace(/\b((?:access|refresh)[_-]?token[:=])[^\s"',;]+/gi, "$1[redacted-oauth-token]");
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null;
+}

package/dist/orchestration/agent-worker.d.ts

@@ -0,0 +1,72 @@
+/**
+ * AgentWorker — 개별 워커 프로세스 관리
+ *
+ * 에이전트 YAML을 로드하고 프로세스를 스폰하여 작업을 실행합니다.
+ */
+import type { DagNode } from "../contracts/dag.js";
+import type { WorkerLogHandle } from "./log-streamer.js";
+import { type SkillAssignment } from "./skill-assigner.js";
+import type { TaskRunContext } from "../contracts/worker-context.js";
+export interface AgentWorkerOptions {
+    node: DagNode;
+    runId: string;
+    agentYamlPath: string;
+    logHandle: WorkerLogHandle;
+    cwd?: string;
+    env?: Record<string, string>;
+    timeout?: number;
+    runContext?: TaskRunContext;
+}
+export interface WorkerOutput {
+    success: boolean;
+    exitCode: number;
+    stdout: string;
+    stderr: string;
+    metadata?: Record<string, unknown>;
+}
+export declare function buildAgentWorkerSpawnEnv(workerEnv: Record<string, string>, metadata: {
+    readonly runId: string;
+    readonly nodeId: string;
+    readonly role: string;
+}): Record<string, string>;
+export declare class AgentWorker {
+    private node;
+    private runId;
+    private agentYamlPath;
+    private logHandle;
+    private cwd;
+    private env;
+    private timeout;
+    private runContext?;
+    private process;
+    private abortController;
+    constructor(options: AgentWorkerOptions);
+    /**
+     * 워커 실행
+     */
+    execute(): Promise<WorkerOutput>;
+    /**
+     * 워커 중단
+     */
+    abort(): void;
+    /**
+     * 워커가 실행 중인지 확인
+     */
+    isRunning(): boolean;
+    /**
+     * 프로세스 ID 가져오기
+     */
+    getPid(): number | undefined;
+    /**
+     * 노드 정보 가져오기
+     */
+    getNode(): DagNode;
+}
+/**
+ * 에이전트 YAML 파일 생성
+ */
+export declare function createAgentYaml(node: DagNode, runId: string, skills: SkillAssignment, outputDir: string): Promise<string>;
+/**
+ * 워커 생성 헬퍼
+ */
+export declare function createAgentWorker(node: DagNode, runId: string, logHandle: WorkerLogHandle, options?: Partial<AgentWorkerOptions>): Promise<AgentWorker>;