@0xmaxma/claude-gateway 1.5.8 → 1.6.0

package/mcp/tools/line/module.ts

@@ -10,9 +10,34 @@
  * is passed, and fall back to push if it's absent or expired/used (the single-use
  * token has no guaranteed lifetime — ~1 min — so push remains the safety net).
  */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
 import type { ToolModule, McpToolDefinition, McpToolResult, ToolVisibility } from '../../types';
 import { messagingApi } from '@line/bot-sdk';
 import { chunkText, planLineSend, LINE_TEXT_LIMIT } from './pure';
+import { createShares, ShareClientError, shareBridgeEnabled } from '../shared/share-client';
+
+/** Default lifetime of a share URL handed to LINE (1 hour). */
+const DEFAULT_MEDIA_URL_TTL_MS = 60 * 60 * 1000;
+
+/**
+ * Convert a media path (absolute under the agent media root, or already relative
+ * like "media/<chat>/<file>.png") to the "media/…"-relative form the gateway's
+ * signed-URL route expects. Returns null if it cannot be resolved to the media root.
+ */
+function toRelativeMediaPath(p: string): string | null {
+  if (!p) return null;
+  const normalized = p.replace(/\\/g, '/');
+  if (!path.isAbsolute(normalized)) {
+    return normalized.startsWith('media/') ? normalized : `media/${normalized.replace(/^\/+/, '')}`;
+  }
+  const workspace = process.env.GATEWAY_WORKSPACE_DIR;
+  if (!workspace) return null;
+  const mediaRoot = path.resolve(workspace, '..', 'media');
+  const rel = path.relative(mediaRoot, path.resolve(normalized));
+  if (rel.startsWith('..') || path.isAbsolute(rel)) return null;
+  return `media/${rel.split(path.sep).join('/')}`;
+}
 
 export class LineModule implements ToolModule {
   id = 'line';
@@ -54,11 +79,43 @@ export class LineModule implements ToolModule {
           required: ['chat_id', 'text'],
         },
       },
+      {
+        name: 'line_image',
+        description:
+          'Send an image to the current LINE user. Pass chat_id (the LINE userId from the ' +
+          '<channel> tag) and image (a media path saved by the gateway, e.g. a generate_image ' +
+          'result path or a "media/…" path). LINE can only fetch public HTTPS URLs, so the tool ' +
+          'mints a signed, short-lived public URL for the file and sends it as an image message. ' +
+          'Pass reply_token from the <channel> tag when present to send for FREE (falls back to push).',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            chat_id: {
+              type: 'string',
+              description: 'LINE userId to send to (the chat_id from the channel turn).',
+            },
+            image: {
+              type: 'string',
+              description: 'Media path of the image (absolute path under the agent media dir, or a "media/…" relative path).',
+            },
+            preview: {
+              type: 'string',
+              description: 'Optional separate preview-image media path. Defaults to the same image.',
+            },
+            reply_token: {
+              type: 'string',
+              description: 'Optional single-use reply token from the <channel> tag (sends free; falls back to push).',
+            },
+          },
+          required: ['chat_id', 'image'],
+        },
+      },
     ];
   }
 
   async handleTool(name: string, args: Record<string, unknown>): Promise<McpToolResult> {
     if (name === 'line_reply') return this.handleReply(args);
+    if (name === 'line_image') return this.handleImage(args);
     return { content: [{ type: 'text', text: `Unknown tool: ${name}` }], isError: true };
   }
 
@@ -124,4 +181,133 @@ export class LineModule implements ToolModule {
       };
     }
   }
