Types

Service, tool, and runtime data shapes from the cyrnel sdk

The cyrnel sdk package exports a small set of typescript types that describe the data cyrnel exchanges between the host, adapters, and environments. Everything else builds on these.

JSONSchema

type JSONSchema = Record<string, unknown>;

A free-form JSON document. Cyrnel internally validates payloads against the schema, any valid JSON schema format is fair game. Adapters and environments treat schemas as opaque.

ServiceDefinition

interface ServiceDefinition {
  name: string;
  summary?: string;
  description: string;
  configSchema: JSONSchema;
  secretsSchema: JSONSchema;
  tools: ToolDefinition[];
  adapterDomain: Record<string, unknown>;
}

The shape an adapter returns from generateDefinition. Cyrnel persists this into the services table along with an id, hash, source, adapter, and enabled flag. See Services.

• summary is an optional short plain-text description shown in lists and search. Keep it terse; use description for long-form markdown.
• configSchema describes per-service configuration (validated on PATCH).
• secretsSchema describes per-service secrets (validated on PATCH).
• adapterDomain is opaque to cyrnel. Adapters use it to carry install-time information that the runtime needs at invoke time.

ToolDefinition

interface ToolDefinition {
  id: string;
  name: string;
  summary?: string;
  description: string;
  inputSchema: JSONSchema;
  outputSchema: JSONSchema;
  adapterDomain: Record<string, unknown>;
}

The shape of each entry in ServiceDefinition.tools. id must be a valid TypeScript identifier; it is what process code addresses. summary is an optional short plain-text label, mirroring the service-level summary.

ServiceState and ToolState

type ToolState = Omit<
  ToolDefinition,
  "id" | "name" | "summary" | "description" | "inputSchema" | "outputSchema"
>;

interface ServiceState
  extends Omit<
    ServiceDefinition,
    "name" | "summary" | "description" | "configSchema" | "secretsSchema" | "tools"
  > {
  id: string;
  tools: Record<string, ToolState>;
  config: Record<string, unknown>;
  secrets: Record<string, unknown>;
}

The snapshot cyrnel hands to an adapter through AdapterModule.hydrateService. It carries everything the adapter needs to serve invocations:

• adapterDomain: The bag the adapter populated in generateDefinition.
• tools: Per-tool adapterDomain keyed by tool id.
• config: Validated configuration object (defaults applied).
• secrets: Decrypted secrets object (defaults applied).

Adapters should treat this as the source of truth and refresh their internal state every time hydrateService is called.

InvokeInput

interface InvokeInput {
  serviceId: string;
  toolId: string;
  parameters: Record<string, unknown>;
}

The payload of every tool call:

• Environment modules receive it through EnvironmentBindings.invokeTool.
• Adapter modules receive it through AdapterModule.invoke.
• The host validates parameters against the tool’s inputSchema before the adapter sees it (adapter-side validation is optional but recommended).

ToolDocsInput

interface ToolDocsInput {
  serviceId: string;
  toolId: string;
  description: string;
  inputSchema: JSONSchema;
  outputSchema: JSONSchema;
}

Passed to EnvironmentModule.generateToolDocs when the API serves GET /tools/:serviceId/:toolId/docs. The environment is expected to return Markdown.

Module logging

The host owns all logging. A module receives a single ModuleLogger through its setup context and never constructs a root logger. Every entry a module emits is automatically tagged with type: "module", moduleId, moduleType, and the owning adapterId/environmentId, these correlation fields are host-managed and the module cannot forge or override them.

MODULE_LOG_LEVELS and ModuleLogLevel

const MODULE_LOG_LEVELS = [
  "trace",
  "debug",
  "info",
  "warn",
  "error",
  "fatal",
] as const;

type ModuleLogLevel = (typeof MODULE_LOG_LEVELS)[number];

The severity levels a module logger accepts. The API maps these to its own internal level vocabulary, so modules are insulated from API-specific level names.

ModuleLogBindings

interface ModuleLogBindings {
  phase?: string;
  event?: string;
}

The only correlation fields a module may set. phase groups a span of work (e.g. "setup", "invoke", "execution"), and event is a structured key describing a specific occurrence (e.g. "adapter-request"). All other correlation fields (moduleId, moduleType, adapterId/environmentId, serviceId, toolId, executionId, dispatchId, requestId) are set by the host and ignored if a module attempts to supply them.

ModuleLogPayload

type ModuleLogPayload = Record<string, unknown>;

The free-form structured object a module passes alongside an optional message. Values are subject to the module’s own redact() patterns and the host baseline before being stored.

ModuleLogger

interface ModuleLogger<C = ModuleLogBindings> {
  readonly context: Readonly<C>;
  trace(payload?: ModuleLogPayload, message?: string): void;
  debug(payload?: ModuleLogPayload, message?: string): void;
  info(payload?: ModuleLogPayload, message?: string): void;
  warn(payload?: ModuleLogPayload, message?: string): void;
  error(payload?: ModuleLogPayload, message?: string): void;
  fatal(payload?: ModuleLogPayload, message?: string): void;
  isLevelEnabled(level: ModuleLogLevel): boolean;
  child<Next extends ModuleLogBindings>(bindings: Next): ModuleLogger<C & Next>;
  redact(patterns: readonly string[]): ModuleLogger<C>;
}

Usage:

const patterns = (context.config.redactionPatterns as string[] | undefined) ?? [];
// configure reduction for yourself from your own config field
this.logger = context.logger.redact(patterns).child({ phase: "setup" });

this.logger?.info({ event: "request", path }, "Sending request");
const scoped = this.logger?.child({ phase: "invoke", event: "adapter-request" });
scoped?.warn({ event: "rate-limited" }, "Upstream throttled");

• child(bindings) returns a new logger that merges only phase/event. Host-owned correlation fields are carried over and cannot be overwritten.
• redact(patterns) returns a new logger that applies the module’s path patterns additively on top of a non-disableable host baseline (secrets / tokens / passwords / authorization). Chained redact() calls accumulate patterns; non-string or empty-split patterns are ignored so a malformed pattern can never redact the whole payload. The host never pushes patterns into the setup context - reduction is configured by the module, for the module.
• context is Readonly: a module reads but never mutates the logger’s bound metadata.

ModuleSetupContext and AdapterSetupContext

interface ModuleSetupContext {
  config: Record<string, unknown>;
  secrets: Record<string, unknown>;
  logger: ModuleLogger;
}

type AdapterSetupContext = ModuleSetupContext;

Passed to Module.setup. config and secrets are the validated module-level objects from its configSchema/secretsSchema; logger is the host-owned logger described above. AdapterSetupContext is a plain alias of ModuleSetupContext, the adapter-vs-environment distinction lives in the AdapterModule/EnvironmentModule interfaces, not in the context type.

Execution constants

const EXECUTION_STATES = ["queued", "running"] as const;
type ExecutionState = (typeof EXECUTION_STATES)[number];

const EXECUTION_EXIT_STATES = [
  "failed",
  "success",
  "timeout",
  "canceled",
] as const;
type ExecutionExitState = (typeof EXECUTION_EXIT_STATES)[number];

The vocabulary an environment uses to report progress. ProcessService adds idle and terminating on top, those are host-side states, not environment-reported ones. See Execution and Processes.