@kolisachint/hoocode-agent 0.5.21 → 0.5.23

package/dist/core/canvas/runner.js

@@ -0,0 +1,196 @@
+/**
+ * Canvas extension runner — forks an extension and speaks the provider protocol.
+ *
+ * Design: `docs/canvas-extensions-design.md` §3.1, §4, §6.1. Two decisions are
+ * load-bearing here:
+ *
+ *   1. **It forks; it does not import.** hoocode's own extensions load in-process
+ *      (`core/extensions/loader.ts`), which would put a third-party canvas inside
+ *      the permission gate with full access to the tool registry and provider
+ *      credentials. Canvas extensions are strangers, so they get a process
+ *      boundary — which is also what the Copilot CLI does, so a canvas behaves
+ *      the same in both hosts.
+ *   2. **Lifecycle mirrors the documented CLI contract**: forked child, JSON-RPC
+ *      over stdio, and shutdown by SIGTERM followed by SIGKILL after 5s.
+ *
+ * stdout is the protocol channel, exactly as in the Copilot CLI, so a stray
+ * `console.log` in an extension corrupts it there and here alike. Rather than
+ * failing opaquely, unparseable lines are surfaced through `onStray` so a caller
+ * can tell the author to use `session.log` instead.
+ */
+import { spawn } from "node:child_process";
+import { CANVAS_ENVELOPE_VERSION, CanvasMessageDecoder, encodeCanvasMessage, isCanvasChildToHostMessage, } from "./protocol.js";
+import { canvasResolverImportArg } from "./resolver.js";
+/** Code on the error a cancelled or timed-out provider call rejects with. */
+export const CANVAS_ERROR_CODE_ABORTED = "aborted";
+/** Grace period between SIGTERM and SIGKILL, matching the documented CLI contract. */
+export const CANVAS_SHUTDOWN_GRACE_MS = 5_000;
+/**
+ * Default ceiling per provider method, so a wedged handler cannot hang a session
+ * (design doc §11.4).
+ *
+ * These differ because the calls do. `canvas.open` may legitimately do real work
+ * before it can return a URL — `pr-artifact-explorer` starts a server and
+ * `inspect_artifact`-shaped canvases may fetch — whereas an action is a request
+ * against an already-open instance, and `close` should be near-instant since the
+ * SDK contract makes `onClose` fire-and-forget. A single 30s ceiling for all three
+ * was a guess, and wrong at both ends.
+ */
+export const CANVAS_REQUEST_TIMEOUT_MS = {
+    "canvas.open": 120_000,
+    "canvas.action.invoke": 30_000,
+    "canvas.close": 5_000,
+};
+/** Error carrying the `CanvasError.code` an extension handler threw. */
+export class CanvasCallError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = "CanvasCallError";
+        this.code = code;
+    }
+}
+/** Fork an extension and return a handle to its provider surface. */
+export function spawnCanvasExtension(options) {
+    const timeouts = { ...CANVAS_REQUEST_TIMEOUT_MS, ...options.requestTimeoutMs };
+    const child = spawn(options.runtime.execPath, [...options.runtime.execArgv, "--import", canvasResolverImportArg(options.runtime.shimUrl), options.entry], {
+        cwd: options.cwd,
+        env: {
+            ...(options.env ?? process.env),
+            HOOCODE_CANVAS_EXTENSION_ID: options.extensionId,
+            // The real SDK's joinSession throws without SESSION_ID (design doc §11.2).
+            // Our shim does not read it, but an extension that uses the SDK directly
+            // would, so setting it is free fidelity. COPILOT_HOME is deliberately left
+            // alone: a canvas should not be able to tell the hosts apart.
+            SESSION_ID: options.sessionId ?? options.extensionId,
+        },
+        stdio: ["pipe", "pipe", "pipe"],
+    });
+    const pending = new Map();
+    const decoder = new CanvasMessageDecoder();
+    let nextId = 1;
+    let exited = false;
+    let readyResolve;
+    let readyReject;
+    const ready = new Promise((resolve, reject) => {
+        readyResolve = resolve;
+        readyReject = reject;
+    });
+    const settleAll = (reason) => {
+        for (const call of pending.values()) {
+            call.dispose();
+            call.reject(reason);
+        }
+        pending.clear();
+    };
+    const handle = (message) => {
+        switch (message.type) {
+            case "ready":
+                readyResolve?.(message);
+                return;
+            case "log":
+                options.onLog?.(message.message, message.level, message.ephemeral);
+                return;
+            default: {
+                // A response for an id no longer pending is one whose caller stopped
+                // waiting — aborted or timed out. Dropping it is the whole point.
+                const call = pending.get(message.id);
+                if (!call)
+                    return;
+                pending.delete(message.id);
+                call.dispose();
+                if (message.type === "response")
+                    call.resolve(message.result);
+                else
+                    call.reject(new CanvasCallError(message.code, message.message));
+            }
+        }
+    };
+    child.stdout.setEncoding("utf8");
+    child.stdout.on("data", (chunk) => {
+        const { values, strays } = decoder.push(chunk);
+        for (const line of strays)
+            options.onStray?.(line);
+        for (const value of values) {
+            if (isCanvasChildToHostMessage(value))
+                handle(value);
+            else
+                options.onStray?.(JSON.stringify(value));
+        }
+    });
+    child.stderr.setEncoding("utf8");
+    child.stderr.on("data", (chunk) => options.onStderr?.(chunk));
+    child.on("error", (error) => {
+        exited = true;
+        readyReject?.(error);
+        settleAll(error);
+    });
+    child.on("exit", (code, signal) => {
+        exited = true;
+        const reason = new Error(`Canvas extension "${options.extensionId}" exited (code ${String(code)}, signal ${String(signal)}).`);
+        readyReject?.(reason);
+        settleAll(reason);
+        options.onExit?.(code, signal);
+    });
+    const call = (method, params, callOptions) => {
+        if (exited) {
+            return Promise.reject(new Error(`Canvas extension "${options.extensionId}" is not running.`));
+        }
+        const signal = callOptions?.signal;
+        if (signal?.aborted) {
+            // Nothing is written to the child: a request nobody awaits should not exist.
+            return Promise.reject(new CanvasCallError(CANVAS_ERROR_CODE_ABORTED, `Canvas ${method} was cancelled before it started.`));
+        }
+        const id = nextId;
+        nextId += 1;
+        const timeoutMs = timeouts[method];
+        return new Promise((resolve, reject) => {
+            const abandon = (error) => {
+                const entry = pending.get(id);
+                if (!entry)
+                    return;
+                pending.delete(id);
+                entry.dispose();
+                reject(error);
+            };
+            const timer = timeoutMs > 0
+                ? setTimeout(() => abandon(new CanvasCallError(CANVAS_ERROR_CODE_ABORTED, `Canvas extension "${options.extensionId}" did not answer ${method} within ${timeoutMs}ms.`)), timeoutMs)
+                : undefined;
+            const onAbort = () => abandon(new CanvasCallError(CANVAS_ERROR_CODE_ABORTED, `Canvas ${method} was cancelled.`));
+            signal?.addEventListener("abort", onAbort, { once: true });
+            pending.set(id, {
+                resolve,
+                reject,
+                dispose: () => {
+                    if (timer)
+                        clearTimeout(timer);
+                    signal?.removeEventListener("abort", onAbort);
+                },
+            });
+            child.stdin.write(encodeCanvasMessage({ envelope: CANVAS_ENVELOPE_VERSION, type: "request", id, method, params }));
+        });
+    };
+    return {
+        extensionId: options.extensionId,
+        ready,
+        get running() {
+            return !exited;
+        },
+        open: (params, callOptions) => call("canvas.open", params, callOptions),
+        close: (params, callOptions) => call("canvas.close", params, callOptions),
+        invokeAction: (params, callOptions) => call("canvas.action.invoke", params, callOptions),
+        terminate: () => new Promise((resolve) => {
+            if (exited) {
+                resolve();
+                return;
+            }
+            const kill = setTimeout(() => child.kill("SIGKILL"), CANVAS_SHUTDOWN_GRACE_MS);
+            child.once("exit", () => {
+                clearTimeout(kill);
+                resolve();
+            });
+            child.kill("SIGTERM");
+        }),
+    };
+}
+//# sourceMappingURL=runner.js.map

