@zseven-w/dsh-openpencil 0.1.0-rc.1

package/lib/mcp-client.js

@@ -0,0 +1,148 @@
+/** Strict loopback JSON-RPC client for one managed OpenPencil editor. */
+const MCP_TIMEOUT_MS = 20_000;
+const MAX_MCP_RESPONSE_BYTES = 2 * 1024 * 1024;
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function finite(value) {
+    return typeof value === 'number' && Number.isFinite(value) ? value : undefined;
+}
+function optionalString(value) {
+    return typeof value === 'string' && value.length > 0 ? value : undefined;
+}
+function textFromContent(value) {
+    if (!Array.isArray(value))
+        return '';
+    const parts = [];
+    for (const item of value) {
+        if (isRecord(item) && item.type === 'text' && typeof item.text === 'string')
+            parts.push(item.text);
+    }
+    return parts.join('\n');
+}
+/** Decode a JSON-RPC tools/call envelope, including MCP's HTTP-200 errors. */
+export function parseOpenPencilMcpResponse(tool, value) {
+    if (!isRecord(value))
+        throw new Error(`OpenPencil MCP ${tool} returned an invalid JSON-RPC response`);
+    if (isRecord(value.error)) {
+        const message = optionalString(value.error.message) ?? JSON.stringify(value.error);
+        throw new Error(`OpenPencil MCP ${tool} failed: ${message}`);
+    }
+    if (!isRecord(value.result))
+        throw new Error(`OpenPencil MCP ${tool} omitted its result`);
+    const text = textFromContent(value.result.content);
+    if (value.result.isError === true) {
+        throw new Error(`OpenPencil MCP ${tool} failed${text === '' ? '' : `: ${text}`}`);
+    }
+    let decoded = text;
+    if (text !== '') {
+        try {
+            decoded = JSON.parse(text);
+        }
+        catch {
+            // Some first-party tools intentionally return human-readable text.
+        }
+    }
+    if (isRecord(decoded) && decoded.applied === false) {
+        const details = Array.isArray(decoded.errors)
+            ? decoded.errors.map(error => typeof error === 'string' ? error : JSON.stringify(error)).join('; ')
+            : text;
+        throw new Error(`OpenPencil MCP ${tool} did not apply${details === '' ? '' : `: ${details}`}`);
+    }
+    return { tool, value: decoded, text };
+}
+/** Call a first-party tool on a managed editor without exposing its daemon token. */
+export async function callOpenPencilMcp(options) {
+    const origin = new URL(options.baseUrl);
+    const loopback = origin.hostname === '127.0.0.1' || origin.hostname === 'localhost' || origin.hostname === '::1';
+    if (!loopback || (origin.protocol !== 'http:' && origin.protocol !== 'https:')) {
+        throw new Error('OpenPencil MCP endpoint must use an HTTP loopback origin');
+    }
+    if (origin.pathname !== '/' || origin.search !== '' || origin.hash !== '') {
+        throw new Error('OpenPencil MCP base URL must be an origin');
+    }
+    const fetcher = options.fetcher ?? fetch;
+    const timeout = AbortSignal.timeout(MCP_TIMEOUT_MS);
+    const signal = options.signal === undefined ? timeout : AbortSignal.any([options.signal, timeout]);
+    const response = await fetcher(new URL('/mcp', origin).href, {
+        method: 'POST',
+        headers: {
+            authorization: `Bearer ${options.token}`,
+            'x-openpencil-token': options.token,
+            'content-type': 'application/json',
+            accept: 'application/json',
+        },
+        body: JSON.stringify({
+            jsonrpc: '2.0',
+            id: `dsh-${Date.now().toString(36)}`,
+            method: 'tools/call',
+            params: { name: options.tool, arguments: options.arguments ?? {} },
+        }),
+        signal,
+    });
+    const bytes = Buffer.from(await response.arrayBuffer());
+    if (bytes.length > MAX_MCP_RESPONSE_BYTES)
+        throw new Error(`OpenPencil MCP ${options.tool} response is too large`);
+    if (!response.ok)
+        throw new Error(`OpenPencil MCP ${options.tool} request failed (${response.status})`);
+    let value;
+    try {
+        value = JSON.parse(bytes.toString('utf8'));
+    }
+    catch {
+        throw new Error(`OpenPencil MCP ${options.tool} returned invalid JSON`);
+    }
+    return parseOpenPencilMcpResponse(options.tool, value);
+}
+/** Probe the daemon document version before and after a write. */
+export async function getOpenPencilMcpVersion(options) {
+    const origin = new URL(options.baseUrl);
+    const loopback = origin.hostname === '127.0.0.1' || origin.hostname === 'localhost' || origin.hostname === '::1';
+    if (!loopback || (origin.protocol !== 'http:' && origin.protocol !== 'https:')) {
+        throw new Error('OpenPencil MCP endpoint must use an HTTP loopback origin');
+    }
+    const timeout = AbortSignal.timeout(options.timeoutMs ?? MCP_TIMEOUT_MS);
+    const signal = options.signal === undefined ? timeout : AbortSignal.any([options.signal, timeout]);
+    const response = await (options.fetcher ?? fetch)(new URL('/api/mcp/version', origin).href, {
+        headers: { authorization: `Bearer ${options.token}`, 'x-openpencil-token': options.token },
+        signal,
+    });
+    if (!response.ok)
+        throw new Error(`OpenPencil MCP version probe failed (${response.status})`);
+    const value = await response.json();
+    if (!isRecord(value) || typeof value.version !== 'number' || !Number.isSafeInteger(value.version) || value.version < 0) {
+        throw new Error('OpenPencil MCP version probe returned an invalid result');
+    }
+    return value.version;
+}
+function nodeSummary(value) {
+    if (!isRecord(value) || typeof value.id !== 'string' || value.id.length === 0)
+        return undefined;
+    return {
+        id: value.id,
+        ...(optionalString(value.type) === undefined ? {} : { type: optionalString(value.type) }),
+        ...(optionalString(value.name) === undefined ? {} : { name: optionalString(value.name) }),
+        ...(finite(value.x) === undefined ? {} : { x: finite(value.x) }),
+        ...(finite(value.y) === undefined ? {} : { y: finite(value.y) }),
+        ...(finite(value.width) === undefined ? {} : { width: finite(value.width) }),
+        ...(finite(value.height) === undefined ? {} : { height: finite(value.height) }),
+    };
+}
+/** Project get_selection into the bounded shape shared with the DSH client. */
+export function selectionSnapshotFromMcp(sourcePath, value, updatedAt = Date.now()) {
+    if (!isRecord(value))
+        throw new Error('OpenPencil get_selection returned an invalid result');
+    const selectedIds = Array.isArray(value.selectedIds)
+        ? value.selectedIds.filter((id) => typeof id === 'string' && id.length > 0)
+        : [];
+    const nodes = Array.isArray(value.nodes)
+        ? value.nodes.map(nodeSummary).filter((node) => node !== undefined)
+        : [];
+    return {
+        sourcePath,
+        activePageId: optionalString(value.activePageId) ?? '',
+        selectedIds,
+        nodes,
+        updatedAt,
+    };
+}

