Copilot Canvas Extension Author

Extension Canvas Authoring

Use this skill when creating or debugging an extension canvas that integrates with the runtime canvas model.

The host app no longer participates in extension canvas registration. Extensions declare canvases directly to the runtime via the Copilot SDK on joinSession; the runtime routes provider callbacks (canvas.open, canvas.action.invoke, etc.) straight to the declaring connection; the host app just renders whatever URL the provider returns.

Authoring workflow (do this in order)

1. Decide the scope. Project (.github/extensions/<name>/) is committed to the repo and shared with the team. User ($COPILOT_HOME/extensions/<name>/) is local to the current user. Session ($COPILOT_HOME/session-state/<sessionId>/extensions/<name>/) is loaded only for the current session — ideal for a throwaway canvas for one conversation. Unless the request makes it obvious, ask before creating files — the choice changes who sees the extension, whether it's committed, and the resulting extensionId.

2. Scaffold via tool, don't hand-write the skeleton.

   extensions_manage({ operation: "scaffold", kind: "canvas", name: "<name>", location: "project" | "user" | "session" })

   The canvas scaffold produces an extension.mjs with joinSession({ canvases: [createCanvas({...})] }), a working loopback HTTP server per instance, an example action, and onClose cleanup. Edit from there.

3. Edit the file. Implement your open, actions[], optional onClose, and (if needed) tools/hooks alongside.

4. Reload. Call extensions_reload. Stale canvas instances flip to stale, then back to ready once the provider reconnects.

5. Verify. Call extensions_manage({ operation: "list" }) and extensions_manage({ operation: "inspect", name: "<name>" }). If the extension is marked failed, inspect surfaces the log file path and a tail — that log is the primary debugging surface.

6. Drive it. Run the validation checklist below via list_canvas_capabilities, open_canvas, and invoke_canvas_action.

Extension shape

A canvas extension is a Copilot CLI extension running as a forked Node process that speaks JSON-RPC over stdio to the CLI.

• Entry file must be named extension.mjs (ES modules only; TypeScript is not supported).
• Discovery scans only immediate subdirectories of .github/extensions/ (relative to git root), $COPILOT_HOME/extensions/, and $COPILOT_HOME/session-state/<sessionId>/extensions/.
• The runtime auto-derives a stable extensionId of ${source}:${name} (e.g. project:my-extension); session-scoped extensions embed the session id as session:<sessionId>:<name>.
• @github/copilot-sdk is resolved automatically by the CLI — do not add a package.json or node_modules for it.
• stdout is reserved for JSON-RPC. Never console.log. Use session.log(message, { level, ephemeral }).
• Tool names must be globally unique across all loaded extensions — collisions cause the second extension to fail.

joinSession signature

import { joinSession, createCanvas, CanvasError } from "@github/copilot-sdk/extension";

const session = await joinSession({
    canvases: [createCanvas({ /* ... */ })],
    tools: [/* optional */],
    hooks: {/* optional */},
    onPermissionRequest: async (request) => ({ kind: "approve-once" }), // optional
});
// session.sessionId, session.workspacePath (string | undefined),
// session.send, session.sendAndWait, session.log, session.on, session.rpc

Canvas API (canvas.d.ts)

import { createCanvas, CanvasError, joinSession } from "@github/copilot-sdk/extension";

const canvas = createCanvas({
    id: "main",                  // unique within this extension
    displayName: "My canvas",    // human-readable label shown in host chrome
    description: "Short summary the agent sees in the system-prompt canvas catalog.",
    inputSchema: { /* JSON Schema for open input (optional) */ },
    actions: [
        {
            name: "do_thing",        // unique within this canvas; MUST NOT start with `canvas.`
            description: "...",
            inputSchema: { /* JSON Schema (optional) */ },
            handler: async (ctx) => {
                // ctx: { sessionId, extensionId, canvasId, instanceId, actionName, input, host }
                // Return raw result; throw CanvasError("code", "message") for errors.
                return { /* ... */ };
            },
        },
    ],
    open: async (ctx) => {
        // ctx: { sessionId, extensionId, canvasId, instanceId, input, host }
        // Idempotent: same instanceId may arrive again after provider reconnect.
        return {
            url: "http://127.0.0.1:<loopback-port>/", // optional for native canvases
            title: "...",   // optional, shown in host chrome
            status: "...",  // optional, shown in host chrome
        };
    },
    onClose: async (ctx) => {
        // Optional. Fire-and-forget; return value ignored.
    },
});