package/dist/core/canvas/runner.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runner.js","sourceRoot":"","sources":["../../../src/core/canvas/runner.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Canvas extension runner — forks an extension and speaks the provider protocol.\n *\n * Design: `docs/canvas-extensions-design.md` §3.1, §4, §6.1. Two decisions are\n * load-bearing here:\n *\n *   1. **It forks; it does not import.** hoocode's own extensions load in-process\n *      (`core/extensions/loader.ts`), which would put a third-party canvas inside\n *      the permission gate with full access to the tool registry and provider\n *      credentials. Canvas extensions are strangers, so they get a process\n *      boundary — which is also what the Copilot CLI does, so a canvas behaves\n *      the same in both hosts.\n *   2. **Lifecycle mirrors the documented CLI contract**: forked child, JSON-RPC\n *      over stdio, and shutdown by SIGTERM followed by SIGKILL after 5s.\n *\n * stdout is the protocol channel, exactly as in the Copilot CLI, so a stray\n * `console.log` in an extension corrupts it there and here alike. Rather than\n * failing opaquely, unparseable lines are surfaced through `onStray` so a caller\n * can tell the author to use `session.log` instead.\n */\n\nimport { type ChildProcessWithoutNullStreams, spawn } from \"node:child_process\";\nimport {\n\tCANVAS_ENVELOPE_VERSION,\n\ttype CanvasChildToHostMessage,\n\tCanvasMessageDecoder,\n\ttype CanvasProviderCloseRequest,\n\ttype CanvasProviderInvokeActionRequest,\n\ttype CanvasProviderMethod,\n\ttype CanvasProviderOpenRequest,\n\ttype CanvasReadyMessage,\n\tencodeCanvasMessage,\n\tisCanvasChildToHostMessage,\n\ttype JsonValue,\n} from \"./protocol.js\";\nimport { canvasResolverImportArg } from \"./resolver.js\";\n\n/** Code on the error a cancelled or timed-out provider call rejects with. */\nexport const CANVAS_ERROR_CODE_ABORTED = \"aborted\";\n\n/** Per-call options. A signal cancels the wait; the child is reconciled by the caller. */\nexport interface CanvasCallOptions {\n\t/**\n\t * Stop waiting when this aborts.\n\t *\n\t * The provider protocol has no cancel verb, so aborting only ends *our* wait —\n\t * the child may still be working and may still answer. `registry.ts` is what\n\t * reconciles that, by closing the instance it will never see (see its `abandon`).\n\t */\n\tsignal?: AbortSignal;\n}\n\n/** Grace period between SIGTERM and SIGKILL, matching the documented CLI contract. */\nexport const CANVAS_SHUTDOWN_GRACE_MS = 5_000;\n\n/**\n * Default ceiling per provider method, so a wedged handler cannot hang a session\n * (design doc §11.4).\n *\n * These differ because the calls do. `canvas.open` may legitimately do real work\n * before it can return a URL — `pr-artifact-explorer` starts a server and\n * `inspect_artifact`-shaped canvases may fetch — whereas an action is a request\n * against an already-open instance, and `close` should be near-instant since the\n * SDK contract makes `onClose` fire-and-forget. A single 30s ceiling for all three\n * was a guess, and wrong at both ends.\n */\nexport const CANVAS_REQUEST_TIMEOUT_MS: Readonly<Record<CanvasProviderMethod, number>> = {\n\t\"canvas.open\": 120_000,\n\t\"canvas.action.invoke\": 30_000,\n\t\"canvas.close\": 5_000,\n};\n\n/** How the child is launched. Injectable so tests can run the TypeScript shim under tsx. */\nexport interface CanvasRuntime {\n\t/** Executable to fork. */\n\texecPath: string;\n\t/** Arguments that precede the entry file, excluding the resolver `--import`. */\n\texecArgv: string[];\n\t/** Absolute `file:` URL of the module the SDK specifier resolves to. */\n\tshimUrl: string;\n}\n\n/** Everything needed to fork one extension. */\nexport interface CanvasRunnerOptions {\n\t/** Provider identifier — the extension directory name. */\n\textensionId: string;\n\t/** Absolute path to the extension's `extension.mjs`. */\n\tentry: string;\n\t/** Value for the child's `SESSION_ID`. Defaults to the extension id. */\n\tsessionId?: string;\n\truntime: CanvasRuntime;\n\t/** Working directory for the child. Defaults to the extension directory's parent. */\n\tcwd?: string;\n\tenv?: NodeJS.ProcessEnv;\n\t/** Per-method overrides merged over {@link CANVAS_REQUEST_TIMEOUT_MS}. 0 disables. */\n\trequestTimeoutMs?: Partial<Record<CanvasProviderMethod, number>>;\n\t/** A `session.log` call from the extension. */\n\tonLog?: (message: string, level: string | undefined, ephemeral: boolean | undefined) => void;\n\t/** A stdout line that was not protocol. Almost always a stray `console.log`. */\n\tonStray?: (line: string) => void;\n\t/** The child's stderr, which extensions use normally. */\n\tonStderr?: (chunk: string) => void;\n\t/** The child exited, expectedly or not. */\n\tonExit?: (code: number | null, signal: NodeJS.Signals | null) => void;\n}\n\n/** A running canvas extension. */\nexport interface CanvasExtensionProcess {\n\treadonly extensionId: string;\n\t/** Resolves with the child's first `ready` message, or rejects if it exits first. */\n\treadonly ready: Promise<CanvasReadyMessage>;\n\t/** Whether the child is still running. */\n\treadonly running: boolean;\n\topen(params: CanvasProviderOpenRequest, options?: CanvasCallOptions): Promise<JsonValue>;\n\tclose(params: CanvasProviderCloseRequest, options?: CanvasCallOptions): Promise<JsonValue>;\n\tinvokeAction(params: CanvasProviderInvokeActionRequest, options?: CanvasCallOptions): Promise<JsonValue>;\n\t/** SIGTERM, then SIGKILL after {@link CANVAS_SHUTDOWN_GRACE_MS}. Resolves on exit. */\n\tterminate(): Promise<void>;\n}\n\ninterface PendingCall {\n\tresolve: (value: JsonValue) => void;\n\treject: (reason: Error) => void;\n\t/** Clear the timer and detach the abort listener. Safe to call twice. */\n\tdispose: () => void;\n}\n\n/** Error carrying the `CanvasError.code` an extension handler threw. */\nexport class CanvasCallError extends Error {\n\treadonly code: string;\n\n\tconstructor(code: string, message: string) {\n\t\tsuper(message);\n\t\tthis.name = \"CanvasCallError\";\n\t\tthis.code = code;\n\t}\n}\n\n/** Fork an extension and return a handle to its provider surface. */\nexport function spawnCanvasExtension(options: CanvasRunnerOptions): CanvasExtensionProcess {\n\tconst timeouts: Record<CanvasProviderMethod, number> = { ...CANVAS_REQUEST_TIMEOUT_MS, ...options.requestTimeoutMs };\n\tconst child = spawn(\n\t\toptions.runtime.execPath,\n\t\t[...options.runtime.execArgv, \"--import\", canvasResolverImportArg(options.runtime.shimUrl), options.entry],\n\t\t{\n\t\t\tcwd: options.cwd,\n\t\t\tenv: {\n\t\t\t\t...(options.env ?? process.env),\n\t\t\t\tHOOCODE_CANVAS_EXTENSION_ID: options.extensionId,\n\t\t\t\t// The real SDK's joinSession throws without SESSION_ID (design doc §11.2).\n\t\t\t\t// Our shim does not read it, but an extension that uses the SDK directly\n\t\t\t\t// would, so setting it is free fidelity. COPILOT_HOME is deliberately left\n\t\t\t\t// alone: a canvas should not be able to tell the hosts apart.\n\t\t\t\tSESSION_ID: options.sessionId ?? options.extensionId,\n\t\t\t},\n\t\t\tstdio: [\"pipe\", \"pipe\", \"pipe\"],\n\t\t},\n\t) as ChildProcessWithoutNullStreams;\n\n\tconst pending = new Map<number, PendingCall>();\n\tconst decoder = new CanvasMessageDecoder();\n\tlet nextId = 1;\n\tlet exited = false;\n\tlet readyResolve: ((value: CanvasReadyMessage) => void) | undefined;\n\tlet readyReject: ((reason: Error) => void) | undefined;\n\tconst ready = new Promise<CanvasReadyMessage>((resolve, reject) => {\n\t\treadyResolve = resolve;\n\t\treadyReject = reject;\n\t});\n\n\tconst settleAll = (reason: Error): void => {\n\t\tfor (const call of pending.values()) {\n\t\t\tcall.dispose();\n\t\t\tcall.reject(reason);\n\t\t}\n\t\tpending.clear();\n\t};\n\n\tconst handle = (message: CanvasChildToHostMessage): void => {\n\t\tswitch (message.type) {\n\t\t\tcase \"ready\":\n\t\t\t\treadyResolve?.(message);\n\t\t\t\treturn;\n\t\t\tcase \"log\":\n\t\t\t\toptions.onLog?.(message.message, message.level, message.ephemeral);\n\t\t\t\treturn;\n\t\t\tdefault: {\n\t\t\t\t// A response for an id no longer pending is one whose caller stopped\n\t\t\t\t// waiting — aborted or timed out. Dropping it is the whole point.\n\t\t\t\tconst call = pending.get(message.id);\n\t\t\t\tif (!call) return;\n\t\t\t\tpending.delete(message.id);\n\t\t\t\tcall.dispose();\n\t\t\t\tif (message.type === \"response\") call.resolve(message.result);\n\t\t\t\telse call.reject(new CanvasCallError(message.code, message.message));\n\t\t\t}\n\t\t}\n\t};\n\n\tchild.stdout.setEncoding(\"utf8\");\n\tchild.stdout.on(\"data\", (chunk: string) => {\n\t\tconst { values, strays } = decoder.push(chunk);\n\t\tfor (const line of strays) options.onStray?.(line);\n\t\tfor (const value of values) {\n\t\t\tif (isCanvasChildToHostMessage(value)) handle(value);\n\t\t\telse options.onStray?.(JSON.stringify(value));\n\t\t}\n\t});\n\n\tchild.stderr.setEncoding(\"utf8\");\n\tchild.stderr.on(\"data\", (chunk: string) => options.onStderr?.(chunk));\n\n\tchild.on(\"error\", (error: Error) => {\n\t\texited = true;\n\t\treadyReject?.(error);\n\t\tsettleAll(error);\n\t});\n\n\tchild.on(\"exit\", (code, signal) => {\n\t\texited = true;\n\t\tconst reason = new Error(\n\t\t\t`Canvas extension \"${options.extensionId}\" exited (code ${String(code)}, signal ${String(signal)}).`,\n\t\t);\n\t\treadyReject?.(reason);\n\t\tsettleAll(reason);\n\t\toptions.onExit?.(code, signal);\n\t});\n\n\tconst call = (\n\t\tmethod: CanvasProviderMethod,\n\t\tparams: JsonValue,\n\t\tcallOptions?: CanvasCallOptions,\n\t): Promise<JsonValue> => {\n\t\tif (exited) {\n\t\t\treturn Promise.reject(new Error(`Canvas extension \"${options.extensionId}\" is not running.`));\n\t\t}\n\t\tconst signal = callOptions?.signal;\n\t\tif (signal?.aborted) {\n\t\t\t// Nothing is written to the child: a request nobody awaits should not exist.\n\t\t\treturn Promise.reject(\n\t\t\t\tnew CanvasCallError(CANVAS_ERROR_CODE_ABORTED, `Canvas ${method} was cancelled before it started.`),\n\t\t\t);\n\t\t}\n\t\tconst id = nextId;\n\t\tnextId += 1;\n\t\tconst timeoutMs = timeouts[method];\n\t\treturn new Promise<JsonValue>((resolve, reject) => {\n\t\t\tconst abandon = (error: Error): void => {\n\t\t\t\tconst entry = pending.get(id);\n\t\t\t\tif (!entry) return;\n\t\t\t\tpending.delete(id);\n\t\t\t\tentry.dispose();\n\t\t\t\treject(error);\n\t\t\t};\n\t\t\tconst timer =\n\t\t\t\ttimeoutMs > 0\n\t\t\t\t\t? setTimeout(\n\t\t\t\t\t\t\t() =>\n\t\t\t\t\t\t\t\tabandon(\n\t\t\t\t\t\t\t\t\tnew CanvasCallError(\n\t\t\t\t\t\t\t\t\t\tCANVAS_ERROR_CODE_ABORTED,\n\t\t\t\t\t\t\t\t\t\t`Canvas extension \"${options.extensionId}\" did not answer ${method} within ${timeoutMs}ms.`,\n\t\t\t\t\t\t\t\t\t),\n\t\t\t\t\t\t\t\t),\n\t\t\t\t\t\t\ttimeoutMs,\n\t\t\t\t\t\t)\n\t\t\t\t\t: undefined;\n\t\t\tconst onAbort = () =>\n\t\t\t\tabandon(new CanvasCallError(CANVAS_ERROR_CODE_ABORTED, `Canvas ${method} was cancelled.`));\n\t\t\tsignal?.addEventListener(\"abort\", onAbort, { once: true });\n\t\t\tpending.set(id, {\n\t\t\t\tresolve,\n\t\t\t\treject,\n\t\t\t\tdispose: () => {\n\t\t\t\t\tif (timer) clearTimeout(timer);\n\t\t\t\t\tsignal?.removeEventListener(\"abort\", onAbort);\n\t\t\t\t},\n\t\t\t});\n\t\t\tchild.stdin.write(\n\t\t\t\tencodeCanvasMessage({ envelope: CANVAS_ENVELOPE_VERSION, type: \"request\", id, method, params }),\n\t\t\t);\n\t\t});\n\t};\n\n\treturn {\n\t\textensionId: options.extensionId,\n\t\tready,\n\t\tget running() {\n\t\t\treturn !exited;\n\t\t},\n\t\topen: (params, callOptions) => call(\"canvas.open\", params as unknown as JsonValue, callOptions),\n\t\tclose: (params, callOptions) => call(\"canvas.close\", params as unknown as JsonValue, callOptions),\n\t\tinvokeAction: (params, callOptions) => call(\"canvas.action.invoke\", params as unknown as JsonValue, callOptions),\n\t\tterminate: () =>\n\t\t\tnew Promise<void>((resolve) => {\n\t\t\t\tif (exited) {\n\t\t\t\t\tresolve();\n\t\t\t\t\treturn;\n\t\t\t\t}\n\t\t\t\tconst kill = setTimeout(() => child.kill(\"SIGKILL\"), CANVAS_SHUTDOWN_GRACE_MS);\n\t\t\t\tchild.once(\"exit\", () => {\n\t\t\t\t\tclearTimeout(kill);\n\t\t\t\t\tresolve();\n\t\t\t\t});\n\t\t\t\tchild.kill(\"SIGTERM\");\n\t\t\t}),\n\t};\n}\n"]}

