graphrt-plugin 0.1.0 → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -28,3 +28,9 @@ Pair it with a `graphrt-plugin.json` manifest; see `docs/plugins.md`.
28
28
  - `ctx.chunk(field, text)`, `ctx.progress(name, data)`, `ctx.log(message)`.
29
29
  - `ctx.signal` aborts when the host cancels the request.
30
30
  - Never `console.log` (stdout carries the protocol); use `console.error`.
31
+ - Tools can return images for the model:
32
+ `{ text, images: [{ media_type: "image/png", data: pngBuffer }] }` (or
33
+ `data_base64`, or `{ url: "https://..." }`); at most 4, png/jpeg/webp/gif,
34
+ 5 MiB each. Hosts without image support get the text plus a note instead.
35
+
36
+ Tests: `npm test` (Node's built-in runner).
package/index.d.ts CHANGED
@@ -61,7 +61,27 @@ export interface ToolSpec {
61
61
  parameters?: Record<string, unknown>;
62
62
  }
63
63
 
64
- export type ToolResult = string | { text: string; data?: unknown; is_error?: boolean };
64
+ /** Feature a host lists in `initialize` when tool results may carry `images`. */
65
+ export declare const TOOL_IMAGES_FEATURE: "tool_images";
66
+ export declare const MAX_TOOL_IMAGES: number;
67
+ export declare const MAX_TOOL_IMAGE_BYTES: number;
68
+ export declare const TOOL_IMAGE_MEDIA_TYPES: string[];
69
+
70
+ export type ToolImageMediaType = "image/png" | "image/jpeg" | "image/webp" | "image/gif";
71
+
72
+ /** An image shown to the model with a tool result (at most 4; 5 MiB each). */
73
+ export type ToolImage =
74
+ | { media_type: ToolImageMediaType; data_base64: string }
75
+ | { media_type: ToolImageMediaType; data: Uint8Array }
76
+ | { url: string };
77
+
78
+ export type ToolResult = string | { text: string; data?: unknown; is_error?: boolean; images?: ToolImage[] };
79
+
80
+ /** Normalize a handler result into a `tool.call` result (images dropped with a note for older hosts). */
81
+ export declare function toolResult(
82
+ result: ToolResult | null | undefined,
83
+ options?: { hostSupportsImages?: boolean },
84
+ ): { text: string; data?: unknown; is_error: boolean; images?: Array<{ media_type: string; data_base64: string } | { url: string }> };
65
85
 
66
86
  export type NodeHandler = (
67
87
  ctx: RunContext,
package/index.mjs CHANGED
@@ -32,6 +32,64 @@ const RESULT_KEYS = new Set(["outputs", "branch", "writes", "usage", "metadata",
32
32
  /** Default line limit; the host announces its own in `initialize` (`max_message_bytes`). */
33
33
  export const MAX_MESSAGE_BYTES = 16 * 1024 * 1024;
34
34
 
35
+ /** Feature a host lists in `initialize` when tool results may carry `images`. */
36
+ export const TOOL_IMAGES_FEATURE = "tool_images";
37
+ /** Tool result image limits (the host enforces the same). */
38
+ export const MAX_TOOL_IMAGES = 4;
39
+ export const MAX_TOOL_IMAGE_BYTES = 5 * 1024 * 1024;
40
+ export const TOOL_IMAGE_MEDIA_TYPES = ["image/png", "image/jpeg", "image/webp", "image/gif"];
41
+
42
+ const BASE64_RE = /^[A-Za-z0-9+/]*={0,2}$/;
43
+
44
+ /** One `images` entry as sent on the wire: `{media_type, data_base64}` or `{url}`. */
45
+ function encodeImage(image, index) {
46
+ const fail = (message) => {
47
+ throw new PluginError(`image #${index}: ${message}`, { kind: "invalid_output" });
48
+ };
49
+ if (image === null || typeof image !== "object") fail("must be an object");
50
+ if (image.url !== undefined) {
51
+ if (typeof image.url !== "string" || !/^https:\/\//i.test(image.url)) fail("`url` must start with https://");
52
+ return { url: image.url };
53
+ }
54
+ const mediaType = image.media_type ?? image.mediaType;
55
+ if (!TOOL_IMAGE_MEDIA_TYPES.includes(mediaType)) {
56
+ fail(`media type \`${mediaType}\` is not supported (use ${TOOL_IMAGE_MEDIA_TYPES.join(", ")})`);
57
+ }
58
+ let data = image.data_base64 ?? image.dataBase64;
59
+ let size;
60
+ if (data === undefined && image.data instanceof Uint8Array) {
61
+ size = image.data.byteLength;
62
+ data = Buffer.from(image.data.buffer, image.data.byteOffset, image.data.byteLength).toString("base64");
63
+ } else if (typeof data === "string" && data.length % 4 !== 1 && BASE64_RE.test(data)) {
64
+ size = Math.floor((data.replace(/=+$/, "").length * 3) / 4);
65
+ } else {
66
+ fail("give `data_base64` (a base64 string) or `data` (a Buffer / Uint8Array)");
67
+ }
68
+ if (size === 0) fail("image data is empty");
69
+ if (size > MAX_TOOL_IMAGE_BYTES) fail(`image is ${size} bytes, above the ${MAX_TOOL_IMAGE_BYTES}-byte limit`);
70
+ return { media_type: mediaType, data_base64: data };
71
+ }
72
+
73
+ /** Normalize a tool handler's return value into a `tool.call` result. */
74
+ export function toolResult(result, { hostSupportsImages = true } = {}) {
75
+ if (typeof result === "string") result = { text: result };
76
+ const { images, ...rest } = result ?? {};
77
+ const out = { text: "", is_error: false, ...rest };
78
+ if (images === undefined || images === null) return out;
79
+ if (!Array.isArray(images)) throw new PluginError("`images` must be an array", { kind: "invalid_output" });
80
+ if (images.length > MAX_TOOL_IMAGES) {
81
+ throw new PluginError(`${images.length} images in one tool result, above the limit of ${MAX_TOOL_IMAGES}`, { kind: "invalid_output" });
82
+ }
83
+ if (images.length === 0) return out;
84
+ if (!hostSupportsImages) {
85
+ const note = `[${images.length} image(s) omitted: the graphrt host does not support image tool results]`;
86
+ out.text = out.text ? `${out.text}\n${note}` : note;
87
+ return out;
88
+ }
89
+ out.images = images.map(encodeImage);
90
+ return out;
91
+ }
92
+
35
93
  /** Best-effort request id from a line that could not be read. */
36
94
  function recoverId(text) {
37
95
  const match = /"id"\s*:\s*("(?:[^"\\]|\\.)*"|-?\d+)/.exec(text.slice(0, 4096));
@@ -105,6 +163,7 @@ export class Plugin {
105
163
  this._tools = new Map();
106
164
  this._running = new Map();
107
165
  this._maxMessageBytes = MAX_MESSAGE_BYTES;
166
+ this._hostFeatures = [];
108
167
  }
109
168
 
110
169
  /**
@@ -118,7 +177,11 @@ export class Plugin {
118
177
  return this;
119
178
  }
120
179
 
121
- /** Register a tool `async (args) => string | {text, data?, is_error?}`. */
180
+ /**
181
+ * Register a tool `async (args) => string | {text, data?, is_error?, images?}`.
182
+ * `images` entries are `{media_type, data_base64}`, `{media_type, data: Buffer}`
183
+ * or `{url: "https://..."}`; at most 4, png/jpeg/webp/gif, 5 MiB each.
184
+ */
122
185
  tool(spec, handler) {
123
186
  this._tools.set(spec.name, { spec: { description: "", parameters: { type: "object" }, ...spec }, handler });
124
187
  return this;
@@ -194,6 +257,7 @@ export class Plugin {
194
257
  if (Number.isInteger(params.max_message_bytes) && params.max_message_bytes >= 1024) {
195
258
  this._maxMessageBytes = params.max_message_bytes;
196
259
  }
260
+ this._hostFeatures = Array.isArray(params.features) ? params.features : [];
197
261
  const result = { protocol_version: PROTOCOL_VERSION, name: this.name };
198
262
  if (this._descriptors.length) result.nodes = this._descriptors;
199
263
  if (this._tools.size) result.tools = [...this._tools.values()].map((t) => t.spec);
@@ -260,9 +324,9 @@ export class Plugin {
260
324
  return;
261
325
  }
262
326
  try {
263
- let result = await tool.handler(params.arguments ?? {});
264
- if (typeof result === "string") result = { text: result };
265
- this._reply(id, { text: "", is_error: false, ...(result ?? {}) });
327
+ const result = await tool.handler(params.arguments ?? {});
328
+ const hostSupportsImages = this._hostFeatures.includes(TOOL_IMAGES_FEATURE);
329
+ this._reply(id, toolResult(result, { hostSupportsImages }));
266
330
  } catch (e) {
267
331
  if (!(e instanceof PluginError)) console.error(e);
268
332
  this._error(id, -32000, e instanceof Error ? e.message : String(e), errorData(e));
@@ -304,6 +368,12 @@ export class Plugin {
304
368
  this._error(id, -32000, `result is not valid JSON: ${e instanceof Error ? e.message : String(e)}`, { kind: "invalid_output" });
305
369
  return;
306
370
  }
371
+ // A line above the host's limit would break the connection: report it instead.
372
+ const size = Buffer.byteLength(line);
373
+ if (size > this._maxMessageBytes) {
374
+ this._error(id, -32000, `result is ${size} bytes, above the ${this._maxMessageBytes}-byte message limit`, { kind: "message_too_large" });
375
+ return;
376
+ }
307
377
  this._output.write(line + "\n");
308
378
  }
309
379
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "graphrt-plugin",
3
- "version": "0.1.0",
3
+ "version": "0.2.0",
4
4
  "description": "SDK for writing graphrt plugins in JavaScript / TypeScript (no dependencies)",
5
5
  "license": "Apache-2.0",
6
6
  "type": "module",
@@ -12,10 +12,19 @@
12
12
  "import": "./index.mjs"
13
13
  }
14
14
  },
15
- "files": ["index.mjs", "index.d.ts", "README.md"],
16
- "engines": { "node": ">=18" },
15
+ "files": [
16
+ "index.mjs",
17
+ "index.d.ts",
18
+ "README.md"
19
+ ],
20
+ "scripts": {
21
+ "test": "node --test"
22
+ },
23
+ "engines": {
24
+ "node": ">=18"
25
+ },
17
26
  "repository": {
18
27
  "type": "git",
19
- "url": "https://github.com/BimaPangestu28/graphrt"
28
+ "url": "git+https://github.com/BimaPangestu28/graphrt.git"
20
29
  }
21
30
  }