@rwoll/canvas-kit 0.0.0-stage → 0.1.0

package/dist/define.js

@@ -0,0 +1,197 @@
+import { z } from 'zod';
+import { CanvasKitError } from "./errors.js";
+import { INTERVAL_PATTERN, JOB_ACTIONS, intervalMs } from "./jobs.js";
+export { formatInterval, intervalMs } from "./jobs.js";
+const emptyInput = z.object({}).strict();
+const ID_PATTERN = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+const ACTION_PATTERN = /^[a-z][a-z0-9_]*$/;
+// scheme://host[:port], where host may start with `*.` and port may be `*`. No paths, keywords, or bare wildcards.
+const CSP_SOURCE_PATTERN = /^(?:https?|wss?):\/\/(?:\[::1\]|(?:\*\.)?[a-z0-9](?:[a-z0-9-]*[a-z0-9])?(?:\.[a-z0-9](?:[a-z0-9-]*[a-z0-9])?)*)(?::(?:\*|[0-9]{1,5}))?$/;
+function compileCsp(id, csp) {
+    const connectSrc = [...(csp?.connectSrc ?? [])];
+    for (const source of connectSrc) {
+        if (typeof source !== 'string' || !CSP_SOURCE_PATTERN.test(source)) {
+            throw new Error(`Canvas ${id} has an invalid csp.connectSrc source: ${JSON.stringify(source)}. Use scheme://host[:port].`);
+        }
+    }
+    return { connectSrc: [...new Set(connectSrc)] };
+}
+const DEFAULT_MAX_EVERY_MS = 30 * 86_400_000;
+const DEFAULT_MAX_JOBS = 20;
+const CONTROLS = ['both', 'ui', 'agent'];
+function checkedInterval(name, field, every) {
+    const ms = intervalMs(every);
+    if (!Number.isFinite(ms) || ms < 1_000) {
+        throw new Error(`Job ${name} needs ${field}: at least 1 second, such as '30s', '15m', '6h', '1d', or milliseconds`);
+    }
+    return ms;
+}
+function compileJob(name, job) {
+    if (!ACTION_PATTERN.test(name))
+        throw new Error(`Job names must be snake_case: ${name}`);
+    if (typeof job?.run !== 'function')
+        throw new Error(`Job ${name} needs a run() function`);
+    const everyMs = checkedInterval(name, 'every', job.every);
+    const minEveryMs = job.minEvery === undefined ? everyMs : checkedInterval(name, 'minEvery', job.minEvery);
+    const maxEveryMs = job.maxEvery === undefined ? Math.max(everyMs, DEFAULT_MAX_EVERY_MS) : checkedInterval(name, 'maxEvery', job.maxEvery);
+    if (minEveryMs > everyMs || everyMs > maxEveryMs)
+        throw new Error(`Job ${name} needs minEvery <= every <= maxEvery`);
+    if (job.controls !== undefined && !CONTROLS.includes(job.controls)) {
+        throw new Error(`Job ${name} has invalid controls: use 'both', 'ui', or 'agent'`);
+    }
+    if (job.input !== undefined && typeof job.input.safeParseAsync !== 'function') {
+        throw new Error(`Job ${name} needs a Zod schema for input`);
+    }
+    if (job.input !== undefined && job.controls === undefined) {
+        throw new Error(`Job ${name} has input, so it needs controls: the UI or the agent adds jobs from it`);
+    }
+    const maxJobs = job.maxJobs ?? DEFAULT_MAX_JOBS;
+    if (!Number.isInteger(maxJobs) || maxJobs < 1 || maxJobs > 1_000)
+        throw new Error(`Job ${name} needs maxJobs between 1 and 1000`);
+    return {
+        name,
+        description: job.description,
+        everyMs,
+        minEveryMs,
+        maxEveryMs,
+        controls: job.controls,
+        input: job.input,
+        maxJobs,
+        run: job.run,
+    };
+}
+/**
+ * The job a job ID belongs to: a declared job's name, or `<name>-<hex>` for a job
+ * added from a job with input. Throws `not_found` with the canvas's job names.
+ */
+export function jobForId(canvas, id) {
+    const declared = canvas.jobs.get(id);
+    if (declared)
+        return declared;
+    const added = /^([a-z][a-z0-9_]*)-[0-9a-f]+$/.exec(id);
+    const job = added ? canvas.jobs.get(added[1]) : undefined;
+    if (job?.input)
+        return job;
+    const known = [...canvas.jobs.keys()];
+    throw new CanvasKitError('not_found', `${canvas.title} has no job ${id}. Its jobs: ${known.length ? known.join(', ') : 'none'}.`);
+}
+/** Who may call a built-in job action: everyone any of the jobs it covers lets in. */
+function exposureFor(jobs) {
+    const ui = jobs.some(job => job.controls === 'both' || job.controls === 'ui');
+    const agent = jobs.some(job => job.controls === 'both' || job.controls === 'agent');
+    return ui && agent ? 'both' : ui ? 'ui' : 'agent';
+}
+const intervalInput = z
+    .union([z.number().int().min(1_000), z.string().regex(INTERVAL_PATTERN)])
+    .describe("Interval such as '15m', '6h', or '1d', or milliseconds");
+const jobId = z.string().min(1).max(100).describe('The job ID from list_jobs');
+/** The built-in actions for jobs with `controls`; the host runs them. */
+function jobActions(title, jobs) {
+    const controlled = jobs.filter(job => job.controls !== undefined);
+    if (controlled.length === 0)
+        return [];
+    const builtIn = (jobAction, description, input, covers) => ({
+        name: jobAction,
+        description,
+        expose: exposureFor(covers),
+        input,
+        inputJsonSchema: toJsonSchema(input),
+        jobAction,
+        run: () => {
+            throw new CanvasKitError('internal_error', `${jobAction} runs in the canvas host`);
+        },
+    });
+    const actions = [
+        builtIn(JOB_ACTIONS.list, `List this ${title} document's scheduled jobs: their IDs, intervals, whether they are paused, and their last and next runs.`, emptyInput, controlled),
+        builtIn(JOB_ACTIONS.update, 'Pause or resume a scheduled job, or change how often it runs, by its ID from list_jobs.', z.object({ id: jobId, enabled: z.boolean().optional(), every: intervalInput.optional() }).strict(), controlled),
+        builtIn(JOB_ACTIONS.run, 'Run a scheduled job now, by its ID from list_jobs.', z.object({ id: jobId }).strict(), controlled),
+    ];
+    const withInput = controlled.filter(job => job.input !== undefined);
+    if (withInput.length > 0) {
+        const variants = withInput.map(job => z
+            .object({ job: z.literal(job.name), input: job.input, every: intervalInput.optional(), enabled: z.boolean().optional() })
+            .strict());
+        const input = variants.length === 1 ? variants[0] : z.discriminatedUnion('job', variants);
+        const kinds = withInput.map(job => (job.description ? `${job.name} (${job.description})` : job.name)).join('; ');
+        actions.push(builtIn(JOB_ACTIONS.add, `Add a scheduled job from one of: ${kinds}. It runs soon after it is added, then on its interval. Returns its ID.`, input, withInput), builtIn(JOB_ACTIONS.remove, 'Remove a job added with add_job, by its ID.', z.object({ id: jobId }).strict(), withInput));
+    }
+    return actions;
+}
+export function toJsonSchema(schema) {
+    const { $schema: _ignored, ...rest } = z.toJSONSchema(schema, { io: 'input', unrepresentable: 'any' });
+    return rest;
+}
+export async function parseWith(schema, value, label) {
+    const result = await schema.safeParseAsync(value);
+    if (!result.success)
+        throw new CanvasKitError('invalid_input', `${label}: ${z.prettifyError(result.error)}`);
+    return result.data;
+}
+/**
+ * Declare a canvas: its state, open input, and actions. The kit supplies the
+ * HTTP server, live state sync, persistence, and Copilot SDK registration.
+ */
+export function defineCanvas(spec) {
+    if (!ID_PATTERN.test(spec.id))
+        throw new Error(`Canvas id must be kebab-case: ${spec.id}`);
+    if (!spec.title.trim())
+        throw new Error(`Canvas ${spec.id} needs a title`);
+    if (!spec.description.trim())
+        throw new Error(`Canvas ${spec.id} needs a description`);
+    const declared = spec.actions?.({ action: definition => definition }) ?? {};
+    const actions = new Map();
+    for (const [name, action] of Object.entries(declared)) {
+        if (!ACTION_PATTERN.test(name))
+            throw new Error(`Action names must be snake_case: ${name}`);
+        if (typeof action?.run !== 'function')
+            throw new Error(`Action ${name} needs a run() function`);
+        const input = action.input ?? emptyInput;
+        actions.set(name, {
+            name,
+            description: action.description,
+            expose: action.expose ?? 'both',
+            input,
+            inputJsonSchema: toJsonSchema(input),
+            run: action.run,
+        });
+    }
+    if (!actions.has('get_state')) {
+        actions.set('get_state', {
+            name: 'get_state',
+            description: `Read the current state of this ${spec.title} instance, including changes made in its UI.`,
+            expose: 'agent',
+            input: emptyInput,
+            inputJsonSchema: toJsonSchema(emptyInput),
+            run: ctx => ctx.state,
+        });
+    }
+    const declaredJobs = spec.jobs?.({ job: definition => definition }) ?? {};
+    const jobs = new Map();
+    for (const [name, job] of Object.entries(declaredJobs))
+        jobs.set(name, compileJob(name, job));
+    for (const action of jobActions(spec.title, [...jobs.values()])) {
+        if (actions.has(action.name))
+            throw new Error(`Action ${action.name} is reserved for job controls; rename it`);
+        actions.set(action.name, action);
+    }
+    return {
+        kind: 'canvas-kit/canvas',
+        id: spec.id,
+        title: spec.title,
+        description: spec.description,
+        state: spec.state,
+        input: spec.input,
+        inputJsonSchema: spec.input ? toJsonSchema(spec.input) : undefined,
+        versionFooter: spec.versionFooter ?? true,
+        csp: compileCsp(spec.id, spec.csp),
+        actions,
+        jobs,
+        persist: spec.persist
+            ? { key: spec.persist.key, version: spec.persist.version ?? 1 }
+            : undefined,
+        init: spec.init,
+        reopen: ctx => spec.reopen?.(ctx),
+        status: state => spec.status?.(state),
+    };
+}
+//# sourceMappingURL=define.js.map