package/dist/core/canvas/sdk-shim/dispatch.test-helpers.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Test doubles for the shim's stdio streams, so dispatch can be exercised without
+ * forking a child process. Kept beside the shim rather than under `test/` because
+ * what these implement is the shim's own stream contract.
+ */
+import type { CanvasShimStreams } from "./index.js";
+/** A readable side whose chunks are pushed by the test. */
+export declare class FakeCanvasInput {
+    private listener;
+    setEncoding(_encoding: "utf8"): this;
+    on(_event: "data", listener: (chunk: string) => void): this;
+    /** Deliver a chunk as if the host had written it. */
+    feed(chunk: string): void;
+}
+/** Streams plus the lines the shim wrote, for assertions. */
+export interface FakeCanvasStreams extends CanvasShimStreams {
+    input: FakeCanvasInput;
+    /** Every line written by the shim, parsed. */
+    written: unknown[];
+}
+/** Build injectable streams whose writes are collected instead of sent to stdout. */
+export declare function fakeCanvasStreams(extensionId?: string): FakeCanvasStreams;
+//# sourceMappingURL=dispatch.test-helpers.d.ts.map

package/dist/core/canvas/sdk-shim/dispatch.test-helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dispatch.test-helpers.d.ts","sourceRoot":"","sources":["../../../../src/core/canvas/sdk-shim/dispatch.test-helpers.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAEpD,2DAA2D;AAC3D,qBAAa,eAAe;IAC3B,OAAO,CAAC,QAAQ,CAAwC;IAExD,WAAW,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAEnC;IAED,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,GAAG,IAAI,CAG1D;IAED,qDAAqD;IACrD,IAAI,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAExB;CACD;AAED,6DAA6D;AAC7D,MAAM,WAAW,iBAAkB,SAAQ,iBAAiB;IAC3D,KAAK,EAAE,eAAe,CAAC;IACvB,8CAA8C;IAC9C,OAAO,EAAE,OAAO,EAAE,CAAC;CACnB;AAED,qFAAqF;AACrF,wBAAgB,iBAAiB,CAAC,WAAW,SAAmB,GAAG,iBAAiB,CAYnF","sourcesContent":["/**\n * Test doubles for the shim's stdio streams, so dispatch can be exercised without\n * forking a child process. Kept beside the shim rather than under `test/` because\n * what these implement is the shim's own stream contract.\n */\n\nimport type { CanvasShimStreams } from \"./index.js\";\n\n/** A readable side whose chunks are pushed by the test. */\nexport class FakeCanvasInput {\n\tprivate listener: ((chunk: string) => void) | undefined;\n\n\tsetEncoding(_encoding: \"utf8\"): this {\n\t\treturn this;\n\t}\n\n\ton(_event: \"data\", listener: (chunk: string) => void): this {\n\t\tthis.listener = listener;\n\t\treturn this;\n\t}\n\n\t/** Deliver a chunk as if the host had written it. */\n\tfeed(chunk: string): void {\n\t\tthis.listener?.(chunk);\n\t}\n}\n\n/** Streams plus the lines the shim wrote, for assertions. */\nexport interface FakeCanvasStreams extends CanvasShimStreams {\n\tinput: FakeCanvasInput;\n\t/** Every line written by the shim, parsed. */\n\twritten: unknown[];\n}\n\n/** Build injectable streams whose writes are collected instead of sent to stdout. */\nexport function fakeCanvasStreams(extensionId = \"test-extension\"): FakeCanvasStreams {\n\tconst written: unknown[] = [];\n\treturn {\n\t\tinput: new FakeCanvasInput(),\n\t\twrite: (chunk: string) => {\n\t\t\tfor (const line of chunk.split(\"\\n\")) {\n\t\t\t\tif (line.trim().length > 0) written.push(JSON.parse(line));\n\t\t\t}\n\t\t},\n\t\textensionId,\n\t\twritten,\n\t};\n}\n"]}

