Types

Source: core/types/session.gleam, core/types/message.gleam, core/types/client.gleam, core/types/response.gleam, core/types/hooks.gleam, core/types/tool_def.gleam, core/types/logging.gleam, core/types/guardrails.gleam

The types directory holds all shared data types used across core, services, and plugins. Each file defines a cohesive group of related types. These modules are pure data -- no functions or logic beyond simple constructors and helpers.

Type Modules

session.gleam

Session and storage row types:

• SessionRow -- full database row for a session (23 fields: id, session_key, source, persona, timestamps, model info, token counts, cost, parent lineage, etc.)
• SessionSummary -- lightweight summary: session_key, source, persona, updated_at, message_count
• FtsSearchResult -- full-text search hit: session_key, message_rowid, role, snippet, timestamp
• CronJobRow -- cron job database row: alias, schedule, job_type, command, prompt, enabled, recurring, last_run_at
• RichSessionSummary -- extended summary with model, title, token counts, cost, api_call_count, ended_at, end_reason

message.gleam

The core conversation data types:

• Message -- four variants: SystemMessage(content), UserMessage(content), AssistantMessage(content, reasoning_content, tool_calls), ToolResultMessage(tool_call_id, content, name)
• ToolCall -- id (API-assigned), name (function name), arguments (JSON string)

client.gleam

LLM client configuration and error types:

• Client -- api_key, base_url, model. Constructor: new_client(api_key), with_base_url(), with_model().
• ClientError -- 7 variants: AuthError, RateLimitError, ServerError, ContextOverflowError, PayloadTooLargeError, NetworkError, JsonParseError. Each carries status code and body where applicable.
• ChatFn -- function type: fn(Client, List(Message), List(ToolDefinition)) -> Result(ChatResponse, ClientError)
• client_error_to_string(err) -- human-readable error formatting

response.gleam

LLM response types:

• ChatResponse -- two variants: TextResponse(content, reasoning_content, finish_reason) and ToolCallsResponse(reasoning_content, tool_calls, finish_reason)

hooks.gleam

Hook state and escalation types:

• CompressionPlan -- Compress(head, middle, tail) or NoCompression(history)
• CooldownState -- CoolingDown(next_retry_at) or Ready
• Escalation -- None, Warn(reason), BlockTool(name, reason), HaltLoop(reason)
• LoopState -- tracks same_tool_failures, same_args_streak, total_failures, last_tool_name, last_tool_args, blocked_tools, halted, recent_results

tool_def.gleam

Tool schema for API registration:

• ToolDefinition -- name, description, parameters (JSON Schema as json.Json)

logging.gleam

Log category enum used by the Logger behaviour:

• LogCategory -- App, Core, Services, Plugins, Tools, Gateways, Hooks, Config

guardrails.gleam

Safety and approval types:

• GuardrailResult -- Allowed, Blocked(reason), NeedsApproval(reason, command)
• Risk -- High, Medium, Low
• ApprovalScope -- Once, Session, Always

Related Pages

• Behaviours -- Behaviour records that use these types
• Loop -- The orchestrator that consumes types like Message, ClientError, ChatResponse
• Tool -- Tool types that complement ToolDefinition