package/dist/define.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"define.js","sourceRoot":"","sources":["../src/define.ts"],"names":[],"mappings":"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"}

package/dist/errors.d.ts

@@ -0,0 +1,12 @@
+/**
+ * An expected canvas failure with a stable code. The kit reports it to the agent
+ * as a `CanvasError` and to the UI as a JSON error response.
+ */
+export declare class CanvasKitError extends Error {
+    readonly code: string;
+    readonly status: number;
+    constructor(code: string, message: string, status?: number);
+    static [Symbol.hasInstance](value: unknown): boolean;
+}
+export declare function errorMessage(error: unknown): string;
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAiBA;;;GAGG;AACH,qBAAa,cAAe,SAAQ,KAAK;IACvC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;gBAEZ,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM;IAQ1D,MAAM,CAAC,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO;CAIrD;AAED,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAEnD"}

package/dist/errors.js

@@ -0,0 +1,39 @@
+const STATUS_BY_CODE = {
+    invalid_input: 400,
+    forbidden: 403,
+    not_found: 404,
+    not_open: 409,
+    conflict: 409,
+    payload_too_large: 413,
+    corrupt_state: 500,
+    unsupported_state: 500,
+    storage_error: 500,
+    internal_error: 500,
+};
+// A registered symbol, so errors thrown by another copy of this module (as in the
+// Vite dev server, which loads canvas code separately from the kit) are still recognized.
+const BRAND = Symbol.for('@rwoll/canvas-kit/CanvasKitError');
+/**
+ * An expected canvas failure with a stable code. The kit reports it to the agent
+ * as a `CanvasError` and to the UI as a JSON error response.
+ */
+export class CanvasKitError extends Error {
+    code;
+    status;
+    constructor(code, message, status) {
+        super(message);
+        this.name = 'CanvasKitError';
+        this.code = code;
+        this.status = status ?? STATUS_BY_CODE[code] ?? 400;
+        Object.defineProperty(this, BRAND, { value: true });
+    }
+    static [Symbol.hasInstance](value) {
+        if (this !== CanvasKitError)
+            return Function.prototype[Symbol.hasInstance].call(this, value);
+        return typeof value === 'object' && value !== null && value[BRAND] === true;
+    }
+}
+export function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,MAAM,cAAc,GAA2B;IAC7C,aAAa,EAAE,GAAG;IAClB,SAAS,EAAE,GAAG;IACd,SAAS,EAAE,GAAG;IACd,QAAQ,EAAE,GAAG;IACb,QAAQ,EAAE,GAAG;IACb,iBAAiB,EAAE,GAAG;IACtB,aAAa,EAAE,GAAG;IAClB,iBAAiB,EAAE,GAAG;IACtB,aAAa,EAAE,GAAG;IAClB,cAAc,EAAE,GAAG;CACpB,CAAC;AAEF,kFAAkF;AAClF,0FAA0F;AAC1F,MAAM,KAAK,GAAkB,MAAM,CAAC,GAAG,CAAC,kCAAkC,CAAC,CAAC;AAE5E;;;GAGG;AACH,MAAM,OAAO,cAAe,SAAQ,KAAK;IAC9B,IAAI,CAAS;IACb,MAAM,CAAS;IAExB,YAAY,IAAY,EAAE,OAAe,EAAE,MAAe;QACxD,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,gBAAgB,CAAC;QAC7B,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,MAAM,GAAG,MAAM,IAAI,cAAc,CAAC,IAAI,CAAC,IAAI,GAAG,CAAC;QACpD,MAAM,CAAC,cAAc,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;IACtD,CAAC;IAED,MAAM,CAAC,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC,KAAc;QACxC,IAAI,IAAI,KAAK,cAAc;YAAE,OAAO,QAAQ,CAAC,SAAS,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC,IAAI,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;QAC7F,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,IAAK,KAA+B,CAAC,KAAK,CAAC,KAAK,IAAI,CAAC;IACzG,CAAC;CACF;AAED,MAAM,UAAU,YAAY,CAAC,KAAc;IACzC,OAAO,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;AAChE,CAAC"}

