API Reference

The code here is type-checked against the SDK but not run; the quickstarts are the projects that run. Terms such as scene, design, version, executor, conversation, tenant, and engine session are defined in Terminology, and how the pieces fit together is in Architecture.

Install#

npm install --save-exact @imgly/codesign-sdk@1.83.0

Run the executor image of the same version, imgly/codesign-executor:1.83.0 ( Versions and Upgrades).

Entry Points#

The package has no runtime dependencies. . and ./testing need no CE.SDK package, because they carry copies of the CE.SDK types they mention (CE.SDK Types), and run on any server runtime that can reach an executor, such as Node.js 22 or later or a Cloudflare Worker. ./cesdk-utils works on the engine of the CE.SDK editor you already load. There is no in-process engine, no API for custom importers or exporters, and no API for building an executor: every product runs IMG.LY’s executor image.

Preparing CoDesign#

prepareCoDesign#

function prepareCoDesign(options: CoDesignOptions): CoDesign;

interface CoDesignOptions {
  conversation: string; // required: your chat, job, or request id; its designs share one executor
  executors: Executors; // required: remoteExecutors({ acquire, token })
  plugins: readonly EnginePluginModule[]; // required: [googleFonts()] is the smallest list
  gateway: GatewayOptions | false; // required: { bearer } adds image generation, false leaves it out
  designs?: DesignStore; // your designs: { listSourceId?, read, write }; default: in memory
  design?: string; // the design a call works on when the model names none
  uploadExport?: (req: UploadExportRequest) => Promise<UploadExportResult>; // lets the agent hand people files
  tools?: readonly CoDesignTool[];
  events?: readonly CoDesignEventListener[];
}

Returns the tools for your agent loop and methods for your own code. It is synchronous, contacts nothing, runs none of your code, and keeps nothing between calls, so create one per chat message, per job, or per workflow step, and discard it after.

Throws at once a CoDesignError of kind invalid_options that names the option, when:

• conversation is not a non-empty string
• executors is not what remoteExecutors (or fakeExecutors) returned
• gateway is neither false nor { bearer } with a function
• uploadExport is not a function
• plugins is not a list, or an entry is not { module, options }, googleFonts(), cesdkDefaults(), or cesdkDemo()
• designs has no read and write functions, or its listSourceId is not a non-empty string
• a listener’s timeoutMs is not a positive number up to 2147483647

One of your tools with a reserved name, or two that share a name, throw tool_name_clash.

Checked at the first call that needs an engine: the token, your modules, your sources, and whether a plugin registered designs.listSourceId (if not: invalid_options, naming the id and the sources the executor reports). Call codesign.handshake() to find out before the person types.

Fails silently: without designs, a CoDesign created per chat message starts every message with no designs. In development the SDK prints one warning when a second CoDesign without designs is built in a process.

CoDesign#

interface CoDesign {
  readonly tools: readonly CoDesignTool[];
  readonly instructions: string;
  readonly fingerprint: string;
  create(opts: {
    title: string;
    group?: string;
    from?: DesignOrigin;
    signal?: AbortSignal;
  }): Promise<LoadResult>;
  load(
    file: Uint8Array | URL,
    opts?: { design?: string; signal?: AbortSignal }
  ): Promise<LoadResult>;
  edit<A, R>(
    code:
      | string
      | ((ctx: { engine: unknown; design: unknown; args: A }) => R | Promise<R>),
    opts?: { design?: string; version?: string; args?: A; signal?: AbortSignal }
  ): Promise<EditResult<Awaited<R>>>;
  export(
    format: 'scene',
    opts?: { design?: string; signal?: AbortSignal }
  ): Promise<string>;
  export(
    format: 'pdfx',
    opts?: { design?: string; pdfx?: PdfxOptions; signal?: AbortSignal }
  ): Promise<Uint8Array<ArrayBuffer>>;
  export(
    format: Exclude<ExportFormat, 'pdfx'>,
    opts?: { design?: string; signal?: AbortSignal }
  ): Promise<Uint8Array<ArrayBuffer>>;
  release(opts?: { design?: string; signal?: AbortSignal }): Promise<void>;
  handshake(opts?: {
    design?: string;
    signal?: AbortSignal;
  }): Promise<HandshakeResult>;
}

interface LoadResult {
  design: string; // the design's id
  format: string; // 'archive', 'scene', 'image', 'svg', 'psd', 'idml', 'pptx', 'pdf', …
  version: string; // your store's version the load wrote (StoredDesign.version)
  warnings?: string[]; // what could not be carried over, such as a substituted font
}

interface EditResult<V> {
  design: string;
  version: string; // your store's version after the call; the one it read when `changed` is false
  changed: boolean;
  value: V | undefined; // what the code returned, as JSON
  findings: { id: number; label: string; message: string }[]; // design-lint findings; they never block the write
}

type DesignOrigin =
  | { template: AssetResult; source: string }
  | { file: AssetResult; source: string }
  | { design: string };

type ExportFormat =
  | 'imgly' | 'png' | 'jpeg' | 'webp' | 'svg'
  | 'pdf' | 'pdfx' | 'html' | 'mp4' | 'wav' | 'm4a';

The object prepareCoDesign returns. Each method works on opts.design, or on the design option when you leave that out, as a tool call does.

Every call, the model’s and yours, reads the design with designs.read, opens the design’s engine session through acquire, runs, and, when it changed the design, writes with designs.write on the version it read. It keeps nothing afterwards. The version the model passes back, parallel calls, and resent calls are explained in Concurrent Edits. There is no close: when your code stops calling, only engine sessions remain open, and they end on their timers (Lifetimes).

create(opts)#

Starts a new design without a model and returns its LoadResult; design is the new id (a UUID the SDK makes up).

• from is { template, source } or { file, source } (an asset your source’s findAssets or fetchAsset returned, and that source’s id), or { design } (a design to copy). Left out, the design is empty. What a file carried is offered to your sources.
• The first designs.write creates the design: it carries no ifMatch and passes title and group on to your store.

load(file)#

Replaces a design’s content with a file, given as bytes or a URL.

• Accepts .imgly, .scene, an image, an SVG, PDF, IDML (InDesign), PPTX (PowerPoint), or PSD (Photoshop), read from the bytes, not the file name (File Formats).
• Writes with designs.write only if nobody wrote the design since load read it; otherwise rejects with design_conflict.
• version is your store’s version it wrote. Put it in the model’s first message, so that its first change is not refused for a missing version.
• A URL is fetched by your runner with globalThis.fetch, from inside your network: never pass a URL a user typed without checking that it is one of yours. A non-2xx answer rejects with http_status, a network failure with fetch_failed. signal stops the download.

