@prismer/runtime 2.0.7 → 2.2.55

package/built-in-skills/image-generate/SKILL.md

@@ -0,0 +1,128 @@
+---
+name: image-generate
+scope: persistence
+description: Generate one new image from a text prompt and deliver it once as the current Prismer reply attachment. Use for draw, generate-image, poster, diagram, illustration, or other text-to-image requests. Do not use for editing or merely describing an existing image.
+applies_to: [hermes, claude-code, openclaw, codex]
+requires:
+  - assets
+phaseModel:
+  defaultPhase: tool_use
+version: 2
+config:
+  - key: IMAGE_GEN_MODEL
+    type: string
+    required: false
+    default: null
+    bindable: [global, role, agent]
+    description: Preferred image-generation model id. The helper discovers the deployment model list and falls back by priority.
+    prompt:
+      zh: "生成图片时希望默认用哪个模型？"
+      en: "Which image model should be used by default?"
+---
+
+# Image Generate
+
+Generate and deliver the requested image through the bundled helper. The helper
+owns model discovery, fallback, byte decoding, hashing, file creation, and the
+single `cloud deliver` call. Do not rebuild those steps in Python, curl, or a
+temporary script.
+
+## Run
+
+From this skill directory, run:
+
+```bash
+node scripts/generate-and-deliver.mjs \
+  --prompt '<complete generation prompt>' \
+  --size 1024x1024
+```
+
+Optional flags:
+
+- `--model <id>` overrides `IMAGE_GEN_MODEL` for this call.
+- `--output <path>` selects the local PNG/JPEG/WebP filename. Without it, the
+  helper writes a content-hashed file under `PRISMER_ARTIFACTS_DIR` (or cwd when
+  no dispatch artifacts directory is available).
+- `--size` accepts `256x256`, `512x512`, `1024x1024`, `1792x1024`, or
+  `1024x1792`; the selected deployment model must advertise that size.
+
+Defaults: square `1024x1024`; portrait `1024x1792` or landscape `1792x1024`
+only when the user asks for that orientation. Generate one image per helper
+invocation.
+
+## Delivery contract
+
+The helper ends by running `cloud deliver <file> --json` exactly once and
+consumes that machine output internally. Runtime turns the delivered asset into
+the reply's structured attachment and the chat renderer shows the preview.
+
+Read the helper's one-line status before replying:
+
+- `[image-generate] delivered` means the asset was uploaded for this reply.
+  Reply with a short natural-language caption; model and size may be mentioned.
+- `[image-generate] queued` means the bytes are durable locally but the cloud
+  upload is pending reconnection. Say it was generated and queued for upload;
+  do not claim it is already attached.
+- `[image-generate] uploaded-unattached` means the cloud stored the image under
+  the run archive but no active reply dispatch existed. Say it was generated
+  and archived; do not claim it is attached.
+- Do not paste the helper's JSON, assetId object, ContentBlock, base64, data URI,
+  signed URL, or local path into the message body.
+- Do not run `cloud deliver`, `cloud file send`, `cloud task attach`, an asset
+  upload command, or a multipart request again for the same output.
+- Do not manually construct a structured attachment. Runtime owns that wire
+  representation.
+
+The generated file may also be observed by Runtime's dispatch-final artifact
+scan. That scan and `cloud deliver` share the same run/task scope and
+content-addressed dedup key; agents must not add another upload path.
+
+## Prompt handling
+
+Use the user's requested subject, composition, style, lighting, camera angle,
+palette, text, and exclusions. Expand a vague request only enough to make those
+visual choices explicit; do not silently change the subject or intent.
+
+Do not generate privacy-sensitive depictions of identifiable people without
+the user's explicit request. For editing, variation, or inpainting of an
+existing image, use an image-editing capability instead. For reading an
+existing image, use the asset/vision path.
+
+## Helper behavior
+
+The bundled script:
+
+1. Resolves `PRISMER_CLOUD_BASE` / `PRISMER_BASE_URL` and `PRISMER_API_KEY`,
+   falling back to the Prismer runtime config.
+2. Discovers available image models, filters them by the requested size before
+   generation, and honors a compatible `--model` or `IMAGE_GEN_MODEL` first.
+3. Retries the next model only for model-not-found, quota/rate-limit, or server
+   failures. Prompt rejection and insufficient credits stop immediately.
+4. Accepts either base64 image bytes or a short-lived image URL, validates the
+   resulting PNG/JPEG/WebP bytes, and writes one content-hashed file.
+5. Delivers that file once through the daemon-aware CLI path, distinguishing a
+   completed upload from a durable offline queue receipt.
+
+If it fails, report its status/code/message and stop. Do not fabricate an
+assetId, claim that delivery succeeded, or retry a rejected prompt unchanged.
+
+## Examples
+
+Square illustration:
+
+```bash
+node scripts/generate-and-deliver.mjs \
+  --prompt 'Isometric server room, glowing blue racks, cinematic lighting' \
+  --size 1024x1024
+```
+
+Portrait poster with an explicit model preference:
+
+```bash
+node scripts/generate-and-deliver.mjs \
+  --prompt 'Minimalist monochrome owl poster, centered subject, clean negative space' \
+  --size 1024x1792 \
+  --model "$IMAGE_GEN_MODEL"
+```
+
+Successful chat reply example: `图已生成并附在这条消息中。`

