@semalt-ai/code 1.8.5 → 1.19.0

package/lib/images.js

@@ -0,0 +1,264 @@
+'use strict';
+
+// ---------------------------------------------------------------------------
+// Multimodal image input (Task 5.4)
+// ---------------------------------------------------------------------------
+//
+// Accept image input (screenshots, mockups, diagrams) so the agent can SEE.
+// This module owns the pure, testable parts: reading an image file through the
+// same `isPathSafe` guard every file read uses, enforcing a size cap, detecting
+// the media type, base64-encoding, and building the PROVIDER-SPECIFIC content
+// part the endpoint expects. The api client (lib/api.js) consumes these to
+// transform a user turn's content into a multimodal `content[]` array.
+//
+// Scope (decided): input formats PNG, JPEG, WebP, GIF. PDF is DEFERRED and image
+// GENERATION is out of scope entirely — this is multimodal *input* only.
+//
+// Provider-format selection (constraint #1). Endpoints encode image input two
+// ways:
+//   * Anthropic-style: { type: 'image', source: { type: 'base64', media_type,
+//                        data } }
+//   * OpenAI-style:    { type: 'image_url', image_url: { url:
+//                        'data:<media_type>;base64,<data>' } }
+//   The shape is chosen per model/profile by `selectImageFormat`, precedence:
+//     1. the matching models[] profile's `image_format`
+//     2. top-level `config.image_format`
+//     3. heuristic: an Anthropic-native api_base → 'anthropic', else 'openai'
+//        (the project's OpenAI-compatible lingua franca is the default).
+//
+// Vision capability (constraint #2) — FAIL LOUD, never silently drop the image.
+//   `resolveVisionCapability` returns true | false | null. `false` (a profile or
+//   config marked non-vision, or a well-known text-only model) → the caller
+//   raises a clear error before sending. `null` (unknown) → proceed and let the
+//   endpoint reject cleanly. We NEVER strip the image from the payload.
+
+const fs = require('fs');
+const path = require('path');
+
+const { DEFAULT_IMAGE_MAX_BYTES } = require('./constants');
+
+// Supported input formats. Extension → media type for the magic-byte fallback.
+const EXT_MEDIA_TYPES = {
+  '.png': 'image/png',
+  '.jpg': 'image/jpeg',
+  '.jpeg': 'image/jpeg',
+  '.webp': 'image/webp',
+  '.gif': 'image/gif',
+};
+
+const SUPPORTED_MEDIA_TYPES = new Set(['image/png', 'image/jpeg', 'image/webp', 'image/gif']);
+
+const VALID_FORMATS = new Set(['anthropic', 'openai']);
+
+// Detect the media type from the file's MAGIC BYTES first (authoritative — a
+// .png that is really a JPEG is classified as JPEG), falling back to the file
+// extension when the header is inconclusive. Returns a supported media type
+// string or null (caller errors on null).
+function detectMediaType(buf, filePath) {
+  if (Buffer.isBuffer(buf) && buf.length >= 12) {
+    // PNG: 89 50 4E 47 0D 0A 1A 0A
+    if (buf[0] === 0x89 && buf[1] === 0x50 && buf[2] === 0x4e && buf[3] === 0x47) return 'image/png';
+    // JPEG: FF D8 FF
+    if (buf[0] === 0xff && buf[1] === 0xd8 && buf[2] === 0xff) return 'image/jpeg';
+    // GIF: 47 49 46 38 ("GIF8" — GIF87a / GIF89a)
+    if (buf[0] === 0x47 && buf[1] === 0x49 && buf[2] === 0x46 && buf[3] === 0x38) return 'image/gif';
+    // WebP: "RIFF" <4-byte size> "WEBP"
+    if (buf[0] === 0x52 && buf[1] === 0x49 && buf[2] === 0x46 && buf[3] === 0x46 &&
+        buf[8] === 0x57 && buf[9] === 0x45 && buf[10] === 0x42 && buf[11] === 0x50) return 'image/webp';
+  }
+  const ext = path.extname(filePath || '').toLowerCase();
+  return EXT_MEDIA_TYPES[ext] || null;
+}
+
+// Read an image from disk for attachment to a user turn. It is a file read, so
+// it goes through the SAME `isPathSafe` guard (out-of-CWD / sensitive dirs
+// refused) every other file read uses. Enforces the raw-byte size cap (base64
+// inflates ~33%; a clear pre-send error beats an opaque endpoint rejection),
+// detects the media type, and base64-encodes. Throws a clear Error on any
+// failure (unsafe path, missing/unreadable, oversize, unsupported format).
+//
+// Returns { path, media_type, data (base64), bytes }.
+function readImage(filePath, { maxBytes = DEFAULT_IMAGE_MAX_BYTES, isPathSafe, fsImpl = fs } = {}) {
+  if (typeof filePath !== 'string' || !filePath.trim()) {
+    throw new Error('Image path is empty.');
+  }
+  // Same confinement as every file read: refuse out-of-CWD / sensitive dirs.
+  if (typeof isPathSafe === 'function' && !isPathSafe(filePath)) {
+    throw new Error(`Image path outside allowed area: ${filePath}. Use --allow-anywhere to override.`);
+  }
+  let stat;
+  try { stat = fsImpl.statSync(filePath); }
+  catch { throw new Error(`Image not found or unreadable: ${filePath}`); }
+  if (!stat.isFile()) throw new Error(`Not a file: ${filePath}`);
+  // Cap on the RAW bytes (before base64). A clear error here, not an opaque
+  // endpoint failure on an oversized payload.
+  if (Number.isFinite(maxBytes) && maxBytes > 0 && stat.size > maxBytes) {
+    throw new Error(
+      `Image too large: ${filePath} is ${stat.size} bytes, exceeds the ${maxBytes}-byte cap ` +
+      `(image_max_bytes). Base64 inflates the payload ~33%; resize the image or raise the cap.`,
+    );
+  }
+  let buf;
+  try { buf = fsImpl.readFileSync(filePath); }
+  catch { throw new Error(`Image not found or unreadable: ${filePath}`); }
+  const mediaType = detectMediaType(buf, filePath);
+  if (!mediaType) {
+    throw new Error(
+      `Unsupported image format: ${filePath}. Supported: PNG, JPEG, WebP, GIF ` +
+      `(PDF and image generation are out of scope).`,
+    );
+  }
+  return { path: filePath, media_type: mediaType, data: buf.toString('base64'), bytes: stat.size };
+}
+
+// Read a list of image paths, preserving order. Throws on the FIRST failure so
+// the user gets a clear, specific error rather than a partial attach.
+function readImages(paths, opts = {}) {
+  return (paths || []).map((p) => readImage(p, opts));
+}
+
+// Normalize a list of mixed image inputs to encoded image records. Accepts a
+// file-path string, a { path } object (both read via readImage through the size
+// + path guards), or an already-encoded { media_type, data } object (so an SDK
+// host can pass bytes it produced itself). Used by the SDK `images` option.
+function resolveImageInputs(images, opts = {}) {
+  return (images || []).map((img) => {
+    if (typeof img === 'string') return readImage(img, opts);
+    if (img && typeof img === 'object' && typeof img.data === 'string' && typeof img.media_type === 'string') {
+      if (!SUPPORTED_MEDIA_TYPES.has(img.media_type)) {
+        throw new Error(`Unsupported image media type: ${img.media_type}. Supported: PNG, JPEG, WebP, GIF.`);
+      }
+      return { path: img.path || '(inline)', media_type: img.media_type, data: img.data, bytes: img.bytes || 0 };
+    }
+    if (img && typeof img === 'object' && typeof img.path === 'string') return readImage(img.path, opts);
+    throw new Error('Invalid image input: expected a file path or { media_type, data } object.');
+  });
+}
+
+// Find the models[] profile backing the active model. Prefers an api_base +
+// model match (the exact active profile), then any profile with that model name.
+function activeProfile(config, model) {
+  if (!config || !Array.isArray(config.models)) return null;
+  return (
+    config.models.find((p) => p && p.model === model && p.api_base === config.api_base) ||
+    config.models.find((p) => p && p.model === model) ||
+    null
+  );
+}
+
+// Choose the provider-specific content-part shape. See the header for the
+// precedence: profile → config → heuristic (Anthropic-native base → 'anthropic',
+// else the OpenAI-compatible default).
+function selectImageFormat(config = {}, model = '') {
+  const profile = activeProfile(config, model);
+  if (profile && VALID_FORMATS.has(profile.image_format)) return profile.image_format;
+  if (VALID_FORMATS.has(config.image_format)) return config.image_format;
+  const base = String(config.api_base || '');
+  if (/(^|\.)anthropic\.com/i.test(base) || /anthropic/i.test(base)) return 'anthropic';
+  return 'openai';
+}
+
+// Well-known NON-vision model families (embeddings, audio, moderation): images
+// to these can never work, so we fail loud rather than send a doomed payload.
+const KNOWN_TEXT_ONLY = /(?:^|[-/_])(?:text-embedding|embedding|embed|whisper|tts|moderation|rerank|reranker)/i;
+// Well-known vision-capable families: a positive signal so an attach proceeds
+// without needing per-profile config.
+const KNOWN_VISION = /(gpt-4o|gpt-4\.1|gpt-4-vision|gpt-4-turbo|claude-3|claude-opus|claude-sonnet|claude-haiku|claude-fable|claude-4|gemini|llava|qwen[\d.]*-?vl|pixtral|llama[-\d.]*(?:-)?vision|internvl|minicpm-v|-vl\b|vision|multimodal)/i;
+
+// Determine vision capability from config/model metadata where available.
+//   true  — accept the image
+//   false — a CLEAR pre-send error (profile/config marked non-vision, or a
+//           well-known text-only model)
+//   null  — unknown; proceed and surface the endpoint's rejection cleanly
+function resolveVisionCapability(config = {}, model = '') {
+  const profile = activeProfile(config, model);
+  if (profile && typeof profile.vision === 'boolean') return profile.vision;
+  if (typeof config.vision === 'boolean') return config.vision;
+  const m = String(model || '');
+  if (KNOWN_TEXT_ONLY.test(m)) return false;
+  if (KNOWN_VISION.test(m)) return true;
+  return null;
+}
+
+// Build a single provider-specific image content part.
+function buildImagePart(image, format) {
+  if (format === 'anthropic') {
+    return { type: 'image', source: { type: 'base64', media_type: image.media_type, data: image.data } };
+  }
+  // OpenAI-style data URL is the default for any OpenAI-compatible endpoint.
+  return { type: 'image_url', image_url: { url: `data:${image.media_type};base64,${image.data}` } };
+}
+
+// Build a multimodal user-message content array: the text part (when non-empty)
+// followed by one image part per attached image.
+function buildMultimodalContent(text, images, format) {
+  const parts = [];
+  const t = text == null ? '' : String(text);
+  if (t) parts.push({ type: 'text', text: t });
+  for (const img of (images || [])) parts.push(buildImagePart(img, format));
+  return parts;
+}
+
+// True when any message carries attached images.
+function messagesHaveImages(messages) {
+  return Array.isArray(messages) && messages.some((m) => m && Array.isArray(m.images) && m.images.length);
+}
+
+// Count all attached images across the message list (for error messages).
+function countImages(messages) {
+  let n = 0;
+  for (const m of (messages || [])) {
+    if (m && Array.isArray(m.images)) n += m.images.length;
+  }
+  return n;
+}
+
+// Transform messages for the wire: any message with attached `images` becomes a
+// provider-specific multimodal `content[]` array; the internal `images` field is
+// stripped from every message. Messages without images pass through unchanged.
+// Pure — returns a new array, leaving the caller's messages intact.
+function buildProviderMessages(messages, format) {
+  return (messages || []).map((m) => {
+    if (m && Array.isArray(m.images) && m.images.length) {
+      const { images, ...rest } = m;
+      return { ...rest, content: buildMultimodalContent(m.content, images, format) };
+    }
+    if (m && typeof m === 'object' && 'images' in m) {
+      const { images, ...rest } = m;
+      return rest;
+    }
+    return m;
+  });
+}
+
+// Attach images to the most recent user message (mutating the array in place by
+// replacing that entry). No-op when there are no images. Used by entry points
+// after they read/encode the images.
+function attachImagesToLastUser(messages, images) {
+  if (!Array.isArray(messages) || !images || !images.length) return messages;
+  for (let i = messages.length - 1; i >= 0; i--) {
+    if (messages[i] && messages[i].role === 'user') {
+      const prior = Array.isArray(messages[i].images) ? messages[i].images : [];
+      messages[i] = { ...messages[i], images: prior.concat(images) };
+      return messages;
+    }
+  }
+  return messages;
+}
+
+module.exports = {
+  EXT_MEDIA_TYPES,
+  SUPPORTED_MEDIA_TYPES,
+  detectMediaType,
+  readImage,
+  readImages,
+  resolveImageInputs,
+  selectImageFormat,
+  resolveVisionCapability,
+  buildImagePart,
+  buildMultimodalContent,
+  messagesHaveImages,
+  countImages,
+  buildProviderMessages,
+  attachImagesToLastUser,
+};