+
+  /**
+   * Send an image to LINE. LINE's servers fetch the image over public HTTPS (the
+   * normal media route is API-key-gated), so we mint a short-lived share token via
+   * the gateway share bridge — the SAME `/shared/:token` primitive the image tools
+   * use — and hand LINE the resulting public URL. The host comes from `.public-base`
+   * (derived by the gateway from the inbound webhook); the token is host-agnostic,
+   * so we simply prepend that base to `/shared/<token>`.
+   */
+  private async handleImage(args: Record<string, unknown>): Promise<McpToolResult> {
+    const chatId = typeof args.chat_id === 'string' ? args.chat_id : '';
+    const image = typeof args.image === 'string' ? args.image : '';
+    const preview = typeof args.preview === 'string' && args.preview ? args.preview : image;
+    const replyToken = typeof args.reply_token === 'string' ? args.reply_token : '';
+    const token = process.env.LINE_CHANNEL_ACCESS_TOKEN ?? '';
+
+    if (!chatId) {
+      return { content: [{ type: 'text', text: 'line_image: missing chat_id' }], isError: true };
+    }
+    if (!image) {
+      return { content: [{ type: 'text', text: 'line_image: image path is required' }], isError: true };
+    }
+    // Fail fast on a missing LINE token BEFORE any file IO or share mint, so a
+    // misconfigured pod never mints a throwaway share it can't deliver.
+    if (!token) {
+      return { content: [{ type: 'text', text: 'line_image: missing LINE_CHANNEL_ACCESS_TOKEN' }], isError: true };
+    }
+
+    // Public base URL is derived by the gateway from the inbound LINE webhook and
+    // written to `<workspace>/../.public-base` (no public-base-URL env var). Read it
+    // here at call-time; if it isn't there yet the pod hasn't seen a webhook, so
+    // ask the user to send another message rather than pushing a broken URL.
+    const workspace = process.env.GATEWAY_WORKSPACE_DIR;
+    if (!workspace) {
+      return {
+        content: [{ type: 'text', text: 'line_image: GATEWAY_WORKSPACE_DIR not set' }],
+        isError: true,
+      };
+    }
+    let publicBase = '';
+    try {
+      publicBase = fs
+        .readFileSync(path.resolve(workspace, '..', '.public-base'), 'utf8')
+        .trim()
+        .replace(/\/+$/, '');
+    } catch {
+      publicBase = '';
+    }
+    if (!publicBase) {
+      return {
+        content: [{ type: 'text', text: 'line_image: public base not resolved yet (send a message again)' }],
+        isError: true,
+      };
+    }
+    // The share bridge (the same authenticated local gateway API the image tools
+    // use) needs the session identity injected into this subprocess. Missing it =
+    // image delivery isn't wired up on this pod.
+    if (!shareBridgeEnabled()) {
+      return {
+        content: [{ type: 'text', text: 'line_image: image delivery not configured (share bridge unavailable)' }],
+        isError: true,
+      };
+    }
+
+    const relImage = toRelativeMediaPath(image);
+    const relPreview = toRelativeMediaPath(preview);
+    if (!relImage || !relPreview) {
+      return {
+        content: [{ type: 'text', text: `line_image: could not resolve media path to the agent media root: ${image}` }],
+        isError: true,
+      };
+    }
+
+    const ttlMs = Number(process.env.GATEWAY_MEDIA_URL_TTL_MS) > 0
+      ? Number(process.env.GATEWAY_MEDIA_URL_TTL_MS)
+      : DEFAULT_MEDIA_URL_TTL_MS;
+    const ttlSeconds = Math.max(10, Math.ceil(ttlMs / 1000));
+
+    // Mint one share per ref (order preserved). Identical refs dedupe to the same
+    // token within the store's idempotency window — fine, LINE gets a valid URL.
+    let originalContentUrl: string;
+    let previewImageUrl: string;
+    try {
+      const items = await createShares(
+        [{ path: relImage }, { path: relPreview }],
+        { purpose: 'line', ttlSeconds },
+      );
+      if (!items[0]?.token || !items[1]?.token) {
+        throw new ShareClientError('share_failed', 'share response missing token', 500);
+      }
+      originalContentUrl = `${publicBase}/shared/${items[0].token}`;
+      previewImageUrl = `${publicBase}/shared/${items[1].token}`;
+    } catch (err) {
+      const msg = err instanceof ShareClientError ? `${err.code}: ${err.message}` : String(err);
+      return {
+        content: [{ type: 'text', text: `line_image: failed to mint share URL — ${msg}` }],
+        isError: true,
+      };
+    }
+
+    const message = {
+      type: 'image' as const,
+      originalContentUrl,
+      previewImageUrl,
+    };
+
+    const client = new messagingApi.MessagingApiClient({ channelAccessToken: token });
+
+    let via = 'push';
+    try {
+      if (replyToken) {
+        try {
+          await client.replyMessage({ replyToken, messages: [message] });
+          via = 'reply';
+        } catch {
+          await client.pushMessage({ to: chatId, messages: [message] });
+          via = 'push (reply fallback)';
+        }
+      } else {
+        await client.pushMessage({ to: chatId, messages: [message] });
+      }
+      return { content: [{ type: 'text', text: `Sent image to LINE (${via}).` }] };
+    } catch (err) {
+      return {
+        content: [{ type: 'text', text: `line_image failed: ${(err as Error).message}` }],
+        isError: true,
+      };
+    }
+  }
 }

package/mcp/tools/share-image/module.ts

