@0xmaxma/claude-gateway 1.5.7 → 1.6.0

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.7",
+  "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"
   ],