edit(code)#

Runs design code without a model, exactly as the model’s code runs: the same engine, sources, design lint (IMG.LY’s checks for problems such as overflowing text), and conditional write. Not charged.

• code sees engine (CE.SDK’s engine), design (CoDesign’s design API, which the handbook the model reads teaches it), and args. It is a string, or a function ({ engine, design, args }) => value, sent as its source text: a function that uses anything it closes over fails with code_failed, before any write.
• args and the return value are JSON. Pass your data in args, never inside the code.
• version runs it only while the design is at that version of your store (default: the latest). A stale version, or a save that landed while it ran, rejects with design_conflict.
• Code that throws rejects with code_failed and writes nothing. Code that returns something that cannot be a result also rejects with code_failed, but its change was already written.
• findings are the design linter’s notes on the result; they never block the write.

export(format)#

Returns the design as your store holds it now. It never writes the design and never calls uploadExport.

• 'scene' returns the scene string. Every other format returns the file’s bytes, rendered on the executor, ready for new Blob([bytes]).

• A PDF keeps CMYK colors (the four process inks of print) as CMYK. html is one self-contained HTML file with its images embedded.

• pdfx is a print-ready PDF/X file (the ISO standard for exchanging print files) with IMG.LY’s defaults. Only export('pdfx', { pdfx }) takes options:

  PdfxOptions field	What it sets	Default
  outputStandard	'PDF/X-4' (keeps live transparency), 'PDF/X-3', or 'PDF/X-1a' (CMYK only, always flattened)	'PDF/X-4'
  outputProfile	The output intent, the printing condition the file is made for: 'fogra39' (European coated paper), 'gracol' (US), 'srgb' (not print-compliant; refused with PDF/X-1a), or 'custom'	'fogra39'
  profileUri	The color profile (an .icc file from your printer): an https URL, required with 'custom' and refused otherwise	none
  nonPrinterProfile	A display profile such as 'srgb': produce the file anyway ('keep') or refuse ('reject')	'keep'
  embedICCProfile	Embed the profile in the file; false gives a plain PDF that is no longer PDF/X	true
  flattenTransparency	PDF/X-3 only: rasterize transparent content (false keeps it live). Ignored on PDF/X-4; PDF/X-1a always flattens	true on PDF/X-3
  flattenResolution	Dots per inch of flattened pages, 1 to 65,535 (PDF/X-1a, and PDF/X-3 unless flattenTransparency is false)	300
  title	The document title	the design’s title
  outputCondition, outputConditionIdentifier	The output condition the file names, as your printer asks	from the profile

• mp4, wav, and m4a need an executor that encodes video; one that does not rejects them with video_unsupported. The handshake’s capabilities.video says whether yours does. For what is supported, see Status.

• Every format except scene and imgly is charged (File Formats).

release()#

Ends a design’s engine session now instead of on its timers. release() works on the design option, release({ design }) on another design.

• An operation still running there finishes first. The next call on that design, from anywhere, loads it again.
• Succeeds when the session is already gone, and when the executor cannot be reached or answers an error. Rejects only with the signal’s reason when you abort it (signal stops only the wait), or with what your acquire throws.
• Once the conversation’s last design is released, its executor exits about 30 seconds later, and the next call waits for a new one. Call it when a conversation or job ends, not after every turn.

handshake()#

Opens the design’s engine session early and returns the executor’s HandshakeResult, or rejects with the error the first tool call would have thrown.

instructions and fingerprint#

codesign.instructions is a few sentences IMG.LY writes for this tool set: read the handbook (IMG.LY’s guide to the engine and to finished designs, which the model reads through the tools) before the first change, look at the design after every change, score it against the handbook’s judging guide before calling it done, and pass back the design and version the last result gave. Append it to your system prompt:

const system = `${yourProductPrompt}\n\n${codesign.instructions}`;

Fails silently: left out, nothing fails, but the model uses the tools worse and learns about versions only from its first refused change. Log one turn’s system prompt and check that it is there.

codesign.fingerprint is a 16-character hex hash of the fixed text the model reads from IMG.LY: the SDK tools’ names, descriptions, and input schemas, instructions, and the handbook. It leaves out your own tools and anything per session (plugins, sources, store). It changes between SDK versions and with uploadExport, gateway, designs, and design. Record it with the handshake’s answer for each eval run and support ticket: together they are what a model saw. The text is byte-identical for one fingerprint, so a model provider’s prompt cache holds.

Tool names, descriptions, and schemas can change in any release, so neither your code nor your prompts depend on them ( Tools). CoDesignToolName, the type of the SDK’s tool names as ToolCallEvent.tool carries them, is for labeling metrics, never for deciding what your product does.

Cancellation: signal#

A signal on create, load, edit, export, or a tool call (ToolCallContext.signal) cancels that call: its promise rejects with the signal’s reason, and nothing is written. A tool call with events rejects once your listeners return.

• Work already running on the executor finishes, and its answer is dropped unwritten. The next call on that design loads the design again.
• A signal also ends a call’s wait for an exiting executor.
• Image generation closes its requests to the AI gateway, but a generation the gateway had already started may still be charged.

Watching Each Call: events#

type CoDesignEventListener = {
  on: 'tool.call';
  timeoutMs?: number; // default 5000
  run: (e: ToolCallEvent) => void | Promise<void>;
};

interface ToolCallEvent {
  type: 'tool.call';
  tool: CoDesignToolName | (string & {}); // or the name of one of your tools
  ok: boolean; // false for an error result or a throw
  error?: {
    kind?: CoDesignErrorKind | 'aborted'; // the reason, when the SDK knows it
    thrown?: unknown; // the error the tool threw
  };
  ms: number; // the whole call, without the listeners
  phases: readonly { name: ToolCallPhase; ms: number }[];
  design?: string; // the design the call worked on (the first, if several)
  wrote?: string; // your store's version the call wrote (StoredDesign.version)
}

type ToolCallPhase = 'store_read' | 'engine_open' | 'engine_run' | 'store_write';

One frozen event per call of each tool in codesign.tools, your own tools included, for latency and error dashboards. create, load, export, and release give none. An event with wrote means that design changed, so a chat can refresh its preview. Build the listener where you handle a request, so it closes over that request’s ids; the event carries none of your data:

import {
  prepareCoDesign,
  type CoDesignEventListener,
  type DesignStore,
  type EnginePluginModule,
  type Executors
} from '@imgly/codesign-sdk';

import { errorTracker, metrics } from './yours.js';

interface Request {
  tenantId: string;
  chatId: string;
  id: string;
}