package/dist/core/canvas/sdk-shim/dispatch.test-helpers.js

@@ -0,0 +1,36 @@
+/**
+ * Test doubles for the shim's stdio streams, so dispatch can be exercised without
+ * forking a child process. Kept beside the shim rather than under `test/` because
+ * what these implement is the shim's own stream contract.
+ */
+/** A readable side whose chunks are pushed by the test. */
+export class FakeCanvasInput {
+    listener;
+    setEncoding(_encoding) {
+        return this;
+    }
+    on(_event, listener) {
+        this.listener = listener;
+        return this;
+    }
+    /** Deliver a chunk as if the host had written it. */
+    feed(chunk) {
+        this.listener?.(chunk);
+    }
+}
+/** Build injectable streams whose writes are collected instead of sent to stdout. */
+export function fakeCanvasStreams(extensionId = "test-extension") {
+    const written = [];
+    return {
+        input: new FakeCanvasInput(),
+        write: (chunk) => {
+            for (const line of chunk.split("\n")) {
+                if (line.trim().length > 0)
+                    written.push(JSON.parse(line));
+            }
+        },
+        extensionId,
+        written,
+    };
+}
+//# sourceMappingURL=dispatch.test-helpers.js.map

package/dist/core/canvas/sdk-shim/dispatch.test-helpers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dispatch.test-helpers.js","sourceRoot":"","sources":["../../../../src/core/canvas/sdk-shim/dispatch.test-helpers.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH,2DAA2D;AAC3D,MAAM,OAAO,eAAe;IACnB,QAAQ,CAAwC;IAExD,WAAW,CAAC,SAAiB,EAAQ;QACpC,OAAO,IAAI,CAAC;IAAA,CACZ;IAED,EAAE,CAAC,MAAc,EAAE,QAAiC,EAAQ;QAC3D,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;QACzB,OAAO,IAAI,CAAC;IAAA,CACZ;IAED,qDAAqD;IACrD,IAAI,CAAC,KAAa,EAAQ;QACzB,IAAI,CAAC,QAAQ,EAAE,CAAC,KAAK,CAAC,CAAC;IAAA,CACvB;CACD;AASD,qFAAqF;AACrF,MAAM,UAAU,iBAAiB,CAAC,WAAW,GAAG,gBAAgB,EAAqB;IACpF,MAAM,OAAO,GAAc,EAAE,CAAC;IAC9B,OAAO;QACN,KAAK,EAAE,IAAI,eAAe,EAAE;QAC5B,KAAK,EAAE,CAAC,KAAa,EAAE,EAAE,CAAC;YACzB,KAAK,MAAM,IAAI,IAAI,KAAK,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC;gBACtC,IAAI,IAAI,CAAC,IAAI,EAAE,CAAC,MAAM,GAAG,CAAC;oBAAE,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC;YAC5D,CAAC;QAAA,CACD;QACD,WAAW;QACX,OAAO;KACP,CAAC;AAAA,CACF","sourcesContent":["/**\n * Test doubles for the shim's stdio streams, so dispatch can be exercised without\n * forking a child process. Kept beside the shim rather than under `test/` because\n * what these implement is the shim's own stream contract.\n */\n\nimport type { CanvasShimStreams } from \"./index.js\";\n\n/** A readable side whose chunks are pushed by the test. */\nexport class FakeCanvasInput {\n\tprivate listener: ((chunk: string) => void) | undefined;\n\n\tsetEncoding(_encoding: \"utf8\"): this {\n\t\treturn this;\n\t}\n\n\ton(_event: \"data\", listener: (chunk: string) => void): this {\n\t\tthis.listener = listener;\n\t\treturn this;\n\t}\n\n\t/** Deliver a chunk as if the host had written it. */\n\tfeed(chunk: string): void {\n\t\tthis.listener?.(chunk);\n\t}\n}\n\n/** Streams plus the lines the shim wrote, for assertions. */\nexport interface FakeCanvasStreams extends CanvasShimStreams {\n\tinput: FakeCanvasInput;\n\t/** Every line written by the shim, parsed. */\n\twritten: unknown[];\n}\n\n/** Build injectable streams whose writes are collected instead of sent to stdout. */\nexport function fakeCanvasStreams(extensionId = \"test-extension\"): FakeCanvasStreams {\n\tconst written: unknown[] = [];\n\treturn {\n\t\tinput: new FakeCanvasInput(),\n\t\twrite: (chunk: string) => {\n\t\t\tfor (const line of chunk.split(\"\\n\")) {\n\t\t\t\tif (line.trim().length > 0) written.push(JSON.parse(line));\n\t\t\t}\n\t\t},\n\t\textensionId,\n\t\twritten,\n\t};\n}\n"]}