package/lib/internals.js

@@ -0,0 +1,49 @@
+'use strict';
+
+// ---------------------------------------------------------------------------
+// Building blocks — the UNSTABLE internals subpath (Task 5.2)
+// ---------------------------------------------------------------------------
+//
+//   ⚠ NO STABILITY GUARANTEE ⚠
+//
+// Everything exported here is an internal building block of @semalt-ai/code.
+// It is exposed via the SEPARATE `@semalt-ai/code/internals` subpath precisely
+// so that the stable facade (`require('@semalt-ai/code')` → createAgent) can be
+// kept narrow and intentional while these factories remain free to change.
+//
+// These names, their signatures, and their behaviour MAY CHANGE OR BE REMOVED
+// IN ANY RELEASE, including patch releases. They are NOT covered by semver. If
+// you build on them you own the breakage. For supported embedding use the
+// stable facade:
+//
+//     const { createAgent } = require('@semalt-ai/code');
+//
+// Reach for /internals only when the facade genuinely cannot express what you
+// need — and pin an exact version if you do.
+
+module.exports = {
+  // The agent loop factory.
+  createAgentRunner: require('./agent').createAgentRunner,
+  // OpenAI-compatible + dashboard HTTP client.
+  createApiClient: require('./api').createApiClient,
+  // Tool execution + XML tool-call extraction.
+  createToolExecutor: require('./tools').createToolExecutor,
+  extractToolCalls: require('./tools').extractToolCalls,
+  // Permission perimeter.
+  createPermissionManager: require('./permissions').createPermissionManager,
+  // Per-pattern rule engine (Task 4.1).
+  loadRuleLayers: require('./permission-rules').loadRuleLayers,
+  resolvePermission: require('./permission-rules').resolvePermission,
+  // Tool registry (static + dynamic).
+  toolRegistry: require('./tool_registry'),
+  // Config layering.
+  config: require('./config'),
+  // Headless output envelope helpers.
+  headless: require('./headless'),
+  // MCP client manager.
+  createMcpManager: require('./mcp/client').createMcpManager,
+  // The shared UI surface (no-op in non-TTY).
+  ui: require('./ui'),
+  // An explicit, machine-readable marker that this is the unstable surface.
+  __unstable__: true,
+};