@@ -0,0 +1,120 @@
+import type { ToolModule, McpToolDefinition, McpToolResult, ToolVisibility } from '../../types';
+import {
+  ShareClientError,
+  createShares,
+  revokeShare,
+  shareBridgeEnabled,
+  type ShareRef,
+} from '../shared/share-client';
+
+/**
+ * Standalone share_image MCP tool (#70, plan §15) — explicit create/revoke of
+ * short-lived public image URLs. There is deliberately NO list action (shares
+ * are unenumerable, §10). generate_image auto-normalizes refs through the same
+ * gateway API, so normal image editing never needs this tool; it exists for
+ * explicit workflows (e.g. handing a temporary URL to an external service).
+ */
+export class ShareImageModule implements ToolModule {
+  id = 'share-image';
+  toolVisibility: ToolVisibility = 'all-configured';
+
+  isEnabled(): boolean {
+    return shareBridgeEnabled();
+  }
+
+  getTools(): McpToolDefinition[] {
+    return shareImageToolDefs;
+  }
+
+  async handleTool(name: string, args: Record<string, unknown>): Promise<McpToolResult> {
+    if (name !== 'share_image') {
+      return { content: [{ type: 'text', text: `Unknown tool: ${name}` }], isError: true };
+    }
+    const action = typeof args.action === 'string' ? args.action : 'create';
+    switch (action) {
+      case 'create':
+        return this.handleCreate(args);
+      case 'revoke':
+        return this.handleRevoke(args);
+      default:
+        return {
+          content: [{ type: 'text', text: `share_image: unknown action "${action}" (expected create | revoke)` }],
+          isError: true,
+        };
+    }
+  }
+
+  private async handleCreate(args: Record<string, unknown>): Promise<McpToolResult> {
+    const single = typeof args.path === 'string' && args.path.trim() ? [args.path.trim()] : [];
+    const many = Array.isArray(args.paths)
+      ? (args.paths.filter((p) => typeof p === 'string' && p.trim()) as string[])
+      : [];
+    if (single.length && many.length) {
+      return { content: [{ type: 'text', text: 'share_image: pass either "path" or "paths", not both.' }], isError: true };
+    }
+    const paths = single.length ? single : many;
+    if (!paths.length) {
+      return { content: [{ type: 'text', text: 'share_image: action="create" requires "path" or "paths".' }], isError: true };
+    }
+    const refs: ShareRef[] = paths.map((p) =>
+      p.startsWith('artifact:') ? { artifact_id: p.slice('artifact:'.length) } : { path: p },
+    );
+    const opts: { purpose?: string; ttlSeconds?: number } = {};
+    if (typeof args.purpose === 'string' && args.purpose.trim()) opts.purpose = args.purpose.trim();
+    if (typeof args.ttl_seconds === 'number' && args.ttl_seconds > 0) opts.ttlSeconds = args.ttl_seconds;
+    try {
+      const items = await createShares(refs, opts);
+      return { content: [{ type: 'text', text: JSON.stringify({ items }, null, 2) }] };
+    } catch (err) {
+      return this.mapError(err);
+    }
+  }
+
+  private async handleRevoke(args: Record<string, unknown>): Promise<McpToolResult> {
+    const shareId = typeof args.share_id === 'string' ? args.share_id.trim() : '';
+    if (!shareId) {
+      return { content: [{ type: 'text', text: 'share_image: action="revoke" requires "share_id".' }], isError: true };
+    }
+    try {
+      await revokeShare(shareId);
+      return { content: [{ type: 'text', text: JSON.stringify({ revoked: true, share_id: shareId }) }] };
+    } catch (err) {
+      return this.mapError(err);
+    }
+  }
+
+  private mapError(err: unknown): McpToolResult {
+    if (err instanceof ShareClientError) {
+      return { content: [{ type: 'text', text: `share_image: ${err.code}: ${err.message}` }], isError: true };
+    }
+    return {
+      content: [{ type: 'text', text: `share_image: gateway unavailable: ${(err as Error).message}` }],
+      isError: true,
+    };
+  }
+}
+
+const shareImageToolDefs: McpToolDefinition[] = [
+  {
+    name: 'share_image',
+    description:
+      'Create or revoke a SHORT-LIVED public URL for an image in this agent\'s media directory. ' +
+      'action="create" takes "path" (one media path or artifact:<id>) or "paths" (up to 5) and returns ' +
+      '{ share_id, url, expires_at } per image — the URL needs no auth and expires automatically (default 30 min). ' +
+      'action="revoke" takes "share_id" and invalidates the URL immediately. ' +
+      'You normally do NOT need this for image editing: generate_image converts local/artifact references ' +
+      'to share URLs automatically. There is no list action.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        action: { type: 'string', enum: ['create', 'revoke'], description: 'create (default) | revoke' },
+        path: { type: 'string', description: 'One media path (e.g. "media/session-1/image.png") or "artifact:<id>" to share.' },
+        paths: { type: 'array', items: { type: 'string' }, description: 'Multiple media paths / artifact refs (max 5).' },
+        ttl_seconds: { type: 'number', description: 'Optional lifetime in seconds (default 1800).' },
+        purpose: { type: 'string', description: 'Optional purpose tag (default "codex_ref").' },
+        share_id: { type: 'string', description: 'Share id to revoke (required for action="revoke").' },
+      },
+      required: [],
+    },
+  },
+];