package/dist/core/canvas/sdk-shim/index.d.ts

@@ -0,0 +1,113 @@
+/**
+ * Child-side `@github/copilot-sdk/extension` implementation.
+ *
+ * Design: `docs/canvas-extensions-design.md` §4, §4.1. A canvas extension from
+ * `github/awesome-copilot` is a directory of plain `.mjs` files whose only
+ * external import is `@github/copilot-sdk/extension` — GitHub's own
+ * `docs/extensions.md` states the import "is resolved automatically — you don't
+ * install it", and none of the 23 catalog extensions ships `node_modules`. This
+ * module is what hoocode resolves that specifier to inside the forked child, so a
+ * catalog canvas runs byte-identical to upstream with nothing written into its
+ * directory.
+ *
+ * What this is not: the SDK's `joinSession` resolves to a full `CopilotSession`
+ * (messaging, events, RPC passthrough, factories). This shim implements the
+ * canvas surface and `log` only. `tools`, `hooks`, and `factories` are accepted
+ * and reported as unsupported so an extension that uses them fails visibly rather
+ * than half-working (design doc §6.2). The canvas types themselves are held
+ * structurally identical to the SDK's by
+ * `test/canvas-protocol-conformance.test.ts`.
+ */
+import { type CanvasDeclaration, type CanvasJsonSchema, type CanvasLogLevel, type CanvasProviderCloseRequest, type CanvasProviderInvokeActionRequest, type CanvasProviderOpenRequest, type CanvasProviderOpenResult } from "../protocol.js";
+/**
+ * A single agent-callable action contributed by a canvas. Mirrors the SDK's
+ * `CanvasAction`: the `handler` closure is stripped before the declaration is
+ * sent and dispatched in-process here.
+ */
+export interface CanvasAction {
+    /** Action identifier, unique within the canvas. */
+    name: string;
+    /** Description shown to the model when picking an action. */
+    description?: string;
+    /** Optional JSON Schema for the action's `input` payload. */
+    inputSchema?: CanvasJsonSchema;
+    /** Required per-action dispatch handler. */
+    handler: (ctx: CanvasProviderInvokeActionRequest) => Promise<unknown> | unknown;
+}
+/** Options accepted by {@link createCanvas}. Mirrors the SDK's `CanvasOptions`. */
+export interface CanvasOptions {
+    /** Canvas id, unique within the declaring connection. */
+    id: string;
+    /** Human-readable label shown in discovery and host UI chrome. */
+    displayName: string;
+    /** Short, single-sentence description shown to the agent in canvas catalogs. */
+    description: string;
+    /** Optional JSON Schema for the `input` payload accepted by `canvas.open`. */
+    inputSchema?: CanvasJsonSchema;
+    /** Agent-invocable actions, each carrying its own required handler. */
+    actions?: CanvasAction[];
+    /** Required. Open a new canvas instance. */
+    open: (ctx: CanvasProviderOpenRequest) => Promise<CanvasProviderOpenResult> | CanvasProviderOpenResult;
+    /**
+     * Optional. Notified when a canvas instance is closed. Fire-and-forget: the
+     * return value is ignored and errors are logged but not surfaced.
+     */
+    onClose?: (ctx: CanvasProviderCloseRequest) => Promise<void> | void;
+}
+/** Structured error returned from canvas handlers. Mirrors the SDK's `CanvasError`. */
+export declare class CanvasError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string);
+    /** Default error when an action is declared but no `handler` is wired. */
+    static noHandler(): CanvasError;
+}
+/** A registered canvas: declarative metadata plus in-process handler closures. */
+export declare class Canvas {
+    readonly declaration: CanvasDeclaration;
+    readonly open: NonNullable<CanvasOptions["open"]>;
+    readonly onClose?: CanvasOptions["onClose"];
+    /** Handlers by action name, kept out of the declaration that crosses the wire. */
+    readonly handlers: ReadonlyMap<string, CanvasAction["handler"]>;
+    constructor(options: CanvasOptions);
+}
+/** Create a canvas declaration with bound in-process handlers. */
+export declare function createCanvas(options: CanvasOptions): Canvas;
+/** Configuration accepted by {@link joinSession}. */
+export interface JoinSessionConfig {
+    canvases?: Canvas[];
+    /** Accepted and reported as unsupported (design doc §6.2). */
+    tools?: unknown;
+    /** Accepted and reported as unsupported (design doc §6.2). */
+    hooks?: unknown;
+    /** Accepted and reported as unsupported (design doc §6.2). */
+    factories?: unknown;
+    /** Accepted and reported as unsupported (design doc §6.2). */
+    onPermissionRequest?: unknown;
+}
+/**
+ * The subset of the SDK's `CopilotSession` this shim provides. Deliberately small:
+ * see the module header.
+ */
+export interface CanvasShimSession {
+    /** Log a message to the session timeline. */
+    log(message: string, options?: {
+        level?: CanvasLogLevel;
+        ephemeral?: boolean;
+    }): Promise<void>;
+}
+/** Streams the shim reads from and writes to. Injectable so tests need no child process. */
+export interface CanvasShimStreams {
+    input: {
+        setEncoding(encoding: "utf8"): unknown;
+        on(event: "data", listener: (chunk: string) => void): unknown;
+    };
+    write(chunk: string): unknown;
+    /** Provider identifier; the runner passes it in the environment. */
+    extensionId: string;
+}
+/**
+ * Join the host session: announce the declared canvases, then serve provider
+ * callbacks until the input stream ends.
+ */
+export declare function joinSession(config?: JoinSessionConfig, streams?: CanvasShimStreams): Promise<CanvasShimSession>;
+//# sourceMappingURL=index.d.ts.map

