Skip to main content

DRIVER

A driver is a TypeScript module that provides an out-of-process execution runtime for models. Drivers receive a bundled model and its arguments, execute the model method in an external environment (a container, a remote API, a language runtime), and return the results. The file lives in extensions/drivers/ and exports a driver object.

Export Shape

import { z } from "npm:zod@4";

export const driver = {
  type: "@mycollective/my-driver",
  name: "My Driver",
  description: "Execute models in my runtime",
  configSchema: z.object({
    apiEndpoint: z.string().url().describe("Runtime API endpoint"),
  }),
  createDriver(config: Record<string, unknown>): Driver {
    // validate config, return driver instance
  },
};

Fields

Field Type Description
type string Unique identifier in @collective/name format. Reserved collectives: swamp, si.
name string Human-readable display name.
description string Short description.
configSchema z.ZodTypeAny Zod schema that validates driver configuration.
createDriver (config: Record<string, unknown>) => Driver Factory that returns a driver instance.

Driver Interface

The object returned by createDriver must have a type and an execute method.

interface Driver {
  type: string;
  execute(
    request: DriverRequest,
    callbacks?: DriverCallbacks,
  ): Promise<DriverExecutionResult>;
}

DriverRequest

Passed to execute with everything the driver needs to run a model method.

Field Type Description
protocolVersion number Protocol version (currently 1).
modelType string The model's type identifier (e.g., @mycollective/my-model).
modelId string Instance ID of the model definition.
methodName string Name of the method to execute.
globalArgs Record<string, unknown> Resolved global arguments.
methodArgs Record<string, unknown> Resolved method-specific arguments.
definitionMeta DefinitionMeta Metadata about the model definition (see below).
resourceSpecs Record<string, unknown> (optional) Resource output specifications from the model.
fileSpecs Record<string, unknown> (optional) File output specifications from the model.
bundle Uint8Array (optional) Bundled model code for the driver to load and execute.

DefinitionMeta

Field Type Description
id string Definition UUID.
name string Definition name.
version number Definition version number.
tags Record<string, string> Definition tags.

DriverCallbacks

Optional callbacks for streaming output during execution.

Field Type Description
onLog (line: string) => void (optional) Called for each log line the driver produces.

DriverExecutionResult

Returned by execute when the method completes.

Field Type Description
status "success" | "error" Whether execution succeeded.
outputs DriverOutput[] Data outputs produced by the method (see below).
logs string[] Collected log lines from the execution.
durationMs number Wall-clock execution time in milliseconds.
error string (optional) Error message when status is "error".

DriverOutput

Field Type Description
kind "pending" Output kind (always "pending").
specName string Name of the resource or file spec.
name string Instance name for this output.
type "resource" | "file" Whether this is structured data or a file.
content Uint8Array Raw output content.

Packaging

Declare the driver in your extension's manifest:

drivers:
  - my_driver.ts

The file path is relative to the extensions/drivers/ directory within the extension root.

← PreviousDatastore ProviderNext →Model