package/dist/extension.d.ts

@@ -0,0 +1,25 @@
+import { joinSession } from '@github/copilot-sdk/extension';
+import type { AnyCanvas } from './define.ts';
+import { CanvasHost } from './server/host.ts';
+export interface RunCanvasExtensionOptions {
+    /** Folder with the built UI, usually `new URL('./ui/', import.meta.url)`. */
+    uiDir: URL | string;
+    /** Plugin name and version, embedded at build time. */
+    plugin: {
+        name: string;
+        version: string;
+    };
+    /** Release stamp written by `canvas-kit release`, usually `<plugin>/release.json`. */
+    releaseFile: URL | string;
+}
+/** What `runCanvasExtension` returns: the joined session and the canvas host. */
+export interface RunningCanvasExtension {
+    session: Awaited<ReturnType<typeof joinSession>>;
+    host: CanvasHost;
+}
+/**
+ * Register a canvas with the current Copilot session. The kit's Vite build
+ * generates the extension entry that calls this; canvases do not call it directly.
+ */
+export declare function runCanvasExtension(canvas: AnyCanvas, options: RunCanvasExtensionOptions): Promise<RunningCanvasExtension>;
+//# sourceMappingURL=extension.d.ts.map

package/dist/extension.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"extension.d.ts","sourceRoot":"","sources":["../src/extension.ts"],"names":[],"mappings":"AAAA,OAAO,EAA6B,WAAW,EAAyB,MAAM,+BAA+B,CAAC;AAE9G,OAAO,KAAK,EAAE,SAAS,EAAY,MAAM,aAAa,CAAC;AAEvD,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAG9C,MAAM,WAAW,yBAAyB;IACxC,6EAA6E;IAC7E,KAAK,EAAE,GAAG,GAAG,MAAM,CAAC;IACpB,uDAAuD;IACvD,MAAM,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;IAC1C,sFAAsF;IACtF,WAAW,EAAE,GAAG,GAAG,MAAM,CAAC;CAC3B;AAED,iFAAiF;AACjF,MAAM,WAAW,sBAAsB;IACrC,OAAO,EAAE,OAAO,CAAC,UAAU,CAAC,OAAO,WAAW,CAAC,CAAC,CAAC;IACjD,IAAI,EAAE,UAAU,CAAC;CAClB;AAiBD;;;GAGG;AACH,wBAAsB,kBAAkB,CAAC,MAAM,EAAE,SAAS,EAAE,OAAO,EAAE,yBAAyB,GAAG,OAAO,CAAC,sBAAsB,CAAC,CA+C/H"}