package/dist/core/canvas/sdk-shim/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/core/canvas/sdk-shim/index.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Child-side `@github/copilot-sdk/extension` implementation.\n *\n * Design: `docs/canvas-extensions-design.md` §4, §4.1. A canvas extension from\n * `github/awesome-copilot` is a directory of plain `.mjs` files whose only\n * external import is `@github/copilot-sdk/extension` — GitHub's own\n * `docs/extensions.md` states the import \"is resolved automatically — you don't\n * install it\", and none of the 23 catalog extensions ships `node_modules`. This\n * module is what hoocode resolves that specifier to inside the forked child, so a\n * catalog canvas runs byte-identical to upstream with nothing written into its\n * directory.\n *\n * What this is not: the SDK's `joinSession` resolves to a full `CopilotSession`\n * (messaging, events, RPC passthrough, factories). This shim implements the\n * canvas surface and `log` only. `tools`, `hooks`, and `factories` are accepted\n * and reported as unsupported so an extension that uses them fails visibly rather\n * than half-working (design doc §6.2). The canvas types themselves are held\n * structurally identical to the SDK's by\n * `test/canvas-protocol-conformance.test.ts`.\n */\n\nimport {\n\tCANVAS_ENVELOPE_VERSION,\n\tCANVAS_ERROR_CODE_INTERNAL,\n\tCANVAS_ERROR_CODE_UNKNOWN_TARGET,\n\tCANVAS_METHOD_CLOSE,\n\tCANVAS_METHOD_INVOKE_ACTION,\n\tCANVAS_METHOD_OPEN,\n\tCANVAS_RESERVED_ACTION_PREFIX,\n\tCANVAS_SDK_PROTOCOL_VERSION,\n\ttype CanvasActionDeclaration,\n\ttype CanvasActionInvokeResult,\n\ttype CanvasChildToHostMessage,\n\ttype CanvasDeclaration,\n\ttype CanvasJsonSchema,\n\ttype CanvasLogLevel,\n\tCanvasMessageDecoder,\n\ttype CanvasProviderCloseRequest,\n\ttype CanvasProviderInvokeActionRequest,\n\ttype CanvasProviderOpenRequest,\n\ttype CanvasProviderOpenResult,\n\tencodeCanvasMessage,\n\tisCanvasHostToChildMessage,\n\ttype JsonValue,\n} from \"../protocol.js\";\n\n/**\n * A single agent-callable action contributed by a canvas. Mirrors the SDK's\n * `CanvasAction`: the `handler` closure is stripped before the declaration is\n * sent and dispatched in-process here.\n */\nexport interface CanvasAction {\n\t/** Action identifier, unique within the canvas. */\n\tname: string;\n\t/** Description shown to the model when picking an action. */\n\tdescription?: string;\n\t/** Optional JSON Schema for the action's `input` payload. */\n\tinputSchema?: CanvasJsonSchema;\n\t/** Required per-action dispatch handler. */\n\thandler: (ctx: CanvasProviderInvokeActionRequest) => Promise<unknown> | unknown;\n}\n\n/** Options accepted by {@link createCanvas}. Mirrors the SDK's `CanvasOptions`. */\nexport interface CanvasOptions {\n\t/** Canvas id, unique within the declaring connection. */\n\tid: string;\n\t/** Human-readable label shown in discovery and host UI chrome. */\n\tdisplayName: string;\n\t/** Short, single-sentence description shown to the agent in canvas catalogs. */\n\tdescription: string;\n\t/** Optional JSON Schema for the `input` payload accepted by `canvas.open`. */\n\tinputSchema?: CanvasJsonSchema;\n\t/** Agent-invocable actions, each carrying its own required handler. */\n\tactions?: CanvasAction[];\n\t/** Required. Open a new canvas instance. */\n\topen: (ctx: CanvasProviderOpenRequest) => Promise<CanvasProviderOpenResult> | CanvasProviderOpenResult;\n\t/**\n\t * Optional. Notified when a canvas instance is closed. Fire-and-forget: the\n\t * return value is ignored and errors are logged but not surfaced.\n\t */\n\tonClose?: (ctx: CanvasProviderCloseRequest) => Promise<void> | void;\n}\n\n/** Structured error returned from canvas handlers. Mirrors the SDK's `CanvasError`. */\nexport class CanvasError extends Error {\n\treadonly code: string;\n\n\tconstructor(code: string, message: string) {\n\t\tsuper(message);\n\t\tthis.name = \"CanvasError\";\n\t\tthis.code = code;\n\t}\n\n\t/** Default error when an action is declared but no `handler` is wired. */\n\tstatic noHandler(): CanvasError {\n\t\treturn new CanvasError(\"no_handler\", \"Canvas action has no handler.\");\n\t}\n}\n\n/** A registered canvas: declarative metadata plus in-process handler closures. */\nexport class Canvas {\n\treadonly declaration: CanvasDeclaration;\n\treadonly open: NonNullable<CanvasOptions[\"open\"]>;\n\treadonly onClose?: CanvasOptions[\"onClose\"];\n\t/** Handlers by action name, kept out of the declaration that crosses the wire. */\n\treadonly handlers: ReadonlyMap<string, CanvasAction[\"handler\"]>;\n\n\tconstructor(options: CanvasOptions) {\n\t\tconst actions: CanvasActionDeclaration[] = [];\n\t\tconst handlers = new Map<string, CanvasAction[\"handler\"]>();\n\t\tfor (const action of options.actions ?? []) {\n\t\t\tif (action.name.startsWith(CANVAS_RESERVED_ACTION_PREFIX)) {\n\t\t\t\tthrow new CanvasError(\n\t\t\t\t\t\"invalid_action_name\",\n\t\t\t\t\t`Action \"${action.name}\" must not start with \"${CANVAS_RESERVED_ACTION_PREFIX}\" — that prefix is reserved for lifecycle verbs.`,\n\t\t\t\t);\n\t\t\t}\n\t\t\tif (handlers.has(action.name)) {\n\t\t\t\tthrow new CanvasError(\"duplicate_action\", `Action \"${action.name}\" is declared more than once.`);\n\t\t\t}\n\t\t\tactions.push({ name: action.name, description: action.description, inputSchema: action.inputSchema });\n\t\t\thandlers.set(action.name, action.handler);\n\t\t}\n\t\tthis.declaration = {\n\t\t\tid: options.id,\n\t\t\tdisplayName: options.displayName,\n\t\t\tdescription: options.description,\n\t\t\tinputSchema: options.inputSchema,\n\t\t\tactions: actions.length > 0 ? actions : undefined,\n\t\t};\n\t\tthis.open = options.open;\n\t\tthis.onClose = options.onClose;\n\t\tthis.handlers = handlers;\n\t}\n}\n\n/** Create a canvas declaration with bound in-process handlers. */\nexport function createCanvas(options: CanvasOptions): Canvas {\n\treturn new Canvas(options);\n}\n\n/** Surfaces a Copilot extension may declare that this shim does not implement. */\nconst UNSUPPORTED_KEYS = [\"tools\", \"hooks\", \"factories\", \"onPermissionRequest\"] as const;\n\n/** Configuration accepted by {@link joinSession}. */\nexport interface JoinSessionConfig {\n\tcanvases?: Canvas[];\n\t/** Accepted and reported as unsupported (design doc §6.2). */\n\ttools?: unknown;\n\t/** Accepted and reported as unsupported (design doc §6.2). */\n\thooks?: unknown;\n\t/** Accepted and reported as unsupported (design doc §6.2). */\n\tfactories?: unknown;\n\t/** Accepted and reported as unsupported (design doc §6.2). */\n\tonPermissionRequest?: unknown;\n}\n\n/**\n * The subset of the SDK's `CopilotSession` this shim provides. Deliberately small:\n * see the module header.\n */\nexport interface CanvasShimSession {\n\t/** Log a message to the session timeline. */\n\tlog(message: string, options?: { level?: CanvasLogLevel; ephemeral?: boolean }): Promise<void>;\n}\n\n/** Streams the shim reads from and writes to. Injectable so tests need no child process. */\nexport interface CanvasShimStreams {\n\tinput: { setEncoding(encoding: \"utf8\"): unknown; on(event: \"data\", listener: (chunk: string) => void): unknown };\n\twrite(chunk: string): unknown;\n\t/** Provider identifier; the runner passes it in the environment. */\n\textensionId: string;\n}\n\nfunction defaultStreams(): CanvasShimStreams {\n\treturn {\n\t\tinput: process.stdin,\n\t\twrite: (chunk: string) => process.stdout.write(chunk),\n\t\textensionId: process.env.HOOCODE_CANVAS_EXTENSION_ID ?? \"unknown-extension\",\n\t};\n}\n\nfunction toJsonValue(value: unknown): JsonValue {\n\t// Handler return values are author-supplied. Round-tripping through JSON is what\n\t// the wire does anyway, so do it here where a cycle or a BigInt fails loudly with\n\t// the action's name attached rather than mid-write.\n\treturn value === undefined ? null : (JSON.parse(JSON.stringify(value)) as JsonValue);\n}\n\nfunction errorOf(cause: unknown): { code: string; message: string } {\n\tif (cause instanceof CanvasError) return { code: cause.code, message: cause.message };\n\treturn {\n\t\tcode: CANVAS_ERROR_CODE_INTERNAL,\n\t\tmessage: cause instanceof Error ? cause.message : String(cause),\n\t};\n}\n\n/**\n * Join the host session: announce the declared canvases, then serve provider\n * callbacks until the input stream ends.\n */\nexport async function joinSession(\n\tconfig: JoinSessionConfig = {},\n\tstreams: CanvasShimStreams = defaultStreams(),\n): Promise<CanvasShimSession> {\n\tconst canvases = new Map<string, Canvas>();\n\tfor (const canvas of config.canvases ?? []) {\n\t\tif (canvases.has(canvas.declaration.id)) {\n\t\t\tthrow new CanvasError(\"duplicate_canvas\", `Canvas \"${canvas.declaration.id}\" is declared more than once.`);\n\t\t}\n\t\tcanvases.set(canvas.declaration.id, canvas);\n\t}\n\n\tconst send = (message: CanvasChildToHostMessage): void => {\n\t\tstreams.write(encodeCanvasMessage(message));\n\t};\n\n\tsend({\n\t\tenvelope: CANVAS_ENVELOPE_VERSION,\n\t\ttype: \"ready\",\n\t\tprotocolVersion: CANVAS_SDK_PROTOCOL_VERSION,\n\t\textensionId: streams.extensionId,\n\t\tcanvases: [...canvases.values()].map((canvas) => canvas.declaration),\n\t\tunsupported: UNSUPPORTED_KEYS.filter((key) => config[key] !== undefined),\n\t});\n\n\tconst decoder = new CanvasMessageDecoder();\n\tstreams.input.setEncoding(\"utf8\");\n\tstreams.input.on(\"data\", (chunk: string) => {\n\t\tfor (const value of decoder.push(chunk).values) {\n\t\t\tif (!isCanvasHostToChildMessage(value)) continue;\n\t\t\tvoid dispatch(canvases, value.id, value.method, value.params, send);\n\t\t}\n\t});\n\n\treturn {\n\t\tlog: async (message, options) => {\n\t\t\tsend({\n\t\t\t\tenvelope: CANVAS_ENVELOPE_VERSION,\n\t\t\t\ttype: \"log\",\n\t\t\t\tmessage,\n\t\t\t\tlevel: options?.level,\n\t\t\t\tephemeral: options?.ephemeral,\n\t\t\t});\n\t\t},\n\t};\n}\n\nasync function dispatch(\n\tcanvases: ReadonlyMap<string, Canvas>,\n\tid: number,\n\tmethod: string,\n\tparams: JsonValue,\n\tsend: (message: CanvasChildToHostMessage) => void,\n): Promise<void> {\n\ttry {\n\t\tsend({\n\t\t\tenvelope: CANVAS_ENVELOPE_VERSION,\n\t\t\ttype: \"response\",\n\t\t\tid,\n\t\t\tresult: await invoke(canvases, method, params),\n\t\t});\n\t} catch (cause) {\n\t\tconst { code, message } = errorOf(cause);\n\t\tsend({ envelope: CANVAS_ENVELOPE_VERSION, type: \"error\", id, code, message });\n\t}\n}\n\nasync function invoke(canvases: ReadonlyMap<string, Canvas>, method: string, params: JsonValue): Promise<JsonValue> {\n\tif (method === CANVAS_METHOD_OPEN) {\n\t\tconst ctx = params as unknown as CanvasProviderOpenRequest;\n\t\treturn toJsonValue(await resolve(canvases, ctx.canvasId).open(ctx));\n\t}\n\tif (method === CANVAS_METHOD_CLOSE) {\n\t\tconst ctx = params as unknown as CanvasProviderCloseRequest;\n\t\t// Fire-and-forget per the SDK contract: a failing onClose must not fail the close.\n\t\tawait resolve(canvases, ctx.canvasId).onClose?.(ctx);\n\t\treturn null;\n\t}\n\tif (method === CANVAS_METHOD_INVOKE_ACTION) {\n\t\tconst ctx = params as unknown as CanvasProviderInvokeActionRequest;\n\t\tconst canvas = resolve(canvases, ctx.canvasId);\n\t\tconst handler = canvas.handlers.get(ctx.actionName);\n\t\tif (!handler) {\n\t\t\tthrow new CanvasError(\n\t\t\t\tCANVAS_ERROR_CODE_UNKNOWN_TARGET,\n\t\t\t\t`Canvas \"${ctx.canvasId}\" does not declare an action named \"${ctx.actionName}\".`,\n\t\t\t);\n\t\t}\n\t\tconst result: CanvasActionInvokeResult = toJsonValue(await handler(ctx));\n\t\treturn result;\n\t}\n\t// Unreachable while the host only sends methods `isCanvasHostToChildMessage`\n\t// accepts, but naming it keeps this function total if the protocol grows.\n\tthrow new CanvasError(CANVAS_ERROR_CODE_UNKNOWN_TARGET, `Unsupported provider method \"${method}\".`);\n}\n\nfunction resolve(canvases: ReadonlyMap<string, Canvas>, canvasId: string): Canvas {\n\tconst canvas = canvases.get(canvasId);\n\tif (!canvas) {\n\t\tthrow new CanvasError(CANVAS_ERROR_CODE_UNKNOWN_TARGET, `No canvas is registered with id \"${canvasId}\".`);\n\t}\n\treturn canvas;\n}\n"]}