package/lib/mcp/boundary.js

@@ -0,0 +1,131 @@
+'use strict';
+
+// MCP boundary module (Task 3.2)
+// -----------------------------------------------------------------------------
+// The official MCP SDK (`@modelcontextprotocol/sdk`) is the project's first — and
+// so far only — runtime dependency. It is **ESM-only** (`"type": "module"`, no
+// CommonJS entry points), but this project is CommonJS: a CJS module cannot
+// `require()` an ESM-only package.
+//
+// This module is the SINGLE place that bridges the gap. It loads the SDK via
+// dynamic `import()` (the one mechanism CJS has for pulling in ESM) and re-exposes
+// a small, CommonJS-friendly **async** surface. Every other file in the codebase
+// stays plain CommonJS and talks to MCP through this boundary — no other module
+// imports the SDK directly. That keeps the ESM/CJS friction contained to one file
+// and means the rest of the project never has to change its module system.
+//
+// The dynamic import is memoized: the SDK's ESM graph is evaluated at most once
+// per process, on first use (lazy — importing this module costs nothing until a
+// boundary function is actually called). Task 3.3 builds the MCP client on top of
+// the helpers here.
+
+const { PACKAGE_JSON } = require('../constants');
+
+// The SDK subpaths we consume. The SDK exposes deep subpath exports
+// (`./client/index.js`, `./client/stdio.js`, …) rather than a single barrel, so
+// we import exactly what we use.
+const CLIENT_SUBPATH = '@modelcontextprotocol/sdk/client/index.js';
+const STDIO_SUBPATH = '@modelcontextprotocol/sdk/client/stdio.js';
+const HTTP_SUBPATH = '@modelcontextprotocol/sdk/client/streamableHttp.js';
+const SSE_SUBPATH = '@modelcontextprotocol/sdk/client/sse.js';
+
+let _sdkPromise = null;
+
+// Lazily load + memoize the SDK's client surface. `import()` is the ONLY bridge
+// from this CommonJS module to the ESM-only package — do not try to `require()`
+// the SDK anywhere. Returns just the named exports the rest of the code needs.
+async function loadSdk() {
+  if (!_sdkPromise) {
+    _sdkPromise = (async () => {
+      const [clientMod, stdioMod] = await Promise.all([
+        import(CLIENT_SUBPATH),
+        import(STDIO_SUBPATH),
+      ]);
+      return {
+        Client: clientMod.Client,
+        StdioClientTransport: stdioMod.StdioClientTransport,
+      };
+    })();
+    // If the import rejects (e.g. the dependency is not installed), clear the
+    // cache so a later call can retry rather than re-throwing a stale rejection.
+    _sdkPromise.catch(() => { _sdkPromise = null; });
+  }
+  return _sdkPromise;
+}
+
+// Whether the SDK is resolvable in this environment (installed in node_modules).
+// Synchronous and side-effect-free: used by the smoke test to skip gracefully
+// when the dependency could not be installed (e.g. an offline CI runner) instead
+// of failing the suite.
+function isSdkAvailable() {
+  try {
+    require.resolve(CLIENT_SUBPATH);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// Default identity advertised to MCP servers during the connect handshake.
+const DEFAULT_CLIENT_INFO = Object.freeze({
+  name: PACKAGE_JSON.name,
+  version: PACKAGE_JSON.version,
+});
+
+// Instantiate an MCP `Client`. Does NOT connect — Task 3.3 owns transport wiring
+// and the `connect()` handshake. `clientInfo` defaults to this CLI's identity;
+// `options` defaults to declaring no client capabilities.
+async function createClient(clientInfo, options) {
+  const { Client } = await loadSdk();
+  return new Client(
+    clientInfo || { ...DEFAULT_CLIENT_INFO },
+    options || { capabilities: {} },
+  );
+}
+
+// Construct a stdio transport for launching a local MCP server subprocess.
+// `params` is the SDK's `StdioServerParameters` ({ command, args, env, … }).
+// When the caller supplies `env`, it is MERGED over the SDK's default safe
+// environment (getDefaultEnvironment) rather than replacing it — otherwise the
+// child would lose PATH/HOME and fail to launch most real servers.
+async function createStdioTransport(params) {
+  const stdioMod = await import(STDIO_SUBPATH);
+  const { StdioClientTransport, getDefaultEnvironment } = stdioMod;
+  const merged = { ...params };
+  if (params && params.env && typeof getDefaultEnvironment === 'function') {
+    merged.env = { ...getDefaultEnvironment(), ...params.env };
+  }
+  return new StdioClientTransport(merged);
+}
+
+// Construct a Streamable-HTTP transport for a remote MCP server. `url` is a URL
+// (or string); `opts` is the SDK's `StreamableHTTPClientTransportOptions`
+// ({ authProvider, requestInit, … }). OAuth is wired through `opts.authProvider`.
+async function createStreamableHttpTransport(url, opts) {
+  const mod = await import(HTTP_SUBPATH);
+  return new mod.StreamableHTTPClientTransport(url instanceof URL ? url : new URL(url), opts);
+}
+
+// Construct a legacy HTTP+SSE transport for a remote MCP server. Same shape as
+// the streamable-HTTP transport; used for servers that only speak the older
+// SSE protocol.
+async function createSseTransport(url, opts) {
+  const mod = await import(SSE_SUBPATH);
+  return new mod.SSEClientTransport(url instanceof URL ? url : new URL(url), opts);
+}
+
+// Test seam: drop the memoized import so a fresh load can be exercised.
+function _reset() {
+  _sdkPromise = null;
+}
+
+module.exports = {
+  loadSdk,
+  isSdkAvailable,
+  createClient,
+  createStdioTransport,
+  createStreamableHttpTransport,
+  createSseTransport,
+  DEFAULT_CLIENT_INFO,
+  _reset,
+};