package/dist/extension.js

@@ -0,0 +1,70 @@
+import { CanvasError, createCanvas, joinSession } from '@github/copilot-sdk/extension';
+import { fileURLToPath } from 'node:url';
+import { CanvasKitError, errorMessage } from "./errors.js";
+import { CanvasHost } from "./server/host.js";
+import { loadRelease } from "./server/release.js";
+const toPath = (value) => (typeof value === 'string' ? value : fileURLToPath(value));
+function toCanvasError(error) {
+    if (error instanceof CanvasError)
+        return error;
+    if (error instanceof CanvasKitError)
+        return new CanvasError(error.code, error.message);
+    return new CanvasError('extension_error', errorMessage(error));
+}
+const guard = (run) => Promise.resolve()
+    .then(run)
+    .catch(error => {
+    throw toCanvasError(error);
+});
+/**
+ * Register a canvas with the current Copilot session. The kit's Vite build
+ * generates the extension entry that calls this; canvases do not call it directly.
+ */
+export async function runCanvasExtension(canvas, options) {
+    let session;
+    const log = (message, level) => {
+        if (!session)
+            return;
+        Promise.resolve(session.log(message, { level })).catch(() => { });
+    };
+    const { release, warning } = await loadRelease(toPath(options.releaseFile), options.plugin);
+    const host = new CanvasHost(canvas, {
+        uiDir: toPath(options.uiDir),
+        release,
+        log,
+        sendToAgent: async (message) => {
+            if (!session)
+                throw new Error('The canvas has not joined a session yet');
+            await session.send(message);
+        },
+    });
+    session = await joinSession({
+        canvases: [
+            createCanvas({
+                id: canvas.id,
+                displayName: canvas.title,
+                description: canvas.description,
+                ...(canvas.inputJsonSchema ? { inputSchema: canvas.inputJsonSchema } : {}),
+                actions: [...canvas.actions.values()]
+                    .filter(action => action.expose !== 'ui')
+                    .map(action => ({
+                    name: action.name,
+                    description: action.description,
+                    inputSchema: action.inputJsonSchema,
+                    handler: ctx => guard(() => host.invoke({ instanceId: ctx.instanceId, actionName: action.name, input: ctx.input, source: 'agent' })),
+                })),
+                open: ctx => guard(() => host.open({ instanceId: ctx.instanceId, input: ctx.input })),
+                onClose: ctx => guard(() => host.closeInstance(ctx.instanceId)),
+            }),
+        ],
+    });
+    if (warning)
+        log(warning, 'warning');
+    const shutdown = () => {
+        host.close().finally(() => process.exit(0));
+    };
+    process.once('SIGTERM', shutdown);
+    process.once('SIGINT', shutdown);
+    return { session, host };
+}
+//# sourceMappingURL=extension.js.map