function eventsFor(req: Request): CoDesignEventListener[] {
  return [
    {
      on: 'tool.call', // the only event type today
      run: async (e) => {
        try {
          metrics.timing(`codesign.${e.tool}`, e.ms, {
            ok: String(e.ok),
            tenant: req.tenantId
          });
          for (const p of e.phases) {
            metrics.timing(`codesign.${e.tool}.${p.name}`, p.ms);
          }
          // A cancel by your user is not an error.
          if (e.error?.thrown !== undefined && e.error.kind !== 'aborted') {
            errorTracker.capture(e.error.thrown, { request: req.id });
          }
        } catch {
          metrics.increment('codesign.events.listener_failed');
        }
      }
    }
  ];
}

export function toolsFor(
  req: Request,
  executors: Executors,
  plugins: EnginePluginModule[],
  designs: DesignStore
) {
  return prepareCoDesign({
    conversation: `${req.tenantId}.${req.chatId}`,
    executors,
    plugins,
    designs,
    gateway: false,
    events: eventsFor(req)
  });
}

Tag metrics only with values from a small set (tenant, tool, ok, kind); every new value makes a new metric series, so per-request ids go to logs or traces.

Later versions add kinds, phases, and events, so handle a value you do not know and compare kinds as strings. Every kind and code is on Errors.

Phases never overlap, and their sum is at most ms. A phase can occur more than once in a call, so add up entries with the same name. Reading the handbook and your own tools have no phases.

• When a listener runs: after the tool’s work, before the result goes back to your loop. Listeners are awaited in order, each for at most its timeoutMs; past that the SDK goes on and logs one line with console.error. Listener time is not in ms but delays the result. Await your send if your platform freezes the process after the response.
• When a listener fails: the tool result does not change. The SDK logs the error once per listener and message, at most 100 lines per prepareCoDesign result. Catch errors in your listener, as the example does.
• Fails silently: the list is copied by prepareCoDesign, so a listener you add to your array later gets no events.
• Your data in errors: error.thrown is the original error with its stack; for an executor error, the executor’s message is in Error.cause. It can contain your store’s URLs or keys, so check it before you send it to an external service.

File Formats#

The executor reads and writes every format itself; you configure nothing.

• Pictures a file carries are offered to your writable sources, then stay inside the design if none keeps them (Where a New File Goes). Fonts in a PSD, IDML, or PDF are looked up in your typeface sources first, then in Google Fonts. LoadResult.warnings lists what could not be carried over.
• The PSD, IDML, and PDF importers need googleFonts() in plugins. Without it, such an import fails with an error that says “sources”.
• An export the model asks for in a format the executor cannot render is refused in words.
• Billing: the executor charges every file export to your IMG.LY account, once per design, version, format, and options. Saving the design itself (scene, imgly) is free ( Billing). A refused charge rejects with export_refused.

Executors#

remoteExecutors#

function remoteExecutors(options: RemoteExecutorsOptions): Executors;

interface RemoteExecutorsOptions {
  // required
  acquire: (req: {
    conversation: string; // prepareCoDesign's `conversation`
    signal?: AbortSignal; // aborted with the tool call that needs the executor
  }) => AcquiredExecutor | undefined | Promise<AcquiredExecutor | undefined>;
  token?: string; // optional here; IMG.LY's image requires one
}

interface AcquiredExecutor {
  url: string;
  fetch?: typeof globalThis.fetch;
}

interface Executors {
  readonly remote: true; // opaque: pass it as `executors`, nothing else
}

Where your executors are. Pass the result as prepareCoDesign’s executors. It builds a value and contacts nothing. The executor runs the engine and your plugins; your design store stays in your runner, which sends a design’s content to the executor when an engine needs it.

Binding to a Conversation#

• An executor binds to the first conversation that opens a design on it and refuses every other with HTTP 409, which rejects with executor_bound. The error carries short hashes of the two conversations, never the ids, and its message calls the executor a sandbox.
• conversation is the only thing acquire routes by; there is no tenant argument.
• GET /health answers bound: true or bound: false. The image keeps the binding in a volume at /var/lib/codesign-executor, so a restarted container stays bound, and only a new container starts unbound.
• Two runners that claim one executor for two conversations at once get executor_bound for the second, and nothing leaks.

Why every conversation gets a new container, and how to run them: see A New Container for Each Conversation.

Engine Sessions#

An executor runs one CE.SDK engine, and every design of its conversation opens on it in turn. A call for another design swaps that design in from your store, which costs about one load; nothing is lost, because every change was already written. Calls run one at a time, in arrival order. Each design has its own engine session on that one engine: its place there, with its own timers, named from the design’s id, the SDK’s build (SDK_VERSION), and your plugin modules; your plugins’ options are not part of the name, so a call with new options sets the sources up again.

What a call gets from the executor:

A tool call that rejects is not a result the model reads: your loop decides whether to report a failed call, retry, or end the run.

When the executor is lost (404 for a forgotten session, an idle close, a restart, unreachable, or a proxy’s 502 or 504), the SDK calls acquire again for the same conversation and loads the design there from your store. If the new executor runs another CE.SDK version, other capabilities, or other sources, the session ends and the call rejects with executor_changed, to your code, never to the model; calling again opens a new session there. Two executors on the same CE.SDK but different SDK builds are not told apart, so run one build. Never put a round-robin load balancer in front of the executors.

Lifetimes#

An operation still running when a timer fires or release arrives finishes first. When an executor exits, its next call finds it gone, acquire answers a new, unbound executor for the same conversation, and the design loads there from your store; that is how a conversation longer than 30 minutes goes on. While a session is open between turns, its container is held, and billed on a platform that bills a container while it runs. The executor’s own limits are in Limits the Executor Sets.

The Handshake#

interface HandshakeResult {
  versions: { sdk: string; cesdk: string }; // the executor's SDK_VERSION and CESDK_VERSION
  capabilities: {
    video: boolean; // the executor encodes video and audio: mp4, wav, m4a, and previews of a moment in time
    exportFormats: ExportFormat[]; // the formats an export can render here
  };
  // The sources, in plugin order.
  sources: {
    id: string;
    mimeTypes: string[]; // its getSupportedMimeTypes()
    roles: ('media' | 'typefaces' | 'palette' | 'templates' | 'components' | 'files')[];
    writable: boolean; // it has `uploadFile`
    description?: string;
  }[];
  plugins: { name: string; version: string }[]; // for diagnostics
}

The executor’s answer when a session opens: what it can do and which sources your plugins registered. It runs on the first call of a session, whatever that call is; later calls on the session do not repeat it.

• The handbook the model reads leaves out what this session cannot do, and an export the executor cannot render is refused in words. The tool list does not change.
• capabilities.video is false on an executor without video encoding, and mp4, wav, and m4a are then refused.
• It is per session. A lost executor replaced by one with another CE.SDK version, other capabilities, or other sources ends the session with executor_changed. plugins and versions.sdk are not compared.
• designs.listSourceId must be one of its sources.

