> ## Documentation Index
> Fetch the complete documentation index at: https://actelos.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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`

```ts theme={null}
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`

```ts theme={null}
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](/cyrnel/docs/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`

```ts theme={null}
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`

```ts theme={null}
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`

```ts theme={null}
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`

```ts theme={null}
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`

```ts theme={null}
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`

```ts theme={null}
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`

```ts theme={null}
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`

```ts theme={null}
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:

```ts theme={null}
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`

```ts theme={null}
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

```ts theme={null}
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](/cyrnel/module-specs/environment-execution) and
[Processes](/cyrnel/docs/processes).