package/lib/new-tool.d.ts

@@ -0,0 +1,23 @@
+/** Create a brand-new OpenPencil document from one transactional design batch. */
+import type FileSystem from '@deepseek-ai/dsh-fs';
+import type { FsObservation, FsTarget } from '@deepseek-ai/dsh-fs';
+import type SandboxPolicyService from '@deepseek-ai/dsh-sandbox-policy';
+import { type ToolRunContext } from '@deepseek-ai/dsh-tools';
+import type { EditorHostController } from './editor-host.js';
+export interface DesignNewArgs {
+    path: string;
+    operations: string;
+    canvasWidth?: number;
+    postProcess?: boolean;
+}
+export interface DesignNewServices {
+    fs: FileSystem;
+    sandboxPolicy: SandboxPolicyService;
+    observe(target: FsTarget, observation: FsObservation, exec: ToolRunContext): void;
+}
+/**
+ * Build and atomically publish a new `.op` document. The first batch runs in
+ * a private managed daemon, so no existing file or browser-owned sidebar is
+ * required and a failed design never leaves an empty target behind.
+ */
+export declare function createDesignNewTool(editorHost: EditorHostController, services: DesignNewServices): import("@deepseek-ai/dsh-tools").ToolDefinition;

package/lib/new-tool.js