await codesign.handshake() returns it early, or rejects as the first tool call would (invalid_options naming a source, executor_unreachable, executor_capacity, executor_version, executor_unauthorized). Use it to show a setup error before the person types, or to start a container while they type.

The Executor Image’s Environment Variables#

Per-tenant setup arrives with each engine session, in plugins; the image itself takes only these. How to run it: Host the Executor.

Optional, for an outbound proxy, used by the server and the engine process ( Allow Only the Hosts the Executor Needs):

Everything else is fixed in the image. Setting EXECUTOR_ONE_SESSION, EXECUTOR_IDLE_MS, EXECUTOR_MAX_LIFETIME_MS, or EXECUTOR_MAX_SESSIONS stops it at start, and so does running it under --init, tini, or a shared process namespace ( Run the Image Hardened).

GET /health needs no token and answers { result: { sessions, accepting, bound, protocol, idleTimeoutMs, maxLifetimeMs } }:

Sources#

An asset source is CE.SDK’s name for a searchable list of things a design can use: your product’s photos, brand typefaces and colors, templates, and saved components. A plugin is CE.SDK’s name for setup code an engine applies (EnginePlugin: { name, version, initialize({ engine }) }); the ones here register asset sources. You list plugins, never the sources: the executor applies them when a session opens, checks each source they registered, and reports them in the handshake. Your runner never runs source code: it sends each module’s text and options with every call, so a source’s findAssets calls your API from wherever the executor runs. How to build them for your files and brand: Connect Your Storage and Bring Your Brand.

Plugin Modules#

A module is one ES module whose default export is (options) => EnginePlugin and that registers each source with engine.asset.addSource. It is the same file your editor applies with cesdk.engine.addPlugin. A complete module, for a product with a media library, a design list, and brand typefaces behind one API:

// Runs in your CE.SDK editor and on the executor. No imports.
// `api` and `token` are this person's values for this session.
export default function acmeSources({ api, token }) {
  const headers = { authorization: `Bearer ${token}` };
  const get = async (path) => {
    const response = await fetch(`${api}${path}`, { headers });
    if (response.status === 404) return undefined;
    if (!response.ok) throw new Error(`${path} answered ${response.status}`);
    return response.json();
  };
  // Your API's file as the asset CE.SDK and the agent place. `meta.uri` is
  // what the design keeps for good: a stable address, never a presigned URL.
  const asAsset = (file) => ({
    id: file.id,
    label: file.name,
    groups: [file.folder], // groups are folders
    meta: {
      uri: `acme://${file.id}`, // your own scheme; `resolve` below makes it fetchable
      thumbUri: file.thumbnailURL,
      mimeType: file.mimeType,
      width: file.width,
      height: file.height
    }
  });

  return {
    name: 'acme.sources', // shows in errors
    version: '1.0.0',
    initialize({ engine }) {
      engine.asset.addSource({
        id: 'acme.media',
        // The model reads this line in search results: say what the source is for.
        description:
          "This team's photos, logos and videos; groups are folders.",
        // What this source holds: it decides the source's role.
        getSupportedMimeTypes: () => ['image/png', 'image/jpeg', 'video/mp4'],
        async findAssets(query) {
          const params = new URLSearchParams({
            q: query.query ?? '',
            page: String(query.page), // from 0
            perPage: String(query.perPage),
            folders: (query.groups ?? []).join(',')
          });
          const found = await get(`/files?${params}`);
          return {
            assets: found.items.map(asAsset),
            currentPage: query.page,
            ...(found.hasMore ? { nextPage: query.page + 1 } : {}),
            total: found.total
          };
        },
        async fetchAsset(id) {
          const file = await get(`/files/${encodeURIComponent(id)}`);
          return file === undefined ? null : asAsset(file); // null: no such file for this person
        },
        async getGroups() {
          return (await get('/folders')).map((folder) => folder.id);
        },
        async getGroupLabels() {
          return Object.fromEntries(
            (await get('/folders')).map((folder) => [folder.id, folder.name])
          );
        },
        // For uris of your own scheme: a URL the engine can fetch right now.
        // `undefined`: not mine.
        async resolve(uri) {
          if (!uri.startsWith('acme://')) return undefined;
          const id = encodeURIComponent(uri.slice('acme://'.length));
          return (await get(`/files/${id}/signed-url`)).url;
        },
        // Having this makes the source writable. Keep the file and return its
        // asset, or return `undefined` to decline, and the next source is offered it.
        async uploadFile(file, { action, group, width, height }) {
          if (action === 'import') return undefined; // pictures inside an imported PSD stay in the design
          const query = new URLSearchParams({
            name: file.name,
            folder: group ?? 'Agent'
          });
          // An image's size in pixels, read by the SDK from the bytes (none for
          // a video). Your API keeps it and answers it as `width` and `height`.
          if (width !== undefined) query.set('width', String(width));
          if (height !== undefined) query.set('height', String(height));
          const response = await fetch(`${api}/files?${query}`, {
            method: 'POST',
            headers: { ...headers, 'content-type': file.type },
            body: file
          });
          if (!response.ok)
            throw new Error(`upload answered ${response.status}`);
          return asAsset(await response.json());
        }
      });

      engine.asset.addSource({
        id: 'acme.designs', // the designs store's listSourceId
        description: "This team's saved designs, by title.",
        // A design is not a file to place or to be offered new files: no types.
        getSupportedMimeTypes: () => [],
        async findAssets(query) {
          const params = new URLSearchParams({
            q: query.query ?? '', // the agent finds saved designs by title
            page: String(query.page),
            perPage: String(query.perPage)
          });
          const found = await get(`/designs?${params}`);
          return {
            assets: found.items.map((design) => ({
              id: design.id, // the design id the SDK reads and writes
              label: design.title,
              meta: { thumbUri: design.thumbnailURL } // a preview for your editor's panel
            })),
            currentPage: query.page,
            ...(found.hasMore ? { nextPage: query.page + 1 } : {}),
            total: found.total
          };
        }
      });

      engine.asset.addSource({
        id: 'acme.fonts',
        description: "The brand's typefaces. Use these before any other font.",
        getSupportedMimeTypes: () => ['application/ubq-typeface'],
        async findAssets(query) {
          const all = (await get('/typefaces')).filter(
            (family) =>
              !query.query ||
              family.name.toLowerCase().includes(query.query.toLowerCase())
          );
          const start = query.page * query.perPage;
          const page = all.slice(start, start + query.perPage);
          return {
            // One asset per family, with every cut in `fonts`.
            assets: page.map((family) => ({
              id: family.id,
              label: family.name,
              payload: {
                typeface: {
                  name: family.name, // exactly the family name
                  fonts: family.files.map((file) => ({
                    uri: file.url, // durable: designs keep it
                    subFamily: file.subFamily,
                    weight: file.weight, // 'normal', 'bold', …
                    style: file.style // 'normal' or 'italic'
                  }))
                }
              }
            })),
            currentPage: query.page,
            ...(start + page.length < all.length
              ? { nextPage: query.page + 1 }
              : {}),
            total: all.length
          };
        }
      });
    }
  };
}

