@embededitor/relay 0.0.0-stage → 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,9 @@
+# Changelog
+
+Every change to `@embededitor/relay`, newest first.
+
+## [0.1.0] - 2026-11-11
+
+### Added
+
+- The relay of Embed Editor's agent link, for one process on your own server: `createRelay` takes its settings as plain values (`allowedOrigins`, `agentSessionSecret`, `publicOrigin`) and gives the relay served on its own (`listen`), or its Hono app and the editor's socket server to serve yourself.

package/LICENSE.md

@@ -0,0 +1,9 @@
+# MIT License
+
+Copyright (c) 2026 Rohde Softwares
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -1,3 +1,88 @@
-# Temporary Holding Version
+# @embededitor/relay
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The relay of [Embed Editor](https://embededitor.com)'s agent link, to run on your own server.
+
+With the agent link, your users' own AI agent (Claude, ChatGPT, Codex, Cursor) edits the photo open in your editor. They copy a link from the editor, paste it into their agent with a request ("blur the faces"), and watch each change land. The relay is the small server in between: the editor connects to it, the agent calls it over MCP, and it passes each call to the editor and the answer back. It keeps no photo and no call.
+
+You don't need it to use the agent link: every editor links through Embed Editor's relay, at `https://agent.embededitor.com`. Run your own when:
+
+- the link and How to Connect must show your own address (a white-label editor);
+- only your signed-in users may make a link;
+- the agent's calls must pass only through your own servers.
+
+**Docs:** [Your Own Relay](https://docs.embededitor.com/agent-link/relay), step by step · [Agent Link](https://docs.embededitor.com/agent-link/overview) · [Protocol](https://docs.embededitor.com/agent-link/protocol)
+
+> **Prototype.** The agent link isn't in a released edition yet, and this package may change before it is.
+
+## Install
+
+```bash
+npm install @embededitor/relay
+```
+
+It runs on Node 20 or later.
+
+## Use
+
+```js
+import { createRelay } from '@embededitor/relay';
+
+const relay = createRelay({
+	agentSessionSecret: null,
+	allowedOrigins: ['https://shop.example.com'],
+	publicOrigin: 'https://agent.shop.example.com'
+});
+
+relay.listen(8788);
+```
+
+Then:
+
+1. Put the relay at a public HTTPS address of its own, like `https://agent.shop.example.com`, behind your reverse proxy or hosting platform. It needs WebSockets.
+2. Give your editor that address, with the agent link on: `<EmbedEditor agentRelay='https://agent.shop.example.com' enableAgent />`.
+3. Connect your agent to `https://agent.shop.example.com/mcp`. In Claude Code: `claude mcp add --transport http photo-editor https://agent.shop.example.com/mcp`. The editor's **How to Connect** shows your users the same steps.
+
+## Settings
+
+`createRelay` takes plain values. Write them in the code, or read them from wherever you keep your configuration.
+
+| Setting | What it does |
+|---|---|
+| `allowedOrigins` | The pages whose editor makes its own link: an exact origin (`'https://shop.example.com'`), every subdomain of a domain (`'https://*.shop.example.com'`, not the domain itself), or `'*'` for every page. `[]`: no page makes one. |
+| `agentSessionSecret` | A secret your backend sends as `Authorization: Bearer <secret>` to make a link for a signed-in user, so no page makes one on its own. A value from `openssl rand -hex 32`, kept in your secret store, never in git or a page. `null`: no backend makes one. |
+| `publicOrigin` | The address the links name, the one your users' browsers and agents reach. `null`: the address each request came in on. Set it behind a proxy, or when your backend calls the relay on an internal address. |
+
+With no page in `allowedOrigins` and no `agentSessionSecret`, the relay makes no link.
+
+For links made by your backend, for signed-in users only, with the editor's `onAgentLink`, see [Only Signed-In Users](https://docs.embededitor.com/agent-link/relay#only-signed-in-users).
+
+## In Your Own Server
+
+`createRelay` also gives the relay's [Hono](https://hono.dev) app and the editor's socket server, to serve them yourself:
+
+```js
+import { createRelay } from '@embededitor/relay';
+import { serve } from '@hono/node-server';
+
+const { app, websocket } = createRelay({ agentSessionSecret: null, allowedOrigins: ['https://shop.example.com'], publicOrigin: null });
+
+serve({ fetch: app.fetch, port: 8788, websocket });
+```
+
+The relay answers at the root of its address, so give it a host of its own. Every link lives in the process's memory: run one process per relay.
+
+## Limits
+
+| Limit | Value |
+|---|---|
+| A link's lifetime | 2 hours |
+| A tab away before its link ends | 2 minutes |
+| A call's wait for the editor | 55 s |
+| An ended link's record, so a late call hears why | 1 hour |
+| A message from the editor (a whole-photo screenshot is about 113 KB) | 8 MiB |
+
+The relay keeps only each link token's SHA-256. Its log names each command, its time and its size, never the token or what a call carried.
+
+## License
+
+MIT, © Rohde Softwares.

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+declare const createRelay: ({ agentSessionSecret, allowedOrigins, publicOrigin }: import("./relay.js").RelaySettings) => {
+    app: import("hono").Hono<import("hono/types").BlankEnv, import("hono/types").BlankSchema, "/">;
+    listen: (port: number) => import("@hono/node-server").ServerType;
+    websocket: {
+        server: import("ws").Server<typeof import("ws").default, typeof import("http").IncomingMessage>;
+    };
+};
+export type { RelaySettings } from './relay.js';
+export { createRelay };

package/dist/index.js

@@ -0,0 +1,5 @@
+// @embededitor/relay: Embed Editor's agent link relay, to run on your own server (README.md,
+// https://docs.embededitor.com/agent-link/relay)
+import relay from './relay.js';
+const { createRelay } = relay;
+export { createRelay };

package/dist/relay.d.ts

@@ -0,0 +1,17 @@
+import { Hono } from 'hono';
+type RelaySettings = {
+    agentSessionSecret: string | null;
+    allowedOrigins: string[];
+    publicOrigin: string | null;
+};
+export type { RelaySettings };
+declare const _default: {
+    createRelay: ({ agentSessionSecret, allowedOrigins, publicOrigin }: RelaySettings) => {
+        app: Hono<import("hono/types").BlankEnv, import("hono/types").BlankSchema, "/">;
+        listen: (port: number) => import("@hono/node-server").ServerType;
+        websocket: {
+            server: import("ws").Server<typeof import("ws").default, typeof import("http").IncomingMessage>;
+        };
+    };
+};
+export default _default;

package/dist/relay.js

@@ -0,0 +1,547 @@
+// Embed Editor's agent link relay in one process, on Hono, built from the protocol page (docs/agent-link/protocol.mdx),
+// published as @embededitor/relay. Every session lives in this process's memory, a map from the token's hash to its
+// session, so a process holds one relay. createRelay takes its settings as plain values, from wherever the integrator
+// keeps them, and gives the relay served on its own (listen) or the Hono app and the editor's socket server to mount in
+// their own server. Everything is web standard (Request, Response, Web Crypto) but Node's server and the editor's
+// socket: @hono/node-server's serve and upgradeWebSocket, with ws under them
+import { bodyLimit } from 'hono/body-limit';
+import { CallToolRequestSchema, ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js';
+import { Hono } from 'hono';
+import { serve, upgradeWebSocket } from '@hono/node-server';
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { WebSocketServer } from 'ws';
+import { WebStandardStreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/webStandardStreamableHttp.js';
+const BEARER = /^Bearer\s+(\S+)$/i;
+const CALL_TIMEOUT = 55 * 1000;
+const CLOSE_ENDED = 4000;
+const CLOSE_REPLACED = 4001;
+const CLOSE_SILENT = 4002;
+// the end of a link may come from any page: its token is its proof
+const END_CORS_HEADERS = { 'access-control-allow-headers': 'content-type', 'access-control-allow-methods': 'POST, OPTIONS', 'access-control-allow-origin': '*' };
+const ENDED_KEPT = 60 * 60 * 1000;
+const ENDED_TEXTS = {
+    DISCONNECTED: 'The person disconnected you from their editor. Ask them for a new link if they want you to keep editing.',
+    EXPIRED: 'This editor link expired. Ask the person for a new link from their editor.',
+    TAB_CLOSED: "The editor's tab was closed, so this link ended. Ask the person for a new link from their editor."
+};
+// the allowedOrigins entry that names every page, whatever its origin: a relay open to any site's editor
+const EVERY_PAGE = '*';
+const FORBIDDEN = {
+    error: 'FORBIDDEN',
+    message: "A link is made by the editor on a page this relay allows (allowedOrigins), or by your server with the relay's secret (Authorization: Bearer <agentSessionSecret>)."
+};
+const GUIDE = [
+    "You are connected to the person's Embed Editor, open in their browser tab. They watch every change you make as you make it.",
+    'How to work:',
+    "1. Call read_size for the image's size, then read_screenshot to see the photo. Every coordinate a command takes is in image px, as read_size gives them; each screenshot comes with a note saying how its px map to image px.",
+    '2. After you place something, look again (read_screenshot, with `area` to zoom on the spot) and correct it with the update command of what you placed.',
+    "3. Every edit is one undo step: history_undo takes back the last one, yours or the person's.",
+    '4. Save (output_save) only when the person asks for it.',
+    'Each command below runs with run_command: its name, and its input as its inputSchema says.'
+].join('\n');
+// the subdomain a pattern's `*` stands for: one or more labels, nothing a port, a path or credentials could hide in
+const LABELS = /^[a-z0-9-]+(\.[a-z0-9-]+)*$/i;
+const LINK_LIFETIME = 2 * 60 * 60 * 1000;
+// the page a person sees opening the link in a browser: the MCP address from the page's own origin, and the token after
+// the # never reaches the relay
+const LINK_PAGE = [
+    '<!doctype html><html lang="en"><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1">',
+    '<title>Embed Editor agent link</title>',
+    '<body style="background:#111;color:#eee;font:16px/1.5 system-ui,sans-serif;margin:0;padding:32px;max-width:640px">',
+    '<h1 style="font-size:20px">This is an Embed Editor agent link</h1>',
+    "<p>Paste it into an AI agent that has the Embed Editor MCP server connected (Claude Desktop, Claude Code). The agent then edits the photo open in your editor's tab, and you watch it happen there.</p>",
+    '<p>The MCP server\'s address is <code id="mcp"></code>.</p>',
+    "<script>document.getElementById('mcp').textContent = location.origin + '/mcp'</script>",
+    '</body></html>'
+].join('');
+// the body of POST /sessions/end is a token and a flag: anything far larger is not one
+const MAX_END_BODY = 4096;
+// a 1024 px JPEG in base64, inside JSON, with room to spare
+const MAX_MESSAGE = 8 * 1024 * 1024;
+const NO_NAME = "run_command takes the command's name, as list_commands gives it.";
+const NOT_A_LINK = "That isn't an Embed Editor link. Ask the person to copy the link the editor shows, and pass it whole.";
+const NOT_CONNECTED = "The editor's tab is not connected right now (it may be in the background, asleep, or offline). Ask the person to bring the tab back, then try again.";
+const NOT_VALID = "This editor link isn't valid. Ask the person to copy it again from their editor.";
+// what an MCP client hears for anything but a POST: a GET would open a stream nothing writes to, and there is no session
+// to DELETE
+const ONLY_POST = { error: { code: -32000, message: 'Method not allowed: this server takes a POST for each call.' }, id: null, jsonrpc: '2.0' };
+const PROTOCOL = 'ee-agent';
+const RECONNECT_GRACE = 2 * 60 * 1000;
+const SOCKET_STALE = 25 * 1000;
+// an allowedOrigins entry for every subdomain of a domain, `scheme://*.domain[:port]`: its scheme and its domain captured
+const SUBDOMAINS = /^([a-z][a-z0-9+.-]*):\/\/\*\.(.+)$/i;
+const TOKEN = /^[A-Za-z0-9_-]{40,}$/;
+const encoder = new TextEncoder();
+const sessions = new Map();
+// the editor's sockets on Node: the subprotocol ee-agent echoed, as a browser requires, and up to MAX_MESSAGE a message
+const wss = new WebSocketServer({
+    handleProtocols: () => {
+        return PROTOCOL;
+    },
+    maxPayload: MAX_MESSAGE,
+    noServer: true
+});
+// the editor's socket on its session: a newer one replaces the open one (4001), and one on a session that ended or
+// doesn't exist is closed at once with 4000 and why. Whether the session took it
+const acceptSocket = ({ hash, ws }) => {
+    const session = sessions.get(hash);
+    if (!session || session.endedReason) {
+        ws.close(CLOSE_ENDED, session?.endedReason ?? 'EXPIRED');
+        return false;
+    }
+    const replaced = session.socket;
+    clearTimeout(session.graceTimer);
+    session.heardAt = Date.now();
+    session.socket = ws;
+    replaced?.close(CLOSE_REPLACED, 'REPLACED');
+    if (session.connected) {
+        sendMessage(ws, { type: 'AGENT_CONNECTED' });
+    }
+    return true;
+};
+// the request's Origin when an allowedOrigins entry names it (covers), or null
+const allowedOrigin = ({ allowedOrigins, headers }) => {
+    const origin = headers.get('origin');
+    const listed = allowedOrigins.some(entry => {
+        return !!origin && covers({ entry, origin });
+    });
+    return origin && listed ? origin : null;
+};
+// Authorization: Bearer <agentSessionSecret>: both hashed and the digests compared with no early exit, so the answer's
+// time says nothing of how much matched. Without a secret, never
+const authorized = async ({ agentSessionSecret, headers }) => {
+    const authorization = headers.get('authorization') ?? '';
+    const match = BEARER.exec(authorization);
+    if (!agentSessionSecret || !match) {
+        return false;
+    }
+    const [given, expected] = await Promise.all([digest(match[1]), digest(agentSessionSecret)]);
+    let diff = 0;
+    for (let i = 0; i < given.length; i += 1) {
+        diff |= given[i] ^ expected[i];
+    }
+    return diff === 0;
+};
+// one run_command: the CALL to the editor, and its result, or why none came within 55 s
+const callEditor = ({ input, name, session, socket }) => {
+    const id = crypto.randomUUID();
+    return new Promise(resolve => {
+        const timer = setTimeout(() => {
+            const res = errorResult(`The editor didn't answer ${name} within ${CALL_TIMEOUT / 1000} s. Take a screenshot to see whether it ran.`);
+            session.calls.delete(id);
+            resolve(res);
+        }, CALL_TIMEOUT);
+        const settle = (res) => {
+            clearTimeout(timer);
+            session.calls.delete(id);
+            resolve(res);
+        };
+        session.calls.set(id, { name, settle });
+        sendMessage(socket, { id, input, name, type: 'CALL' });
+    });
+};
+// a tools/call: the link first, then the tool; run_command's name before its session
+const callTool = async ({ arguments: args = {}, name }) => {
+    const token = readToken(args.link);
+    if (!token) {
+        return errorResult(NOT_A_LINK);
+    }
+    const hash = await hashToken(token);
+    if (name === 'list_commands') {
+        return listCommands(hash);
+    }
+    if (name === 'run_command') {
+        return runCommand({ args, hash });
+    }
+    return errorResult(`No tool ${name}: this server has list_commands and run_command.`);
+};
+// whether an allowedOrigins entry names a page's origin: `*` every one, else that origin exactly, or, for
+// `scheme://*.domain[:port]`, an origin of that scheme on a subdomain of that domain, at that port (never the domain
+// itself)
+const covers = ({ entry, origin }) => {
+    if (entry === EVERY_PAGE) {
+        return true;
+    }
+    const [, scheme = '', domain = ''] = SUBDOMAINS.exec(entry) ?? [];
+    if (!scheme) {
+        return entry === origin;
+    }
+    const prefix = `${scheme}://`;
+    const suffix = `.${domain}`;
+    if (!origin.startsWith(prefix) || !origin.endsWith(suffix)) {
+        return false;
+    }
+    const subdomain = origin.slice(prefix.length, origin.length - suffix.length);
+    return LABELS.test(subdomain);
+};
+// a fresh MCP server for one request, as stateless Streamable HTTP has it
+const createMcpServer = (origin) => {
+    const text = instructions(origin);
+    const tools = mcpTools(origin);
+    const server = new Server({ name: 'embed-editor', version: '0.0.0' }, { capabilities: { tools: {} }, instructions: text });
+    server.setRequestHandler(ListToolsRequestSchema, () => {
+        return { tools };
+    });
+    server.setRequestHandler(CallToolRequestSchema, req => {
+        return callTool(req.params);
+    });
+    return server;
+};
+// the relay on `settings`: served on its own (listen), or its routes on a Hono app and the editor's socket server, for a
+// server of yours to serve (serve's `fetch` and `websocket`) or mount
+const createRelay = ({ agentSessionSecret, allowedOrigins, publicOrigin }) => {
+    const app = new Hono();
+    // makes a link, for a page in allowedOrigins or a backend with the secret
+    app.all('/sessions', async (c) => {
+        const origin = allowedOrigin({ allowedOrigins, headers: c.req.raw.headers });
+        const headers = { vary: 'origin' };
+        if (origin) {
+            headers['access-control-allow-headers'] = 'content-type';
+            headers['access-control-allow-methods'] = 'POST, OPTIONS';
+            headers['access-control-allow-origin'] = origin;
+        }
+        if (c.req.method === 'OPTIONS') {
+            return c.body(null, 204, headers);
+        }
+        if (c.req.method !== 'POST') {
+            return c.text('Method not allowed', 405, headers);
+        }
+        const allowed = await authorized({ agentSessionSecret, headers: c.req.raw.headers });
+        if (!origin && !allowed) {
+            return c.json(FORBIDDEN, 403, headers);
+        }
+        const { session, token } = await createSession();
+        const relay = relayOrigin({ publicOrigin, url: c.req.url });
+        return c.json({ expiresAt: session.expiresAt, link: `${relay}/link#${token}`, token }, 200, headers);
+    });
+    // ends a link at once: the person's Disconnect, or the tab closing (closed: true), by fetch or sendBeacon as text
+    app.all('/sessions/end', bodyLimit({
+        maxSize: MAX_END_BODY,
+        onError: c => {
+            return c.text('Expected a token', 400, END_CORS_HEADERS);
+        }
+    }), async (c) => {
+        if (c.req.method === 'OPTIONS') {
+            return c.body(null, 204, END_CORS_HEADERS);
+        }
+        const text = c.req.method === 'POST' ? await c.req.text() : '';
+        const body = readEndBody(text);
+        if (!body) {
+            return c.text('Expected a token', 400, END_CORS_HEADERS);
+        }
+        const hash = await hashToken(body.token);
+        const session = sessions.get(hash);
+        if (session) {
+            endSession(session, body.closed ? 'TAB_CLOSED' : 'DISCONNECTED');
+        }
+        return c.body(null, 204, END_CORS_HEADERS);
+    });
+    // the editor's socket: 400 for anything but its upgrade, which is accepted whatever its session's state
+    app.all('/socket', async (c) => {
+        const token = socketToken(c.req.raw.headers);
+        if (!token) {
+            return c.text('Expected the editor socket', 400);
+        }
+        const hash = await hashToken(token);
+        const events = socketEvents(hash);
+        return upgradeWebSocket(c, events);
+    });
+    // MCP's Streamable HTTP, stateless: a fresh server and transport for each request (no session id generator), answered
+    // as JSON
+    app.post('/mcp', async (c) => {
+        const origin = relayOrigin({ publicOrigin, url: c.req.url });
+        const server = createMcpServer(origin);
+        const transport = new WebStandardStreamableHTTPServerTransport({ enableJsonResponse: true });
+        await server.connect(transport);
+        return transport.handleRequest(c.req.raw);
+    });
+    app.all('/mcp', c => {
+        return c.json(ONLY_POST, 405, { allow: 'POST' });
+    });
+    // the page a person sees opening a link in a browser, for any method
+    app.all('/', c => {
+        return c.html(LINK_PAGE);
+    });
+    app.all('/link', c => {
+        return c.html(LINK_PAGE);
+    });
+    app.notFound(c => {
+        return c.text('Not found', 404);
+    });
+    app.onError((err, c) => {
+        console.error(err);
+        return c.text('Internal error', 500);
+    });
+    // the relay served on its own on `port`: its routes and the editor's socket, its Node server given back
+    const listen = (port) => {
+        return serve({ fetch: app.fetch, port, websocket: { server: wss } });
+    };
+    return { app, listen, websocket: { server: wss } };
+};
+// a new session, waiting for its socket, and its token (32 random bytes as base64url): only the token's hash is kept
+const createSession = async () => {
+    const bytes = crypto.getRandomValues(new Uint8Array(32));
+    const binary = String.fromCharCode(...bytes);
+    const base64 = btoa(binary);
+    const token = base64.replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
+    const hash = await hashToken(token);
+    const session = {
+        calls: new Map(),
+        commands: [],
+        connected: false,
+        endedReason: null,
+        expiresAt: Date.now() + LINK_LIFETIME,
+        expireTimer: scheduleEnd({ hash, ms: LINK_LIFETIME, reason: 'EXPIRED' }),
+        graceTimer: scheduleEnd({ hash, ms: RECONNECT_GRACE, reason: 'TAB_CLOSED' }),
+        hash,
+        heardAt: 0,
+        socket: null
+    };
+    sessions.set(hash, session);
+    return { session, token };
+};
+// a text's SHA-256, as bytes
+const digest = async (text) => {
+    const bytes = encoder.encode(text);
+    const buffer = await crypto.subtle.digest('SHA-256', bytes);
+    return new Uint8Array(buffer);
+};
+// the session's end: ENDED and a close with 4000 for its socket, the ended sentence for every call on its way, and its
+// record kept an hour, so a late call hears why
+const endSession = (session, reason) => {
+    if (session.endedReason) {
+        return;
+    }
+    clearTimeout(session.expireTimer);
+    clearTimeout(session.graceTimer);
+    session.endedReason = reason;
+    settleCalls(session, () => {
+        return ENDED_TEXTS[reason];
+    });
+    if (session.socket) {
+        sendMessage(session.socket, { reason, type: 'ENDED' });
+        session.socket.close(CLOSE_ENDED, reason);
+        session.socket = null;
+    }
+    setTimeout(() => {
+        sessions.delete(session.hash);
+    }, ENDED_KEPT);
+};
+const errorResult = (text) => {
+    return { content: [{ text, type: 'text' }], isError: true };
+};
+// the session's name: the SHA-256 of the token's text, as 64 lowercase hex characters
+const hashToken = async (token) => {
+    const bytes = await digest(token);
+    const hex = Array.from(bytes, byte => {
+        return byte.toString(16).padStart(2, '0');
+    });
+    return hex.join('');
+};
+const instructions = (origin) => {
+    return [
+        "This server drives a person's Embed Editor (an image editor open in their browser tab) through the editor's own commands.",
+        `The person gives you a link from the editor, like ${origin}/link#… — call list_commands with it first, then run_command for each command, the link in every call.`,
+        'The commands annotate the photo (arrows, texts, boxes), blur or pixelate areas, adjust, filter, crop, frame, undo and save.'
+    ].join('\n');
+};
+// the guide, a blank line, then the editor's latest command list, as it came; even while the tab is away
+const listCommands = (hash) => {
+    const { error, session } = readSession(hash);
+    if (error) {
+        return error;
+    }
+    const commands = JSON.stringify(session.commands);
+    markConnected(session);
+    return { content: [{ text: `${GUIDE}\n\n${commands}`, type: 'text' }], isError: false };
+};
+// the socket closed or found silent: every call on its way hears so, and the 2-minute grace starts
+const loseSocket = (session) => {
+    session.socket = null;
+    settleCalls(session, name => {
+        return `The editor's tab disconnected while ${name} ran: it may have run or not. Once the tab is back, take a screenshot to see.`;
+    });
+    clearTimeout(session.graceTimer);
+    session.graceTimer = scheduleEnd({ hash: session.hash, ms: RECONNECT_GRACE, reason: 'TAB_CLOSED' });
+};
+// an agent's first call: the editor shows "Agent connected" from then on
+const markConnected = (session) => {
+    if (session.connected) {
+        return;
+    }
+    session.connected = true;
+    if (session.socket) {
+        sendMessage(session.socket, { type: 'AGENT_CONNECTED' });
+    }
+};
+const mcpTools = (origin) => {
+    const link = {
+        description: `The link the person copied from the editor, as they pasted it (like ${origin}/link#…).`,
+        type: 'string'
+    };
+    return [
+        {
+            description: "Lists the commands of the person's Embed Editor, open in their browser tab, by the link they copied from it: each command's name, what it does, and its input as JSON Schema. Call it first, then run_command for each command.",
+            inputSchema: { properties: { link }, required: ['link'], type: 'object' },
+            name: 'list_commands'
+        },
+        {
+            description: "Runs one of the editor's commands, as list_commands gives them: its name, and its input as the command's inputSchema says.",
+            inputSchema: {
+                properties: {
+                    input: { description: "The command's input, as its inputSchema in list_commands says ({} for a command that takes none).", type: 'object' },
+                    link,
+                    name: { description: "The command's name, as list_commands gives it (like read_screenshot).", type: 'string' }
+                },
+                required: ['link', 'name', 'input'],
+                type: 'object'
+            },
+            name: 'run_command'
+        }
+    ];
+};
+const parseJson = (text) => {
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return null;
+    }
+};
+// the body of POST /sessions/end: its token and whether the tab is closing (`closed`, the beacon's), or null
+const readEndBody = (text) => {
+    const body = parseJson(text);
+    const token = readToken(body?.token);
+    return token ? { closed: body?.closed === true, token } : null;
+};
+// one frame from the editor: ping, its command list, or a call's result. A call belongs to its session, so its result
+// counts from whichever of the session's sockets brings it; only the open socket's ping and commands count
+const readMessage = ({ current, session, text, ws }) => {
+    if (text === 'ping') {
+        if (current) {
+            session.heardAt = Date.now();
+        }
+        ws.send('pong');
+        return;
+    }
+    const message = parseJson(text);
+    if (message?.type === 'result') {
+        const call = session.calls.get(message.id);
+        call?.settle({ content: message.content, isError: message.isError });
+        return;
+    }
+    if (current && message?.type === 'commands' && Array.isArray(message.commands)) {
+        session.commands = message.commands;
+    }
+};
+// the live session a call's link names, or why there is none: never made (or deleted an hour after its end), or ended
+const readSession = (hash) => {
+    const session = sessions.get(hash);
+    if (!session) {
+        return { error: errorResult(NOT_VALID), session: null };
+    }
+    if (session.endedReason) {
+        return { error: errorResult(ENDED_TEXTS[session.endedReason]), session: null };
+    }
+    return { error: null, session };
+};
+// the token in a link: what follows the last # (or the whole text, for a token pasted alone), trimmed
+const readToken = (link) => {
+    if (typeof link !== 'string') {
+        return null;
+    }
+    const start = link.lastIndexOf('#') + 1;
+    const token = link.slice(start).trim();
+    return TOKEN.test(token) ? token : null;
+};
+// the origin a request's links and MCP instructions name: the settings' publicOrigin, else the request's own
+const relayOrigin = ({ publicOrigin, url }) => {
+    const { origin } = new URL(url);
+    return publicOrigin ?? origin;
+};
+// sends a CALL when the editor's socket is open and not silent, and answers its result unchanged. The name goes to the
+// editor unchecked: it runs only a command it offered
+const runCommand = async ({ args, hash }) => {
+    const { name } = args;
+    const input = args.input ?? {};
+    if (typeof name !== 'string') {
+        return errorResult(NO_NAME);
+    }
+    const { error, session } = readSession(hash);
+    if (error) {
+        return error;
+    }
+    markConnected(session);
+    // a socket with no ping for over 25 s is a tab away: closed with 4002, and the grace starts
+    if (session.socket && Date.now() - session.heardAt > SOCKET_STALE) {
+        session.socket.close(CLOSE_SILENT, 'SILENT');
+        loseSocket(session);
+    }
+    const { socket } = session;
+    if (!socket) {
+        return errorResult(NOT_CONNECTED);
+    }
+    const startedAt = Date.now();
+    const res = await callEditor({ input, name, session, socket });
+    const ms = Date.now() - startedAt;
+    const content = JSON.stringify(res.content);
+    const bytes = encoder.encode(content);
+    // the log names the command, its time and its size, never the token or what the call carried
+    console.log(`run_command ${name}: ${ms} ms, ${bytes.length} bytes${res.isError ? ', an error' : ''}`);
+    return res;
+};
+// a timer that ends the hash's session for `reason` after `ms`
+const scheduleEnd = ({ hash, ms, reason }) => {
+    return setTimeout(() => {
+        const session = sessions.get(hash);
+        if (session) {
+            endSession(session, reason);
+        }
+    }, ms);
+};
+// the relay's messages to the editor, as JSON (pong, the one plain word, is sent as it is)
+const sendMessage = (socket, message) => {
+    const text = JSON.stringify(message);
+    socket.send(text);
+};
+// answers every call on its way, each with its own sentence
+const settleCalls = (session, textFor) => {
+    session.calls.forEach(call => {
+        const text = textFor(call.name);
+        const res = errorResult(text);
+        call.settle(res);
+    });
+};
+// the socket's events. The session holds the socket as it opened, and every later event of the connection is matched by
+// that one: a runtime may hand each event a context of its own
+const socketEvents = (hash) => {
+    let opened = null;
+    return {
+        onClose: () => {
+            const session = sessions.get(hash);
+            if (session && opened && session.socket === opened) {
+                loseSocket(session);
+            }
+        },
+        onMessage: (e, ws) => {
+            const session = sessions.get(hash);
+            if (session && opened) {
+                readMessage({ current: session.socket === opened, session, text: `${e.data}`, ws });
+            }
+        },
+        onOpen: (e, ws) => {
+            opened = acceptSocket({ hash, ws }) ? ws : null;
+        }
+    };
+};
+// the token of the editor's socket: an upgrade, with the subprotocols ee-agent and the token, in that order, or null
+const socketToken = (headers) => {
+    const upgrade = headers.get('upgrade') ?? '';
+    const protocols = headers.get('sec-websocket-protocol') ?? '';
+    const parts = protocols.split(',');
+    const [protocol, token = ''] = parts.map(item => {
+        return item.trim();
+    });
+    return upgrade.toLowerCase() === 'websocket' && protocol === PROTOCOL && TOKEN.test(token) ? token : null;
+};
+export default { createRelay };

package/package.json

@@ -1,6 +1,54 @@
 {
-  "name": "@embededitor/relay",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+	"name": "@embededitor/relay",
+	"type": "module",
+	"version": "0.1.0",
+	"description": "Embed Editor's agent link relay, to run on your own server: your users' AI agent edits the photo open in your editor, through your own address.",
+	"license": "MIT",
+	"homepage": "https://docs.embededitor.com/agent-link/relay",
+	"keywords": [
+		"embed-editor",
+		"photo-editor",
+		"mcp",
+		"ai-agent",
+		"relay",
+		"hono"
+	],
+	"engines": {
+		"node": ">=20"
+	},
+	"exports": {
+		".": {
+			"types": "./dist/index.d.ts",
+			"default": "./dist/index.js"
+		}
+	},
+	"files": [
+		"dist",
+		"CHANGELOG.md",
+		"LICENSE.md",
+		"README.md"
+	],
+	"publishConfig": {
+		"access": "public"
+	},
+	"scripts": {
+		"build": "rm -rf dist && tsc -p tsconfig.build.json",
+		"lint": "eslint . --fix",
+		"prepack": "npm run build",
+		"release": "vitest --run && npm publish --@embededitor:registry=https://registry.npmjs.org/",
+		"test": "vitest --run",
+		"typecheck": "tsc"
+	},
+	"dependencies": {
+		"@hono/node-server": "^2.1.6",
+		"@modelcontextprotocol/sdk": "1.32.2",
+		"@types/ws": "^8.18.2",
+		"hono": "^4.13.17",
+		"ws": "^8.21.0"
+	},
+	"devDependencies": {
+		"@types/node": "^24.0.10",
+		"typescript": "^6.0.3",
+		"vitest": "^5.0.2"
+	}
+}