package/built-in-skills/image-generate/scripts/generate-and-deliver.mjs

@@ -0,0 +1,289 @@
+#!/usr/bin/env node
+
+import { execFile } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { dirname, extname, join, resolve } from 'node:path';
+import { promisify } from 'node:util';
+
+const execFileAsync = promisify(execFile);
+const ALLOWED_SIZES = new Set(['256x256', '512x512', '1024x1024', '1792x1024', '1024x1792']);
+
+function usage() {
+  return [
+    'Usage: node scripts/generate-and-deliver.mjs --prompt <text> [options]',
+    '',
+    'Options:',
+    '  --size <WxH>       Default: 1024x1024',
+    '  --model <id>       Default: IMAGE_GEN_MODEL or deployment priority',
+    '  --output <path>    Default: $PRISMER_ARTIFACTS_DIR/generated-<sha8>.<ext> (or cwd)',
+    '  --base-url <url>   Default: Prismer runtime env/config',
+    '  --help',
+  ].join('\n');
+}
+
+function parseArgs(argv) {
+  const out = { size: '1024x1024' };
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg === '--help' || arg === '-h') out.help = true;
+    else if (arg === '--prompt') out.prompt = argv[++i];
+    else if (arg === '--size') out.size = argv[++i];
+    else if (arg === '--model') out.model = argv[++i];
+    else if (arg === '--output') out.output = argv[++i];
+    else if (arg === '--base-url') out.baseUrl = argv[++i];
+    else throw new Error(`Unknown argument: ${arg}`);
+  }
+  if (!out.help && (typeof out.prompt !== 'string' || out.prompt.trim().length === 0)) {
+    throw new Error('--prompt is required');
+  }
+  if (!out.help && out.prompt.length > 4000) throw new Error('--prompt must be at most 4000 characters');
+  if (!out.help && !ALLOWED_SIZES.has(out.size)) throw new Error(`Unsupported --size: ${out.size}`);
+  return out;
+}
+
+async function readRuntimeConfig() {
+  const root = process.env.PRISMER_HOME || join(homedir(), '.prismer');
+  try {
+    const raw = await readFile(join(root, 'config.toml'), 'utf8');
+    const value = (keys) => {
+      for (const key of keys) {
+        const match = raw.match(new RegExp(`^${key}\\s*=\\s*["']([^"']+)["']`, 'm'));
+        if (match?.[1]) return match[1];
+      }
+      return undefined;
+    };
+    return {
+      baseUrl: value(['cloud_api_base', 'base_url']),
+      apiKey: value(['api_key']),
+    };
+  } catch {
+    return {};
+  }
+}
+
+async function resolveAuth(args) {
+  const config = await readRuntimeConfig();
+  const baseUrl =
+    args.baseUrl ||
+    process.env.PRISMER_CLOUD_BASE ||
+    process.env.PRISMER_BASE_URL ||
+    process.env.CLOUD_API_BASE ||
+    process.env.PRISMER_CLOUD_API_BASE ||
+    config.baseUrl;
+  const apiKey = process.env.PRISMER_API_KEY || config.apiKey;
+  if (!baseUrl) throw new Error('Missing Prismer cloud base URL (set PRISMER_CLOUD_BASE or configure cloud_api_base)');
+  if (!apiKey) throw new Error('Missing PRISMER_API_KEY and no api_key was found in config.toml');
+  return { baseUrl: baseUrl.replace(/\/$/, ''), apiKey };
+}
+
+async function readJson(response) {
+  const text = await response.text();
+  if (!text) return {};
+  try {
+    return JSON.parse(text);
+  } catch {
+    throw new Error(`Cloud returned non-JSON status=${response.status}: ${text.slice(0, 200)}`);
+  }
+}
+
+function errorDetail(status, body) {
+  const error = body?.error;
+  const code = typeof error?.code === 'string' ? error.code : typeof error?.type === 'string' ? error.type : '';
+  const message = typeof error?.message === 'string' ? error.message : typeof error === 'string' ? error : `HTTP ${status}`;
+  return { status, code, message };
+}
+
+function canFallback(error) {
+  if (error.status === 402) return false;
+  return (
+    error.status === 404 ||
+    error.status === 429 ||
+    error.status >= 500 ||
+    ['model_not_found', 'rate_limit', 'rate_limit_exceeded', 'insufficient_quota'].includes(error.code)
+  );
+}
+
+function normalizeModel(model) {
+  return {
+    id: model.id,
+    sizes: Array.isArray(model.sizes) ? model.sizes.filter((size) => typeof size === 'string') : null,
+  };
+}
+
+function supportsSize(model, size) {
+  return model.sizes === null || model.sizes.length === 0 || model.sizes.includes(size);
+}
+
+async function discoverModels(auth, preferred, size) {
+  const response = await fetch(`${auth.baseUrl}/api/v1/image-models`, {
+    headers: { Authorization: `Bearer ${auth.apiKey}` },
+    signal: AbortSignal.timeout(30_000),
+  });
+  const body = await readJson(response);
+  if (!response.ok || !Array.isArray(body.data)) {
+    const detail = errorDetail(response.status, body);
+    if (preferred) return [{ id: preferred, sizes: null }];
+    throw new Error(`Image model discovery failed: ${detail.status} ${detail.code} ${detail.message}`.trim());
+  }
+  const discovered = body.data
+    .filter((model) => model && typeof model.id === 'string')
+    .sort((a, b) => Number(a.priority ?? 999) - Number(b.priority ?? 999))
+    .map(normalizeModel);
+  const preferredModel = preferred ? discovered.find((model) => model.id === preferred) : undefined;
+  const candidates = [
+    ...(preferred && !preferredModel ? [{ id: preferred, sizes: null }] : []),
+    ...(preferredModel ? [preferredModel] : []),
+    ...discovered,
+  ].filter((model) => supportsSize(model, size));
+  const unique = candidates.filter((model, index) => candidates.findIndex((item) => item.id === model.id) === index);
+  if (unique.length === 0) {
+    const available = discovered
+      .map((model) => `${model.id}=[${model.sizes?.join(',') || 'unknown'}]`)
+      .join(', ');
+    throw new Error(`No image model supports size=${size}; available: ${available || 'none'}`);
+  }
+  return unique;
+}
+
+async function generate(auth, args, models) {
+  const failures = [];
+  for (const candidate of models) {
+    const model = candidate.id;
+    const response = await fetch(`${auth.baseUrl}/api/v1/images/generations`, {
+      method: 'POST',
+      headers: {
+        Authorization: `Bearer ${auth.apiKey}`,
+        'Content-Type': 'application/json',
+      },
+      body: JSON.stringify({
+        prompt: args.prompt,
+        model,
+        size: args.size,
+        n: 1,
+        response_format: 'b64_json',
+      }),
+      signal: AbortSignal.timeout(180_000),
+    });
+    const body = await readJson(response);
+    if (!response.ok) {
+      const detail = { model, ...errorDetail(response.status, body) };
+      failures.push(detail);
+      if (canFallback(detail)) {
+        process.stderr.write(`[image-generate] model=${model} failed (${detail.status} ${detail.code || 'error'}); trying fallback\n`);
+        continue;
+      }
+      throw new Error(`Image generation failed: model=${model} status=${detail.status} code=${detail.code || '-'} message=${detail.message}`);
+    }
+    const item = body?.data?.[0];
+    if (typeof item?.b64_json === 'string' && item.b64_json.length > 0) {
+      return { bytes: Buffer.from(item.b64_json, 'base64'), model };
+    }
+    if (typeof item?.url === 'string' && item.url.length > 0) {
+      return { bytes: await downloadImage(item.url), model };
+    }
+    throw new Error(`Image generation returned no bytes or URL for model=${model}`);
+  }
+  throw new Error(
+    `All image models failed: ${failures.map((failure) => `${failure.model}:${failure.status}/${failure.code || 'error'}`).join(', ')}`,
+  );
+}
+
+async function downloadImage(url) {
+  if (url.startsWith('data:')) {
+    const match = url.match(/^data:[^;,]+;base64,(.+)$/s);
+    if (!match) throw new Error('Unsupported image data URL');
+    return Buffer.from(match[1], 'base64');
+  }
+  const response = await fetch(url, { signal: AbortSignal.timeout(60_000) });
+  if (!response.ok) throw new Error(`Generated image download failed: HTTP ${response.status}`);
+  return Buffer.from(await response.arrayBuffer());
+}
+
+function detectImage(bytes) {
+  if (bytes.subarray(0, 8).equals(Buffer.from('89504e470d0a1a0a', 'hex'))) return { extension: '.png', mediaType: 'image/png' };
+  if (bytes.subarray(0, 3).equals(Buffer.from('ffd8ff', 'hex'))) return { extension: '.jpg', mediaType: 'image/jpeg' };
+  if (bytes.subarray(0, 4).toString('ascii') === 'RIFF' && bytes.subarray(8, 12).toString('ascii') === 'WEBP') {
+    return { extension: '.webp', mediaType: 'image/webp' };
+  }
+  throw new Error('Generated bytes are not a supported PNG, JPEG, or WebP image');
+}
+
+async function saveImage(args, bytes) {
+  const detected = detectImage(bytes);
+  const sha = createHash('sha256').update(bytes).digest('hex');
+  const generatedName = `generated-${sha.slice(0, 8)}${detected.extension}`;
+  const output = args.output
+    ? resolve(args.output)
+    : resolve(process.env.PRISMER_ARTIFACTS_DIR || process.cwd(), generatedName);
+  if (args.output && extname(output).toLowerCase() !== detected.extension) {
+    throw new Error(`--output extension must match generated ${detected.mediaType} bytes (${detected.extension})`);
+  }
+  await mkdir(dirname(output), { recursive: true });
+  await writeFile(output, bytes);
+  return { output, sha, mediaType: detected.mediaType };
+}
+
+async function deliver(output) {
+  const cloudBin = process.env.PRISMER_CLOUD_BIN || 'cloud';
+  let stdout;
+  try {
+    ({ stdout } = await execFileAsync(cloudBin, ['deliver', output, '--json'], {
+      encoding: 'utf8',
+      timeout: 120_000,
+      maxBuffer: 1024 * 1024,
+    }));
+  } catch (error) {
+    const detail = typeof error?.stderr === 'string' ? error.stderr.trim() : error.message;
+    throw new Error(`cloud deliver failed: ${detail}`);
+  }
+  let result;
+  try {
+    result = JSON.parse(stdout);
+  } catch {
+    throw new Error(`cloud deliver returned non-JSON output: ${stdout.slice(0, 200)}`);
+  }
+  if (result?.ok !== true) throw new Error(`cloud deliver rejected the image: ${result?.error || 'unknown error'}`);
+  if (result.status === 202 || result.queued === true) return { status: 'queued', receipt: result };
+  if (typeof result.assetId !== 'string' || result.assetId.length === 0) {
+    throw new Error('cloud deliver returned ok without an assetId or queued receipt');
+  }
+  if (result.ridesReply === false) return { status: 'uploaded-unattached', receipt: result };
+  return { status: 'delivered', receipt: result };
+}
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+  if (args.help) {
+    process.stdout.write(`${usage()}\n`);
+    return;
+  }
+  const auth = await resolveAuth(args);
+  const preferred = args.model || process.env.IMAGE_GEN_MODEL;
+  const models = await discoverModels(auth, preferred, args.size);
+  if (models.length === 0) throw new Error('No image generation models are available');
+  const generated = await generate(auth, args, models);
+  const saved = await saveImage(args, generated.bytes);
+  const delivery = await deliver(saved.output);
+  if (delivery.status === 'queued') {
+    process.stdout.write(
+      `[image-generate] queued file=${saved.output} model=${generated.model} size=${args.size} sha=${saved.sha.slice(0, 12)}; upload pending reconnect\n`,
+    );
+    return;
+  }
+  if (delivery.status === 'uploaded-unattached') {
+    process.stdout.write(
+      `[image-generate] uploaded-unattached file=${saved.output} assetId=${delivery.receipt.assetId} model=${generated.model} size=${args.size} sha=${saved.sha.slice(0, 12)}; no reply dispatch was available\n`,
+    );
+    return;
+  }
+  process.stdout.write(
+    `[image-generate] delivered file=${saved.output} assetId=${delivery.receipt.assetId} model=${generated.model} size=${args.size} sha=${saved.sha.slice(0, 12)}\n`,
+  );
+}
+
+main().catch((error) => {
+  process.stderr.write(`[image-generate] ${error instanceof Error ? error.message : String(error)}\n`);
+  process.exitCode = 1;
+});