The runner sends the file’s text and its options. The smallest list is plugins: [googleFonts()]:

import { readFileSync } from 'node:fs';

import {
  googleFonts,
  prepareCoDesign,
  type DesignStore,
  type Executors
} from '@imgly/codesign-sdk';

import { mintToken } from './yours.js';

// The module's text, sent with every call; the file is the one your editor applies.
const acmeSources = readFileSync(
  new URL('./acme-sources.plugin.js', import.meta.url),
  'utf8'
);

export function toolsForChat(req: {
  tenantId: string;
  chatId: string;
  userId: string;
  designId: string;
  executors: Executors;
  designs: DesignStore;
}) {
  return prepareCoDesign({
    conversation: `${req.tenantId}.${req.chatId}`, // this chat: its one executor
    executors: req.executors,
    plugins: [
      {
        module: acmeSources,
        // Passed to the module's default export. The model's code can read
        // these, so the token is this person's own, for this session, and short-lived.
        options: { api: 'https://api.acme.com', token: mintToken(req.userId) }
      }, // brand typefaces rank first
      googleFonts() // after the brand's typefaces
    ],
    designs: req.designs,
    design: req.designId,
    gateway: false
  });
}

// The clients this page's code calls that are yours to write, over what your product already has.

import type { AcquiredExecutor } from '@imgly/codesign-sdk';

/** Your metrics client, such as StatsD or Datadog. */
export const metrics = {
  timing(_name: string, _ms: number, _tags?: Record<string, string>): void {
    throw new Error('yours to write');
  },
  increment(_name: string): void {
    throw new Error('yours to write');
  }
};

/** Your error tracking, such as Sentry. */
export const errorTracker = {
  capture(_error: unknown, _context?: Record<string, string>): void {
    throw new Error('yours to write');
  }
};

/** A short-lived token that carries exactly this person's rights in your API. */
export function mintToken(_userId: string): string {
  throw new Error('yours to write');
}

/** Your database client, such as node-postgres's `Pool`. */
export const db = {
  async query(
    _sql: string,
    _params: readonly unknown[]
  ): Promise<{ rows: Record<string, any>[] }> {
    throw new Error('yours to write');
  }
};

/** Your object storage. */
export const bucket = {
  async put(_key: string, _bytes: Uint8Array, _type: string): Promise<void> {
    throw new Error('yours to write');
  },
  async delete(_key: string): Promise<void> {
    throw new Error('yours to write');
  },
  async get(_key: string): Promise<Uint8Array> {
    throw new Error('yours to write');
  }
};

/** A download link to one stored file that expires after a while. */
export async function signedLink(_key: string): Promise<string> {
  throw new Error('yours to write');
}

/** Your `acquire`: the conversation's executor, the same one while it lives, and an unused one for a new conversation. */
export async function acquire(_req: {
  conversation: string;
  signal?: AbortSignal;
}): Promise<AcquiredExecutor | undefined> {
  throw new Error('yours to write');
}

Rules for a module:

• No imports. Nothing on the executor installs a package; bundle a module that uses a library into one file first (esbuild acme-sources.js --bundle --format=esm).
• No text built from a function (`export default ${fn}`): a bundler or coverage tool changes what Function.prototype.toString returns, and the executor gets a module that throws.
• Only fetch, URL, TextEncoder, timers, and the engine, which both the executor and a browser have; no window, document, or process.
• Per-session values go in options, never in the code. The executor keeps every module it loads for the life of its process. A session’s modules together may be at most 256 KB, because the runner sends them with every call.
• State lives inside the function, not at the top of the file: one loaded module serves every session that sends it.
• initialize may run again on the same engine with new options. The executor removes the sources the last setup added; anything else a module installs must be safe to install twice.
• Every design of one conversation sends the same module texts. Only options may differ between calls (Engine Sessions).
• Do not call setURIResolver. CE.SDK has one resolver slot per engine; the SDK installs one that asks each source’s resolve in list order.
• A token in options is this person’s, per session, and short-lived, and stays valid until the last call that sends it ends. The model’s code runs beside your sources and can read their options, with the person’s rights ( Security).
• Your engineers write modules; your users never do. A module runs with everything the engine process can reach.

Source Roles#

Each source answers CE.SDK’s getSupportedMimeTypes() with the kinds of file it holds. From that answer alone the SDK derives the source’s role, which decides how the agent uses it. There are no role options.

A source can hold several kinds. The SDK reads a new file’s type from its bytes, never its name, and always spells it one way (font/ttf, not font/sfnt; audio/mp4, not audio/x-m4a). The ASSET_MIME_TYPES constants, for a module that cannot import them:

The session fails with invalid_options, whose source is the source’s id, when:

• a type is an alias the SDK never passes (image/jpg; the message names image/jpeg), or an application/ubq-… type that is none of ASSET_MIME_TYPES
• the source is writable (it has uploadFile) but names no type
• the source holds typeface assets without declaring ASSET_MIME_TYPES.typeface, or color assets without ASSET_MIME_TYPES.color; without this check the font lookup would skip it with no error

testAssetSource runs the same checks in your tests.

Where a New File Goes#