@@ -0,0 +1,136 @@
+/** Create a brand-new OpenPencil document from one transactional design batch. */
+import { createHash } from 'node:crypto';
+import { lstat } from 'node:fs/promises';
+import { basename, dirname, extname, isAbsolute } from 'node:path';
+import { defineTool } from '@deepseek-ai/dsh-tools';
+import { OPENPENCIL_NEW_TOOL_NAME } from './tool-names.js';
+const MAX_OPERATIONS_LENGTH = 256 * 1024;
+const ROOT_OPERATION_EXAMPLE = 'root=I(null,{"type":"frame","name":"Home","width":390,"height":844,"layout":"vertical","gap":24,"padding":24,"fill":"#F7F1E7","children":[{"type":"text","name":"Title","content":"Forage","fontSize":32,"fontWeight":700,"fill":"#173C2B"}]})';
+const IMAGE_OPERATION_EXAMPLE = 'slot=I(root,{"type":"frame","name":"Hero photo","width":"fill_container","height":240,"cornerRadius":20,"clipContent":true,"children":[]})\nphoto=G(slot,"search","seasonal food photography")';
+function renderJson(_args, value) {
+    return [{ type: 'text', text: JSON.stringify(value, null, 2) }];
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/**
+ * Build and atomically publish a new `.op` document. The first batch runs in
+ * a private managed daemon, so no existing file or browser-owned sidebar is
+ * required and a failed design never leaves an empty target behind.
+ */
+export function createDesignNewTool(editorHost, services) {
+    return defineTool({
+        name: OPENPENCIL_NEW_TOOL_NAME,
+        description: 'Create and save a brand-new OpenPencil .op design from one transactional batch_design program. '
+            + 'Use this for natural-language requests to make a new design when no .op file or live editor exists. '
+            + 'Do not inspect or hand-write .op JSON and do not ask the user to open a sidebar. '
+            + 'Choose a concise workspace-relative .op filename when the user did not specify one. '
+            + 'This is a local OpenPencil-host operation and requires the session Workspace Write permission. '
+            + 'The target must not already exist and its parent directory must exist. '
+            + `Start with this valid pattern: ${ROOT_OPERATION_EXAMPLE}. `
+            + 'A complete new design must create at least one renderable root frame. Prefer nested children for a cohesive initial screen and prefer at most 25 top-level operations. '
+            + `For requested photography, add these valid lines in the same batch: ${IMAGE_OPERATION_EXAMPLE}. `
+            + 'Use OpenPencil image search or an editable placeholder without pausing for external image-service setup; do not ask image-provider questions unless the user explicitly requested external generation. '
+            + 'All operations apply together and the resulting document is saved atomically. '
+            + 'After success, immediately call openpencil_render with the returned path, editable=true, and autoOpen=true to show and automatically expand the editor once.',
+        parameters: {
+            path: {
+                type: 'string', required: true,
+                description: 'New workspace-relative or absolute .op path. Choose a useful filename without asking when the user omitted one. Existing targets are never overwritten.',
+            },
+            operations: {
+                type: 'string', required: true,
+                description: `A complete batch_design program, preferably at most 25 top-level newline-separated operations. Begin with ${ROOT_OPERATION_EXAMPLE}. Use returned bindings for later I/U/G operations. For photography use ${IMAGE_OPERATION_EXAMPLE}.`,
+            },
+            canvasWidth: { type: 'number', description: 'Optional canvas-width hint for OpenPencil post-processing.' },
+            postProcess: { type: 'boolean', description: 'Run OpenPencil post-processing after the batch. Default false.' },
+        },
+        output: {
+            schema: {
+                type: 'object', additionalProperties: false,
+                properties: {
+                    path: { type: 'string', required: true },
+                    filename: { type: 'string', required: true },
+                    bytes: { type: 'integer', required: true },
+                    sha256: { type: 'string', required: true },
+                    created: { type: 'boolean', const: true, required: true },
+                    applied: { type: 'boolean', const: true, required: true },
+                    saved: { type: 'boolean', const: true, required: true },
+                    result: { type: 'object', additionalProperties: true },
+                    note: { type: 'string', required: true },
+                },
+            },
+            render: renderJson,
+        },
+        async execute(args, exec) {
+            const requestedPath = args.path.trim();
+            if (requestedPath.length === 0)
+                throw new Error(`${OPENPENCIL_NEW_TOOL_NAME}: path is required`);
+            if (extname(requestedPath).toLowerCase() !== '.op') {
+                throw new Error(`${OPENPENCIL_NEW_TOOL_NAME}: path must end in .op`);
+            }
+            if (args.operations.trim().length === 0)
+                throw new Error(`${OPENPENCIL_NEW_TOOL_NAME}: operations must not be empty`);
+            if (args.operations.length > MAX_OPERATIONS_LENGTH)
+                throw new Error(`${OPENPENCIL_NEW_TOOL_NAME}: operations are too large`);
+            if (args.canvasWidth !== undefined && (!Number.isFinite(args.canvasWidth) || args.canvasWidth <= 0 || args.canvasWidth > 16_384)) {
+                throw new Error(`${OPENPENCIL_NEW_TOOL_NAME}: canvasWidth must be greater than 0 and at most 16384`);
+            }
+            const sandboxPolicy = services.sandboxPolicy.resolve({ session: exec.agent?.session });
+            if (services.fs.sandboxMode !== undefined && sandboxPolicy.mode === 'read-only') {
+                throw new Error(`${OPENPENCIL_NEW_TOOL_NAME}: creating a design requires Workspace Write access; switch this session from Read Only to Workspace Write and retry`);
+            }
+            const resolveOptions = { cwd: sandboxPolicy.workspaceRoot, signal: exec.signal };
+            const pathInfo = await services.fs.lstat(requestedPath, { cwd: sandboxPolicy.workspaceRoot }, exec.signal);
+            if (pathInfo !== undefined)
+                throw new Error(`${OPENPENCIL_NEW_TOOL_NAME}: target already exists: ${requestedPath}`);
+            const target = await services.fs.resolve(requestedPath, resolveOptions);
+            const processPath = services.fs.processPath(target);
+            if (extname(processPath).toLowerCase() !== '.op') {
+                throw new Error(`${OPENPENCIL_NEW_TOOL_NAME}: resolved target must end in .op`);
+            }
+            if (!isAbsolute(processPath))
+                throw new Error(`${OPENPENCIL_NEW_TOOL_NAME}: the DSH filesystem did not provide an absolute host path`);
+            let parentInfo;
+            try {
+                parentInfo = await lstat(dirname(processPath));
+            }
+            catch {
+                throw new Error(`${OPENPENCIL_NEW_TOOL_NAME}: the target parent is not available to the local OpenPencil host; use an existing directory in a local DSH workspace`);
+            }
+            if (!parentInfo.isDirectory()) {
+                throw new Error(`${OPENPENCIL_NEW_TOOL_NAME}: target parent must be a local directory`);
+            }
+            const resolvedInfo = await services.fs.stat(target, exec.signal);
+            if (resolvedInfo !== undefined) {
+                services.observe(target, { kind: 'present', version: resolvedInfo.version }, exec);
+                throw new Error(`${OPENPENCIL_NEW_TOOL_NAME}: target already exists: ${requestedPath}`);
+            }
+            services.observe(target, { kind: 'absent' }, exec);
+            const batch = await editorHost.createDocumentBatch({
+                operations: args.operations,
+                ...(args.canvasWidth === undefined ? {} : { canvasWidth: args.canvasWidth }),
+                ...(args.postProcess === undefined ? {} : { postProcess: args.postProcess }),
+                signal: exec.signal,
+            });
+            const outcome = await services.fs.writeText(target, batch.documentJson, { kind: 'createIfAbsent' }, exec.signal, sandboxPolicy);
+            services.observe(target, { kind: 'present', version: outcome.version }, exec);
+            const bytes = Buffer.byteLength(outcome.after);
+            const sha256 = createHash('sha256').update(outcome.after).digest('hex');
+            return {
+                path: processPath,
+                filename: basename(processPath),
+                bytes,
+                sha256,
+                created: true,
+                applied: true,
+                saved: true,
+                ...(isRecord(batch.result) ? { result: batch.result } : {}),
+                note: `Created and saved ${processPath}. Call openpencil_render with this path, editable=true, and autoOpen=true now.`,
+            };
+        },
+        presentCall: (args) => ({
+            card: 'generic', title: `Create ${args.path}`, kind: 'execute', locations: [{ path: args.path }],
+        }),
+    });
+}

package/lib/presentation-hydration.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Safe recovery of browser-only presentation metadata for nested Code Mode
+ * tool calls.
+ *
+ * DSH persists a nested `openpencil_render` outcome as a
+ * `tool/code-dispatch` event, but published DSH through 0.1.0-rc.6 omits the native
+ * `tool/result` presentation metadata from that event. The browser can ask
+ * this same-origin endpoint to re-project that metadata without submitting
+ * any path or tool result of its own. Live results are remembered briefly so
+ * an explicitly requested editor grant can be restored; replayed durable
+ * events are preview-only.
+ *
+ * @module dsh-openpencil/presentation-hydration
+ */
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import { type SessionStore } from '@deepseek-ai/dsh-session';
+import type { ToolExecution, ToolExecutionResult } from '@deepseek-ai/dsh-tools';
+import { type EditorHostController } from './editor-host.js';
+import { RenderAccessController, type RenderResult } from './renderer.js';
+import type { ViewerAssetController } from './viewer-assets.js';
+/** Exact same-origin endpoint used by the client to recover nested metadata. */
+export declare const PRESENTATION_HYDRATION_ROUTE = "/_dsh/dsh-openpencil/presentation";
+interface PresentationHydrationOptions {
+    ttlMs?: number;
+    maxEntries?: number;
+    maxRecordBytes?: number;
+    maxBytes?: number;
+    now?: () => number;
+}
+interface PresentationHydrationDependencies {
+    sessions: Pick<SessionStore, 'get'>;
+    render: RenderAccessController;
+    viewer?: Pick<ViewerAssetController, 'viewerGrant'>;
+    editor?: Pick<EditorHostController, 'grantFor'>;
+    /** DSH Web authorities derived from `webRuntime.trustedHosts`. */
+    trustedHosts?: readonly string[] | (() => readonly string[]);
+}
+/**
+ * Accept only the canonical, content-addressed result shape emitted by this
+ * plugin. Hydration never signs a legacy absolute-path-only render.
+ */
+export declare function parseHydratableRenderResult(value: unknown): RenderResult | undefined;
+/** TTL/LRU cache plus fail-closed hydration endpoint. */
+export declare class PresentationHydrationController {
+    #private;
+    private readonly dependencies;
+    constructor(dependencies: PresentationHydrationDependencies, options?: PresentationHydrationOptions);
+    /** Observe one trusted in-process result before Code Mode drops its meta. */
+    observeToolResult(exec: Readonly<ToolExecution>, result: Readonly<ToolExecutionResult>): void;
+    /** Drop all live editor-capable records owned by a disposed session. */
+    forgetSession(sessionId: string): void;
+    /** Handle the exact same-origin POST hydration route. */
+    handle(req: IncomingMessage, res: ServerResponse): Promise<void>;
+}
+export {};