package/dist/extension.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"extension.js","sourceRoot":"","sources":["../src/extension.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export { z } from 'zod';
+export { defineCanvas, formatInterval, intervalMs } from './define.ts';
+export type { ActionContext, ActionExposure, ActionInput, ActionResult, ActionsOf, ActionSource, ActionSpec, AgentMessage, AnyCanvas, CanvasCsp, CanvasDefinition, CanvasSpec, Interval, JobContext, JobControls, JobDefinitionInfo, JobInput, JobName, JobSpec, JobStatus, JobStatusOf, JobWithInputName, JobsOf, LogLevel, OpenContext, PersistOptions, ReopenContext, StateOf, UiActionName, } from './define.ts';
+export { CanvasKitError } from './errors.ts';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,YAAY,EAAE,cAAc,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACvE,YAAY,EACV,aAAa,EACb,cAAc,EACd,WAAW,EACX,YAAY,EACZ,SAAS,EACT,YAAY,EACZ,UAAU,EACV,YAAY,EACZ,SAAS,EACT,SAAS,EACT,gBAAgB,EAChB,UAAU,EACV,QAAQ,EACR,UAAU,EACV,WAAW,EACX,iBAAiB,EACjB,QAAQ,EACR,OAAO,EACP,OAAO,EACP,SAAS,EACT,WAAW,EACX,gBAAgB,EAChB,MAAM,EACN,QAAQ,EACR,WAAW,EACX,cAAc,EACd,aAAa,EACb,OAAO,EACP,YAAY,GACb,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC"}

package/dist/index.js

@@ -0,0 +1,4 @@
+export { z } from 'zod';
+export { defineCanvas, formatInterval, intervalMs } from "./define.js";
+export { CanvasKitError } from "./errors.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,YAAY,EAAE,cAAc,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAgCvE,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC"}