1. The SDK reads the file’s type from its bytes.
2. Candidates are the sources that have uploadFile and whose types admit that type, in list order. A wildcard such as image/* never admits PSD, PDF, or IDML.
3. Each candidate is offered the file in turn. The first to return an asset keeps it; undefined declines, and the next is offered it; a throw fails the operation (throw refusal(text) to tell the model why).
4. If nobody takes it, a generated file, an imported picture, or an imported font stays inside the design, which is then saved as an .imgly archive (designs.write gets { archive }). Saved blocks have no such place and fail with refused.
5. When two or more candidates remain, the model may choose which one keeps the file.

Who acted is not passed: the editor and the agent apply the same module with different options, so a product that treats the agent’s writes differently says so there, such as a token that grants less.

Fails silently: a source with uploadFile that never declines takes every file its types admit, including ones you wanted a later source to keep. Check it with testAssetSource’s uploads.

Searching#

A search runs on the executor, as the same engine.asset.findAssets the model’s code calls, so a file uploaded a second ago is found. The result lists each source with its description, its group names (getGroupLabels), and the assets of its page. A source that throws is named as unavailable while the others answer. A search filtered by type passes CE.SDK filter data to findAssets; a source may ignore it, because the SDK drops what does not match.

Image Sizes#

Every image asset a source returns carries its size in pixels, as a positive meta.width and meta.height (a number or a numeric string, 640 or "640"), as CE.SDK’s own catalogs do. CE.SDK sizes a placed image’s block from them, and the model reads them to keep the image’s aspect ratio. The rule covers PNG, JPEG, WebP, GIF, AVIF, and SVG assets; PSDs, videos, typefaces, and colors need no size.

• uploadFile is told the size, read from the bytes, as width and height. Keep it and answer it from findAssets and fetchAsset. The asset uploadFile returns may leave it out: the SDK adds it.
• Fails loudly: a search that meets an image asset without a size rejects with invalid_asset, naming the source (error.source) and the asset. So does storing a new image whose size neither the asset nor its bytes give, such as an SVG sized only in %. testAssetSource reports it first.

For an image your own code keeps, such as an upload in your editor:

function imageSizeOf(
  bytes: Uint8Array,
  mimeType: string
): { width: number; height: number } | undefined;

Reads the size from the file’s header without decoding it: PNG, JPEG, WebP, GIF, and AVIF, and an SVG’s width and height in pixels or its viewBox. Returns undefined for another type, or for bytes that do not say.

Typefaces#

A typeface is a font family: a name and one file per weight and style. A font is one of those files.

• One asset per family, with every cut in payload.typeface.fonts, name exactly the family, and query honored. Otherwise bold and italic silently do not exist.
• A family in two typeface sources comes from the first in plugins order. Google Fonts and CE.SDK’s default typefaces share many names, such as Roboto, so keep a brand family out of the sources listed after it; testAssetSource’s laterTypefaceSources flags it.
• A font file’s uri is written into every design that uses it, so it must last as long as the design: a public, versioned https URL, or a uri of your own scheme that resolve answers. Never a presigned URL.
• UploadFileOptions.font is for a typeface source to add an imported font file to the right family; the SDK leaves it unset.

googleFonts#

function googleFonts(opts?: { baseURL?: string }): EnginePluginModule;

IMG.LY’s Google Fonts: the source ly.img.gfonts, which the font lookup searches, and ly.img.gfonts-fallbacks, the stand-ins the PSD, IDML, PDF, and PowerPoint importers use for common fonts a file names, such as Helvetica. Nothing is added unless listed. To serve the catalog yourself, copy IMG.LY’s folder as it is and pass it as baseURL; the font files it lists still point at cdn.img.ly. When the catalog cannot be loaded, the call that opens the session rejects:

plugin 0 (ly.img.google-fonts): initialize threw: Google Fonts: could not load …/ly.img.gfonts/content.json (…)

Allow cdn.img.ly, or your copy’s host, in the executor’s egress ( Allow Only the Hosts the Executor Needs).

cesdkDefaults and cesdkDemo#

function cesdkDefaults(opts?: {
  include?: readonly string[]; // source ids; default: all of them
  baseURL?: string;
}): EnginePluginModule;
function cesdkDemo(opts?: {
  include?: readonly string[];
  baseURL?: string;
}): EnginePluginModule;

CE.SDK’s own catalogs for exactly CESDK_VERSION, with that editor’s ids and content. cesdkDefaults() is what an editor ships with: stickers, vector shapes, text components, ly.img.typeface, the color palette, text styles, effects, filters, blurs, and crop and page presets. cesdkDemo() is trial content (ly.img.image, ly.img.video, ly.img.audio, and ly.img.templates) for trying the agent before your own sources exist; do not ship it as your content. include takes source ids and throws invalid_options for one that is not in the set. ly.img.typeface and googleFonts() share family names (Typefaces).

Opening a Session#

The executor loads every module, calls each default export with its options, and awaits its initialize, in order, 10 seconds each. It adds nothing of its own, then checks each source and answers with the handshake.

Fails at open, naming the module by its position and name (plugin 0 (acme.sources): initialize threw: /typefaces answered 401), when a module does not load, imports anything, or has no function as its default export; when initialize throws or takes over 10 seconds; when the modules are over 256 KB together; or when a source fails its checks. Values of the module’s options, URL queries, and Bearer tokens are removed from its error message.

An image, video, audio, or font the engine cannot load, such as a scheme no resolve answers, a signer that answered 403, or a deleted file:

• One the model’s code adds now is refused: the new blocks are rolled back, and the change fails with the engine’s error.
• One already in the design does not stop it from opening or saving. Every result, every look at the design, every export, and a render_failed error name it with its uri and the engine’s error ('Hero' (id 12): acme://a1b2.png could not be loaded (FileFetch)). Run a design that uses each of your schemes and fonts through codesign.edit() and codesign.export() before you rely on a source.

Schemes a saved design may hold: http, https, and bundle (CE.SDK’s built-in assets). When the engine refuses to save a scheme it does not know, such as your acme://, the session allows it for the rest of its life and saves again; you list no schemes. Never allowed: buffer:, blob:, data:, file:, javascript:, vbscript:, about:, the SDK’s own codesign-pending:, and any one-letter scheme (a drive letter).

The Source Interface#

CoDesignAssetSource is what your module passes to addSource: CE.SDK’s AssetSource plus description, resolve, and uploadFile, which CE.SDK ignores and CoDesign reads.

interface CoDesignAssetSource {
  id: string; // unique among every source of the session
  description?: string;
  getSupportedMimeTypes(): SupportedMimeType[]; // synchronous, pure
  findAssets(
    query: AssetQueryData,
    opts?: SourceCallOptions
  ): Promise<AssetsQueryResult | undefined>;
  fetchAsset?(
    id: string,
    params?: { locale?: string },
    opts?: SourceCallOptions
  ): Promise<AssetResult | null>;
  getGroups?(opts?: SourceCallOptions): Promise<string[]>;
  getGroupLabels?(
    opts?: { locale?: string } & SourceCallOptions
  ): Promise<Record<string, string>>;
  resolve?(
    uri: string,
    opts?: SourceCallOptions
  ): string | undefined | Promise<string | undefined>;
  uploadFile?(
    file: File,
    opts: UploadFileOptions
  ): Promise<AssetDefinition | AssetResult | undefined>;
}

interface SourceCallOptions {
  signal?: AbortSignal; // aborted with the call that asked; ignoring it is allowed
  design?: string; // the design the call is for
}

interface UploadFileOptions extends SourceCallOptions {
  action: 'upload' | 'import' | 'generate' | 'saveComponent';
  group?: string; // `upload`: the folder a person uploaded into
  label?: string;
  thumbnail?: File; // `saveComponent`: a PNG of the blocks
  font?: { family: string; weight: FontWeight; style: FontStyle }; // left unset by the SDK
  width?: number; // an image: its size in pixels, read from the bytes; keep it as meta.width
  height?: number; // … and as meta.height
}

Your CE.SDK web editor applies the same plugin list, with this person’s options, through addPluginModules, so its panels and the agent see the same sources ( Your Editor).

What You Implement#

Besides your sources: a design store over the table where your product keeps designs, and, if the model should hand people files, an uploadExport function. How to build them over your storage: Connect Your Storage.

Designs#

interface DesignStore {
  listSourceId?: string; // the asset source that lists the designs; lets the agent list saved designs
  read(
    id: string,
    opts: { signal?: AbortSignal }
  ): Promise<StoredDesign | undefined>;
  write(
    id: string,
    content: DesignContent<ArrayBuffer>,
    opts: DesignWriteOptions
  ): Promise<string | undefined>; // the version written; undefined: the stored version moved on
}

interface DesignWriteOptions {
  ifMatch?: string; // the version the SDK read; absent: create, only if the id is free
  cesdkVersion: string; // the CE.SDK that produced this content
  editKey?: string; // a key of this edit; absent for an import or a load
  title?: string; // the new design's title, on its first write only
  group?: string; // the new design's folder in your list, on its first write only
  signal?: AbortSignal; // aborted with the tool call that writes
}

interface StoredDesign {
  content: DesignContent | { uri: string }; // the content of exactly `version`
  version: string; // changes with every write and is never reused for this design
  cesdkVersion: string | null; // the CE.SDK that made `version`, as `write` received it; null: unknown
  title?: string; // what the model calls it, and the name of files it hands out; default: the id
  editKey?: string; // the editKey of the write that made `version`
}

type DesignContent<B extends ArrayBufferLike = ArrayBufferLike> =
  | { scene: string; archive?: undefined }
  | { archive: Uint8Array<B>; scene?: undefined };

Your designs, as prepareCoDesign({ designs }). They run only in your runner: the model’s code runs on the executor and never reaches them or their credentials, so the checks below cannot be skipped. Build the store per request, already limited to the signed-in person’s tenant.

• { uri } content. read may return a URL of exactly this version, which the executor fetches itself, so a large design never passes through your runner. The executor must be allowed to reach that host, and the bytes behind the URL must never change for that version. Return the same URL on every read of one version: the engine recognizes a design it holds by URL and version, and an export’s render id derives from them, so a URL signed afresh on every read loads the design on every call and charges a retried export again.
• Archives. A design that holds files no source kept is stored as an .imgly archive (content.archive), and a call that reads one writes an archive again until the files find a home. Your editor saves it as an archive too, never as a scene string, which would lose the images inside.
• CE.SDK versions. Keep the cesdkVersion write receives and return it from read (null when unknown; the field is required, so a store cannot turn the check off by forgetting it). The SDK refuses to write over, or copy, a design a newer CE.SDK saved, rejecting with older_saver (saver, recorded). A null design may be saved by any CE.SDK. Your editor’s save route keeps the same check with assertCanSave.
• Existing designs need no conversion: a scene from saveToString() loads as it is, and its image URLs must be fetchable from the executor or resolved by one of your sources. Give each row a version; "0" is a version.

The listing source is a plain CE.SDK asset source in your plugin module. It only lists, so its token needs no right to write designs. The engine refuses to place its assets, and a search of your sources leaves it out:

engine.asset.addSource({
  id: 'acme.designs', // the designs store's listSourceId
  description: "This team's saved designs, by title.",
  // A design is not a file to place or to be offered new files: no types.
  getSupportedMimeTypes: () => [],
  async findAssets(query) {
    const params = new URLSearchParams({
      q: query.query ?? '', // the agent finds saved designs by title
      page: String(query.page),
      perPage: String(query.perPage)
    });
    const found = await get(`/designs?${params}`);
    return {
      assets: found.items.map((design) => ({
        id: design.id, // the design id the SDK reads and writes
        label: design.title,
        meta: { thumbUri: design.thumbnailURL } // a preview for your editor's panel
      })),
      currentPage: query.page,
      ...(found.hasMore ? { nextPage: query.page + 1 } : {}),
      total: found.total
    };
  }
});

A complete store over a SQL table and a bucket is in Connect Your Storage.

uploadExport#

uploadExport?: (req: UploadExportRequest) => Promise<UploadExportResult>;

interface UploadExportRequest {
  format: ExportFormat; // 'png', 'pdf', …
  title: string; // the design's title; a file name is `<title>.<ext>`
  mimeType: string; // such as 'image/png'; 'application/zip' for an imgly file
  bytes: Uint8Array<ArrayBuffer>; // the file, ready for `new Blob([bytes])`
  design: string;
  version: string; // your store's version that was rendered (StoredDesign.version)
  signal?: AbortSignal; // aborted with the tool call
}

type UploadExportResult =
  | { downloadURL: string; note?: string }
  | { note: string; downloadURL?: string }; // at least one

Lets the agent hand people files. When the model asks for an export, the SDK renders and charges the file on the executor, then calls uploadExport with the bytes. Store them where your product keeps a person’s files and answer with the link they open (downloadURL), a line for the model to pass on (note), or both.

import type {
  UploadExportRequest,
  UploadExportResult
} from '@imgly/codesign-sdk';

import { bucket, signedLink } from './yours.js';

export async function uploadExport(
  req: UploadExportRequest
): Promise<UploadExportResult> {
  const key = `exports/${req.design}/${req.version}-${req.format}`;
  await bucket.put(key, req.bytes, req.mimeType);
  return { downloadURL: await signedLink(key) };
}

• A throw fails the export. The file was already charged, and a retry renders under the same render id, so it is charged once. Throw refusal(text) to give the model a reason. An answer with neither downloadURL nor note rejects with export_refused.
• The model chooses the PDF/X settings; you receive the finished file.
• An export never writes the design. imgly carries the design’s images, including those from private sources.
• For an approval step before a change reaches a person’s design, run the turn on a copy ( Run a Turn on a Copy).
• Known limit: the bytes travel from the executor through your runner to your storage, held in memory on the way.

The Tool Contract#

Every tool in codesign.tools, the SDK’s and yours, has one shape, which maps onto any model API’s tool calling, with no Model Context Protocol (MCP) server involved. These types do not change within a major version. For complete mappings to agent frameworks, see the quickstart kits, such as Quickstart: Vercel AI SDK.

CoDesignTool#

interface CoDesignTool {
  name: string;
  description?: string;
  inputSchema: JSONSchema; // the arguments, as a JSON Schema object
  annotations?: { readOnlyHint?: boolean };
  call: (args: unknown, ctx?: ToolCallContext) => Promise<ToolResult>;
}

interface ToolCallContext {
  signal?: AbortSignal | undefined; // cancels this call
}

type ToolResult = {
  content: ToolResultPart[];
  isError?: boolean; // the call failed; `content` says why, in words for the model
};

type ToolResultPart =
  | { type: 'text'; text: string }
  | { type: 'image'; data: string; mimeType: string }; // data: base64

ToolResult is a subset of MCP’s CallToolResult; a new part type would be a major version. The read-only tools carry annotations: { readOnlyHint: true }, MCP’s field for this; pass it on if your framework uses it.

Your own tools take the same shape; see Adding Your Own Tools.

JSONSchema#

A copy of the JSON Schema object type (draft 7), so inputSchema passes to the Vercel AI SDK’s jsonSchema() with no cast. The SDK’s own schemas keep to a subset that Anthropic, Gemini, and OpenAI (without strict mode) all accept:

• The root is { type: 'object', properties }.
• Only type, description, properties, required, items, enum, minimum, maximum, and a boolean additionalProperties. No $ref, $defs, oneOf, anyOf, allOf, not, const, or if, and no exclusive bounds.
• Every node has one type. An enum is a list of strings on a type: 'string' node, an array has items, and required names only declared properties.

OpenAI’s strict mode, which requires every property to be required, is not a target. Keep your own tools’ schemas to the same subset if you use several providers.

Reserved Tool Names#

Your tools may not use a name the SDK’s tools use, or a name the handbook is gated on: the handbook has passages shown only when a tool or capability of that name exists, and a tool of yours with such a name would switch them on.

skill, edit, preview, import, open, export, designs, asset_generate, asset_add, asset_search, checklist, components, diagnostics, drafts, files, login, ly.img.gfonts, ly.img.workspace.images, media, palette, scorecard, templates, typefaces, version, video, view.

The list can grow in any release, so prefix your tools with your product’s name (acme_brand_kit). A clash, or two of your tools with one name, makes prepareCoDesign throw tool_name_clash, naming the tool.

Images in Tool Results#

Every image the SDK’s tools render, such as the pages and blocks the agent looks at and the render after a change, is a PNG sized for a model’s context:

• about 262,144 pixels (512 × 512) per image, at the block’s own aspect ratio
• no side longer than 1,568 pixels, above which Anthropic’s models downscale an image silently
• at most 10 images in one result

A look at a stored asset shows your file as stored, in its own type (PNG, JPEG, GIF, WebP, or SVG), and refuses one over 512 kB. A chat-completions API takes a tool result as text only, so your loop moves the images into a user message after it ( Troubleshooting).

Image Generation: gateway#

interface GatewayOptions {
  bearer: (opts?: { forceRefresh?: boolean }) => Promise<string | undefined>; // required
  baseURL?: string; // default https://gateway.img.ly
  fetch?: typeof globalThis.fetch;
}

gateway is required: { bearer } lets the agent generate images, video, speech, music, and sound effects through IMG.LY’s AI gateway, a paid service; false leaves that out, for products that supply every image or jobs that only rearrange a design, such as resizing.

import {
  googleFonts,
  prepareCoDesign,
  remoteExecutors
} from '@imgly/codesign-sdk';

import { acquire } from './yours.js';

export function toolsForJob(jobId: string) {
  return prepareCoDesign({
    conversation: jobId,
    executors: remoteExecutors({ acquire, token: process.env.EXECUTOR_TOKEN }),
    plugins: [googleFonts()], // add a plugin whose source has `uploadFile` to keep generated files
    design: jobId,
    // Your gateway key, from your secrets; without one, false rather than a tool that fails.
    gateway: process.env.IMGLY_GATEWAY_API_KEY
      ? { bearer: async () => process.env.IMGLY_GATEWAY_API_KEY }
      : false
  });
}

• Generation runs in your runner, next to your license key, never on the executor. Each result is a new file, routed with action: 'generate' (Where a New File Goes).
• bearer is called for each request and returns your CoDesign license key, so the SDK never holds it. undefined makes the SDK tell the model there is no credential, for a key that is briefly unavailable. After a 401 it is called once more with forceRefresh: true.
• A resent generation call generates, and is charged, again.
• Out of credits (HTTP 402): the call rejects with generation_refused, and nothing is charged. Its message is the sentence for the person (“This account is out of credits — this request was not charged. Top up at …”). Tell the person and end or continue the turn. Every other gateway problem reaches the model as a refusal it can act on.

Errors#

interface CoDesignError extends Error {
  readonly kind: CoDesignErrorKind; // open: a later version adds kinds
  readonly design?: string | undefined;
  readonly source?: string | undefined;
  readonly retryAfterMs?: number | undefined;
  readonly saver?: string | undefined;
  readonly recorded?: string | undefined;
}

function isCoDesignError(err: unknown): err is CoDesignError;
function refusal(text: string): CoDesignError;

• A failure the model can fix reaches it as an isError tool result; one it cannot fix rejects the tool call with a CoDesignError. Your own create(), load(), edit(), export(), and handshake() reject with every kind.
• isCoDesignError also recognizes an error from another copy of the SDK in your bundle. Switch on kind with a default.
• Throw refusal(text) from a member you write to tell the model no, in words.

Every kind, when it is raised, who gets it, and what to do: Errors. Retrying your own calls while an executor exits or cannot be reached:

import { isCoDesignError } from '@imgly/codesign-sdk';

// For example: await whenEngineAvailable(() => codesign.load(file))
export async function whenEngineAvailable<T>(
  call: () => Promise<T>
): Promise<T> {
  const retiringUntil = Date.now() + 5 * 60_000; // executor_capacity: an executor still exiting after the SDK's own minute
  const downUntil = Date.now() + 30_000; // executor_unreachable: 30 seconds for an executor that does not answer
  for (;;) {
    try {
      return await call();
    } catch (err) {
      if (!isCoDesignError(err)) throw err;
      let waitMs: number;
      switch (err.kind) {
        case 'executor_capacity':
          if (Date.now() > retiringUntil) throw err;
          waitMs = err.retryAfterMs ?? 1000;
          break;
        case 'executor_unreachable':
          if (Date.now() > downUntil) throw err;
          waitMs = 1000;
          break;
        default:
          throw err; // anything else, and any kind a later version adds
      }
      await new Promise((resolve) => setTimeout(resolve, waitMs));
    }
  }
}