package/mcp/tools/shared/share-client.ts

@@ -0,0 +1,197 @@
+/**
+ * Image share bridge client (#70) — the ONLY way MCP subprocesses touch the
+ * share/artifact store. They call the authenticated local Gateway HTTP API
+ * (GATEWAY_API_URL + GATEWAY_API_KEY, both already injected into the session
+ * subprocess env) and NEVER open the SQLite DB themselves (plan §9/§10).
+ *
+ * Self-contained on purpose: mcp/** ships as source without src/**, so this
+ * module must not import from src/ (see tests/unit/mcp-no-src-imports.test.ts).
+ */
+
+const REQUEST_TIMEOUT_MS = 15_000;
+
+export type ShareRef = { artifact_id?: string; path?: string };
+
+export type ShareItem = { share_id: string; token: string; url?: string; expires_at: string };
+
+export type ArtifactItem = { artifact_id: string; artifact_ref: string; index: number; path: string };
+
+/**
+ * One entry of the session image catalog (#72). `index` is 1-based and stable —
+ * it is the order of FIRST appearance of that file in the session, so "image 1"
+ * / "the first image" maps to index 1 deterministically. `ref` is what to feed
+ * back into generate_image's image/images argument.
+ */
+export type CatalogItem = {
+  index: number;
+  ref: string;
+  relative_path: string;
+  origin: string;
+  ts: number;
+  available: boolean;
+  /** What the image is: the generation prompt (origin=generated) or the user
+   *  text that accompanied the upload. Absent when neither exists. */
+  desc?: string;
+};
+
+/** Error carrying the gateway's stable machine-readable code (e.g. image_ref_not_found). */
+export class ShareClientError extends Error {
+  readonly code: string;
+  readonly status: number;
+  constructor(code: string, message: string, status: number) {
+    super(message);
+    this.code = code;
+    this.status = status;
+  }
+}
+
+/**
+ * The bridge client is usable when the gateway API identity reached this
+ * subprocess. gateway.publicUrl is the sole server-side enable switch: when it
+ * is absent the private mint endpoint is not mounted and calls fail closed.
+ */
+export function shareBridgeEnabled(): boolean {
+  return (
+    !!process.env.GATEWAY_API_URL &&
+    !!process.env.GATEWAY_API_KEY &&
+    !!process.env.GATEWAY_AGENT_ID &&
+    !!process.env.GATEWAY_SESSION_ID
+  );
+}
+
+function apiBase(): string {
+  return (process.env.GATEWAY_API_URL ?? '').replace(/\/+$/, '');
+}
+
+async function callGateway(
+  method: 'GET' | 'POST' | 'DELETE',
+  pathname: string,
+  body?: Record<string, unknown>,
+): Promise<{ status: number; json: Record<string, unknown> }> {
+  const res = await fetch(`${apiBase()}${pathname}`, {
+    method,
+    headers: {
+      'Content-Type': 'application/json',
+      Authorization: `Bearer ${process.env.GATEWAY_API_KEY}`,
+    },
+    body: body ? JSON.stringify(body) : undefined,
+    signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+  });
+  const text = await res.text().catch(() => '');
+  let json: Record<string, unknown> = {};
+  try {
+    json = JSON.parse(text) as Record<string, unknown>;
+  } catch {
+    /* non-JSON body */
+  }
+  return { status: res.status, json };
+}
+
+/** Mint short-lived share URLs for local/artifact refs — order preserved. */
+export async function createShares(
+  refs: ShareRef[],
+  opts: { purpose?: string; ttlSeconds?: number } = {},
+): Promise<ShareItem[]> {
+  const body: Record<string, unknown> = {
+    agent_id: process.env.GATEWAY_AGENT_ID,
+    session_id: process.env.GATEWAY_SESSION_ID,
+    purpose: opts.purpose ?? 'codex_ref',
+    refs,
+  };
+  if (opts.ttlSeconds !== undefined) body.ttl_seconds = opts.ttlSeconds;
+  const { status, json } = await callGateway('POST', '/api/v1/shares', body);
+  if (status !== 201) {
+    const code = typeof json.code === 'string' ? json.code : 'share_failed';
+    const message = typeof json.error === 'string' ? json.error : `share request failed (HTTP ${status})`;
+    throw new ShareClientError(code, message, status);
+  }
+  const items = json.items;
+  if (!Array.isArray(items)) throw new ShareClientError('share_failed', 'invalid share response', status);
+  return items as ShareItem[];
+}
+
+/**
+ * Read the ground-truth catalog of every image in this session (#72), numbered
+ * by first appearance. Read-only: no token is minted and nothing is persisted.
+ * Callers must check shareBridgeEnabled() first (same contract as createShares).
+ */
+export async function listSessionImages(): Promise<CatalogItem[]> {
+  const query =
+    `agent_id=${encodeURIComponent(process.env.GATEWAY_AGENT_ID ?? '')}` +
+    `&session_id=${encodeURIComponent(process.env.GATEWAY_SESSION_ID ?? '')}`;
+  const { status, json } = await callGateway('GET', `/api/v1/image-catalog?${query}`);
+  if (status !== 200) {
+    const { code, message } = extractError(json, `image catalog request failed (HTTP ${status})`, 'catalog_failed');
+    throw new ShareClientError(code, message, status);
+  }
+  const items = json.items;
+  if (!Array.isArray(items)) throw new ShareClientError('catalog_failed', 'invalid catalog response', status);
+  return items as CatalogItem[];
+}
+
+/**
+ * Pull a { code, message } out of a gateway error body. The private routes are
+ * not uniform: some return { error: "text", code: "x" } (share mint) and some
+ * return { error: { code, message } } (image service style), so accept both and
+ * fall back to the supplied defaults.
+ */
+function extractError(
+  json: Record<string, unknown>,
+  fallbackMessage: string,
+  fallbackCode: string,
+): { code: string; message: string } {
+  let code = typeof json.code === 'string' ? json.code : '';
+  let message = typeof json.error === 'string' ? json.error : '';
+  const err = json.error;
+  if (err && typeof err === 'object') {
+    const nested = err as { code?: unknown; message?: unknown };
+    if (!code && typeof nested.code === 'string') code = nested.code;
+    if (!message && typeof nested.message === 'string') message = nested.message;
+  }
+  return { code: code || fallbackCode, message: message || fallbackMessage };
+}
+
+/** Revoke a share by id. Throws ShareClientError on failure. */
+export async function revokeShare(shareId: string): Promise<void> {
+  const { status, json } = await callGateway('DELETE', `/api/v1/shares/${encodeURIComponent(shareId)}`);
+  if (status !== 200) {
+    const message = typeof json.error === 'string' ? json.error : `revoke failed (HTTP ${status})`;
+    throw new ShareClientError('revoke_failed', message, status);
+  }
+}
+
+/** Best-effort revoke of freshly minted shares (used when submit fails, §18). */
+export async function revokeSharesBestEffort(shareIds: string[]): Promise<void> {
+  for (const id of shareIds) {
+    try {
+      await revokeShare(id);
+    } catch {
+      /* best-effort — TTL still bounds exposure */
+    }
+  }
+}
+
+/**
+ * Register generated image files as private artifacts (§8). Best-effort: on
+ * any failure returns null so image delivery itself never breaks.
+ */
+export async function registerArtifacts(
+  files: string[],
+  meta: { provider: string; model: string; taskId?: string; prompt?: string },
+): Promise<ArtifactItem[] | null> {
+  try {
+    const { status, json } = await callGateway('POST', '/api/v1/image-artifacts', {
+      agent_id: process.env.GATEWAY_AGENT_ID,
+      session_id: process.env.GATEWAY_SESSION_ID,
+      provider: meta.provider,
+      model: meta.model,
+      ...(meta.taskId ? { task_id: meta.taskId } : {}),
+      ...(meta.prompt ? { prompt: meta.prompt } : {}),
+      files,
+    });
+    if (status !== 201 || !Array.isArray(json.items)) return null;
+    return json.items as ArtifactItem[];
+  } catch {
+    return null;
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@0xmaxma/claude-gateway",
-  "version": "1.5.8",
+  "version": "1.6.0",
   "description": "Multi-agent gateway for Claude",
   "repository": {
     "type": "git",
@@ -18,6 +18,8 @@
     "lib/",
     "resource/",
     "mcp/",
+    "!mcp/node_modules",
+    "!mcp/node_modules/**",
     "README.md",
     "config.template.json"
   ],