package/dist/jobs.d.ts

@@ -0,0 +1,56 @@
+/** A duration such as `30s`, `15m`, `6h`, or `1d`, or milliseconds. */
+export type Interval = number | `${number}${'s' | 'm' | 'h' | 'd'}`;
+/** Who may pause, resume, retime, and run a job, and add jobs from a job with input. */
+export type JobControls = 'both' | 'ui' | 'agent';
+export declare const INTERVAL_PATTERN: RegExp;
+/** Milliseconds in an `Interval`, or NaN when it is not one. */
+export declare function intervalMs(every: Interval): number;
+/** The shortest `Interval` for a duration: `90_000` is `90s`, `3_600_000` is `1h`. */
+export declare function formatInterval(ms: number): Interval;
+/** A job's schedule for one document, as the UI and the agent see it. */
+export interface JobStatus<Name extends string = string, Input = unknown> {
+    /** The job's name for a job without input; otherwise a generated ID such as `remind-3f9a2c`. */
+    id: string;
+    job: Name;
+    description?: string;
+    /** The input it was added with, for a job added from a job with input. */
+    input?: Input;
+    /** Interval in milliseconds; `formatInterval()` turns it into text such as `6h`. */
+    every: number;
+    /** The shortest and longest interval that may be chosen, in milliseconds. */
+    minEvery: number;
+    maxEvery: number;
+    /** False while paused. */
+    enabled: boolean;
+    lastRunAt?: string;
+    /** The error from the last run, when it failed. */
+    lastError?: string;
+    /** When it next runs while a chat has the canvas open; absent while paused or before its first run. */
+    nextRunAt?: string;
+    /** Who may control it; absent when only code may. */
+    controls?: JobControls;
+    /** True for a job added from a job with input, which may be removed. */
+    added: boolean;
+}
+/** A job declared by the canvas, for UIs that add jobs from a job with input. */
+export interface JobDefinitionInfo {
+    name: string;
+    description?: string;
+    every: number;
+    minEvery: number;
+    maxEvery: number;
+    controls?: JobControls;
+    /** True when it takes input: users add jobs from it instead of it running on its own. */
+    hasInput: boolean;
+    maxJobs: number;
+}
+/** Built-in actions added for jobs with `controls`. */
+export declare const JOB_ACTIONS: {
+    readonly list: "list_jobs";
+    readonly update: "update_job";
+    readonly run: "run_job";
+    readonly add: "add_job";
+    readonly remove: "remove_job";
+};
+export type JobAction = (typeof JOB_ACTIONS)[keyof typeof JOB_ACTIONS];
+//# sourceMappingURL=jobs.d.ts.map

package/dist/jobs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"jobs.d.ts","sourceRoot":"","sources":["../src/jobs.ts"],"names":[],"mappings":"AAEA,uEAAuE;AACvE,MAAM,MAAM,QAAQ,GAAG,MAAM,GAAG,GAAG,MAAM,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,EAAE,CAAC;AAEpE,wFAAwF;AACxF,MAAM,MAAM,WAAW,GAAG,MAAM,GAAG,IAAI,GAAG,OAAO,CAAC;AAElD,eAAO,MAAM,gBAAgB,QAA+B,CAAC;AAQ7D,gEAAgE;AAChE,wBAAgB,UAAU,CAAC,KAAK,EAAE,QAAQ,GAAG,MAAM,CAKlD;AAED,sFAAsF;AACtF,wBAAgB,cAAc,CAAC,EAAE,EAAE,MAAM,GAAG,QAAQ,CAKnD;AAED,yEAAyE;AACzE,MAAM,WAAW,SAAS,CAAC,IAAI,SAAS,MAAM,GAAG,MAAM,EAAE,KAAK,GAAG,OAAO;IACtE,gGAAgG;IAChG,EAAE,EAAE,MAAM,CAAC;IACX,GAAG,EAAE,IAAI,CAAC;IACV,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,0EAA0E;IAC1E,KAAK,CAAC,EAAE,KAAK,CAAC;IACd,oFAAoF;IACpF,KAAK,EAAE,MAAM,CAAC;IACd,6EAA6E;IAC7E,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,0BAA0B;IAC1B,OAAO,EAAE,OAAO,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,mDAAmD;IACnD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,uGAAuG;IACvG,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,qDAAqD;IACrD,QAAQ,CAAC,EAAE,WAAW,CAAC;IACvB,wEAAwE;IACxE,KAAK,EAAE,OAAO,CAAC;CAChB;AAED,iFAAiF;AACjF,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,WAAW,CAAC;IACvB,yFAAyF;IACzF,QAAQ,EAAE,OAAO,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,uDAAuD;AACvD,eAAO,MAAM,WAAW;;;;;;CAMd,CAAC;AACX,MAAM,MAAM,SAAS,GAAG,CAAC,OAAO,WAAW,CAAC,CAAC,MAAM,OAAO,WAAW,CAAC,CAAC"}

