@kolisachint/hoocode-agent 0.5.21 → 0.5.23

package/dist/core/canvas/discovery.js

@@ -0,0 +1,83 @@
+/**
+ * Canvas extension discovery.
+ *
+ * Design: `docs/canvas-extensions-design.md` §4.1, §4.3. GitHub's
+ * `docs/extensions.md` is specific: the CLI "scans `.github/extensions/`
+ * (project) and the user's copilot config extensions directory for
+ * subdirectories containing `extension.mjs`", the entry file is required and must
+ * be named `extension.mjs`, and only ES modules are supported. All 23 extensions
+ * in `github/awesome-copilot` comply.
+ *
+ * So discovery keys off `<dir>/extension.mjs` and nothing else. In particular it
+ * does not read `package.json`: 3 of those 23 extensions ship without one, none
+ * ships `node_modules`, and where a `package.json` does exist its `main` is
+ * always `extension.mjs` anyway. Keying off it would add a failure mode without
+ * adding information.
+ *
+ * The extension id is the directory name, matching how the catalog and the
+ * Copilot app refer to extensions (`pr-artifact-explorer`).
+ *
+ * Some extensions also carry a `copilot-extension.json`, but it is neither
+ * required nor informative: 8 of the 23 catalog extensions have one, every
+ * instance holds exactly `{ name, version }`, and `name` always equals the
+ * directory name. Reading it would add a parse and a disagreement case without
+ * telling us anything the directory name does not.
+ */
+import { readdirSync, statSync } from "node:fs";
+import * as path from "node:path";
+/** Required entry file name. */
+export const CANVAS_ENTRY_FILE = "extension.mjs";
+/**
+ * Search roots in precedence order. `.agents/` first per
+ * `docs/plugin-format-mapping.md` §0; the Copilot conventions follow as
+ * compatibility inputs.
+ *
+ * `.github/extensions/` travels with a clone, so anything found there is subject
+ * to the workspace-trust gate before it is ever forked (design doc §5). Discovery
+ * itself is read-only and always safe to run.
+ */
+export function canvasSearchRoots(cwd, homeDir) {
+    return [
+        { dir: path.join(cwd, ".agents", "extensions"), scope: "agents" },
+        { dir: path.join(cwd, ".github", "extensions"), scope: "project" },
+        { dir: path.join(homeDir, ".copilot", "extensions"), scope: "user" },
+    ];
+}
+function subdirectories(dir) {
+    try {
+        return readdirSync(dir, { withFileTypes: true })
+            .filter((entry) => entry.isDirectory() || entry.isSymbolicLink())
+            .map((entry) => entry.name)
+            .sort();
+    }
+    catch {
+        return [];
+    }
+}
+function hasEntryFile(dir) {
+    try {
+        return statSync(path.join(dir, CANVAS_ENTRY_FILE)).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Discover canvas extensions across `roots`. First root wins on an id collision,
+ * so a project-local extension shadows a same-named user-scope one.
+ */
+export function discoverCanvasExtensions(roots) {
+    const found = new Map();
+    for (const root of roots) {
+        for (const id of subdirectories(root.dir)) {
+            if (found.has(id))
+                continue;
+            const dir = path.join(root.dir, id);
+            if (!hasEntryFile(dir))
+                continue;
+            found.set(id, { id, dir, entry: path.join(dir, CANVAS_ENTRY_FILE), scope: root.scope });
+        }
+    }
+    return [...found.values()];
+}
+//# sourceMappingURL=discovery.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"discovery.js","sourceRoot":"","sources":["../../../src/core/canvas/discovery.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,OAAO,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAChD,OAAO,KAAK,IAAI,MAAM,WAAW,CAAC;AAElC,gCAAgC;AAChC,MAAM,CAAC,MAAM,iBAAiB,GAAG,eAAe,CAAC;AAsBjD;;;;;;;;GAQG;AACH,MAAM,UAAU,iBAAiB,CAAC,GAAW,EAAE,OAAe,EAAsB;IACnF,OAAO;QACN,EAAE,GAAG,EAAE,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,SAAS,EAAE,YAAY,CAAC,EAAE,KAAK,EAAE,QAAQ,EAAE;QACjE,EAAE,GAAG,EAAE,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,SAAS,EAAE,YAAY,CAAC,EAAE,KAAK,EAAE,SAAS,EAAE;QAClE,EAAE,GAAG,EAAE,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,UAAU,EAAE,YAAY,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE;KACpE,CAAC;AAAA,CACF;AAED,SAAS,cAAc,CAAC,GAAW,EAAY;IAC9C,IAAI,CAAC;QACJ,OAAO,WAAW,CAAC,GAAG,EAAE,EAAE,aAAa,EAAE,IAAI,EAAE,CAAC;aAC9C,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,WAAW,EAAE,IAAI,KAAK,CAAC,cAAc,EAAE,CAAC;aAChE,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC;aAC1B,IAAI,EAAE,CAAC;IACV,CAAC;IAAC,MAAM,CAAC;QACR,OAAO,EAAE,CAAC;IACX,CAAC;AAAA,CACD;AAED,SAAS,YAAY,CAAC,GAAW,EAAW;IAC3C,IAAI,CAAC;QACJ,OAAO,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,iBAAiB,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC;IAC7D,CAAC;IAAC,MAAM,CAAC;QACR,OAAO,KAAK,CAAC;IACd,CAAC;AAAA,CACD;AAED;;;GAGG;AACH,MAAM,UAAU,wBAAwB,CAAC,KAAyB,EAA+B;IAChG,MAAM,KAAK,GAAG,IAAI,GAAG,EAAqC,CAAC;IAC3D,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QAC1B,KAAK,MAAM,EAAE,IAAI,cAAc,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;YAC3C,IAAI,KAAK,CAAC,GAAG,CAAC,EAAE,CAAC;gBAAE,SAAS;YAC5B,MAAM,GAAG,GAAG,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC;YACpC,IAAI,CAAC,YAAY,CAAC,GAAG,CAAC;gBAAE,SAAS;YACjC,KAAK,CAAC,GAAG,CAAC,EAAE,EAAE,EAAE,EAAE,EAAE,GAAG,EAAE,KAAK,EAAE,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,iBAAiB,CAAC,EAAE,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,CAAC,CAAC;QACzF,CAAC;IACF,CAAC;IACD,OAAO,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC,CAAC;AAAA,CAC3B","sourcesContent":["/**\n * Canvas extension discovery.\n *\n * Design: `docs/canvas-extensions-design.md` §4.1, §4.3. GitHub's\n * `docs/extensions.md` is specific: the CLI \"scans `.github/extensions/`\n * (project) and the user's copilot config extensions directory for\n * subdirectories containing `extension.mjs`\", the entry file is required and must\n * be named `extension.mjs`, and only ES modules are supported. All 23 extensions\n * in `github/awesome-copilot` comply.\n *\n * So discovery keys off `<dir>/extension.mjs` and nothing else. In particular it\n * does not read `package.json`: 3 of those 23 extensions ship without one, none\n * ships `node_modules`, and where a `package.json` does exist its `main` is\n * always `extension.mjs` anyway. Keying off it would add a failure mode without\n * adding information.\n *\n * The extension id is the directory name, matching how the catalog and the\n * Copilot app refer to extensions (`pr-artifact-explorer`).\n *\n * Some extensions also carry a `copilot-extension.json`, but it is neither\n * required nor informative: 8 of the 23 catalog extensions have one, every\n * instance holds exactly `{ name, version }`, and `name` always equals the\n * directory name. Reading it would add a parse and a disagreement case without\n * telling us anything the directory name does not.\n */\n\nimport { readdirSync, statSync } from \"node:fs\";\nimport * as path from \"node:path\";\n\n/** Required entry file name. */\nexport const CANVAS_ENTRY_FILE = \"extension.mjs\";\n\n/** Where a canvas extension came from, in precedence order. */\nexport type CanvasScope = \"agents\" | \"project\" | \"user\";\n\n/** Directory searched for canvas extensions. */\nexport interface CanvasSearchRoot {\n\tdir: string;\n\tscope: CanvasScope;\n}\n\n/** One discovered extension. */\nexport interface DiscoveredCanvasExtension {\n\t/** Directory name, used as the provider identifier. */\n\tid: string;\n\t/** Absolute path to the extension directory. */\n\tdir: string;\n\t/** Absolute path to `extension.mjs`. */\n\tentry: string;\n\tscope: CanvasScope;\n}\n\n/**\n * Search roots in precedence order. `.agents/` first per\n * `docs/plugin-format-mapping.md` §0; the Copilot conventions follow as\n * compatibility inputs.\n *\n * `.github/extensions/` travels with a clone, so anything found there is subject\n * to the workspace-trust gate before it is ever forked (design doc §5). Discovery\n * itself is read-only and always safe to run.\n */\nexport function canvasSearchRoots(cwd: string, homeDir: string): CanvasSearchRoot[] {\n\treturn [\n\t\t{ dir: path.join(cwd, \".agents\", \"extensions\"), scope: \"agents\" },\n\t\t{ dir: path.join(cwd, \".github\", \"extensions\"), scope: \"project\" },\n\t\t{ dir: path.join(homeDir, \".copilot\", \"extensions\"), scope: \"user\" },\n\t];\n}\n\nfunction subdirectories(dir: string): string[] {\n\ttry {\n\t\treturn readdirSync(dir, { withFileTypes: true })\n\t\t\t.filter((entry) => entry.isDirectory() || entry.isSymbolicLink())\n\t\t\t.map((entry) => entry.name)\n\t\t\t.sort();\n\t} catch {\n\t\treturn [];\n\t}\n}\n\nfunction hasEntryFile(dir: string): boolean {\n\ttry {\n\t\treturn statSync(path.join(dir, CANVAS_ENTRY_FILE)).isFile();\n\t} catch {\n\t\treturn false;\n\t}\n}\n\n/**\n * Discover canvas extensions across `roots`. First root wins on an id collision,\n * so a project-local extension shadows a same-named user-scope one.\n */\nexport function discoverCanvasExtensions(roots: CanvasSearchRoot[]): DiscoveredCanvasExtension[] {\n\tconst found = new Map<string, DiscoveredCanvasExtension>();\n\tfor (const root of roots) {\n\t\tfor (const id of subdirectories(root.dir)) {\n\t\t\tif (found.has(id)) continue;\n\t\t\tconst dir = path.join(root.dir, id);\n\t\t\tif (!hasEntryFile(dir)) continue;\n\t\t\tfound.set(id, { id, dir, entry: path.join(dir, CANVAS_ENTRY_FILE), scope: root.scope });\n\t\t}\n\t}\n\treturn [...found.values()];\n}\n"]}

package/dist/core/canvas/launch.d.ts

@@ -0,0 +1,90 @@
+/**
+ * Whether canvases can run here, and how to fork one.
+ *
+ * Design: `docs/canvas-extensions-design.md` §11.1. A canvas child must run under
+ * **Node ≥ 20.6** — the version that introduced `module.register`, which
+ * `resolver.ts` uses to make the SDK specifier resolvable inside the child without
+ * writing into the extension directory.
+ *
+ * The requirement is on the *child*, not on hoocode. An earlier version of this
+ * module conflated the two and refused to run canvases at all under the
+ * self-contained build; but a Bun-compiled parent forking a Node child is fine, so
+ * the question is "is a usable Node reachable?", not "are we Node?". That makes
+ * canvases available on every install path where Node exists — npm, bun, or the
+ * standalone binary with Node on PATH.
+ *
+ * Two traps found by running it rather than reasoning about it, both of which fail
+ * *silently* if you get them wrong:
+ *
+ *  1. **Bun exports `module.register` but ignores resolve hooks.** The call
+ *     succeeds, nothing warns, and the child then resolves the real
+ *     `@github/copilot-sdk` out of Bun's global install cache instead of the shim.
+ *     So the child may never be Bun, however the parent was launched.
+ *  2. **`process.versions.node` does not identify Node.** Bun reports
+ *     `process.versions.node = "24.3.0"` next to `process.versions.bun`. Deciding
+ *     "we can fork ourselves" must therefore require `process.versions.bun` to be
+ *     absent, never just a satisfying Node version.
+ *
+ * Resolution is not cached here. It can spawn `node --version`, so the caller should
+ * resolve once per session and hold the result rather than asking per open.
+ */
+import type { CanvasRuntime } from "./runner.js";
+/** Minimum Node that supports `module.register`, which `resolver.ts` depends on. */
+export declare const CANVAS_MIN_NODE_MAJOR = 20;
+/** Minimum minor within {@link CANVAS_MIN_NODE_MAJOR}. */
+export declare const CANVAS_MIN_NODE_MINOR = 6;
+/** How long to wait for `node --version` before giving up on PATH discovery. */
+export declare const CANVAS_NODE_PROBE_TIMEOUT_MS = 5000;
+/** Either a runtime that can fork canvases, or the reason none is available. */
+export type CanvasAvailability = {
+    available: true;
+    runtime: CanvasRuntime;
+} | {
+    available: false;
+    reason: string;
+};
+/**
+ * A shim the child could import, paired with whatever argv it needs to do so.
+ *
+ * The pairing is the point: the built `.js` needs nothing, while the TypeScript source
+ * needs a loader. Offering a shim without its prerequisite is how you get an
+ * "available" that fails at fork time.
+ */
+export interface CanvasShimCandidate {
+    /** `file:` URL of the shim module. */
+    url: string;
+    /** Extra argv prepended for the child, e.g. a TypeScript loader. */
+    execArgv: string[];
+}
+/** A Node executable found on PATH. */
+export interface DiscoveredNode {
+    /** Passed straight to `spawn`, so a bare name is fine — it resolves via PATH. */
+    execPath: string;
+    /** Version without the leading `v`. */
+    version: string;
+}
+/** Host facts {@link resolveCanvasRuntime} reads. Injectable so tests need no subprocess. */
+export interface CanvasHostProbe {
+    /** `process.versions.bun`, or undefined on Node. */
+    bunVersion: string | undefined;
+    /** `process.versions.node` — meaningless as a Node check; see the module header. */
+    nodeVersion: string;
+    /** `process.execPath`. */
+    execPath: string;
+    /** Candidate shims, highest precedence first. */
+    shimCandidates: CanvasShimCandidate[];
+    /** Whether a `file:` URL exists on disk. */
+    exists: (fileUrl: string) => boolean;
+    /** Locate a Node on PATH. Resolves undefined when there is none. */
+    probePathNode: () => Promise<DiscoveredNode | undefined>;
+}
+/** Read the current process. */
+export declare function currentCanvasHostProbe(): CanvasHostProbe;
+/**
+ * Decide whether canvases can run, and produce the runtime if so.
+ *
+ * Never throws and never guesses: an unavailable result carries a sentence a person
+ * can act on, because "no Node here" is a legitimate state rather than a failure.
+ */
+export declare function resolveCanvasRuntime(probe?: CanvasHostProbe): Promise<CanvasAvailability>;
+//# sourceMappingURL=launch.d.ts.map

package/dist/core/canvas/launch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"launch.d.ts","sourceRoot":"","sources":["../../../src/core/canvas/launch.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AASH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAKjD,oFAAoF;AACpF,eAAO,MAAM,qBAAqB,KAAK,CAAC;AACxC,0DAA0D;AAC1D,eAAO,MAAM,qBAAqB,IAAI,CAAC;AAEvC,gFAAgF;AAChF,eAAO,MAAM,4BAA4B,OAAQ,CAAC;AAElD,gFAAgF;AAChF,MAAM,MAAM,kBAAkB,GAAG;IAAE,SAAS,EAAE,IAAI,CAAC;IAAC,OAAO,EAAE,aAAa,CAAA;CAAE,GAAG;IAAE,SAAS,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAEpH;;;;;;GAMG;AACH,MAAM,WAAW,mBAAmB;IACnC,sCAAsC;IACtC,GAAG,EAAE,MAAM,CAAC;IACZ,oEAAoE;IACpE,QAAQ,EAAE,MAAM,EAAE,CAAC;CACnB;AAED,uCAAuC;AACvC,MAAM,WAAW,cAAc;IAC9B,mFAAiF;IACjF,QAAQ,EAAE,MAAM,CAAC;IACjB,uCAAuC;IACvC,OAAO,EAAE,MAAM,CAAC;CAChB;AAED,6FAA6F;AAC7F,MAAM,WAAW,eAAe;IAC/B,oDAAoD;IACpD,UAAU,EAAE,MAAM,GAAG,SAAS,CAAC;IAC/B,sFAAoF;IACpF,WAAW,EAAE,MAAM,CAAC;IACpB,0BAA0B;IAC1B,QAAQ,EAAE,MAAM,CAAC;IACjB,iDAAiD;IACjD,cAAc,EAAE,mBAAmB,EAAE,CAAC;IACtC,4CAA4C;IAC5C,MAAM,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC;IACrC,oEAAoE;IACpE,aAAa,EAAE,MAAM,OAAO,CAAC,cAAc,GAAG,SAAS,CAAC,CAAC;CACzD;AA4ED,gCAAgC;AAChC,wBAAgB,sBAAsB,IAAI,eAAe,CASxD;AAWD;;;;;GAKG;AACH,wBAAsB,oBAAoB,CACzC,KAAK,GAAE,eAA0C,GAC/C,OAAO,CAAC,kBAAkB,CAAC,CAmC7B","sourcesContent":["/**\n * Whether canvases can run here, and how to fork one.\n *\n * Design: `docs/canvas-extensions-design.md` §11.1. A canvas child must run under\n * **Node ≥ 20.6** — the version that introduced `module.register`, which\n * `resolver.ts` uses to make the SDK specifier resolvable inside the child without\n * writing into the extension directory.\n *\n * The requirement is on the *child*, not on hoocode. An earlier version of this\n * module conflated the two and refused to run canvases at all under the\n * self-contained build; but a Bun-compiled parent forking a Node child is fine, so\n * the question is \"is a usable Node reachable?\", not \"are we Node?\". That makes\n * canvases available on every install path where Node exists — npm, bun, or the\n * standalone binary with Node on PATH.\n *\n * Two traps found by running it rather than reasoning about it, both of which fail\n * *silently* if you get them wrong:\n *\n *  1. **Bun exports `module.register` but ignores resolve hooks.** The call\n *     succeeds, nothing warns, and the child then resolves the real\n *     `@github/copilot-sdk` out of Bun's global install cache instead of the shim.\n *     So the child may never be Bun, however the parent was launched.\n *  2. **`process.versions.node` does not identify Node.** Bun reports\n *     `process.versions.node = \"24.3.0\"` next to `process.versions.bun`. Deciding\n *     \"we can fork ourselves\" must therefore require `process.versions.bun` to be\n *     absent, never just a satisfying Node version.\n *\n * Resolution is not cached here. It can spawn `node --version`, so the caller should\n * resolve once per session and hold the result rather than asking per open.\n */\n\nimport { execFile } from \"node:child_process\";\nimport { existsSync } from \"node:fs\";\nimport { createRequire } from \"node:module\";\nimport * as path from \"node:path\";\nimport { fileURLToPath, pathToFileURL } from \"node:url\";\nimport { promisify } from \"node:util\";\nimport { getCanvasDir } from \"../../config.js\";\nimport type { CanvasRuntime } from \"./runner.js\";\n\nconst execFileAsync = promisify(execFile);\nconst require = createRequire(import.meta.url);\n\n/** Minimum Node that supports `module.register`, which `resolver.ts` depends on. */\nexport const CANVAS_MIN_NODE_MAJOR = 20;\n/** Minimum minor within {@link CANVAS_MIN_NODE_MAJOR}. */\nexport const CANVAS_MIN_NODE_MINOR = 6;\n\n/** How long to wait for `node --version` before giving up on PATH discovery. */\nexport const CANVAS_NODE_PROBE_TIMEOUT_MS = 5_000;\n\n/** Either a runtime that can fork canvases, or the reason none is available. */\nexport type CanvasAvailability = { available: true; runtime: CanvasRuntime } | { available: false; reason: string };\n\n/**\n * A shim the child could import, paired with whatever argv it needs to do so.\n *\n * The pairing is the point: the built `.js` needs nothing, while the TypeScript source\n * needs a loader. Offering a shim without its prerequisite is how you get an\n * \"available\" that fails at fork time.\n */\nexport interface CanvasShimCandidate {\n\t/** `file:` URL of the shim module. */\n\turl: string;\n\t/** Extra argv prepended for the child, e.g. a TypeScript loader. */\n\texecArgv: string[];\n}\n\n/** A Node executable found on PATH. */\nexport interface DiscoveredNode {\n\t/** Passed straight to `spawn`, so a bare name is fine — it resolves via PATH. */\n\texecPath: string;\n\t/** Version without the leading `v`. */\n\tversion: string;\n}\n\n/** Host facts {@link resolveCanvasRuntime} reads. Injectable so tests need no subprocess. */\nexport interface CanvasHostProbe {\n\t/** `process.versions.bun`, or undefined on Node. */\n\tbunVersion: string | undefined;\n\t/** `process.versions.node` — meaningless as a Node check; see the module header. */\n\tnodeVersion: string;\n\t/** `process.execPath`. */\n\texecPath: string;\n\t/** Candidate shims, highest precedence first. */\n\tshimCandidates: CanvasShimCandidate[];\n\t/** Whether a `file:` URL exists on disk. */\n\texists: (fileUrl: string) => boolean;\n\t/** Locate a Node on PATH. Resolves undefined when there is none. */\n\tprobePathNode: () => Promise<DiscoveredNode | undefined>;\n}\n\n/**\n * Where the child looks for the shim, best first.\n *\n * 1. The built `index.js`, via `getCanvasDir()` so the standalone binary's sidecar\n *    copy is found the same way themes and the HTML export template are. Needs no\n *    extra argv.\n * 2. The TypeScript source, for a checkout run through `tsx` (`hoocode-test.sh`)\n *    where no `dist` exists. Offered **only** when `tsx` actually resolves, so this\n *    is a verified capability rather than a hopeful one — a forked child cannot\n *    import `.ts` on its own, and an \"available\" that fails at fork time is worse\n *    than an honest no.\n *\n * Without (2), the people most likely to be writing canvases — contributors running\n * from source — could not open one.\n */\nfunction defaultShimCandidates(): CanvasShimCandidate[] {\n\tconst canvasDir = getCanvasDir();\n\tconst candidates: CanvasShimCandidate[] = [\n\t\t{ url: pathToFileURL(path.join(canvasDir, \"sdk-shim\", \"index.js\")).href, execArgv: [] },\n\t];\n\tconst loader = typescriptLoaderArg();\n\tif (loader) {\n\t\tcandidates.push({\n\t\t\turl: pathToFileURL(path.join(canvasDir, \"sdk-shim\", \"index.ts\")).href,\n\t\t\texecArgv: [\"--import\", loader],\n\t\t});\n\t}\n\treturn candidates;\n}\n\n/**\n * An absolute `--import` argument for `tsx`, or undefined when it is not installed.\n *\n * Absolute on purpose: Node resolves a bare `--import` specifier against the *child's*\n * working directory, so `tsx/esm` would work only while an extension happened to sit\n * inside this repository and fail elsewhere with ERR_MODULE_NOT_FOUND.\n */\nfunction typescriptLoaderArg(): string | undefined {\n\ttry {\n\t\treturn pathToFileURL(require.resolve(\"tsx/esm\")).href;\n\t} catch {\n\t\treturn undefined;\n\t}\n}\n\nfunction fileUrlExists(fileUrl: string): boolean {\n\ttry {\n\t\treturn existsSync(fileURLToPath(fileUrl));\n\t} catch {\n\t\treturn false;\n\t}\n}\n\n/**\n * Ask PATH for a Node.\n *\n * `spawn` resolves a bare command name through PATH (and PATHEXT on Windows)\n * without a shell, so there is no directory scanning to get wrong here — and unlike\n * `npx`/`npm`, `node` is a real executable rather than a `.cmd` shim, so the Windows\n * caveat in `extensions/core/mcp-loader.ts` does not apply.\n */\nasync function probeNodeOnPath(): Promise<DiscoveredNode | undefined> {\n\ttry {\n\t\tconst { stdout } = await execFileAsync(\"node\", [\"--version\"], {\n\t\t\ttimeout: CANVAS_NODE_PROBE_TIMEOUT_MS,\n\t\t\twindowsHide: true,\n\t\t});\n\t\tconst version = stdout.trim().replace(/^v/, \"\");\n\t\treturn version.length > 0 ? { execPath: \"node\", version } : undefined;\n\t} catch {\n\t\treturn undefined;\n\t}\n}\n\n/** Read the current process. */\nexport function currentCanvasHostProbe(): CanvasHostProbe {\n\treturn {\n\t\tbunVersion: process.versions.bun,\n\t\tnodeVersion: process.versions.node,\n\t\texecPath: process.execPath,\n\t\tshimCandidates: defaultShimCandidates(),\n\t\texists: fileUrlExists,\n\t\tprobePathNode: probeNodeOnPath,\n\t};\n}\n\nfunction meetsMinimum(nodeVersion: string): boolean {\n\tconst [major, minor] = nodeVersion.split(\".\").map((part) => Number.parseInt(part, 10));\n\tif (!Number.isInteger(major) || !Number.isInteger(minor)) return false;\n\tif (major > CANVAS_MIN_NODE_MAJOR) return true;\n\treturn major === CANVAS_MIN_NODE_MAJOR && minor >= CANVAS_MIN_NODE_MINOR;\n}\n\nconst MIN_LABEL = `${CANVAS_MIN_NODE_MAJOR}.${CANVAS_MIN_NODE_MINOR}`;\n\n/**\n * Decide whether canvases can run, and produce the runtime if so.\n *\n * Never throws and never guesses: an unavailable result carries a sentence a person\n * can act on, because \"no Node here\" is a legitimate state rather than a failure.\n */\nexport async function resolveCanvasRuntime(\n\tprobe: CanvasHostProbe = currentCanvasHostProbe(),\n): Promise<CanvasAvailability> {\n\tconst shim = probe.shimCandidates.find((candidate) => probe.exists(candidate.url));\n\tif (shim === undefined) {\n\t\treturn {\n\t\t\tavailable: false,\n\t\t\treason:\n\t\t\t\t\"Canvas extensions need the built canvas shim, which was not found where it ships. \" +\n\t\t\t\t\"This usually means an incomplete install; reinstalling hoocode should restore it.\",\n\t\t};\n\t}\n\n\t// Forking ourselves is only sound when we are genuinely Node: Bun reports a\n\t// satisfying process.versions.node but ignores the resolve hook the child needs.\n\tif (probe.bunVersion === undefined && meetsMinimum(probe.nodeVersion)) {\n\t\treturn { available: true, runtime: { execPath: probe.execPath, execArgv: shim.execArgv, shimUrl: shim.url } };\n\t}\n\n\tconst found = await probe.probePathNode();\n\tif (!found) {\n\t\treturn {\n\t\t\tavailable: false,\n\t\t\treason:\n\t\t\t\t`Canvas extensions run in a Node child process and no \\`node\\` was found on PATH. ` +\n\t\t\t\t`Install Node ${MIN_LABEL} or newer to use canvases.`,\n\t\t};\n\t}\n\tif (!meetsMinimum(found.version)) {\n\t\treturn {\n\t\t\tavailable: false,\n\t\t\treason:\n\t\t\t\t`Canvas extensions need Node ${MIN_LABEL} or newer for module.register(); ` +\n\t\t\t\t`the \\`node\\` on PATH is ${found.version}.`,\n\t\t};\n\t}\n\treturn { available: true, runtime: { execPath: found.execPath, execArgv: shim.execArgv, shimUrl: shim.url } };\n}\n"]}

package/dist/core/canvas/launch.js

@@ -0,0 +1,176 @@
+/**
+ * Whether canvases can run here, and how to fork one.
+ *
+ * Design: `docs/canvas-extensions-design.md` §11.1. A canvas child must run under
+ * **Node ≥ 20.6** — the version that introduced `module.register`, which
+ * `resolver.ts` uses to make the SDK specifier resolvable inside the child without
+ * writing into the extension directory.
+ *
+ * The requirement is on the *child*, not on hoocode. An earlier version of this
+ * module conflated the two and refused to run canvases at all under the
+ * self-contained build; but a Bun-compiled parent forking a Node child is fine, so
+ * the question is "is a usable Node reachable?", not "are we Node?". That makes
+ * canvases available on every install path where Node exists — npm, bun, or the
+ * standalone binary with Node on PATH.
+ *
+ * Two traps found by running it rather than reasoning about it, both of which fail
+ * *silently* if you get them wrong:
+ *
+ *  1. **Bun exports `module.register` but ignores resolve hooks.** The call
+ *     succeeds, nothing warns, and the child then resolves the real
+ *     `@github/copilot-sdk` out of Bun's global install cache instead of the shim.
+ *     So the child may never be Bun, however the parent was launched.
+ *  2. **`process.versions.node` does not identify Node.** Bun reports
+ *     `process.versions.node = "24.3.0"` next to `process.versions.bun`. Deciding
+ *     "we can fork ourselves" must therefore require `process.versions.bun` to be
+ *     absent, never just a satisfying Node version.
+ *
+ * Resolution is not cached here. It can spawn `node --version`, so the caller should
+ * resolve once per session and hold the result rather than asking per open.
+ */
+import { execFile } from "node:child_process";
+import { existsSync } from "node:fs";
+import { createRequire } from "node:module";
+import * as path from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { promisify } from "node:util";
+import { getCanvasDir } from "../../config.js";
+const execFileAsync = promisify(execFile);
+const require = createRequire(import.meta.url);
+/** Minimum Node that supports `module.register`, which `resolver.ts` depends on. */
+export const CANVAS_MIN_NODE_MAJOR = 20;
+/** Minimum minor within {@link CANVAS_MIN_NODE_MAJOR}. */
+export const CANVAS_MIN_NODE_MINOR = 6;
+/** How long to wait for `node --version` before giving up on PATH discovery. */
+export const CANVAS_NODE_PROBE_TIMEOUT_MS = 5_000;
+/**
+ * Where the child looks for the shim, best first.
+ *
+ * 1. The built `index.js`, via `getCanvasDir()` so the standalone binary's sidecar
+ *    copy is found the same way themes and the HTML export template are. Needs no
+ *    extra argv.
+ * 2. The TypeScript source, for a checkout run through `tsx` (`hoocode-test.sh`)
+ *    where no `dist` exists. Offered **only** when `tsx` actually resolves, so this
+ *    is a verified capability rather than a hopeful one — a forked child cannot
+ *    import `.ts` on its own, and an "available" that fails at fork time is worse
+ *    than an honest no.
+ *
+ * Without (2), the people most likely to be writing canvases — contributors running
+ * from source — could not open one.
+ */
+function defaultShimCandidates() {
+    const canvasDir = getCanvasDir();
+    const candidates = [
+        { url: pathToFileURL(path.join(canvasDir, "sdk-shim", "index.js")).href, execArgv: [] },
+    ];
+    const loader = typescriptLoaderArg();
+    if (loader) {
+        candidates.push({
+            url: pathToFileURL(path.join(canvasDir, "sdk-shim", "index.ts")).href,
+            execArgv: ["--import", loader],
+        });
+    }
+    return candidates;
+}
+/**
+ * An absolute `--import` argument for `tsx`, or undefined when it is not installed.
+ *
+ * Absolute on purpose: Node resolves a bare `--import` specifier against the *child's*
+ * working directory, so `tsx/esm` would work only while an extension happened to sit
+ * inside this repository and fail elsewhere with ERR_MODULE_NOT_FOUND.
+ */
+function typescriptLoaderArg() {
+    try {
+        return pathToFileURL(require.resolve("tsx/esm")).href;
+    }
+    catch {
+        return undefined;
+    }
+}
+function fileUrlExists(fileUrl) {
+    try {
+        return existsSync(fileURLToPath(fileUrl));
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Ask PATH for a Node.
+ *
+ * `spawn` resolves a bare command name through PATH (and PATHEXT on Windows)
+ * without a shell, so there is no directory scanning to get wrong here — and unlike
+ * `npx`/`npm`, `node` is a real executable rather than a `.cmd` shim, so the Windows
+ * caveat in `extensions/core/mcp-loader.ts` does not apply.
+ */
+async function probeNodeOnPath() {
+    try {
+        const { stdout } = await execFileAsync("node", ["--version"], {
+            timeout: CANVAS_NODE_PROBE_TIMEOUT_MS,
+            windowsHide: true,
+        });
+        const version = stdout.trim().replace(/^v/, "");
+        return version.length > 0 ? { execPath: "node", version } : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Read the current process. */
+export function currentCanvasHostProbe() {
+    return {
+        bunVersion: process.versions.bun,
+        nodeVersion: process.versions.node,
+        execPath: process.execPath,
+        shimCandidates: defaultShimCandidates(),
+        exists: fileUrlExists,
+        probePathNode: probeNodeOnPath,
+    };
+}
+function meetsMinimum(nodeVersion) {
+    const [major, minor] = nodeVersion.split(".").map((part) => Number.parseInt(part, 10));
+    if (!Number.isInteger(major) || !Number.isInteger(minor))
+        return false;
+    if (major > CANVAS_MIN_NODE_MAJOR)
+        return true;
+    return major === CANVAS_MIN_NODE_MAJOR && minor >= CANVAS_MIN_NODE_MINOR;
+}
+const MIN_LABEL = `${CANVAS_MIN_NODE_MAJOR}.${CANVAS_MIN_NODE_MINOR}`;
+/**
+ * Decide whether canvases can run, and produce the runtime if so.
+ *
+ * Never throws and never guesses: an unavailable result carries a sentence a person
+ * can act on, because "no Node here" is a legitimate state rather than a failure.
+ */
+export async function resolveCanvasRuntime(probe = currentCanvasHostProbe()) {
+    const shim = probe.shimCandidates.find((candidate) => probe.exists(candidate.url));
+    if (shim === undefined) {
+        return {
+            available: false,
+            reason: "Canvas extensions need the built canvas shim, which was not found where it ships. " +
+                "This usually means an incomplete install; reinstalling hoocode should restore it.",
+        };
+    }
+    // Forking ourselves is only sound when we are genuinely Node: Bun reports a
+    // satisfying process.versions.node but ignores the resolve hook the child needs.
+    if (probe.bunVersion === undefined && meetsMinimum(probe.nodeVersion)) {
+        return { available: true, runtime: { execPath: probe.execPath, execArgv: shim.execArgv, shimUrl: shim.url } };
+    }
+    const found = await probe.probePathNode();
+    if (!found) {
+        return {
+            available: false,
+            reason: `Canvas extensions run in a Node child process and no \`node\` was found on PATH. ` +
+                `Install Node ${MIN_LABEL} or newer to use canvases.`,
+        };
+    }
+    if (!meetsMinimum(found.version)) {
+        return {
+            available: false,
+            reason: `Canvas extensions need Node ${MIN_LABEL} or newer for module.register(); ` +
+                `the \`node\` on PATH is ${found.version}.`,
+        };
+    }
+    return { available: true, runtime: { execPath: found.execPath, execArgv: shim.execArgv, shimUrl: shim.url } };
+}
+//# sourceMappingURL=launch.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"launch.js","sourceRoot":"","sources":["../../../src/core/canvas/launch.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Whether canvases can run here, and how to fork one.\n *\n * Design: `docs/canvas-extensions-design.md` §11.1. A canvas child must run under\n * **Node ≥ 20.6** — the version that introduced `module.register`, which\n * `resolver.ts` uses to make the SDK specifier resolvable inside the child without\n * writing into the extension directory.\n *\n * The requirement is on the *child*, not on hoocode. An earlier version of this\n * module conflated the two and refused to run canvases at all under the\n * self-contained build; but a Bun-compiled parent forking a Node child is fine, so\n * the question is \"is a usable Node reachable?\", not \"are we Node?\". That makes\n * canvases available on every install path where Node exists — npm, bun, or the\n * standalone binary with Node on PATH.\n *\n * Two traps found by running it rather than reasoning about it, both of which fail\n * *silently* if you get them wrong:\n *\n *  1. **Bun exports `module.register` but ignores resolve hooks.** The call\n *     succeeds, nothing warns, and the child then resolves the real\n *     `@github/copilot-sdk` out of Bun's global install cache instead of the shim.\n *     So the child may never be Bun, however the parent was launched.\n *  2. **`process.versions.node` does not identify Node.** Bun reports\n *     `process.versions.node = \"24.3.0\"` next to `process.versions.bun`. Deciding\n *     \"we can fork ourselves\" must therefore require `process.versions.bun` to be\n *     absent, never just a satisfying Node version.\n *\n * Resolution is not cached here. It can spawn `node --version`, so the caller should\n * resolve once per session and hold the result rather than asking per open.\n */\n\nimport { execFile } from \"node:child_process\";\nimport { existsSync } from \"node:fs\";\nimport { createRequire } from \"node:module\";\nimport * as path from \"node:path\";\nimport { fileURLToPath, pathToFileURL } from \"node:url\";\nimport { promisify } from \"node:util\";\nimport { getCanvasDir } from \"../../config.js\";\nimport type { CanvasRuntime } from \"./runner.js\";\n\nconst execFileAsync = promisify(execFile);\nconst require = createRequire(import.meta.url);\n\n/** Minimum Node that supports `module.register`, which `resolver.ts` depends on. */\nexport const CANVAS_MIN_NODE_MAJOR = 20;\n/** Minimum minor within {@link CANVAS_MIN_NODE_MAJOR}. */\nexport const CANVAS_MIN_NODE_MINOR = 6;\n\n/** How long to wait for `node --version` before giving up on PATH discovery. */\nexport const CANVAS_NODE_PROBE_TIMEOUT_MS = 5_000;\n\n/** Either a runtime that can fork canvases, or the reason none is available. */\nexport type CanvasAvailability = { available: true; runtime: CanvasRuntime } | { available: false; reason: string };\n\n/**\n * A shim the child could import, paired with whatever argv it needs to do so.\n *\n * The pairing is the point: the built `.js` needs nothing, while the TypeScript source\n * needs a loader. Offering a shim without its prerequisite is how you get an\n * \"available\" that fails at fork time.\n */\nexport interface CanvasShimCandidate {\n\t/** `file:` URL of the shim module. */\n\turl: string;\n\t/** Extra argv prepended for the child, e.g. a TypeScript loader. */\n\texecArgv: string[];\n}\n\n/** A Node executable found on PATH. */\nexport interface DiscoveredNode {\n\t/** Passed straight to `spawn`, so a bare name is fine — it resolves via PATH. */\n\texecPath: string;\n\t/** Version without the leading `v`. */\n\tversion: string;\n}\n\n/** Host facts {@link resolveCanvasRuntime} reads. Injectable so tests need no subprocess. */\nexport interface CanvasHostProbe {\n\t/** `process.versions.bun`, or undefined on Node. */\n\tbunVersion: string | undefined;\n\t/** `process.versions.node` — meaningless as a Node check; see the module header. */\n\tnodeVersion: string;\n\t/** `process.execPath`. */\n\texecPath: string;\n\t/** Candidate shims, highest precedence first. */\n\tshimCandidates: CanvasShimCandidate[];\n\t/** Whether a `file:` URL exists on disk. */\n\texists: (fileUrl: string) => boolean;\n\t/** Locate a Node on PATH. Resolves undefined when there is none. */\n\tprobePathNode: () => Promise<DiscoveredNode | undefined>;\n}\n\n/**\n * Where the child looks for the shim, best first.\n *\n * 1. The built `index.js`, via `getCanvasDir()` so the standalone binary's sidecar\n *    copy is found the same way themes and the HTML export template are. Needs no\n *    extra argv.\n * 2. The TypeScript source, for a checkout run through `tsx` (`hoocode-test.sh`)\n *    where no `dist` exists. Offered **only** when `tsx` actually resolves, so this\n *    is a verified capability rather than a hopeful one — a forked child cannot\n *    import `.ts` on its own, and an \"available\" that fails at fork time is worse\n *    than an honest no.\n *\n * Without (2), the people most likely to be writing canvases — contributors running\n * from source — could not open one.\n */\nfunction defaultShimCandidates(): CanvasShimCandidate[] {\n\tconst canvasDir = getCanvasDir();\n\tconst candidates: CanvasShimCandidate[] = [\n\t\t{ url: pathToFileURL(path.join(canvasDir, \"sdk-shim\", \"index.js\")).href, execArgv: [] },\n\t];\n\tconst loader = typescriptLoaderArg();\n\tif (loader) {\n\t\tcandidates.push({\n\t\t\turl: pathToFileURL(path.join(canvasDir, \"sdk-shim\", \"index.ts\")).href,\n\t\t\texecArgv: [\"--import\", loader],\n\t\t});\n\t}\n\treturn candidates;\n}\n\n/**\n * An absolute `--import` argument for `tsx`, or undefined when it is not installed.\n *\n * Absolute on purpose: Node resolves a bare `--import` specifier against the *child's*\n * working directory, so `tsx/esm` would work only while an extension happened to sit\n * inside this repository and fail elsewhere with ERR_MODULE_NOT_FOUND.\n */\nfunction typescriptLoaderArg(): string | undefined {\n\ttry {\n\t\treturn pathToFileURL(require.resolve(\"tsx/esm\")).href;\n\t} catch {\n\t\treturn undefined;\n\t}\n}\n\nfunction fileUrlExists(fileUrl: string): boolean {\n\ttry {\n\t\treturn existsSync(fileURLToPath(fileUrl));\n\t} catch {\n\t\treturn false;\n\t}\n}\n\n/**\n * Ask PATH for a Node.\n *\n * `spawn` resolves a bare command name through PATH (and PATHEXT on Windows)\n * without a shell, so there is no directory scanning to get wrong here — and unlike\n * `npx`/`npm`, `node` is a real executable rather than a `.cmd` shim, so the Windows\n * caveat in `extensions/core/mcp-loader.ts` does not apply.\n */\nasync function probeNodeOnPath(): Promise<DiscoveredNode | undefined> {\n\ttry {\n\t\tconst { stdout } = await execFileAsync(\"node\", [\"--version\"], {\n\t\t\ttimeout: CANVAS_NODE_PROBE_TIMEOUT_MS,\n\t\t\twindowsHide: true,\n\t\t});\n\t\tconst version = stdout.trim().replace(/^v/, \"\");\n\t\treturn version.length > 0 ? { execPath: \"node\", version } : undefined;\n\t} catch {\n\t\treturn undefined;\n\t}\n}\n\n/** Read the current process. */\nexport function currentCanvasHostProbe(): CanvasHostProbe {\n\treturn {\n\t\tbunVersion: process.versions.bun,\n\t\tnodeVersion: process.versions.node,\n\t\texecPath: process.execPath,\n\t\tshimCandidates: defaultShimCandidates(),\n\t\texists: fileUrlExists,\n\t\tprobePathNode: probeNodeOnPath,\n\t};\n}\n\nfunction meetsMinimum(nodeVersion: string): boolean {\n\tconst [major, minor] = nodeVersion.split(\".\").map((part) => Number.parseInt(part, 10));\n\tif (!Number.isInteger(major) || !Number.isInteger(minor)) return false;\n\tif (major > CANVAS_MIN_NODE_MAJOR) return true;\n\treturn major === CANVAS_MIN_NODE_MAJOR && minor >= CANVAS_MIN_NODE_MINOR;\n}\n\nconst MIN_LABEL = `${CANVAS_MIN_NODE_MAJOR}.${CANVAS_MIN_NODE_MINOR}`;\n\n/**\n * Decide whether canvases can run, and produce the runtime if so.\n *\n * Never throws and never guesses: an unavailable result carries a sentence a person\n * can act on, because \"no Node here\" is a legitimate state rather than a failure.\n */\nexport async function resolveCanvasRuntime(\n\tprobe: CanvasHostProbe = currentCanvasHostProbe(),\n): Promise<CanvasAvailability> {\n\tconst shim = probe.shimCandidates.find((candidate) => probe.exists(candidate.url));\n\tif (shim === undefined) {\n\t\treturn {\n\t\t\tavailable: false,\n\t\t\treason:\n\t\t\t\t\"Canvas extensions need the built canvas shim, which was not found where it ships. \" +\n\t\t\t\t\"This usually means an incomplete install; reinstalling hoocode should restore it.\",\n\t\t};\n\t}\n\n\t// Forking ourselves is only sound when we are genuinely Node: Bun reports a\n\t// satisfying process.versions.node but ignores the resolve hook the child needs.\n\tif (probe.bunVersion === undefined && meetsMinimum(probe.nodeVersion)) {\n\t\treturn { available: true, runtime: { execPath: probe.execPath, execArgv: shim.execArgv, shimUrl: shim.url } };\n\t}\n\n\tconst found = await probe.probePathNode();\n\tif (!found) {\n\t\treturn {\n\t\t\tavailable: false,\n\t\t\treason:\n\t\t\t\t`Canvas extensions run in a Node child process and no \\`node\\` was found on PATH. ` +\n\t\t\t\t`Install Node ${MIN_LABEL} or newer to use canvases.`,\n\t\t};\n\t}\n\tif (!meetsMinimum(found.version)) {\n\t\treturn {\n\t\t\tavailable: false,\n\t\t\treason:\n\t\t\t\t`Canvas extensions need Node ${MIN_LABEL} or newer for module.register(); ` +\n\t\t\t\t`the \\`node\\` on PATH is ${found.version}.`,\n\t\t};\n\t}\n\treturn { available: true, runtime: { execPath: found.execPath, execArgv: shim.execArgv, shimUrl: shim.url } };\n}\n"]}

package/dist/core/canvas/protocol.d.ts

@@ -0,0 +1,229 @@
+/**
+ * Canvas wire protocol — the entire GitHub-facing surface.
+ *
+ * Design: `docs/canvas-extensions-design.md` §2. The short version: GitHub's own
+ * types (`@github/copilot-sdk` `dist/canvas.d.ts`) state that the Node
+ * `createCanvas`/`joinSession` API is one of five language wrappers over the same
+ * JSON-RPC wire protocol, and that "the divergence is API ergonomics only". So
+ * hoocode binds to the wire protocol, not to the Node sugar, and the drift
+ * surface is the three provider methods below plus one version integer.
+ *
+ * Everything a third-party canvas can observe lives in this file. If GitHub
+ * moves the protocol, this file and `sdk-shim/` move; nothing else does.
+ *
+ * Two layers are deliberately separated here:
+ *
+ *   1. **Provider contract** (`CanvasProvider*`, `CANVAS_METHOD_*`) — GitHub's.
+ *      These payload shapes reach extension code as the `ctx` argument of
+ *      `open`, `onClose`, and action handlers, so they must stay structurally
+ *      identical to the SDK's. `test/canvas-protocol-conformance.test.ts` fails
+ *      the build if they drift.
+ *   2. **Host envelope** (`Canvas*Message`) — ours. It carries provider calls
+ *      between hoocode's runner and the child-side shim. In the Copilot case the
+ *      equivalent layer sits between their CLI and their SDK and an extension
+ *      never sees it, so we are free to keep it simple: newline-delimited JSON.
+ */
+/** JSON value, mirroring the SDK's `JsonValue`. */
+export type JsonValue = null | boolean | number | string | JsonValue[] | {
+    [key: string]: JsonValue;
+};
+/** JSON Schema carried as data, mirroring the SDK's `CanvasJsonSchema`. */
+export type CanvasJsonSchema = JsonValue;
+/** Result of an action invocation, mirroring the SDK's `CanvasActionInvokeResult`. */
+export type CanvasActionInvokeResult = JsonValue;
+/**
+ * SDK protocol version this implementation targets, mirroring the SDK's
+ * `SDK_PROTOCOL_VERSION`. The conformance test asserts the two are equal, so a
+ * protocol bump surfaces as a failing test rather than a runtime mismatch.
+ */
+export declare const CANVAS_SDK_PROTOCOL_VERSION = 3;
+/** Provider callback: open a canvas instance. */
+export declare const CANVAS_METHOD_OPEN = "canvas.open";
+/** Provider callback: a canvas instance was closed. */
+export declare const CANVAS_METHOD_CLOSE = "canvas.close";
+/** Provider callback: invoke an agent-callable action. */
+export declare const CANVAS_METHOD_INVOKE_ACTION = "canvas.action.invoke";
+/** The three provider callbacks, in the order the design doc lists them. */
+export declare const CANVAS_PROVIDER_METHODS: readonly ["canvas.open", "canvas.close", "canvas.action.invoke"];
+/** One of the three provider callback names. */
+export type CanvasProviderMethod = (typeof CANVAS_PROVIDER_METHODS)[number];
+/** Host capabilities advertised to the provider. */
+export interface CanvasHostContextCapabilities {
+    /** Whether canvas rendering is supported. */
+    canvases?: boolean;
+}
+/** Host context supplied by the runtime. */
+export interface CanvasHostContext {
+    capabilities?: CanvasHostContextCapabilities;
+}
+/** Session context supplied by the runtime. */
+export interface CanvasSessionContext {
+    /** Active session working directory, when known. */
+    workingDirectory?: string;
+}
+/** Fields shared by every provider callback payload. */
+interface CanvasProviderRequestBase {
+    /** Target session identifier. */
+    sessionId: string;
+    /** Owning provider identifier. */
+    extensionId: string;
+    /** Provider-local canvas identifier. */
+    canvasId: string;
+    /** Canvas instance identifier. */
+    instanceId: string;
+    host?: CanvasHostContext;
+    session?: CanvasSessionContext;
+}
+/** `canvas.open` payload. */
+export interface CanvasProviderOpenRequest extends CanvasProviderRequestBase {
+    /** Canvas open input. */
+    input?: JsonValue;
+}
+/** `canvas.open` result. A web-rendered canvas returns the URL the host loads. */
+export interface CanvasProviderOpenResult {
+    /** URL for web-rendered canvases. */
+    url?: string;
+    /** Provider-supplied title. */
+    title?: string;
+    /** Provider-supplied status text. */
+    status?: string;
+}
+/** `canvas.close` payload. */
+export interface CanvasProviderCloseRequest extends CanvasProviderRequestBase {
+}
+/** `canvas.action.invoke` payload. */
+export interface CanvasProviderInvokeActionRequest extends CanvasProviderRequestBase {
+    /** Action name to invoke. */
+    actionName: string;
+    /** Action input. */
+    input?: JsonValue;
+}
+/**
+ * Action metadata as it crosses the wire. The SDK strips each action's `handler`
+ * closure before sending the declaration, so this is `CanvasAction` minus the
+ * handler.
+ */
+export interface CanvasActionDeclaration {
+    /** 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;
+}
+/** Declarative metadata for a single canvas. */
+export interface CanvasDeclaration {
+    /** 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. */
+    actions?: CanvasActionDeclaration[];
+}
+/**
+ * Reserved action-name prefix. The SDK is explicit: "Names MUST NOT start with
+ * `canvas.` — that prefix is reserved for lifecycle verbs."
+ */
+export declare const CANVAS_RESERVED_ACTION_PREFIX = "canvas.";
+/** Log levels accepted by `session.log`. */
+export type CanvasLogLevel = "info" | "warning" | "error";
+/**
+ * Host envelope version. Ours, not GitHub's — bumped only when the
+ * runner↔shim framing changes.
+ */
+export declare const CANVAS_ENVELOPE_VERSION = 1;
+/** Child announces itself and its canvases. Always the first message. */
+export interface CanvasReadyMessage {
+    envelope: typeof CANVAS_ENVELOPE_VERSION;
+    type: "ready";
+    /** The `CANVAS_SDK_PROTOCOL_VERSION` the child was built against. */
+    protocolVersion: number;
+    /** Provider identifier, derived by the runner from the extension directory. */
+    extensionId: string;
+    canvases: CanvasDeclaration[];
+    /**
+     * Surfaces declared by the extension that this shim does not implement, so the
+     * runner can warn once instead of letting the extension half-work
+     * (design doc §6.2).
+     */
+    unsupported?: string[];
+}
+/** Child forwards a `session.log` call. */
+export interface CanvasLogMessage {
+    envelope: typeof CANVAS_ENVELOPE_VERSION;
+    type: "log";
+    message: string;
+    level?: CanvasLogLevel;
+    ephemeral?: boolean;
+}
+/** Host asks the child to run one provider callback. */
+export interface CanvasRequestMessage {
+    envelope: typeof CANVAS_ENVELOPE_VERSION;
+    type: "request";
+    id: number;
+    method: CanvasProviderMethod;
+    params: JsonValue;
+}
+/** Child returns a provider callback result. */
+export interface CanvasResponseMessage {
+    envelope: typeof CANVAS_ENVELOPE_VERSION;
+    type: "response";
+    id: number;
+    result: JsonValue;
+}
+/**
+ * Child returns a failure. `code` carries `CanvasError.code` when the handler threw
+ * one, so the agent gets a machine-readable code rather than a string to parse.
+ */
+export interface CanvasErrorMessage {
+    envelope: typeof CANVAS_ENVELOPE_VERSION;
+    type: "error";
+    id: number;
+    code: string;
+    message: string;
+}
+/** Anything the host may send to a child. */
+export type CanvasHostToChildMessage = CanvasRequestMessage;
+/** Anything a child may send to the host. */
+export type CanvasChildToHostMessage = CanvasReadyMessage | CanvasLogMessage | CanvasResponseMessage | CanvasErrorMessage;
+/** Error code used when a handler throws something that is not a `CanvasError`. */
+export declare const CANVAS_ERROR_CODE_INTERNAL = "internal_error";
+/** Error code used when the host asks for a canvas or action the child does not declare. */
+export declare const CANVAS_ERROR_CODE_UNKNOWN_TARGET = "unknown_target";
+/** Whether `value` is a provider callback name. */
+export declare function isCanvasProviderMethod(value: unknown): value is CanvasProviderMethod;
+/** Narrow a decoded value to a host→child message. */
+export declare function isCanvasHostToChildMessage(value: unknown): value is CanvasHostToChildMessage;
+/** Narrow a decoded value to a child→host message. */
+export declare function isCanvasChildToHostMessage(value: unknown): value is CanvasChildToHostMessage;
+/** Serialize one message as a single NDJSON line, newline included. */
+export declare function encodeCanvasMessage(message: CanvasHostToChildMessage | CanvasChildToHostMessage): string;
+/** One decode pass: parsed JSON values plus any lines that were not JSON at all. */
+export interface CanvasDecodeResult {
+    values: unknown[];
+    /**
+     * Lines that failed to parse. In the Copilot CLI stdout is the JSON-RPC channel,
+     * so a stray `console.log` corrupts it; we keep the same discipline but report
+     * the stray text so the runner can tell the author to use `session.log`
+     * instead of leaving them with a silent protocol error.
+     */
+    strays: string[];
+}
+/**
+ * Incremental NDJSON decoder. Chunk boundaries do not respect line boundaries, so
+ * a partial trailing line is held until the rest arrives.
+ */
+export declare class CanvasMessageDecoder {
+    private buffer;
+    /** Decode everything complete in `chunk`, buffering any partial trailing line. */
+    push(chunk: string): CanvasDecodeResult;
+    /** Decode whatever is left, for use when the stream ends without a trailing newline. */
+    flush(): CanvasDecodeResult;
+    private take;
+}
+export {};
+//# sourceMappingURL=protocol.d.ts.map