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 +6 -0
- package/index.d.ts +21 -1
- package/index.mjs +74 -4
- package/package.json +13 -4
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
|
-
|
|
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
|
-
/**
|
|
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
|
-
|
|
264
|
-
|
|
265
|
-
this._reply(id,
|
|
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.
|
|
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": [
|
|
16
|
-
|
|
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
|
}
|