@ai-agent-tools/picgen 0.1.0-alpha.2 → 0.1.0-alpha.4

package/README.md

@@ -91,6 +91,14 @@ OPENAI_API_KEY=...
 GEMINI_API_KEY=...
 ```
 
+For non-technical users, `picgen setup` can save API keys for you in:
+
+```text
+~/.picgen/.env
+```
+
+PicGen loads this managed env file automatically. Shell environment variables take priority, and a project `.env` can override the managed file for local testing.
+
 You can start from the included example:
 
 ```bash
@@ -101,6 +109,12 @@ Provider `base_url` values should be host-only. Do not include `/v1` or `/v1beta
 
 Providers may optionally set `test_model` in `~/.picgen/config.yaml` when health checks should use a lightweight model instead of the first generation model.
 
+Generation requests use adaptive provider timeouts: fast draft requests allow 120s, balanced requests allow 180s, and high quality or large requests allow 300s. If a third-party channel is slower, override it with `PICGEN_PROVIDER_TIMEOUT_MS`:
+
+```bash
+PICGEN_PROVIDER_TIMEOUT_MS=450000 picgen create --yes --preset poster "一张产品发布会主视觉"
+```
+
 Providers expose capabilities such as `text-to-image` and `reference-image`. Old configs that omit capabilities are upgraded in memory from the provider protocol: Gemini supports both text and reference-image generation, while OpenAI-compatible `/v1/images/generations` supports text-to-image only.
 
 Generated image data and provider-only fields such as base64 image payloads and Gemini thought signatures are redacted from metadata. PicGen keeps the generated assets as local image files and keeps stdout compact for agent workflows.

package/dist/cli.js

@@ -1,7 +1,6 @@
 #!/usr/bin/env node
 
 // src/cli.ts
-import "dotenv/config";
 import { Command } from "commander";
 
 // src/commands/create.ts
@@ -459,6 +458,53 @@ async function ensureConfig() {
 // src/providers/gemini.ts
 import { readFile as readFile2 } from "fs/promises";
 
+// src/providers/timeout.ts
+var FAST_PROVIDER_TIMEOUT_MS = 12e4;
+var DEFAULT_PROVIDER_TIMEOUT_MS = 18e4;
+var SLOW_PROVIDER_TIMEOUT_MS = 3e5;
+function resolveProviderTimeoutMs(plan) {
+  const override = parseTimeoutOverride(process.env.PICGEN_PROVIDER_TIMEOUT_MS);
+  if (override !== void 0) return override;
+  if (plan.presetName === "fast-draft" || plan.modeName === "fast" || plan.preset.quality === "low") {
+    return FAST_PROVIDER_TIMEOUT_MS;
+  }
+  if (plan.modeName === "premium" || plan.preset.size === "large" || plan.preset.quality === "high") {
+    return SLOW_PROVIDER_TIMEOUT_MS;
+  }
+  return DEFAULT_PROVIDER_TIMEOUT_MS;
+}
+async function fetchWithProviderTimeout(input3, init, timeoutMs) {
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    return await fetch(input3, {
+      ...init,
+      signal: controller.signal
+    });
+  } catch (error) {
+    if (isAbortError(error)) {
+      throw new Error(formatProviderTimeoutError(timeoutMs));
+    }
+    throw error;
+  } finally {
+    clearTimeout(timeout);
+  }
+}
+function formatProviderTimeoutError(timeoutMs) {
+  return `Provider request timed out after ${Math.ceil(
+    timeoutMs / 1e3
+  )}s. The provider may still be processing or temporarily unavailable. Try again, use a faster preset, or increase PICGEN_PROVIDER_TIMEOUT_MS.`;
+}
+function parseTimeoutOverride(value) {
+  if (!value) return void 0;
+  const timeoutMs = Number(value);
+  if (!Number.isInteger(timeoutMs) || timeoutMs <= 0) return void 0;
+  return timeoutMs;
+}
+function isAbortError(error) {
+  return error instanceof Error && error.name === "AbortError";
+}
+
 // src/providers/urls.ts
 function normalizeProviderBaseUrl(baseUrl) {
   const url = new URL(baseUrl);
@@ -495,15 +541,20 @@ var GeminiAdapter = class {
     const providerImages = [];
     const requestCount = Math.max(1, plan.preset.n);
     const referenceParts = await readReferenceImageParts(plan);
+    const timeoutMs = resolveProviderTimeoutMs(plan);
     for (let index = 0; index < requestCount; index += 1) {
-      const response = await fetch(buildGeminiGenerateContentUrl(plan.provider.base_url, plan.model), {
-        method: "POST",
-        headers: {
-          "x-goog-api-key": apiKey,
-          "Content-Type": "application/json"
+      const response = await fetchWithProviderTimeout(
+        buildGeminiGenerateContentUrl(plan.provider.base_url, plan.model),
+        {
+          method: "POST",
+          headers: {
+            "x-goog-api-key": apiKey,
+            "Content-Type": "application/json"
+          },
+          body: JSON.stringify(buildGeminiGenerateContentRequest(plan, referenceParts))
         },
-        body: JSON.stringify(buildGeminiGenerateContentRequest(plan, referenceParts))
-      });
+        timeoutMs
+      );
       const raw = await readJsonResponse(response);
       if (!response.ok) {
         throw new Error(formatGeminiError(response.status, response.statusText, raw));
@@ -624,14 +675,18 @@ var OpenAIImagesAdapter = class {
     if (!apiKey) {
       throw new Error(`Missing API key environment variable: ${plan.provider.api_key_env}`);
     }
-    const response = await fetch(buildOpenAIImagesUrl(plan.provider.base_url), {
-      method: "POST",
-      headers: {
-        Authorization: `Bearer ${apiKey}`,
-        "Content-Type": "application/json"
+    const response = await fetchWithProviderTimeout(
+      buildOpenAIImagesUrl(plan.provider.base_url),
+      {
+        method: "POST",
+        headers: {
+          Authorization: `Bearer ${apiKey}`,
+          "Content-Type": "application/json"
+        },
+        body: JSON.stringify(buildOpenAIImagesRequest(plan))
       },
-      body: JSON.stringify(buildOpenAIImagesRequest(plan))
-    });
+      resolveProviderTimeoutMs(plan)
+    );
     const raw = await readJsonResponse2(response);
     if (!response.ok) {
       throw new Error(formatOpenAIImagesError(response.status, response.statusText, raw));
@@ -999,7 +1054,7 @@ import { homedir as homedir2 } from "os";
 
 // src/version.ts
 var PACKAGE_NAME = "@ai-agent-tools/picgen";
-var VERSION = "0.1.0-alpha.2";
+var VERSION = "0.1.0-alpha.4";
 
 // src/commands/update.ts
 var UPDATE_CACHE_TTL_MS = 24 * 60 * 60 * 1e3;
@@ -1469,7 +1524,7 @@ function formatQuickstart() {
     "  npm install -g @ai-agent-tools/picgen",
     "",
     "Configure:",
-    "  picgen setup",
+    "  picgen setup  # can save provider API keys for you",
     "  picgen doctor --json",
     "",
     "Preview before spending quota:",
@@ -1482,10 +1537,11 @@ function formatQuickstart() {
     '  picgen create --dry-run --reference ./reference.png "\u57FA\u4E8E\u53C2\u8003\u56FE\u751F\u6210\u4E00\u5F20\u54C1\u724C\u6D77\u62A5"',
     "",
     "Agent prompt:",
-    "  \u8BF7\u5B89\u88C5\u5E76\u4F53\u9A8C @ai-agent-tools/picgen\uFF1A\u5168\u5C40\u5B89\u88C5 npm install -g @ai-agent-tools/picgen\uFF0C\u8FD0\u884C picgen setup \u914D\u7F6E\uFF0C\u7136\u540E\u5148 dry-run \u9884\u89C8\uFF0C\u518D\u786E\u8BA4\u751F\u6210\u4E00\u5F20\u6D4B\u8BD5\u56FE\u3002\u5982\u679C\u6211\u8981\u7528\u53C2\u8003\u56FE\uFF0C\u8BF7\u4F7F\u7528 --reference <\u56FE\u7247\u8DEF\u5F84>\u3002",
+    "  \u8BF7\u5B89\u88C5\u5E76\u4F53\u9A8C @ai-agent-tools/picgen\uFF1A\u5168\u5C40\u5B89\u88C5 npm install -g @ai-agent-tools/picgen\uFF0C\u8FD0\u884C picgen setup \u5F15\u5BFC\u6211\u914D\u7F6E provider \u548C API key\uFF0C\u7136\u540E\u5148 dry-run \u9884\u89C8\uFF0C\u518D\u786E\u8BA4\u751F\u6210\u4E00\u5F20\u6D4B\u8BD5\u56FE\u3002\u5982\u679C\u6211\u8981\u7528\u53C2\u8003\u56FE\uFF0C\u8BF7\u4F7F\u7528 --reference <\u56FE\u7247\u8DEF\u5F84>\u3002",
     "",
     "Notes:",
     "  - Provider host URLs should not include /v1 or /v1beta.",
+    "  - picgen setup can store API keys in ~/.picgen/.env.",
     "  - Agent workflows should dry-run before real generation.",
     "  - Generated images are saved locally; do not paste base64 into chat.",
     "  - First-user rollout checklist: docs/release-alpha.md"
@@ -1493,7 +1549,62 @@ function formatQuickstart() {
 }
 
 // src/commands/setup.ts
-import { confirm as confirm2, input as input2, select as select2 } from "@inquirer/prompts";
+import { confirm as confirm2, input as input2, password, select as select2 } from "@inquirer/prompts";
+
+// src/config/env.ts
+import { chmod, mkdir as mkdir4, readFile as readFile4, writeFile as writeFile4 } from "fs/promises";
+import { existsSync } from "fs";
+import { dirname as dirname3, join as join5, resolve as resolve2 } from "path";
+import { homedir as homedir3 } from "os";
+import { parse } from "dotenv";
+function getManagedEnvPath() {
+  return process.env.PICGEN_ENV_PATH ?? join5(homedir3(), ".picgen", ".env");
+}
+async function loadPicgenEnv() {
+  const shellEnv = new Set(Object.keys(process.env));
+  await loadEnvFile(getManagedEnvPath(), shellEnv, false);
+  await loadEnvFile(resolve2(process.cwd(), ".env"), shellEnv, true);
+}
+async function saveManagedEnvVar(name, value) {
+  const path = getManagedEnvPath();
+  const current = await readManagedEnvFile(path);
+  const next = {
+    ...current,
+    [name]: value
+  };
+  await mkdir4(dirname3(path), { recursive: true });
+  await writeFile4(path, stringifyEnv(next), "utf8");
+  await chmod(path, 384);
+  process.env[name] = value;
+  return path;
+}
+async function loadEnvFile(path, shellEnv, overrideManagedValues) {
+  if (!existsSync(path)) return;
+  const parsed = parse(await readFile4(path, "utf8"));
+  for (const [name, value] of Object.entries(parsed)) {
+    if (shellEnv.has(name)) continue;
+    if (!overrideManagedValues && process.env[name] !== void 0) continue;
+    process.env[name] = value;
+  }
+}
+async function readManagedEnvFile(path) {
+  try {
+    return parse(await readFile4(path, "utf8"));
+  } catch (error) {
+    if (error.code === "ENOENT") return {};
+    throw error;
+  }
+}
+function stringifyEnv(values) {
+  return `${Object.entries(values).map(([name, value]) => `${name}=${quoteEnvValue(value)}`).join("\n")}
+`;
+}
+function quoteEnvValue(value) {
+  if (/^[A-Za-z0-9_./:@+-]+$/.test(value)) return value;
+  return JSON.stringify(value);
+}
+
+// src/commands/setup.ts
 async function runSetup() {
   await ensureConfig();
   console.log(`PicGen config: ${getConfigPath()}`);
@@ -1508,6 +1619,7 @@ async function runSetup() {
         { name: "Quick add a common provider/channel", value: "quick-add" },
         { name: "Choose default provider/channel", value: "provider" },
         { name: "Choose generation preference", value: "mode" },
+        { name: "Configure API key", value: "key" },
         { name: "Test a provider", value: "test" },
         { name: "Advanced: add a custom provider/channel", value: "add" },
         { name: "Finish setup", value: "done" }
@@ -1519,6 +1631,8 @@ async function runSetup() {
       await chooseDefaultProvider();
     } else if (action === "mode") {
       await chooseDefaultMode();
+    } else if (action === "key") {
+      await chooseProviderKeyToConfigure();
     } else if (action === "test") {
       await chooseProviderToTest();
     } else if (action === "add") {
@@ -1537,7 +1651,7 @@ async function printSetupSummary() {
   for (const [providerName, provider2] of Object.entries(config.providers)) {
     const preference = providerName === config.routing.default_provider ? "default" : config.routing.fallback_providers.includes(providerName) ? "fallback" : "manual";
     console.log(
-      `- ${providerName}: ${provider2.enabled ? "enabled" : "disabled"}, ${preference}, ${providerLabel(provider2)}, capabilities=${provider2.capabilities.join(",")}`
+      `- ${providerName}: ${provider2.enabled ? "enabled" : "disabled"}, ${preference}, ${providerLabel(provider2)}, key=${provider2.api_key_env}${process.env[provider2.api_key_env] ? " set" : " missing"}, capabilities=${provider2.capabilities.join(",")}`
     );
   }
 }
@@ -1585,6 +1699,18 @@ async function chooseProviderToTest() {
   if (result.model) console.log(`Model: ${result.model}`);
   if (result.http_status) console.log(`HTTP status: ${result.http_status}`);
 }
+async function chooseProviderKeyToConfigure() {
+  const config = await loadConfig();
+  const name = await select2({
+    message: "Choose the provider key to configure",
+    default: config.routing.default_provider,
+    choices: Object.entries(config.providers).map(([providerName, provider2]) => ({
+      name: `${providerName} (${provider2.api_key_env}${process.env[provider2.api_key_env] ? ", currently set" : ", missing"})`,
+      value: providerName
+    }))
+  });
+  await configureProviderApiKey(config.providers[name]);
+}
 async function quickAddProvider() {
   const config = await loadConfig();
   const template = await select2({
@@ -1644,7 +1770,27 @@ async function quickAddProvider() {
   }
   await saveConfig(config);
   console.log(`Added provider: ${name}`);
-  console.log(`Set ${apiKeyEnv} in your shell or .env before testing this provider.`);
+  await configureProviderApiKey(provider2);
+}
+async function configureProviderApiKey(provider2) {
+  if (process.env[provider2.api_key_env]) {
+    const replace = await confirm2({
+      message: `${provider2.api_key_env} is already available. Replace the saved PicGen key?`,
+      default: false
+    });
+    if (!replace) return;
+  }
+  const value = await password({
+    message: `Paste API key for ${provider2.api_key_env} (leave empty to skip)`,
+    mask: "*"
+  });
+  if (!value.trim()) {
+    console.log(`Skipped API key. You can configure it later with picgen setup.`);
+    return;
+  }
+  const path = await saveManagedEnvVar(provider2.api_key_env, value.trim());
+  console.log(`Saved ${provider2.api_key_env} to ${path}`);
+  console.log(`PicGen loads this file automatically. Advanced users can override it with shell env vars or a project .env.`);
 }
 function quickProviderDefaults(template) {
   switch (template) {
@@ -1709,6 +1855,7 @@ function modeLabel(modeName) {
 }
 
 // src/cli.ts
+await loadPicgenEnv();
 var program = new Command();
 program.name("picgen").description("Lightweight image generation connector for AI agents.").version(VERSION);
 program.command("setup").description("Run the interactive PicGen setup wizard.").action(runSetup);

package/docs/release-alpha.md

@@ -40,7 +40,17 @@ https://generativelanguage.googleapis.com
 
 Do not include `/v1` or `/v1beta`.
 
-4. Set API keys in the shell or a local `.env` file:
+4. Configure API keys:
+
+For non-technical users, prefer `picgen setup`. It can save provider API keys in PicGen's managed env file:
+
+```text
+~/.picgen/.env
+```
+
+PicGen loads this file automatically.
+
+Advanced users can still use shell environment variables or a local project `.env`:
 
 ```bash
 cp .env.example .env