package/dist/jobs.js

@@ -0,0 +1,33 @@
+// Job types and helpers shared by the server and the browser. No Node.js or Zod imports.
+export const INTERVAL_PATTERN = /^(\d+(?:\.\d+)?)(s|m|h|d)$/;
+const UNITS = [
+    ['d', 86_400_000],
+    ['h', 3_600_000],
+    ['m', 60_000],
+    ['s', 1_000],
+];
+/** Milliseconds in an `Interval`, or NaN when it is not one. */
+export function intervalMs(every) {
+    if (typeof every === 'number')
+        return every;
+    const match = INTERVAL_PATTERN.exec(every);
+    const unit = match && UNITS.find(([name]) => name === match[2]);
+    return match && unit ? Number(match[1]) * unit[1] : Number.NaN;
+}
+/** The shortest `Interval` for a duration: `90_000` is `90s`, `3_600_000` is `1h`. */
+export function formatInterval(ms) {
+    for (const [name, size] of UNITS) {
+        if (ms >= size && ms % size === 0)
+            return `${ms / size}${name}`;
+    }
+    return ms;
+}
+/** Built-in actions added for jobs with `controls`. */
+export const JOB_ACTIONS = {
+    list: 'list_jobs',
+    update: 'update_job',
+    run: 'run_job',
+    add: 'add_job',
+    remove: 'remove_job',
+};
+//# sourceMappingURL=jobs.js.map

package/dist/jobs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"jobs.js","sourceRoot":"","sources":["../src/jobs.ts"],"names":[],"mappings":"AAAA,yFAAyF;AAQzF,MAAM,CAAC,MAAM,gBAAgB,GAAG,4BAA4B,CAAC;AAC7D,MAAM,KAAK,GAAG;IACZ,CAAC,GAAG,EAAE,UAAU,CAAC;IACjB,CAAC,GAAG,EAAE,SAAS,CAAC;IAChB,CAAC,GAAG,EAAE,MAAM,CAAC;IACb,CAAC,GAAG,EAAE,KAAK,CAAC;CACJ,CAAC;AAEX,gEAAgE;AAChE,MAAM,UAAU,UAAU,CAAC,KAAe;IACxC,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAC;IAC5C,MAAM,KAAK,GAAG,gBAAgB,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IAC3C,MAAM,IAAI,GAAG,KAAK,IAAI,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,EAAE,EAAE,CAAC,IAAI,KAAK,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;IAChE,OAAO,KAAK,IAAI,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC;AACjE,CAAC;AAED,sFAAsF;AACtF,MAAM,UAAU,cAAc,CAAC,EAAU;IACvC,KAAK,MAAM,CAAC,IAAI,EAAE,IAAI,CAAC,IAAI,KAAK,EAAE,CAAC;QACjC,IAAI,EAAE,IAAI,IAAI,IAAI,EAAE,GAAG,IAAI,KAAK,CAAC;YAAE,OAAO,GAAG,EAAE,GAAG,IAAI,GAAG,IAAI,EAAc,CAAC;IAC9E,CAAC;IACD,OAAO,EAAE,CAAC;AACZ,CAAC;AAyCD,uDAAuD;AACvD,MAAM,CAAC,MAAM,WAAW,GAAG;IACzB,IAAI,EAAE,WAAW;IACjB,MAAM,EAAE,YAAY;IACpB,GAAG,EAAE,SAAS;IACd,GAAG,EAAE,SAAS;IACd,MAAM,EAAE,YAAY;CACZ,CAAC"}

package/dist/playwright.d.ts