package/built-in-skills/ingest/SKILL.md

@@ -0,0 +1,73 @@
+---
+name: ingest
+scope: common
+description: Turn external web URLs into LLM-ready content — load + cache web pages (HQCC compression) and search the web. Use whenever the user gives a URL, asks you to read a webpage, or wants top-K pages on a topic. Executes via the `cloud load` and `cloud search` CLIs. For local document parsing (PDF text + OCR), use the `liteparse` skill instead.
+---
+
+# Ingest
+
+Use this skill to **bring external web content into the LLM context window** without copy-pasting raw HTML or burning tokens on uncompressed prose:
+
+- **Web content** → `cloud load` / `cloud search` → returns HQCC (a compressed, LLM-optimized form). Cache hits are free.
+
+> **Local documents (PDF text extraction + OCR) are handled by the `liteparse` skill**, not here — it's a local-first, zero-network tool with Tesseract + PDFium bundled. `ingest` covers web URLs only.
+
+> If your runtime registers the `workspace_web_search` / `web_load` tools (Hermes agents do), prefer them over the CLI — same workspace-billed cloud lane (`/api/context/load`). Never script HTTP via `execute_code`/subprocess for web research.
+
+## When to use
+
+- The user pastes a URL or asks "what does this page say".
+- The user asks to research a topic ("AI agent frameworks 2025") — use `search` to fetch top-K relevant pages.
+- A task description contains URLs that need to be resolved into actual content before the assignee can act.
+
+> Attached PDFs / images / scans → use the `liteparse` skill (local-first PDF text + OCR), not `ingest`.
+
+## CLI Reference
+
+```bash
+# Single URL → HQCC
+cloud load https://example.com
+cloud load https://example.com --format raw     # exact wording / code / tables (more tokens)
+
+# Batch (up to 50 URLs)
+cloud load https://a.com https://b.com https://c.com
+
+# Search → load (fetch top-K relevant pages)
+cloud search "AI agent frameworks 2025"
+cloud search "topic" -k 10
+
+# Pre-save to cache (e.g. content you scraped elsewhere)
+cloud context save https://example.com "compressed content"
+```
+
+## Workflow
+
+### For web URLs
+
+1. Decide: single URL load? Batch? Or search query?
+2. Default to `--format hqcc` (compressed). Use `raw` only when **exact wording, code, or tables** are needed.
+3. Run `cloud load` / `cloud search` and capture: source URLs, titles, cache status, cost.
+4. Base downstream reasoning **only on the returned content**. If a load failed, say so; don't pretend you read it.
+
+## Operating Rules
+
+### Load / Search
+
+- **Prefer cached context.** Don't re-process the same source — the service handles cache lookup automatically; just don't re-issue identical loads in tight loops.
+- Preserve **source URLs** in your notes and citations. The HQCC return retains origin pointers; use them.
+- Don't claim to have read a source until the load **succeeds**. If it fails (404, blocked, timeout), report the failed URL and continue only with clearly stated assumptions or ask for a better source.
+- `--format raw` costs more tokens. Only use when the user needs exact wording (legal text, code snippets, tables that compress badly).
+- For batch loads, the service runs them concurrently up to a limit; you don't need to throttle yourself.
+- For a document / image / scan (not a web page), hand off to the `liteparse` skill — `ingest` does not do OCR or PDF extraction.
+
+## Output reporting
+
+After load/search:
+- One-line summary per source: `<title> · <url> · cache_hit | fresh · <cost>`
+- Then proceed with the user's actual question, citing the source by URL.
+
+## Backing capabilities (D22 mapping)
+
+Replaces the v1.x built-in skill `context-load`. Local document OCR /
+extraction (formerly `parse-document`, backed by the now-retired
+`parser.prismer.dev` service) moved to the local-first `liteparse` skill.