Runtime rules:

• Action names starting with canvas. are reserved and rejected at declaration time.
• Every actions[] entry must have a handler; missing handlers fall through to CanvasError.noHandler().
• Canvas-level inputSchema is validated before open; action-level inputSchema is validated before dispatch. Failure returns canvas_input_invalid with Ajv details.
• Return raw values from action handlers; throw CanvasError("code", "message") for errors.
• ctx.canvasId (not ctx.id) is the canvas identifier in handler context.

Loopback server pattern

import { createServer } from "node:http";
import { createCanvas, joinSession } from "@github/copilot-sdk/extension";

const servers = new Map(); // instanceId → { server, url }

async function startServer(instanceId) {
    const server = createServer((req, res) => {
        res.setHeader("Content-Type", "text/html; charset=utf-8");
        res.end(renderHtml(instanceId));
    });
    await new Promise((r) => server.listen(0, "127.0.0.1", r));
    const port = server.address().port;
    return { server, url: `http://127.0.0.1:${port}/` };
}

await joinSession({
    canvases: [
        createCanvas({
            id: "my-canvas",
            displayName: "My canvas",
            description: "...",
            open: async (ctx) => {
                let entry = servers.get(ctx.instanceId);
                if (!entry) {
                    entry = await startServer(ctx.instanceId);
                    servers.set(ctx.instanceId, entry);
                }
                return { title: "My canvas", url: entry.url };
            },
            onClose: async (ctx) => {
                const entry = servers.get(ctx.instanceId);
                if (entry) {
                    servers.delete(ctx.instanceId);
                    await new Promise((r) => entry.server.close(() => r()));
                }
            },
        }),
    ],
});

Bind embedded servers to loopback only (127.0.0.1). The host only embeds loopback URLs. Push state updates to the iframe with Server-Sent Events (/events).

ID model — three distinct identifiers

• canvasId — the canvas type declared by the extension. Accepted by list_canvas_capabilities and open_canvas; not by invoke_canvas_action.
• extensionId — auto-derived ${source}:${name} (e.g. project:triage-board). Only pass it to disambiguate when two extensions declare the same canvasId.
• instanceId — caller-invented handle for one running panel (slug or UUID). Two panels of the same canvas need two instanceIds. Validated against ^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$ — max 128 chars, alphanumeric first character, then only [A-Za-z0-9._-].

Example: open_canvas({ canvasId: "triage-board", instanceId: "triage-1" }) then invoke_canvas_action({ instanceId: "triage-1", actionName: "refresh" }).

Agent-side canvas tools

// Open a canvas panel
open_canvas({ canvasId: "my-canvas", instanceId: "my-canvas-1", input?: {...} })
// Returns { instanceId, url? } — no extensionId needed unless two providers share the canvasId.

// Discover a canvas type's actions and input schema
list_canvas_capabilities({ canvasId: "my-canvas" })

// Invoke an action on an open panel
invoke_canvas_action({ instanceId: "my-canvas-1", actionName: "do_thing", input?: {...} })

Re-opening the same instanceId focuses the existing panel (the host emits session.canvas.opened with reopen: true and reloads the iframe without invoking the provider again).

Injecting instructions

• additionalContext from hooks (everyday path). onSessionStart → once-per-session guidance; onUserPromptSubmitted → per-turn nudges. The runtime appends it as a developer-role message.
• systemMessage on joinSession (system-prompt path):
  • { mode: "append", content } — append to the SDK foundation.
  • { mode: "customize", sections: {...} } — override individual sections (identity, tone, safety, custom_instructions, runtime_instructions, etc.) with replace / remove / append / prepend / transform-callback actions.
  • Do NOT use { mode: "replace", content } from an extension — it discards the entire SDK-managed prompt including safety guardrails.