@@ -143,6 +153,14 @@ picgen provider test <provider-name> --json
 
 Check `base_url`, API key, model name, and provider availability.
 
+`Provider request timed out`
+
+High quality, large, or slow third-party image channels can take longer. Try again, use a faster preset, or raise the request timeout:
+
+```bash
+PICGEN_PROVIDER_TIMEOUT_MS=450000 picgen create --yes --preset poster "<prompt>"
+```
+
 `No enabled provider can satisfy...`
 
 Run `picgen provider list`, enable a provider, add a fallback provider, or adjust the selected mode/model.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ai-agent-tools/picgen",
-  "version": "0.1.0-alpha.2",
+  "version": "0.1.0-alpha.4",
   "description": "A lightweight image generation connector for AI agents.",
   "type": "module",
   "bin": {

package/skills/picgen/SKILL.md

@@ -20,7 +20,7 @@ Never silently spend user quota. Do not send full conversation context to provid
 ## Workflow
 
 1. Run `picgen doctor --json` to check configuration.
-2. If no usable provider is configured, guide the user to run `picgen setup`.
+2. If no usable provider is configured, guide the user to run `picgen setup`. The setup wizard can configure providers and save API keys for non-technical users.
 3. Choose a preset from the user's intent, such as `poster`, `product-shot`, or `social-cover`.
 4. Run `picgen create --dry-run --preset <preset> "<prompt>"`.
 5. Present the dry-run as a user-facing generation preview. Do not expose `dry-run` as a technical term unless useful.
@@ -75,7 +75,7 @@ PicGen redacts generated image payloads and Gemini thought signatures from metad
 
 If `doctor` reports no usable provider, ask the user to run `picgen setup`.
 
-If an API key is missing, name the required environment variable.
+If an API key is missing, guide the user to run `picgen setup` and choose `Configure API key`. Name the required environment variable only when useful for debugging.
 
 If a provider is disabled, suggest enabling it or using a one-off provider override.