package/dist/core/canvas/sdk-shim/index.js

@@ -0,0 +1,184 @@
+/**
+ * Child-side `@github/copilot-sdk/extension` implementation.
+ *
+ * Design: `docs/canvas-extensions-design.md` §4, §4.1. A canvas extension from
+ * `github/awesome-copilot` is a directory of plain `.mjs` files whose only
+ * external import is `@github/copilot-sdk/extension` — GitHub's own
+ * `docs/extensions.md` states the import "is resolved automatically — you don't
+ * install it", and none of the 23 catalog extensions ships `node_modules`. This
+ * module is what hoocode resolves that specifier to inside the forked child, so a
+ * catalog canvas runs byte-identical to upstream with nothing written into its
+ * directory.
+ *
+ * What this is not: the SDK's `joinSession` resolves to a full `CopilotSession`
+ * (messaging, events, RPC passthrough, factories). This shim implements the
+ * canvas surface and `log` only. `tools`, `hooks`, and `factories` are accepted
+ * and reported as unsupported so an extension that uses them fails visibly rather
+ * than half-working (design doc §6.2). The canvas types themselves are held
+ * structurally identical to the SDK's by
+ * `test/canvas-protocol-conformance.test.ts`.
+ */
+import { CANVAS_ENVELOPE_VERSION, CANVAS_ERROR_CODE_INTERNAL, CANVAS_ERROR_CODE_UNKNOWN_TARGET, CANVAS_METHOD_CLOSE, CANVAS_METHOD_INVOKE_ACTION, CANVAS_METHOD_OPEN, CANVAS_RESERVED_ACTION_PREFIX, CANVAS_SDK_PROTOCOL_VERSION, CanvasMessageDecoder, encodeCanvasMessage, isCanvasHostToChildMessage, } from "../protocol.js";
+/** Structured error returned from canvas handlers. Mirrors the SDK's `CanvasError`. */
+export class CanvasError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = "CanvasError";
+        this.code = code;
+    }
+    /** Default error when an action is declared but no `handler` is wired. */
+    static noHandler() {
+        return new CanvasError("no_handler", "Canvas action has no handler.");
+    }
+}
+/** A registered canvas: declarative metadata plus in-process handler closures. */
+export class Canvas {
+    declaration;
+    open;
+    onClose;
+    /** Handlers by action name, kept out of the declaration that crosses the wire. */
+    handlers;
+    constructor(options) {
+        const actions = [];
+        const handlers = new Map();
+        for (const action of options.actions ?? []) {
+            if (action.name.startsWith(CANVAS_RESERVED_ACTION_PREFIX)) {
+                throw new CanvasError("invalid_action_name", `Action "${action.name}" must not start with "${CANVAS_RESERVED_ACTION_PREFIX}" — that prefix is reserved for lifecycle verbs.`);
+            }
+            if (handlers.has(action.name)) {
+                throw new CanvasError("duplicate_action", `Action "${action.name}" is declared more than once.`);
+            }
+            actions.push({ name: action.name, description: action.description, inputSchema: action.inputSchema });
+            handlers.set(action.name, action.handler);
+        }
+        this.declaration = {
+            id: options.id,
+            displayName: options.displayName,
+            description: options.description,
+            inputSchema: options.inputSchema,
+            actions: actions.length > 0 ? actions : undefined,
+        };
+        this.open = options.open;
+        this.onClose = options.onClose;
+        this.handlers = handlers;
+    }
+}
+/** Create a canvas declaration with bound in-process handlers. */
+export function createCanvas(options) {
+    return new Canvas(options);
+}
+/** Surfaces a Copilot extension may declare that this shim does not implement. */
+const UNSUPPORTED_KEYS = ["tools", "hooks", "factories", "onPermissionRequest"];
+function defaultStreams() {
+    return {
+        input: process.stdin,
+        write: (chunk) => process.stdout.write(chunk),
+        extensionId: process.env.HOOCODE_CANVAS_EXTENSION_ID ?? "unknown-extension",
+    };
+}
+function toJsonValue(value) {
+    // Handler return values are author-supplied. Round-tripping through JSON is what
+    // the wire does anyway, so do it here where a cycle or a BigInt fails loudly with
+    // the action's name attached rather than mid-write.
+    return value === undefined ? null : JSON.parse(JSON.stringify(value));
+}
+function errorOf(cause) {
+    if (cause instanceof CanvasError)
+        return { code: cause.code, message: cause.message };
+    return {
+        code: CANVAS_ERROR_CODE_INTERNAL,
+        message: cause instanceof Error ? cause.message : String(cause),
+    };
+}
+/**
+ * Join the host session: announce the declared canvases, then serve provider
+ * callbacks until the input stream ends.
+ */
+export async function joinSession(config = {}, streams = defaultStreams()) {
+    const canvases = new Map();
+    for (const canvas of config.canvases ?? []) {
+        if (canvases.has(canvas.declaration.id)) {
+            throw new CanvasError("duplicate_canvas", `Canvas "${canvas.declaration.id}" is declared more than once.`);
+        }
+        canvases.set(canvas.declaration.id, canvas);
+    }
+    const send = (message) => {
+        streams.write(encodeCanvasMessage(message));
+    };
+    send({
+        envelope: CANVAS_ENVELOPE_VERSION,
+        type: "ready",
+        protocolVersion: CANVAS_SDK_PROTOCOL_VERSION,
+        extensionId: streams.extensionId,
+        canvases: [...canvases.values()].map((canvas) => canvas.declaration),
+        unsupported: UNSUPPORTED_KEYS.filter((key) => config[key] !== undefined),
+    });
+    const decoder = new CanvasMessageDecoder();
+    streams.input.setEncoding("utf8");
+    streams.input.on("data", (chunk) => {
+        for (const value of decoder.push(chunk).values) {
+            if (!isCanvasHostToChildMessage(value))
+                continue;
+            void dispatch(canvases, value.id, value.method, value.params, send);
+        }
+    });
+    return {
+        log: async (message, options) => {
+            send({
+                envelope: CANVAS_ENVELOPE_VERSION,
+                type: "log",
+                message,
+                level: options?.level,
+                ephemeral: options?.ephemeral,
+            });
+        },
+    };
+}
+async function dispatch(canvases, id, method, params, send) {
+    try {
+        send({
+            envelope: CANVAS_ENVELOPE_VERSION,
+            type: "response",
+            id,
+            result: await invoke(canvases, method, params),
+        });
+    }
+    catch (cause) {
+        const { code, message } = errorOf(cause);
+        send({ envelope: CANVAS_ENVELOPE_VERSION, type: "error", id, code, message });
+    }
+}
+async function invoke(canvases, method, params) {
+    if (method === CANVAS_METHOD_OPEN) {
+        const ctx = params;
+        return toJsonValue(await resolve(canvases, ctx.canvasId).open(ctx));
+    }
+    if (method === CANVAS_METHOD_CLOSE) {
+        const ctx = params;
+        // Fire-and-forget per the SDK contract: a failing onClose must not fail the close.
+        await resolve(canvases, ctx.canvasId).onClose?.(ctx);
+        return null;
+    }
+    if (method === CANVAS_METHOD_INVOKE_ACTION) {
+        const ctx = params;
+        const canvas = resolve(canvases, ctx.canvasId);
+        const handler = canvas.handlers.get(ctx.actionName);
+        if (!handler) {
+            throw new CanvasError(CANVAS_ERROR_CODE_UNKNOWN_TARGET, `Canvas "${ctx.canvasId}" does not declare an action named "${ctx.actionName}".`);
+        }
+        const result = toJsonValue(await handler(ctx));
+        return result;
+    }
+    // Unreachable while the host only sends methods `isCanvasHostToChildMessage`
+    // accepts, but naming it keeps this function total if the protocol grows.
+    throw new CanvasError(CANVAS_ERROR_CODE_UNKNOWN_TARGET, `Unsupported provider method "${method}".`);
+}
+function resolve(canvases, canvasId) {
+    const canvas = canvases.get(canvasId);
+    if (!canvas) {
+        throw new CanvasError(CANVAS_ERROR_CODE_UNKNOWN_TARGET, `No canvas is registered with id "${canvasId}".`);
+    }
+    return canvas;
+}
+//# sourceMappingURL=index.js.map