@@ -0,0 +1,79 @@
+import { type Page, type PlaywrightTestConfig } from '@playwright/test';
+import type { AgentMessage, AnyCanvas, JobName, StateOf } from './define.ts';
+import type { JobOutcome, RunJobOptions } from './server/host.ts';
+import type { ReleaseInfo } from './server/release.ts';
+import { type HarnessAction, type HarnessInput, type HarnessResult, type TestCanvas } from './testing.ts';
+export interface CanvasTestOptions {
+    /**
+     * Folder with the built UI. Defaults to `dist/plugin/extensions/<name>/ui` in the
+     * current folder, where `<name>` is the current folder's name, which is what
+     * `vite build` writes for a canvas package.
+     */
+    uiDir?: string;
+    /**
+     * Release shown in the version footer. Defaults to an unpublished build of the
+     * package in the current folder, so screenshots stay stable.
+     */
+    release?: ReleaseInfo;
+    /** Clock for actions and jobs (`ctx.now()`), to test time-based jobs. Defaults to `Date.now`. */
+    now?: () => number;
+}
+export interface OpenedCanvas<C extends AnyCanvas> {
+    /** The page showing the canvas, already live. */
+    page: Page;
+    url: string;
+    instanceId: string;
+    /** The instance's current state on the server. */
+    state(): StateOf<C> | undefined;
+    /** Open the same instance in another page of the browser context, to check that views stay in sync. */
+    openAnotherPage(): Promise<Page>;
+}
+export interface CanvasAgent<C extends AnyCanvas> {
+    /** Run an action as the agent, including the built-in job actions. Defaults to the most recently opened instance. */
+    invoke<K extends HarnessAction<C>>(action: K, input?: HarnessInput<C, K>, options?: {
+        instanceId?: string;
+    }): Promise<HarnessResult<C, K>>;
+    /** Messages the canvas sent to the agent with `ctx.sendToAgent()`, oldest first. */
+    readonly messages: AgentMessage[];
+    /** Make the next `ctx.sendToAgent()` fail, to test how the canvas reports it. */
+    failNextSend(error?: Error): void;
+}
+export interface CanvasFixtures<C extends AnyCanvas> {
+    /** The canvas running on a real local server with a temporary data folder. */
+    canvasHarness: TestCanvas<C>;
+    /** Open an instance, point `page` at it, and wait until it is live. */
+    openCanvas(input?: unknown, options?: {
+        instanceId?: string;
+    }): Promise<OpenedCanvas<C>>;
+    /** Act as the agent and see what the canvas sent it. */
+    agent: CanvasAgent<C>;
+    /** Save state for a `persist` key before opening, to test reopening saved documents. */
+    seed(key: string, state: unknown): Promise<void>;
+    /**
+     * Run a job now, as its schedule would. Defaults to the most recently opened
+     * instance; pass `key` to run it for a saved document with no chat open.
+     */
+    runJob(id: JobName<C> | (string & {}), options?: RunJobOptions): Promise<JobOutcome>;
+}
+/**
+ * Playwright fixtures for a canvas. Use the returned `test` like Playwright's own:
+ *
+ * ```ts
+ * export const test = canvasTest(canvas)
+ * test('adds a blocker', async ({ openCanvas, agent }) => { ... })
+ * ```
+ */
+export declare function canvasTest<C extends AnyCanvas>(canvas: C, options?: CanvasTestOptions): import("@playwright/test").TestType<import("@playwright/test").PlaywrightTestArgs & import("@playwright/test").PlaywrightTestOptions & CanvasFixtures<C> & {
+    _canvasState: {
+        messages: AgentMessage[];
+        failures: Error[];
+        lastInstance: string;
+    };
+}, import("@playwright/test").PlaywrightWorkerArgs & import("@playwright/test").PlaywrightWorkerOptions>;
+/**
+ * Playwright config for canvas tests: specs in `e2e/`, run in light, dark, and
+ * high-contrast Chromium. Pass overrides as you would to `defineConfig`.
+ */
+export declare function defineCanvasConfig(config?: PlaywrightTestConfig): PlaywrightTestConfig;
+export { expect } from '@playwright/test';
+//# sourceMappingURL=playwright.d.ts.map

package/dist/playwright.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"playwright.d.ts","sourceRoot":"","sources":["../src/playwright.ts"],"names":[],"mappings":"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"}