openclaw
Version:
Multi-channel AI gateway with extensible messaging integrations
12,095 lines • 517 kB
TypeScript
import { B as AgentBinding, C as Tool, H as TtsAutoMode, J as GroupToolPolicyConfig, O as OperatorScope, Q as QueueMode, b as TextContent, bt as ChatType, ft as MarkdownTableMode, g as Message, h as ImageContent, l as ModelProviderConfig, lt as GroupScope, n as OpenClawConfig, ot as DmPolicy, pt as ReplyToMode, r as PluginInstallRecord, st as DmScope, t as ConfigFileSnapshot, xt as FastMode, y as StreamFn$1, yt as SecretRef } from "./types.openclaw-BC-OHYtd.js";
import { Static, TSchema, Type } from "typebox";
import { z } from "zod";
import "json5";
import "@openclaw/ai/validation";
//#region src/runtime.d.ts
type RuntimeExitOptions = {
/** Route ANSI terminal-reset bytes away from structured stdout when needed. */
resetStream?: NodeJS.WriteStream;
};
type RuntimeEnv = {
log: (...args: unknown[]) => void;
error: (...args: unknown[]) => void;
/**
* Exit the process after restoring terminal state.
* Pass `resetStream` to route the ANSI reset sequence to a specific
* stream (e.g. stderr) when structured output on stdout must stay clean.
*/
exit: (code: number, opts?: RuntimeExitOptions) => void;
};
//#endregion
//#region packages/model-catalog-core/src/model-catalog-types.d.ts
/** Supported API protocols for model catalog entries. */
declare const MODEL_CATALOG_APIS: readonly ["openai-completions", "openai-responses", "openai-chatgpt-responses", "anthropic-messages", "google-generative-ai", "google-vertex", "github-copilot", "bedrock-converse-stream", "ollama", "azure-openai-responses"];
/** API protocol for a model catalog entry. */
type ModelCatalogApi = (typeof MODEL_CATALOG_APIS)[number];
/** Supported model thinking/reasoning wire formats. */
declare const MODEL_CATALOG_THINKING_FORMATS: readonly ["openai", "openrouter", "deepseek", "together", "qwen", "qwen-chat-template", "zai"];
/** Thinking/reasoning wire format for model compatibility. */
type ModelCatalogThinkingFormat = (typeof MODEL_CATALOG_THINKING_FORMATS)[number];
/** Compatibility flags and provider-specific routing metadata for one model. */
type ModelCatalogCompatConfig = {
supportsStore?: boolean;
supportsDeveloperRole?: boolean;
supportsReasoningEffort?: boolean;
/** Whether the model accepts the temperature parameter (GPT-5.6 family rejects it). */
supportsTemperature?: boolean;
/** Whether the provider honors top-level `instructions` on Responses requests. */
supportsInstructions?: boolean;
supportsUsageInStreaming?: boolean;
supportsStrictMode?: boolean;
supportsJsonSchemaResponseFormat?: boolean;
maxTokensField?: "max_completion_tokens" | "max_tokens";
requiresToolResultName?: boolean;
requiresAssistantAfterToolResult?: boolean;
requiresThinkingAsText?: boolean;
requiresReasoningContentOnAssistantMessages?: boolean;
openRouterRouting?: ModelCatalogOpenRouterRouting;
vercelGatewayRouting?: ModelCatalogVercelGatewayRouting;
zaiToolStream?: boolean;
cacheControlFormat?: "anthropic";
sendSessionAffinityHeaders?: boolean;
sendSessionIdHeader?: boolean;
supportsEagerToolInputStreaming?: boolean;
supportsLongCacheRetention?: boolean;
supportsPromptCacheKey?: boolean;
supportsTools?: boolean;
/** Code-mode tier consumed by `tools.codeMode.enabled: "auto"`; absent means "capable". */
codeMode?: "preferred" | "capable";
requiresStringContent?: boolean;
strictMessageKeys?: boolean;
toolSchemaProfile?: string;
unsupportedToolSchemaKeywords?: string[];
toolCallArgumentsEncoding?: string;
requiresOpenAiAnthropicToolPayload?: boolean;
thinkingFormat?: ModelCatalogThinkingFormat;
supportedReasoningEfforts?: string[];
reasoningEffortMap?: Record<string, string>;
visibleReasoningDetailTypes?: string[];
};
/** OpenRouter routing preferences copied into request metadata. */
type ModelCatalogOpenRouterRouting = {
allow_fallbacks?: boolean;
require_parameters?: boolean;
data_collection?: "deny" | "allow";
zdr?: boolean;
enforce_distillable_text?: boolean;
order?: string[];
only?: string[];
ignore?: string[];
quantizations?: string[];
sort?: string | {
by?: string;
partition?: string | null;
};
max_price?: {
prompt?: number | string;
completion?: number | string;
image?: number | string;
audio?: number | string;
request?: number | string;
};
preferred_min_throughput?: number | {
p50?: number;
p75?: number;
p90?: number;
p99?: number;
};
preferred_max_latency?: number | {
p50?: number;
p75?: number;
p90?: number;
p99?: number;
};
};
/** Vercel AI Gateway routing preferences. */
type ModelCatalogVercelGatewayRouting = {
only?: string[];
order?: string[];
};
/** Image input limits for a model. */
type ModelCatalogImageInputConfig = {
maxBytes?: number;
maxPixels?: number;
maxSidePx?: number;
preferredSidePx?: number;
tokenMode?: "tile" | "detail" | "provider";
};
/** Media input limits for a model. */
type ModelCatalogMediaInputConfig = {
image?: ModelCatalogImageInputConfig;
};
/** Supported input modality for a model. */
type ModelCatalogInput = "text" | "image" | "document";
/** Model-level thinking settings carried by provider catalog metadata. */
declare const MODEL_CATALOG_THINKING_LEVELS: readonly ["off", "minimal", "low", "medium", "high", "xhigh", "max"];
type ModelCatalogThinkingLevel = (typeof MODEL_CATALOG_THINKING_LEVELS)[number];
type ModelCatalogThinkingLevelMap = Partial<Record<ModelCatalogThinkingLevel, string | null>>;
/** Discovery lifecycle for a provider catalog. */
type ModelCatalogDiscovery = "static" | "refreshable" | "runtime";
/** Availability state for a model. */
type ModelCatalogStatus = "available" | "preview" | "deprecated" | "disabled";
/** Unified catalog kind across text and generated media models. */
type UnifiedModelCatalogKind = "text" | "voice" | "image_generation" | "video_generation" | "music_generation";
/** Source for unified model catalog entries. */
type UnifiedModelCatalogSource = "manifest" | "provider-index" | "static" | "live" | "cache" | "configured" | "runtime-refresh";
/** Unified model catalog entry for provider/model pickers. */
type UnifiedModelCatalogEntry<TCapabilities = unknown> = {
kind: UnifiedModelCatalogKind;
provider: string;
model: string;
label?: string;
source: UnifiedModelCatalogSource;
default?: boolean;
configured?: boolean;
capabilities?: TCapabilities;
modes?: readonly string[];
authEnvVars?: readonly string[];
docsPath?: string;
fetchedAt?: number;
expiresAt?: number;
warnings?: readonly string[];
};
/** Tiered token cost row. */
type ModelCatalogTieredCost = {
input: number;
output: number;
cacheRead: number;
cacheWrite: number;
range: [number, number] | [number];
};
/** Token cost metadata for one model. */
type ModelCatalogCost = {
input?: number;
output?: number;
cacheRead?: number;
cacheWrite?: number;
tieredPricing?: ModelCatalogTieredCost[];
};
/** Bounded provider-declared context-window choice for one model. */
type ModelCatalogContextWindowOption = {
id: string;
label: string;
contextWindow: number;
};
/** Provider manifest model entry. */
type ModelCatalogModel = {
id: string;
name?: string;
api?: ModelCatalogApi;
baseUrl?: string;
headers?: Record<string, string>;
input?: ModelCatalogInput[];
reasoning?: boolean;
contextWindow?: number;
contextWindows?: ModelCatalogContextWindowOption[];
contextWindowDefault?: string;
contextTokens?: number;
maxTokens?: number;
thinkingLevelMap?: ModelCatalogThinkingLevelMap;
cost?: ModelCatalogCost;
compat?: ModelCatalogCompatConfig;
/**
* Provider/model ref of the same upstream model in another bundled catalog,
* for vendors reachable through several provider ids under different model
* ids. Authoring metadata only: normalization drops it, and the shared-model
* contract test uses it to keep `compat` capability tiers from drifting apart.
*/
upstreamModel?: string;
mediaInput?: ModelCatalogMediaInputConfig;
status?: ModelCatalogStatus;
statusReason?: string;
replaces?: string[];
replacedBy?: string;
tags?: string[];
};
/** Provider manifest catalog entry. */
type ModelCatalogProvider = {
baseUrl?: string;
api?: ModelCatalogApi;
headers?: Record<string, string>;
/** Provider-recommended primary model id. */
defaultModel?: string;
/** Provider-recommended small model id for short internal utility tasks. */
defaultUtilityModel?: string;
models: ModelCatalogModel[];
};
/** Provider alias entry. */
type ModelCatalogAlias = {
provider: string;
api?: ModelCatalogApi;
baseUrl?: string;
};
/** Suppression rule for hiding a provider/model under matching config. */
type ModelCatalogSuppression = {
provider: string;
model: string;
reason?: string;
when?: {
baseUrlHosts?: string[];
providerConfigApiIn?: string[];
};
};
/** Raw model catalog manifest shape. */
type ModelCatalog = {
/** Publication-time opt-in: owned OpenClaw provider id -> models.dev provider id. */
modelsDev?: Record<string, string>;
providers?: Record<string, ModelCatalogProvider>;
aliases?: Record<string, ModelCatalogAlias>;
suppressions?: ModelCatalogSuppression[];
discovery?: Record<string, ModelCatalogDiscovery>;
runtimeAugment?: boolean;
};
//#endregion
//#region packages/model-catalog-core/src/model-catalog-pricing.d.ts
declare const MODEL_PRICING_SOURCES: readonly [{
readonly id: "openCode";
readonly label: "OpenCode";
readonly url: "https://models.opencode.ai/api.json";
readonly authoritative: true;
}, {
readonly id: "venice";
readonly label: "Venice";
readonly url: "https://api.venice.ai/api/v1/models";
readonly authoritative: true;
}, {
readonly id: "chutes";
readonly label: "Chutes";
readonly url: "https://llm.chutes.ai/v1/models";
readonly authoritative: true;
}, {
readonly id: "cerebras";
readonly label: "Cerebras";
readonly url: "https://api.cerebras.ai/public/v1/models";
readonly authoritative: true;
}, {
readonly id: "deepinfra";
readonly label: "DeepInfra";
readonly url: "https://api.deepinfra.com/models/list";
readonly authoritative: true;
}, {
readonly id: "openRouter";
readonly label: "OpenRouter";
readonly url: "https://openrouter.ai/api/v1/models";
readonly authoritative: false;
}, {
readonly id: "liteLLM";
readonly label: "LiteLLM";
readonly url: "https://raw.githubusercontent.com/BerriAI/litellm/main/model_prices_and_context_window.json";
readonly authoritative: false;
}];
type ModelPricingSourceId = (typeof MODEL_PRICING_SOURCES)[number]["id"];
type ModelPricingSource = {
provider?: string;
passthroughProviderModel?: boolean;
modelIdTransforms?: "version-dots"[];
};
type ModelPricingProvider = {
external?: boolean;
} & Partial<Record<ModelPricingSourceId, ModelPricingSource | false>>;
//#endregion
//#region src/shared/config-ui-hints-types.d.ts
type ConfigUiPresentation = "phone-number";
//#endregion
//#region src/shared/json-schema.types.d.ts
/** TypeBox schema value widened for generic JSON-schema object transforms. */
type JsonSchemaObject = TSchema & Record<string, unknown>;
//#endregion
//#region src/channels/plugins/types.config.d.ts
/** Optional UI metadata for a JSON Schema property. */
type ChannelConfigUiHint = {
label?: string;
help?: string;
tags?: string[];
advanced?: boolean;
sensitive?: boolean;
placeholder?: string;
presentation?: ConfigUiPresentation;
itemTemplate?: unknown;
};
/** Normalized validation issue emitted by a channel runtime parser. */
type ChannelConfigRuntimeIssue = {
path?: Array<string | number>;
message?: string;
code?: string;
} & Record<string, unknown>;
/** Minimal safeParse result shape accepted from channel-owned validators. */
type ChannelConfigRuntimeParseResult = {
success: true;
data: unknown;
} | {
success: false;
issues: ChannelConfigRuntimeIssue[];
};
/** Runtime validator contract paired with the JSON Schema config surface. */
type ChannelConfigRuntimeSchema = {
safeParse: (value: unknown) => ChannelConfigRuntimeParseResult;
};
/** Complete channel config schema description exposed to host tooling. */
type ChannelConfigSchema = {
schema: JsonSchemaObject;
uiHints?: Record<string, ChannelConfigUiHint>;
runtime?: ChannelConfigRuntimeSchema;
};
//#endregion
//#region src/plugins/doctor-session-route-state-owner-types.d.ts
type DoctorSessionRouteStateOwner = {
id: string;
label: string;
providerIds?: readonly string[];
runtimeIds?: readonly string[];
cliSessionKeys?: readonly string[];
authProfilePrefixes?: readonly string[];
};
//#endregion
//#region src/plugins/manifest-command-aliases.d.ts
type PluginManifestCommandAliasKind = "runtime-slash";
/** One command alias declared by a plugin manifest. */
type PluginManifestCommandAlias = {
/** Command-like name users may put in plugin config by mistake. */
name: string;
/** Command family, used for targeted diagnostics. */
kind?: PluginManifestCommandAliasKind;
/** Optional root CLI command that handles related CLI operations. */
cliCommand?: string;
};
//#endregion
//#region src/plugins/plugin-kind.types.d.ts
/** Plugin kind labels for non-provider plugin capability groups. */
type PluginKind = "memory" | "context-engine";
//#endregion
//#region src/plugins/manifest-types.d.ts
/** UI hint metadata for plugin config schema fields. */
type PluginConfigUiHint = {
label?: string;
help?: string;
tags?: string[];
advanced?: boolean;
sensitive?: boolean;
placeholder?: string;
presentation?: ConfigUiPresentation;
};
/** Top-level plugin manifest format. */
type PluginFormat = "openclaw" | "bundle";
/** Supported external bundle manifest formats. */
type PluginBundleFormat = "agent" | "codex" | "claude" | "cursor";
/**
* Closed classification codes for plugin diagnostics. Health surfaces branch
* on these instead of matching freeform diagnostic message text.
*/
type PluginDiagnosticCode = "backup-resource-declaration-invalid" | "channel-setup-failure" | "dashboard-declaration-invalid" | "plugin-verification" | "workspace-scope-omitted";
/** Diagnostic emitted while discovering or validating plugins. */
type PluginDiagnostic = {
level: "warn" | "error";
message: string;
pluginId?: string;
source?: string;
code?: PluginDiagnosticCode;
};
type PluginManifestChannelConfig = {
schema: JsonSchemaObject;
uiHints?: Record<string, PluginConfigUiHint>;
runtime?: ChannelConfigRuntimeSchema;
label?: string;
description?: string;
preferOver?: string[];
commands?: PluginManifestChannelCommandDefaults;
};
type PluginManifestChannelCommandDefaults = {
nativeCommandsAutoEnabled?: boolean;
nativeSkillsAutoEnabled?: boolean;
};
type PluginManifestModelSupport = {
/**
* Cheap manifest-owned model-id prefixes for transparent provider activation
* from shorthand model refs such as `gpt-5.4` or `claude-sonnet-4.6`.
*/
modelPrefixes?: string[];
/**
* Regex sources matched against the raw model id after profile suffixes are
* stripped. Use this when simple prefixes are not expressive enough.
*/
modelPatterns?: string[];
};
type PluginManifestModelCatalog = ModelCatalog;
type PluginManifestModelPricing = {
providers?: Record<string, ModelPricingProvider>;
};
type PluginManifestModelIdPrefixRule = {
modelPrefix: string;
prefix: string;
};
type PluginManifestModelIdNormalizationProvider = {
aliases?: Record<string, string>;
stripPrefixes?: string[];
prefixWhenBare?: string;
prefixWhenBareAfterAliasStartsWith?: PluginManifestModelIdPrefixRule[];
};
type PluginManifestModelIdNormalization = {
providers?: Record<string, PluginManifestModelIdNormalizationProvider>;
};
type PluginManifestProviderEndpoint = {
/**
* Core endpoint class this plugin-owned endpoint should map to. Core must
* already know the class; manifests own host/baseUrl matching metadata.
*/
endpointClass: string;
/** Hostnames that should resolve to this endpoint class. */
hosts?: string[];
/** Host suffixes that should resolve to this endpoint class. */
hostSuffixes?: string[];
/** Exact normalized base URLs that should resolve to this endpoint class. */
baseUrls?: string[];
/** Static Google Vertex region metadata for exact global hosts. */
googleVertexRegion?: string;
/** Host suffix whose prefix should be exposed as the Google Vertex region. */
googleVertexRegionHostSuffix?: string;
};
type PluginManifestProviderRequestProvider = {
family?: string;
compatibilityFamily?: "moonshot";
openAICompletions?: {
supportsStreamingUsage?: boolean;
};
};
type PluginManifestProviderRequest = {
providers?: Record<string, PluginManifestProviderRequestProvider>;
};
type PluginManifestSecretProviderIntegration = {
providerAlias?: string;
displayName?: string;
description?: string;
source: "exec";
command: "${node}";
args?: string[];
timeoutMs?: number;
noOutputTimeoutMs?: number;
maxOutputBytes?: number;
jsonOnly?: boolean;
env?: Record<string, string>;
passEnv?: string[];
};
type PluginManifestActivationCapability = "provider" | "channel" | "tool" | "hook";
type PluginManifestActivation = {
/**
* Explicit Gateway startup activation. Set true when the plugin must be
* imported during Gateway startup; set false when narrower activation
* triggers should load it on demand.
*/
onStartup?: boolean;
/**
* Provider ids that should include this plugin in activation/load plans.
* This is planner metadata only; runtime behavior still comes from register().
*/
onProviders?: string[];
/** Agent harness runtime ids that should include this plugin in activation/load plans. */
onAgentHarnesses?: string[];
/** Command ids that should include this plugin in activation/load plans. */
onCommands?: string[];
/** Channel ids that should include this plugin in activation/load plans. */
onChannels?: string[];
/** Route kinds that should include this plugin in activation/load plans. */
onRoutes?: string[];
/** Root-relative config paths that should include this plugin in startup/load plans. */
onConfigPaths?: string[];
/** Broad capability hints for activation/load plans. Prefer narrower ownership metadata. */
onCapabilities?: PluginManifestActivationCapability[];
};
/** Root CLI command metadata available before plugin code is imported. */
type PluginManifestCliCommand = {
name: string;
description: string;
hasSubcommands: boolean;
};
type PluginManifestDefaultPlatform = NodeJS.Platform;
type PluginManifestSetupProvider = {
/** Provider id surfaced during setup/onboarding. */
id: string;
/** Setup/auth methods that this provider supports. */
authMethods?: string[];
/** Environment variables that can satisfy setup without runtime loading. */
envVars?: string[];
/**
* Cheap local evidence that a provider can authenticate without loading
* runtime code. Evidence checks must not read secrets, shell out, or call
* provider APIs.
*/
authEvidence?: PluginManifestSetupProviderAuthEvidence[];
};
type PluginManifestSetupProviderAuthEvidence = {
/** Generic local file evidence gated by required environment metadata. */
type: "local-file-with-env";
/** Optional env var containing an explicit credential file path. */
fileEnvVar?: string;
/** Optional fallback credential file paths. Supports `${HOME}` and `${APPDATA}`. */
fallbackPaths?: string[];
/** At least one of these env vars must be non-empty when provided. */
requiresAnyEnv?: string[];
/** Every env var listed here must be non-empty when provided. */
requiresAllEnv?: string[];
/** Non-secret marker returned when this evidence is present. */
credentialMarker: string;
/** Human-readable auth source label. */
source?: string;
};
type PluginManifestSetup = {
/** Cheap provider setup metadata exposed before runtime loads. */
providers?: PluginManifestSetupProvider[];
/** Setup-time backend ids available without full runtime activation. */
cliBackends?: string[];
/** Config migration ids owned by this plugin's setup surface. */
configMigrations?: string[];
/**
* Whether setup still needs plugin runtime execution after descriptor lookup.
* Explicit false disables setup runtime; omission preserves the legacy fallback.
*/
requiresRuntime?: boolean;
};
type PluginManifestDoctorContract = {
configRepair?: boolean;
resolveSessionStoreAgentIds?: boolean;
/**
* @deprecated Declare static ownership in top-level sessionRouteStateOwners instead.
* Removal plan: remove the module fallback in OpenClaw 2027.1 after external plugins migrate.
*/
sessionRouteStateOwners?: boolean;
stateMigrations?: boolean;
};
type PluginManifestQaRunner = {
/** Subcommand mounted beneath `openclaw qa`, for example `matrix`. */
commandName: string;
/** Optional user-facing help text for fallback host stubs. */
description?: string;
};
type PluginManifestDashboardDataBinding = {
/** Plugin-local id. Widget grants receive the plugin-id prefix. */
id: string;
/** Read-scoped Gateway method registered by this plugin. */
method: string;
description: string;
};
type PluginManifestDashboardActionVerb = {
/** Plugin-local id. Widget grants receive the plugin-id prefix. */
id: string;
/** Write-scoped Gateway method registered by this plugin. */
method: string;
description: string;
/** Optional JSON Schema for the action params object. */
paramShape?: JsonSchemaObject;
};
type PluginManifestDashboard = {
dataBindings?: PluginManifestDashboardDataBinding[];
actionVerbs?: PluginManifestDashboardActionVerb[];
};
/** Built browser assets activated by the trusted native Control UI host. */
type PluginManifestControlUi = {
/** JavaScript entry in a dedicated dist subdirectory, relative to the plugin root. */
entry: string;
/** Stylesheets in the same asset directory, loaded before activation. */
styles?: string[];
};
type PluginManifestMcpServer = Record<string, unknown>;
type PluginManifestConfigLiteral = string | number | boolean | null;
type PluginManifestDangerousConfigFlag = {
/**
* Dot-separated config path relative to `plugins.entries.<id>.config`.
* Supports `*` wildcards for map/array segments.
*/
path: string;
/** Exact literal that marks this config value as dangerous. */
equals: PluginManifestConfigLiteral;
};
type PluginManifestSecretInputPath = {
/**
* Dot-separated config path relative to `plugins.entries.<id>.config`.
* Supports `*` wildcards for map/array segments.
*/
path: string;
/** Expected resolved type for SecretRef materialization. */
expected?: "string";
/** Runtime owner kind used to isolate this surface when resolution fails. */
ownerKind?: "capability" | "route";
};
type PluginManifestSecretInputContracts = {
/**
* Override bundled-plugin default enablement when deciding whether this
* SecretRef surface is active. Use this when the plugin is bundled but the
* surface should stay inactive until explicitly enabled in config.
*/
bundledDefaultEnabled?: boolean;
paths: PluginManifestSecretInputPath[];
};
type PluginManifestConfigContracts = {
/**
* Root-relative config paths that indicate this plugin's setup-time
* compatibility migrations might apply. Use this to keep generic runtime
* config reads from loading every plugin setup surface when the config does
* not reference the plugin at all.
*/
compatibilityMigrationPaths?: string[];
/**
* Root-relative compatibility paths that this plugin can service during
* runtime before plugin code fully activates. Use this for legacy surfaces
* that should cheaply narrow bundled candidate sets without importing every
* compatible plugin runtime.
*/
compatibilityRuntimePaths?: string[];
dangerousFlags?: PluginManifestDangerousConfigFlag[];
secretInputs?: PluginManifestSecretInputContracts;
};
type PluginManifestCatalog = {
featured?: boolean;
order?: number;
};
/** Declarative backup ownership rooted at host-managed state or each configured agent. */
type PluginManifestBackupResource = {
disposition: "include" | "regenerable";
scope: "state" | "agent";
relativePath: string;
};
type PluginManifest = {
id: string;
configSchema: JsonSchemaObject;
/** Static backup inclusion/exclusion declarations; resolved without loading plugin runtime. */
backupResources?: PluginManifestBackupResource[];
/** Plugin ids that must also be installed for this plugin to have effect. */
requiresPlugins?: string[];
enabledByDefault?: boolean;
enabledByDefaultOnPlatforms?: PluginManifestDefaultPlatform[];
/** Legacy plugin ids that should normalize to this plugin id. */
legacyPluginIds?: string[];
/** Provider ids that should auto-enable this plugin when referenced in auth/config/models. */
autoEnableWhenConfiguredProviders?: string[];
kind?: PluginKind | PluginKind[];
channels?: string[];
providers?: string[];
/**
* Optional lightweight module that exports provider plugin metadata for
* auth/catalog discovery. It should not import the full plugin runtime.
*/
providerCatalogEntry?: string;
/** Lightweight capability descriptor collections; omitted families retain register() discovery. */
capabilityCatalogEntry?: string;
/**
* Cheap model-family ownership metadata used before plugin runtime loads.
* Use this for shorthand model refs that omit an explicit provider prefix.
*/
modelSupport?: PluginManifestModelSupport;
/**
* Declarative model catalog metadata used by future read-only listing,
* onboarding, and model picker surfaces before provider runtime loads.
*/
modelCatalog?: PluginManifestModelCatalog;
/** Manifest-owned external pricing lookup policy for provider refs. */
modelPricing?: PluginManifestModelPricing;
/** Manifest-owned model-id normalization used before provider runtime loads. */
modelIdNormalization?: PluginManifestModelIdNormalization;
/** Cheap provider endpoint metadata used before provider runtime loads. */
providerEndpoints?: PluginManifestProviderEndpoint[];
/** Cheap provider request metadata used before provider runtime loads. */
providerRequest?: PluginManifestProviderRequest;
/** Declarative SecretRef provider presets owned by this plugin. */
secretProviderIntegrations?: Record<string, PluginManifestSecretProviderIntegration>;
/** Cheap startup activation lookup for plugin-owned CLI inference backends. */
cliBackends?: string[];
/**
* Provider or CLI backend refs whose plugin-owned synthetic auth hook should
* be probed during cold model discovery before the runtime registry exists.
*/
syntheticAuthRefs?: string[];
/**
* Bundled-plugin-owned placeholder API key values that represent non-secret
* local, OAuth, or ambient credential state.
*/
nonSecretAuthMarkers?: string[];
/**
* Plugin-owned command aliases that should resolve to this plugin during
* config diagnostics before runtime loads.
*/
commandAliases?: PluginManifestCommandAlias[];
/** Root commands advertised by help and activation planning before runtime loads. */
cliCommands?: PluginManifestCliCommand[];
/** Usage/billing credentials excluded from inference auth but included in secret scrubbing. */
providerUsageAuthEnvVars?: Record<string, string[]>;
/** Provider ids that should reuse another provider id for auth lookup. */
providerAuthAliases?: Record<string, string>;
/**
* Cheap onboarding/auth-choice metadata used by config validation, CLI help,
* and non-runtime auth-choice routing before provider runtime loads.
*/
providerAuthChoices?: PluginManifestProviderAuthChoice[];
/** Cheap activation planner metadata exposed before plugin runtime loads. */
activation?: PluginManifestActivation;
/** Cheap setup/onboarding metadata exposed before plugin runtime loads. */
setup?: PluginManifestSetup;
/** Doctor contract surfaces available without loading the plugin artifact. */
doctorContract?: PluginManifestDoctorContract;
/** Whether the plugin public API registers structured health checks. */
doctorHealthChecks?: boolean;
/** Static ownership metadata for doctor session-route state repairs. */
sessionRouteStateOwners?: DoctorSessionRouteStateOwner[];
/** Cheap QA runner metadata exposed before plugin runtime loads. */
qaRunners?: PluginManifestQaRunner[];
/** Widget data and action capabilities validated against runtime registrations. */
dashboard?: PluginManifestDashboard;
controlUi?: PluginManifestControlUi;
/** Static MCP servers contributed while this plugin is enabled. */
mcpServers?: Record<string, PluginManifestMcpServer>;
skills?: string[];
name?: string;
description?: string;
/** Optional presentation hints for plugin catalog surfaces. */
catalog?: PluginManifestCatalog;
version?: string;
uiHints?: Record<string, PluginConfigUiHint>;
/**
* Static capability ownership snapshot used for manifest-driven discovery,
* compat wiring, and contract coverage without importing plugin runtime.
*/
contracts?: PluginManifestContracts;
/** Cheap media-understanding provider defaults without importing plugin runtime. */
mediaUnderstandingProviderMetadata?: Record<string, PluginManifestMediaUnderstandingProviderMetadata>;
/** Cheap image-generation provider auth metadata without importing plugin runtime. */
imageGenerationProviderMetadata?: Record<string, PluginManifestCapabilityProviderMetadata>;
/** Cheap video-generation provider auth metadata without importing plugin runtime. */
videoGenerationProviderMetadata?: Record<string, PluginManifestCapabilityProviderMetadata>;
/** Cheap music-generation provider auth metadata without importing plugin runtime. */
musicGenerationProviderMetadata?: Record<string, PluginManifestCapabilityProviderMetadata>;
/** Cheap plugin-tool availability metadata without importing plugin runtime. */
toolMetadata?: Record<string, PluginManifestToolMetadata>;
/** Manifest-owned config behavior consumed by generic core helpers. */
configContracts?: PluginManifestConfigContracts;
channelConfigs?: Record<string, PluginManifestChannelConfig>;
};
type PluginManifestContracts = {
embeddedExtensionFactories?: string[];
agentToolResultMiddleware?: string[];
trustedToolPolicies?: string[];
/**
* Provider ids whose external auth profile hook can contribute runtime-only
* credentials. Declaring this lets auth-store overlays load only the owning
* plugin instead of every provider plugin.
*/
externalAuthProviders?: string[];
embeddingProviders?: string[];
speechProviders?: string[];
realtimeTranscriptionProviders?: string[];
realtimeVoiceProviders?: string[];
mediaUnderstandingProviders?: string[];
transcriptSourceProviders?: string[];
documentExtractors?: string[];
imageGenerationProviders?: string[];
videoGenerationProviders?: string[];
musicGenerationProviders?: string[];
webContentExtractors?: string[];
webFetchProviders?: string[];
webSearchProviders?: string[];
workerProviders?: string[];
/** Provider ids whose plugin owns usage auth and snapshot hooks. */
usageProviders?: string[];
migrationProviders?: string[];
gatewayMethodDispatch?: string[];
tools?: string[];
};
type PluginManifestMediaUnderstandingCapability = "image" | "audio" | "video";
type PluginManifestMediaUnderstandingProviderMetadata = {
capabilities?: PluginManifestMediaUnderstandingCapability[];
defaultModels?: Partial<Record<PluginManifestMediaUnderstandingCapability, string>>;
autoPriority?: Partial<Record<PluginManifestMediaUnderstandingCapability, number>>;
nativeDocumentInputs?: Array<"pdf">;
documentModels?: Partial<Record<"pdf", {
textExtraction?: string;
image?: string | false;
}>>;
};
type PluginManifestProviderBaseUrlGuard = {
provider: string;
defaultBaseUrl?: string;
allowedBaseUrls: string[];
};
type PluginManifestCapabilityProviderAuthSignal = {
provider: string;
providerBaseUrl?: PluginManifestProviderBaseUrlGuard;
};
type PluginManifestCapabilityProviderModeConfigSignal = {
path?: string;
default?: string;
allowed?: string[];
disallowed?: string[];
};
type PluginManifestCapabilityProviderConfigSignal = {
rootPath: string;
overlayPath?: string;
overlayMapPath?: string;
required?: string[];
requiredAny?: string[];
mode?: PluginManifestCapabilityProviderModeConfigSignal;
};
type PluginManifestCapabilityProviderMetadata = {
aliases?: string[];
authProviders?: string[];
authSignals?: PluginManifestCapabilityProviderAuthSignal[];
configSignals?: PluginManifestCapabilityProviderConfigSignal[];
referenceAudioInputs?: boolean;
};
type PluginManifestToolMetadata = PluginManifestCapabilityProviderMetadata & {
optional?: boolean;
/** Built-in tool profiles that expose this plugin tool by default. */
profiles?: PluginManifestToolProfile[];
/** Tool execution is safe to repeat after an incomplete model turn. */
replaySafe?: boolean;
/** Tool execution can change durable state and failed attempts must remain visible. */
sideEffecting?: boolean;
};
type PluginManifestToolProfile = "minimal" | "coding" | "messaging" | "full";
type PluginManifestProviderAuthChoice = {
/** Provider id owned by this manifest entry. */
provider: string;
/** Provider auth method id that this choice should dispatch to. */
method: string;
/** Stable auth-choice id used by onboarding and other CLI auth flows. */
choiceId: string;
/** Optional user-facing choice label/hint for grouped onboarding UI. */
choiceLabel?: string;
choiceHint?: string;
/** Optional HTTPS artwork URL for native and web onboarding surfaces. */
icon?: string;
/** Optional HTTPS product or installation URL for onboarding surfaces. */
website?: string;
/** Lower values sort earlier in interactive assistant pickers. */
assistantPriority?: number;
/** Keep the choice out of interactive assistant pickers while preserving manual CLI support. */
assistantVisibility?: "visible" | "manual-only";
/** Legacy choice ids that should point users at this replacement choice. */
deprecatedChoiceIds?: string[];
/** Optional grouping metadata for auth-choice pickers. */
groupId?: string;
groupLabel?: string;
groupHint?: string;
/**
* Surface this group in the featured tier of the interactive onboarding
* picker. Featured groups appear before the "More…" entry.
*/
onboardingFeatured?: boolean;
/** Optional CLI flag metadata for one-flag auth flows such as API keys. */
optionKey?: string;
cliFlag?: string;
cliOption?: string;
cliDescription?: string;
/** One pasted secret plus provider defaults is sufficient for app-guided setup. */
appGuidedSecret?: boolean;
/** Interactive method stages one inline credential without host login imports or persistence. */
personalAccount?: boolean;
/** Short provider-owned command label for starting app-guided setup. */
appGuidedActionLabel?: string;
/** Provider-owned interactive login that native setup clients can render generically. */
appGuidedAuth?: "oauth" | "device-code";
/**
* Interactive onboarding surfaces where this auth choice should appear.
* Defaults to `["text-inference"]` when omitted.
*/
onboardingScopes?: PluginManifestOnboardingScope[];
/** Provider runtime can discover and prepare an already-installed local model. */
appGuidedDiscovery?: boolean;
};
type PluginManifestOnboardingScope = "text-inference" | "image-generation" | "music-generation";
//#endregion
//#region src/channels/plugins/setup-input.d.ts
type ChannelSetupEnvelope = {
name?: string;
token?: string;
tokenFile?: string;
useEnv?: boolean;
defaultTo?: string;
allowFrom?: string[];
};
/**
* Compatibility fields with known published readers in the 2026-07-22 registry sweep.
* Each field is deleted as soon as no published plugin reads it; no version boundary is needed.
*/
type DeprecatedChannelSetupFields = {
/** @deprecated Declare this field in the owning plugin's setup input type: https://docs.openclaw.ai/plugins/sdk-setup#channel-owned-setup-input-fields. Removed once no published plugin reads it. */
privateKey?: string;
/** @deprecated Declare this field in the owning plugin's setup input type: https://docs.openclaw.ai/plugins/sdk-setup#channel-owned-setup-input-fields. Removed once no published plugin reads it. */
secret?: string;
/** @deprecated Declare this field in the owning plugin's setup input type: https://docs.openclaw.ai/plugins/sdk-setup#channel-owned-setup-input-fields. Removed once no published plugin reads it. */
botToken?: string;
/** @deprecated Declare this field in the owning plugin's setup input type: https://docs.openclaw.ai/plugins/sdk-setup#channel-owned-setup-input-fields. Removed once no published plugin reads it. */
appToken?: string;
/** @deprecated Declare this field in the owning plugin's setup input type: https://docs.openclaw.ai/plugins/sdk-setup#channel-owned-setup-input-fields. Removed once no published plugin reads it. */
signingSecret?: string;
/** @deprecated Declare this field in the owning plugin's setup input type: https://docs.openclaw.ai/plugins/sdk-setup#channel-owned-setup-input-fields. Removed once no published plugin reads it. */
mode?: "socket" | "http" | "relay";
/** @deprecated Declare this field in the owning plugin's setup input type: https://docs.openclaw.ai/plugins/sdk-setup#channel-owned-setup-input-fields. Removed once no published plugin reads it. */
cliPath?: string;
/** @deprecated Declare this field in the owning plugin's setup input type: https://docs.openclaw.ai/plugins/sdk-setup#channel-owned-setup-input-fields. Removed once no published plugin reads it. */
authDir?: string;
/** @deprecated Declare this field in the owning plugin's setup input type: https://docs.openclaw.ai/plugins/sdk-setup#channel-owned-setup-input-fields. Removed once no published plugin reads it. */
httpUrl?: string;
/** @deprecated Declare this field in the owning plugin's setup input type: https://docs.openclaw.ai/plugins/sdk-setup#channel-owned-setup-input-fields. Removed once no published plugin reads it. */
httpPort?: string;
/** @deprecated Declare this field in the owning plugin's setup input type: https://docs.openclaw.ai/plugins/sdk-setup#channel-owned-setup-input-fields. Removed once no published plugin reads it. */
webhookPath?: string;
/** @deprecated Declare this field in the owning plugin's setup input type: https://docs.openclaw.ai/plugins/sdk-setup#channel-owned-setup-input-fields. Removed once no published plugin reads it. */
webhookUrl?: string;
/** @deprecated Declare this field in the owning plugin's setup input type: https://docs.openclaw.ai/plugins/sdk-setup#channel-owned-setup-input-fields. Removed once no published plugin reads it. */
userId?: string;
/** @deprecated Declare this field in the owning plugin's setup input type: https://docs.openclaw.ai/plugins/sdk-setup#channel-owned-setup-input-fields. Removed once no published plugin reads it. */
accessToken?: string;
/** @deprecated Declare this field in the owning plugin's setup input type: https://docs.openclaw.ai/plugins/sdk-setup#channel-owned-setup-input-fields. Removed once no published plugin reads it. */
password?: string;
/** @deprecated Declare this field in the owning plugin's setup input type: https://docs.openclaw.ai/plugins/sdk-setup#channel-owned-setup-input-fields. Removed once no published plugin reads it. */
deviceName?: string;
/** @deprecated Declare this field in the owning plugin's setup input type: https://docs.openclaw.ai/plugins/sdk-setup#channel-owned-setup-input-fields. Removed once no published plugin reads it. */
url?: string;
/** @deprecated Declare this field in the owning plugin's setup input type: https://docs.openclaw.ai/plugins/sdk-setup#channel-owned-setup-input-fields. Removed once no published plugin reads it. */
baseUrl?: string;
/** @deprecated Declare this field in the owning plugin's setup input type: https://docs.openclaw.ai/plugins/sdk-setup#channel-owned-setup-input-fields. Removed once no published plugin reads it. */
code?: string;
/** @deprecated Declare this field in the owning plugin's setup input type: https://docs.openclaw.ai/plugins/sdk-setup#channel-owned-setup-input-fields. Removed once no published plugin reads it. */
groupChannels?: string[];
/** @deprecated Declare this field in the owning plugin's setup input type: https://docs.openclaw.ai/plugins/sdk-setup#channel-owned-setup-input-fields. Removed once no published plugin reads it. */
dmAllowlist?: string[];
/** @deprecated Declare this field in the owning plugin's setup input type: https://docs.openclaw.ai/plugins/sdk-setup#channel-owned-setup-input-fields. Removed once no published plugin reads it. */
autoDiscoverChannels?: boolean;
};
/** Generic setup envelope used by CLI, onboarding, and channel-owned setup adapters. */
type ChannelSetupInput = ChannelSetupEnvelope & DeprecatedChannelSetupFields;
//#endregion
//#region src/channels/plugins/setup-adapter.types.d.ts
type ChannelSetupAdapter<Input extends {
name?: string;
} = ChannelSetupInput> = {
/** Keep root config as an independent identity when the host adds named accounts. */
configPromotion?: "preserve-root";
resolveAccountId?: (params: {
cfg: OpenClawConfig;
accountId?: string;
input?: Input;
}) => string;
prepareAccountConfigInput?: (params: {
cfg: OpenClawConfig;
accountId: string;
input: Input;
runtime: RuntimeEnv;
}) => Promise<Input> | Input;
resolveBindingAccountId?: (params: {
cfg: OpenClawConfig;
agentId: string;
accountId?: string;
}) => string | undefined;
applyAccountName?: (params: {
cfg: OpenClawConfig;
accountId: string;
name?: string;
}) => OpenClawConfig;
applyAccountConfig: (params: {
cfg: OpenClawConfig;
accountId: string;
input: Input;
}) => OpenClawConfig;
afterAccountConfigWritten?: (params: {
previousCfg: OpenClawConfig;
cfg: OpenClawConfig;
accountId: string;
input: Input;
runtime: RuntimeEnv;
}) => Promise<void> | void;
validateInput?: (params: {
cfg: OpenClawConfig;
accountId: string;
input: Input;
}) => string | null;
singleAccountKeysToMove?: readonly string[];
namedAccountPromotionKeys?: readonly string[];
resolveSingleAccountPromotionTarget?: (params: {
channel: Record<string, unknown>;
}) => string | undefined;
};
//#endregion
//#region src/channels/plugins/setup-contract.d.ts
type ChannelSetupCliOption = {
flags: string;
negatedFlags?: string;
description: string;
defaultValue?: boolean | string;
};
type ChannelSetupStringField = {
kind: "string";
sensitive?: boolean;
cli: ChannelSetupCliOption;
};
type ChannelSetupBooleanField = {
kind: "boolean";
cli: ChannelSetupCliOption;
envVars?: readonly string[];
envVarMode?: "all" | "any";
};
type ChannelSetupIntegerField = {
kind: "integer";
cli: ChannelSetupCliOption;
};
type ChannelSetupStringListField = {
kind: "string-list";
sensitive?: boolean;
cli: ChannelSetupCliOption;
};
type ChannelSetupChoiceField<Choices extends readonly string[] = readonly string[]> = {
kind: "choice";
choices: Choices;
cli: ChannelSetupCliOption;
};
type ChannelSetupField = ChannelSetupStringField | ChannelSetupBooleanField | ChannelSetupIntegerField | ChannelSetupStringListField | ChannelSetupChoiceField;
type ChannelSetupFieldMetadataFor<Field extends ChannelSetupField> = Field extends ChannelSetupField ? Field & {
key: string;
} : never;
type ChannelSetupFieldMetadata = ChannelSetupFieldMetadataFor<ChannelSetupField>;
type ChannelSetupMetadata = {
fields: readonly ChannelSetupFieldMetadata[];
};
type ChannelSetupParseResult = {
ok: true;
value: unknown;
} | {
ok: false;
error: string;
};
type ChannelOwnedSetupAdapterShape<Input extends {
name?: string;
}> = ChannelSetupAdapter<Input>;
type ChannelOwnedSetupContract = {
kind: "channel-owned";
configPromotion?: ChannelSetupAdapter["configPromotion"];
metadata: ChannelSetupMetadata;
parseInput: (input: unknown) => ChannelSetupParseResult;
resolveAccountId?: (params: {
cfg: OpenClawConfig;
accountId?: string;
input?: unknown;
}) => string;
prepareAccountConfigInput?: (params: {
cfg: OpenClawConfig;
accountId: string;
input: unknown;
runtime: RuntimeEnv;
}) => Promise<object> | object;
resolveBindingAccountId?: ChannelOwnedSetupAdapterShape<{
name?: string;
}>["resolveBindingAccountId"];
applyAccountName?: ChannelOwnedSetupAdapterShape<{
name?: string;
}>["applyAccountName"];
applyAccountConfig: (params: {
cfg: OpenClawConfig;
accountId: string;
input: unknown;
}) => OpenClawConfig;
afterAccountConfigWritten?: (params: {
previousCfg: OpenClawConfig;
cfg: OpenClawConfig;
accountId: string;
input: unknown;
runtime: RuntimeEnv;
}) => Promise<void> | void;
validateInput?: (params: {
cfg: OpenClawConfig;
accountId: string;
input: unknown;
}) => string | null;
singleAccountKeysToMove?: readonly string[];
namedAccountPromotionKeys?: readonly string[];
resolveSingleAccountPromotionTarget?: ChannelOwnedSetupAdapterShape<{
name?: string;
}>["resolveSingleAccountPromotionTarget"];
};
//#endregion
//#region src/compat/legacy-names.d.ts
declare const MANIFEST_KEY: "openclaw";
//#endregion
//#region src/plugins/package-manifest.types.d.ts
/** package.json OpenClaw metadata used for plugin setup and catalog discovery. */
type PluginPackageChannelApprovalFlag = "native";
type PluginPackageChannel = {
id?: string;
label?: string;
selectionLabel?: string;
detailLabel?: string;
docsPath?: string;
docsLabel?: string;
blurb?: string;
order?: number;
aliases?: readonly string[];
preferOver?: readonly string[];
systemImage?: string;
selectionDocsPrefix?: string;
selectionDocsOmitLabel?: boolean;
selectionExtras?: readonly string[];
markdownCapable?: boolean;
/** Closed manifest flags for approval behavior available before the channel runtime loads. */
approvalFlags?: readonly PluginPackageChannelApprovalFlag[];
exposure?: {
configured?: boolean;
setup?: boolean;
docs?: boolean;
};
quickstartAllowFrom?: boolean;
forceAccountBinding?: boolean;
preferSessionLookupForAnnounceTarget?: boolean;
commands?: PluginManifestChannelCommandDefaults;
configuredState?: {
specifier?: string;
exportName?: string;
env?: {
allOf?: readonly string[];
anyOf?: readonly string[];
};
};
persistedAuthState?: {
specifier?: string;
exportName?: string;
};
doctorCapabilities?: PluginPackageChannelDoctorCapabilities;
/** Typed, serializable setup fields available before plugin runtime load. */
setup?: ChannelSetupMetadata;
/** @deprecated Use setup.fields. */
cliAddOptions?: readonly PluginPackageChannelCliOption[];
};
type PluginPackageChannelDoctorCapabilities = {
dmAllowFromMode?: "topOnly" | "topOrNested" | "nestedOnly";
/** Whether dmPolicy="open" requires an explicit "*" in allowFrom. Defaults to true. */
openDmRequiresAllowFromWildcard?: boolean;
groupModel?: "sender" | "route" | "hybrid";
groupAllowFromFallbackToAllowFrom?: boolean;
warnOnEmptyGroupSenderAllowlist?: boolean;
};
type PluginPackageChannelCliOption = {
flags: string;
negatedFlags?: string;
description: string;
defaultValue?: boolean | string;
valueType?: "int" | "list";
};
type PluginPackageInstall = {
clawhubSpec?: string;
npmSpec?: string;
localPath?: string;
defaultChoice?: "clawhub" | "npm" | "local";
minHostVersion?: string;
expectedIntegrity?: string;
allowInvalidConfigRecovery?: boolean;
requiredPlatformPackages?: string[];
};
type OpenClawPackageSetupFeatures = {
configPromotion?: boolean | "preserve-root";
/**
* @deprecated Declare doctorContract.stateMigrations in openclaw.plugin.json instead.
* Removal plan: remove the setup-entry adapter after the 2027.1 external-plugin migration window.
*/
legacyStateMigrations?: boolean;
legacySessionSurfaces?: boolean;
};
type OpenClawPackageCompat = {
pluginApi?: string;
minGatewayVersion?: string;
};
type OpenClawPackageBuild = {
bundledDist?: boolean;
openclawVersion?: string;
pluginSdkVersion?: string;
};
type OpenClawPackageManifest = {
extensions?: string[];
runtimeExtensions?: string[];
setupEntry?: string;
runtimeSetupEntry?: string;
controlUi?: string;
setupFeatures?: OpenClawPackageSetupFeatures;
plugin?: {
id?: string;
label?: string;
};
channel?: PluginPackageChannel;
compat?: OpenClawPackageCompat;
install?: PluginPackageInstall;
build?: OpenClawPackageBuild;
};
type ManifestKey = typeof MANIFEST_KEY;
type PackageManifest = {
name?: string;
version?: string;
description?: string;
dependencies?: Record<string, string>;
optionalDependencies?: Record<string, string>;
} & Partial<Record<ManifestKey, OpenClawPackageManifest>>;
//#endregion
//#region src/plugins/plugin-origin.types.d.ts
/** Origin class for plugin discovery and runtime trust decisions. */
type PluginOrigin = "bundled" | "global" | "workspace" | "config";
//#endregion
//#region src/plugins/status-dependencies-core.d.ts
/** Dependency name-to-version map from a plugin package manifest. */
type PluginDependencySpecMap = Record<string, string>;
/** Installation status for one plugin dependency. */
type PluginDependencyEntry = {
name: string;
spec: string;
installed: boolean;
optional: boolean;
resolvedPath?: string;
};
/** Aggregate installation status for required and optional plugin dependencies. */
type PluginDependencyStatus = {
hasDependencies: boolean;
installed: boolean;
requiredInstalled: boolean;
optionalInstalled: boolean;
missing: string[];
missingOptional: string[];
dependencies: PluginDependencyEntry[];
optionalDependencies: PluginDependencyEntry[];
};
//#endregion
//#region src/plugins/discovery.types.d.ts
/** One potential plugin root discovered before manifest validation and registry normalization. */
type PluginCandidate = {
idHint: string;
/** Discovery-owned identity for one entry in a multi-entry package pack. */
effectivePluginId?: string;
diagnosticIdHint?: string;
source: string;
setupSource?: string;
rootDir: string;
origin: PluginOrigin;
/** Retains explicit load-path precedence when physical aliases merge their provenance. */
configSelected?: true;
/** An intentional source overlay must not execute its packaged peer. */
sourcePreferred?: true;
format?: PluginFormat;
bundleFormat?: PluginBundleFormat;
workspaceDir?: string;
packageName?: string;
packageVersion?: string;
packageDescription?: string;
packageDir?: string;
packageManifest?: OpenClawPackageManifest;
packageDependencies?: PluginDependencySpecMap;
packageOptionalDependencies?: PluginDependencySpecMap;
bundledManifestId?: string;
bundledManifest?: PluginManifest;
bundledManifestPath?: string;
requiredPluginIds?: string[];
requiredPluginSource?: string;
rawPackageManifest?: PackageManifest;
};
/** Discovery candidates plus warnings/errors emitted while scanning roots. */
type PluginDiscoveryResult = {
candidates: PluginCandidate[];
diagnostics: PluginDiagnostic[];
};
//#endregion
//#region src/plugins/compat/registry-records.d.ts
declare const PLUGIN_COMPAT_RECORDS: readonly [...({
code: "plugin-sdk-agent-config-primitives-subpath" | "plugin-sdk-channel-logging-subpath" | "plugin-sdk-channel-secret-runtime-subpath" | "plugin-sdk-channel-streaming-subpath" | "plugin-sdk-group-access-subpath" | "plugin-sdk-matrix-subpath" | "plugin-sdk-text-runtime-subpath" | "plugin-sdk-zod-subpath";
status: "removed";
owner: "channel" | "config" | "sdk";
introduced: string;
replacement: "`openclaw/plugin-sdk/channel-config-schema`" | "`openclaw/plugin-sdk/channel-inbound` and `openclaw/plugin-sdk/channel-outbound`" | "`openclaw/plugin-sdk/channel-ingress-runtime`" | "`openclaw/plugin-sdk/channel-outbound`" | "`openclaw/plugin-sdk/channel-secret-basic-runtime` and `openclaw/plugin-sdk/channel-secret-tts-runtime`" | "`openclaw/plugin-sdk/logging-core`, `openclaw/plugin-sdk/text-chunking`, `openclaw/plugin-sdk/text-utility-runtime`, and `openclaw/plugin-sdk/string-coerce-runtime`" | "`openclaw/plugin-sdk/run-command`" | "the direct `zod` package import";
docsPath: string;
surfaces: string[];
diagnostics: string[];
tests: string[];
releaseNote: "The deprecated `agent-config-primitives` Plugin SDK subpath was removed; plugins now use maintained config-schema primitives." | "The deprecated `channel-logging` Plugin SDK subpath was removed; channel logging helpers now come from the inbound and outbound channel surfaces." | "The deprecated `channel-secret-runtime` Plugin SDK subpath was removed; plugins now use the focused basic and TTS secret-runtime subpaths." | "The deprecated `channel-streaming` Plugin SDK subpath was removed; plugins now import channel streaming helpers from `channel-outbound`." | "The deprecated `group-access` Plugin SDK subpath was removed; plugins now resolve message admission through `channel-ingress-runtime`." | "The deprecated `matrix` Plugin SDK facade was removed; command execution now uses the generic `run-command` subpath." | "The deprecated `text-runtime` Plugin SDK facade was removed; plugins now import logging, chunking, text utility, and string coercion helpers from their focused subpaths." | "The deprecated `zod` Plugin SDK re-export was removed; plugins now import `zod` directly.";
deprecated?: undefined;
warningStarts?: undefined;
removeAfter?: undefined;
removalGate?: undefined;
} | {
releaseNote?: undefined;
code: "plugin-sdk-channel-lifecycle-subpath" | "plugin-sdk-channel-message-subpath" | "plugin-sdk-channel-reply-pipeline-subpath" | "plugin-sdk-config-runtime-subpath" | "plugin-sdk-inbound-reply-dispatch-subpath" | "plugin-sdk-infra-runtime-subpath";
status: "deprecated" | "removal-pending";
owner: "channel" | "config" | "sdk";
introduced: string;
deprecated: string;
warningStarts: string;
removeAfter: "2026-10-01" | undefined;
removalGate: "next-plugin-sdk-major" | undefined;
replacement: "`api.pluginConfig`, `openclaw/plugin-sdk/config-mutation`, `openclaw/plugin-sdk/runtime-config-snapshot`, and `openclaw/plugin-sdk/config-contracts`; retain until supported external plugin migration is verified" | "`openclaw/plugin-sdk/channel-inbound` and `openclaw/plugin-sdk/channel-outbound`" | "`openclaw/plugin-sdk/channel-outbound` and `openclaw/plugin-sdk/channel-inbound`; retain until supported external plugin migration is verified" | "`openclaw/plugin-sdk/channel-outbound`; retain until supported external plugin migration is verified" | "focused subpaths including `openclaw/plugin-sdk/delivery-queue-runtime`, `openclaw/plugin-sdk/diagnostic-runtime`, `openclaw/plugin-sdk/error-runtime`, `openclaw/plugin-sdk/exec-approvals-runtime`, `openclaw/plugin-sdk/fetch-runtime`, and `openclaw/plugin-sdk/ssrf-runtime`; retain until supported external plugin migration is verified and system-event snapshot inspection and consumption have a modern public replacement";
docsPath: string;
surfaces: string[];
diagnostics: string[];
tests: string[];
} | {
status: "removal-pending";
removeAfter: "2026-09-30";
replacement: "`api.registerMediaUnderstandingProvider(...)` with provider-owned request helpers and types from `openclaw/plugin-sdk/plugin-entry`; retain the public subpath through the 2026-09-30 window while official plugin consumers migrate";
docsPath: "/plugins/architecture";
code: "plugin-sdk-media-understanding-public-demotion" | "plugin-sdk-memory-host-core-public-demotion" | "plugin-sdk-plugin-config-runtime-public-demotion" | "plugin-sdk-tool-plugin-public-demotion";
owner: "sdk";
introduced: string;
deprecated: string;
warningStarts: string;
surfaces: string[];
diagnostics: string[];
tests: string[];
} | {
status: "removal-pending";
removeAfter: "2026-09-30";
replacement: "host-prepared memory prompts via `openclaw/plugin-sdk/core` and memory capability registration through the injected plugin API; retain the facade through the 2026-09-30 window and until a focused public-artifact read seam exists";
docsPath: "/plugins/architecture-internals#context-engine-plugins";
code: "plugin-sdk-media-understanding-public-demotion" | "plugin-sdk-memory-host-core-public-demotion" | "plugin-sdk-plugin-config-runtime-public-demotion" | "plugin-sdk-tool-plugin-public-demotion";
owner: "sdk";
introduced: string;
deprecated: string;
warningStarts: string;
surfaces: string[];
diagnostics: string[];
tests: string[];
} | {
status: "removal-pending";
removeAfter: "2026-12-01";
replacement: "`api.pluginConfig`, runtime tool context config, and focused `config-contracts`, `runtime-config-snapshot`, or `config-mutation` subpaths; retain the public subpath through the 2026-12-01 window while official plugin consumers migrate";
docsPath: "/plugins/sdk-runtime";
code: "plugin-sdk-media-understanding-public-demotion" | "plugin-sdk-memory-host-core-public-demotion" | "plugin-sdk-plugin-config-runtime-public-demotion" | "plugin-sdk-tool-plugin-public-demotion";
owner: "sdk";
introduced: string;
deprecated: string;
warningStarts: string;
surfaces: string[];
diagnostics: string[];
tests: string[];
} | {
status: "deprecated";
replacement: "retain the public subpath until plugin authoring has a nonexecuting static metadata replacement for `defineToolPlugin`; `getToolPluginMetadata` currently reads metadata only from an already-executed entry";
docsPath: "/plugins/tool-plugins";
code: "plugin-sdk-media-understanding-public-demotion" | "plugin-sdk-memory-host-core-public-demotion" | "plugin-sdk-plugin-config-runtime-public-demotion" | "plugin-sdk-tool-plugin-public-demotion";
owner: "sdk";
introduced: string;
deprecated: string;
warningStarts: string;
surfaces: string[];
diagnostics: string[];
tests: string[];
})[], {
readonly code: "plugin-sdk-channel-setup-input-fields";
readonly status: "deprecated";
readonly owner: "channel";
readonly introduced: "2026-07-25";
readonly deprecated: "2026-07-25";
readonly warningStarts: "2026-07-25";
readonly removeAfter: "2026-10-01";
readonly replacement: "plugin-local setup input intersections that declare each owning channel field";
readonly docsPath: "/plugins/sdk-migration#published-channel-setup-compatibility";
readonly surfaces: readonly ["ChannelSetupInput.privateKey", "ChannelSetupInput.secret", "ChannelSetupInput.botToken", "ChannelSetupInput.appToken", "ChannelSetupInput.signingSecret", "ChannelSetupInput.mode", "ChannelSetupInput.cliPath", "ChannelSetupInput.authDir", "ChannelSetupInput.httpUrl", "ChannelSetupInput.httpPort", "ChannelSetupInput.webhookPath", "ChannelSetupInput.webhookUrl", "ChannelSetupInput.userId", "ChannelSetupInput.accessToken", "ChannelSetupInput.password", "ChannelSetupInput.deviceName", "ChannelSetupInput.url", "ChannelSetupInput.baseUrl", "ChannelSetupInput.code", "ChannelSetupInput.groupChannels", "ChannelSetupInput.dmAllowlist", "ChannelSetupInput.autoDiscoverChannels"];
readonly diagnostics: readonly ["TypeScript @deprecated annotations on the reader-backed ChannelSetupInput compatibility tier", "published-plugin artifact reader sweep required before field removal"];
readonly tests: readonly ["src/plugin-sdk/channel-setup.test.ts", "src/plugins/compat/registry.test.ts"];
readonly releaseNote: "ChannelSetupInput keeps its reader-backed channel fields through the dated migration window while plugins move them into plugin-local input types.";
}, {
readonly code: "plugin-sdk-broad-runtime-barrels";
readonly status: "deprecated";
readonly owner: "sdk";
readonly introduced: "2026-07-25";
readonly deprecated: "2026-07-25";
readonly warningStarts: "2026-07-25";
readonly removeAfter: "2026-10-01";
readonly replacement: "focused plugin SDK subpaths for each runtime capability";
readonly docsPath: "/plugins/sdk-migration#compatibility-policy";
readonly surfaces: readonly ["openclaw/plugin-sdk/agent-runtime", "openclaw/plugin-sdk/agent-runtime loadModelCatalog params.useCache", "openclaw/plugin-sdk/agent-runtime loadModelCatalog params.cacheOnly", "openclaw/plugin-sdk/agent-runtime loadModelCatalog params.metadataSnapshot", "openclaw/plugin-sdk/agent-runtime loadModelCatalog", "openclaw/plugin-sdk/cli-runtime", "openclaw/plugin-sdk/conversation-runtime", "openclaw/plugin-sdk/hook-runtime", "openclaw/plugin-sdk/media-runtime", "openclaw/plugin-sdk/media-runtime buildAgentMediaPayload", "openclaw/plugin-sdk/plugin-runtime", "openclaw/plugin-sdk/security-runtime"];
readonly diagnostics: readonly ["TypeScript @deprecated annotations on broad plugin SDK barrels", "plugin boundary report compatibility inventory"];
readonly tests: readonly ["src/plugins/contracts/plugin-sdk-subpaths.test.ts", "src/plugins/compat/registry.test.ts"];
readonly releaseNote: "Broad agent, CLI, conversation, hook, media, plugin, and security runtime barrels remain available while bundled and external plugins migrate to focused subpaths.";
}, {
readonly code: "plugin-sdk-provider-owned-helper-shims";
readonly status: "deprecated";
readonly owner: "provider";
readonly introduced: "2026-07-25";
readonly deprecated: "2026-07-25";
readonly warningStarts: "2026-07-25";
readonly removeAfter: "2026-10-01";
readonly replacement: "provider-local auth, model, replay, OAuth, and stream helper APIs";
readonly docsPath: "/plugins/sdk-migration#compatibility-policy";
readonly surfaces: readonly ["openclaw/plugin-sdk/provider-stream GOOGLE_THINKING_STREAM_HOOKS", "openclaw/plugin-sdk/provider-stream KILOCODE_THINKING_STREAM_HOOKS", "openclaw/plugin-sdk/provider-stream MOONSHOT_THINKING_STREAM_HOOKS", "openclaw/plugin-sdk/provider-stream MINIMAX_FAST_MODE_STREAM_HOOKS", "openclaw/plugin-sdk/provider-stream OPENAI_RESPONSES_STREAM_HOOKS", "openclaw/plugin-sdk/provider-stream OPENROUTER_THINKING_STREAM_HOOKS", "openclaw/plugin-sdk/provider-stream TOOL_STREAM_DEFAULT_ON_HOOKS", "openclaw/plugin-sdk/provider-stream-shared defaultToolStreamExtraParams", "openclaw/plugin-sdk/provider-stream-shared stripTrailingAnthropicAssistantPrefillWhenThinking", "openclaw/plugin-sdk/provider-stream-shared createAnthropicThinkingPrefillPayloadWrapper", "openclaw/plugin-sdk/provider-stream-shared OpenAICompatibleThinkingLevel", "openclaw/plugin-sdk/provider-stream-shared isOpenAICompatibleThinkingEnabled", "openclaw/plugin-sdk/provider-stream-shared DeepSeekV4ThinkingLevel", "openclaw/plugin-sdk/provider-stream-shared DeepSeekV4ReasoningEffort", "openclaw/plugin-sdk/provider-stream-shared createDeepSeekV4OpenAICompatibleThinkingWrapper", "openclaw/plugin-sdk/provider-stream-shared createThinkingOnlyFinalTextWrapper", "openclaw/plugin-sdk/provider-stream-shared createGoogleThinkingPayloadWrapper", "openclaw/plugin-sdk/provider-stream-shared createGoogleThinkingStreamWrapper", "openclaw/plugin-sdk/provider-model-shared isProxyReasoningUnsupportedModelHint", "openclaw/plugin-sdk/provider-model-shared OPENAI_COMPATIBLE_REPLAY_HOOKS", "openclaw/plugin-sdk/provider-model-shared ANTHROPIC_BY_MODEL_REPLAY_HOOKS", "openclaw/plugin-sdk/provider-model-shared NATIVE_ANTHROPIC_REPLAY_HOOKS", "openclaw/plugin-sdk/provider-model-shared PASSTHROUGH_GEMINI_REPLAY_HOOKS", "openclaw/plugin-sdk/provider-auth DEFAULT_COPILOT_API_BASE_URL", "openclaw/plugin-sdk/provider-auth deriveCopilotApiBaseUrlFromToken", "openclaw/plugin-sdk/provider-auth resolveCopilotApiToken", "openclaw/plugin-sdk/provider-auth-copilot-cache CachedCopilotToken", "openclaw/plugin-sdk/oauth-utils toFormUrlEncoded", "openclaw/plugin-sdk/oauth-utils generatePkceVerifierChallenge", "openclaw/plugin-sdk/provider-oauth-runtime OAuthProvider", "openclaw/plugin-sdk/provider-oauth-runtime OAuthProviderInfo"];
readonly diagnostics: readonly ["TypeScript @deprecated annotations naming provider-local replacements", "plugin boundary report compatibility inventory"];
readonly tests: readonly ["src/plugins/contracts/plugin-sdk-subpaths.test.ts", "src/plugins/compat/registry.test.ts"];
readonly releaseNote: "Provider-specific auth, model, replay, OAuth, and stream shortcuts remain as deprecated SDK shims while providers move to their local APIs.";
}, {
readonly code: "message-presentation-legacy-bridges";
readonly status: "deprecated";
readonly owner: "channel";
readonly introduced: "2026-07-25";
readonly deprecated: "2026-07-25";
readonly warningStarts: "2026-07-25";
readonly removeAfter: "2026-10-01";
readonly replacement: "MessagePresentation values and channel presentation renderers";
readonly docsPath: "/plugins/sdk-migration#compatibility-policy";
readonly surfaces: readonly ["InteractiveReplyButton.value", "InteractiveReplyButton.url", "InteractiveReplyButton.webApp", "InteractiveReplyButton.web_app", "InteractiveReplyOption.value", "InteractiveReplyButton", "InteractiveReplyOption", "InteractiveReplyBlock", "InteractiveReply", "normalizeInteractiveReply", "hasInteractiveReplyBlocks", "presentationToInteractiveReply", "presentationToInteractiveControlsReply", "interactiveReplyToPresentation", "resolveInteractiveTextFallback", "src/auto-reply ReplyPayload.interactive", "openclaw/plugin-sdk/reply-payload ReplyPayload.interactive", "reduceInteractiveReply", "@openclaw/discord buildDiscordInteractiveComponents", "@openclaw/slack buildSlackInteractiveBlocks", "@openclaw/telegram buildTelegramInteractiveButtons"];
readonly diagnostics: readonly ["TypeScript @deprecated annotations naming MessagePresentation replacements", "plugin boundary report compatibility inventory"];
readonly tests: readonly ["src/interactive/payload.test.ts", "src/plugin-sdk/reply-payload.test.ts", "src/plugins/compat/registry.test.ts"];
readonly releaseNote: "Legacy interactive reply values and channel-specific rendering bridges remain available while producers migrate to MessagePresentation.";
}, {
readonly code: "plugin-sdk-focused-compat-aliases";
readonly status: "deprecated";
readonly owner: "sdk";
readonly introduced: "2026-07-25";
readonly deprecated: "2026-07-25";
readonly warningStarts: "2026-07-25";
readonly removeAfter: "2026-10-01";
readonly replacement: "the focused replacement named by each TypeScript @deprecated annotation";
readonly docsPath: "/plugins/sdk-migration#compatibility-policy";
readonly surfaces: readonly ["openclaw/plugin-sdk/acp-runtime __testing", "openclaw/plugin-sdk/approval-reaction-runtime", "openclaw/plugin-sdk/channel-inbound BuildChannelTurnContextParams", "openclaw/plugin-sdk/channel-inbound BuiltChannelTurnContext", "openclaw/plugin-sdk/channel-inbound buildChannelTurnContext", "openclaw/plugin-sdk/channel-inbound finalizeChannelInboundContext", "openclaw/plugin-sdk/channel-inbound filterChannelTurnSupplementalContext", "openclaw/plugin-sdk/channel-send-result ChannelSendRawResult", "openclaw/plugin-sdk/command-auth", "openclaw/plugin-sdk/command-auth ResolveSenderCommandAuthorizationParams", "openclaw/plugin-sdk/command-auth resolveCommandAuthorizedFromAuthorizers", "openclaw/plugin-sdk/command-auth CommandAuthorizationRuntime", "openclaw/plugin-sdk/command-auth ResolveSenderCommandAuthorizationWithRuntimeParams", "openclaw/plugin-sdk/command-auth resolveDirectDmAuthorizationOutcome", "openclaw/plugin-sdk/command-auth resolveSenderCommandAuthorizationWithRuntime", "openclaw/plugin-sdk/command-auth resolveSenderCommandAuthorization", "openclaw/plugin-sdk/keyed-async-queue KeyedAsyncQueue.getTailMapForTesting", "openclaw/plugin-sdk/persistent-dedupe PersistentDedupeLegacyPathOptions.lockOptions", "openclaw/plugin-sdk/retry-runtime createTelegramRetryRunner", "openclaw/plugin-sdk/ssrf-policy SsrfPolicyOptions.allowPrivateNetwork", "openclaw/plugin-sdk/ssrf-policy ssrfPolicyFromAllowPrivateNetwork", "openclaw/plugin-sdk/tts-runtime TtsSynthesisStreamResult", "openclaw/plugin-sdk/tts-runtime TtsRuntimeFacade._test"];
readonly diagnostics: readonly ["TypeScript @deprecated annotations naming focused replacements", "plugin boundary report compatibility inventory"];
readonly tests: readonly ["src/plugin-sdk/channel-inbound.test.ts", "src/plugin-sdk/command-auth.test.ts", "src/plugin-sdk/ssrf-policy.test.ts", "src/plugins/compat/registry.test.ts"];
readonly releaseNote: "Focused SDK compatibility aliases remain available through a dated window while callers adopt their annotated replacements.";
}, {
readonly code: "agent-harness-terminal-result-aliases";
readonly status: "deprecated";
readonly owner: "agent-runtime";
readonly introduced: "2026-07-25";
readonly deprecated: "2026-07-25";
readonly warningStarts: "2026-07-25";
readonly removeAfter: "2026-10-01";
readonly replacement: "AgentHarnessAttemptResult.terminal and AgentHarnessDeliveryDefaults.visibleReplies";
readonly docsPath: "/plugins/sdk-agent-harness";
readonly surfaces: readonly ["AgentHarnessAttemptResult.aborted", "AgentHarnessAttemptResult.externalAbort", "AgentHarnessAttemptResult.timedOut", "AgentHarnessAttemptResult.idleTimedOut", "AgentHarnessAttemptResult.timedOutDuringCompaction", "AgentHarnessAttemptResult.timedOutDuringToolExecution", "AgentHarnessAttemptResult.timedOutByRunBudget", "AgentHarnessAttemptResult.promptError", "AgentHarnessAttemptResult.promptErrorSource", "AgentHarnessDeliveryDefaults.sourceVisibleReplies"];
readonly diagnostics: readonly ["TypeScript @deprecated annotations on agent harness result and delivery defaults", "plugin boundary report compatibility inventory"];
readonly tests: readonly ["src/agents/harness/settled-turn-finalization-result.test.ts", "src/plugins/compat/registry.test.ts"];
readonly releaseNote: "Agent harness result booleans and sourceVisibleReplies remain available while harnesses migrate to terminal outcomes and visibleReplies.";
}, {
readonly code: "official-plugin-export-aliases";
readonly status: "deprecated";
readonly owner: "channel";
readonly introduced: "2026-07-25";
readonly deprecated: "2026-07-25";
readonly warningStarts: "2026-07-25";
readonly removeAfter: "2026-10-01";
readonly replacement: "the canonical testing export, MessagePresentation renderers, and host-owned timeout/runtime behavior";
readonly docsPath: "/plugins/compatibility#current-compatibility-areas";
readonly surfaces: readonly ["@openclaw/google-meet __testing", "@openclaw/discord buildDiscordInteractiveComponents", "@openclaw/discord normalizeDiscordListenerTimeoutMs", "@openclaw/discord normalizeDiscordInboundWorkerTimeoutMs", "@openclaw/discord isAbortError", "@openclaw/discord runDiscordTaskWithTimeout", "@openclaw/slack buildSlackInteractiveBlocks"];
readonly diagnostics: readonly ["TypeScript @deprecated annotations on published official-plugin exports", "plugin boundary report compatibility inventory"];
readonly tests: readonly ["extensions/google-meet/index.test.ts", "src/plugins/compat/registry.test.ts"];
readonly releaseNote: "Published Google Meet testing, channel presentation, and Discord timeout aliases remain available while consumers move to their canonical exports and host-owned behavior.";
}, {
readonly code: "memory-host-compatibility-aliases";
readonly status: "deprecated";
readonly owner: "sdk";
readonly introduced: "2026-07-25";
readonly deprecated: "2026-07-25";
readonly warningStarts: "2026-07-25";
readonly removeAfter: "2026-10-01";
readonly replacement: "canonical memory cache/FTS tables and getRuntimeConfig or caller-provided config";
readonly docsPath: "/plugins/sdk-migration#compatibility-policy";
readonly surfaces: readonly ["@openclaw/memory-host-sdk ensureMemoryIndexSchema.embeddingCacheTable", "@openclaw/memory-host-sdk ensureMemoryIndexSchema.ftsTable", "@openclaw/memory-host-sdk/runtime-core loadConfig", "@openclaw/memory-host-sdk/host/openclaw-runtime loadConfig"];
readonly diagnostics: readonly ["TypeScript @deprecated annotations on memory-host SDK compatibility fields", "plugin boundary report memory-host SDK summary"];
readonly tests: readonly ["packages/memory-host-sdk/src/host/memory-schema.test.ts", "src/plugins/compat/registry.test.ts"];
readonly releaseNote: "Memory-host cache-table overrides and runtime config reload aliases remain available while callers migrate to canonical tables and prepared config.";
}, {
readonly code: "plugin-runtime-api-compat-aliases";
readonly status: "deprecated";
readonly owner: "plugin-execution";
readonly introduced: "2026-07-25";
readonly deprecated: "2026-07-25";
readonly warningStarts: "2026-07-25";
readonly removeAfter: "2026-10-01";
readonly replacement: "the namespaced plugin API and focused runtime methods named per surface";
readonly docsPath: "/plugins/sdk-migration#compatibility-policy";
readonly surfaces: readonly ["OpenClawPluginApi.registerSessionExtension", "OpenClawPluginApi.enqueueNextTurnInjection", "OpenClawPluginApi.registerControlUiDescriptor", "OpenClawPluginApi.registerRuntimeLifecycle", "OpenClawPluginApi.registerAgentEventSubscription", "OpenClawPluginApi.emitAgentEvent", "OpenClawPluginApi.setRunContext", "OpenClawPluginApi.getRunContext", "OpenClawPluginApi.clearRunContext", "OpenClawPluginApi.registerSessionSchedulerJob", "OpenClawPluginApi.registerSessionAction", "OpenClawPluginApi.sendSessionAttachment", "OpenClawPluginApi.scheduleSessionTurn", "OpenClawPluginApi.unscheduleSessionTurnsByTag", "PluginHookContext.senderExternalId", "PluginAttachmentChannelHints.telegram", "PluginAttachmentChannelHints.slack", "AgentPromptSurfaceKind pi_main", "PluginRuntime.channel.reply.createReplyDispatcherWithTyping", "PluginRuntime.channel.reply.resolveHumanDelayConfig", "PluginRuntime.channel.reply.dispatchReplyFromConfig", "PluginRuntime.channel.reply.finalizeInboundContext", "PluginRuntime.channel.media.fetchRemoteMedia", "PluginRuntime.channel.session.resolveStorePath", "PluginRuntime.channel.session.recordInboundSession", "PluginRuntime.channel.inbound.runPreparedReply", "PluginRuntime.system.requestHeartbeatNow"];
readonly diagnostics: readonly ["TypeScript @deprecated annotations on plugin API and runtime aliases", "plugin boundary report compatibility inventory"];
readonly tests: readonly ["src/plugins/captured-registration.test.ts", "src/plugins/runtime/index.test.ts", "src/plugins/compat/registry.test.ts"];
readonly releaseNote: "Flat plugin registration and broad runtime aliases remain available while plugins migrate to namespaced APIs and focused runtime methods.";
}, {
readonly code: "plugin-provider-manifest-compat-aliases";
readonly status: "deprecated";
readonly owner: "provider";
readonly introduced: "2026-07-25";
readonly deprecated: "2026-07-25";
readonly warningStarts: "2026-07-25";
readonly removeAfter: "2026-10-01";
readonly replacement: "manifest-owned plugin kind/setup metadata and model catalog registration";
readonly docsPath: "/plugins/sdk-migration#compatibility-policy";
readonly surfaces: readonly ["DefinePluginEntryOptions.kind", "SingleProviderPluginOptions.kind", "OpenClawPluginDefinition.kind", "PluginPackageChannel.cliAddOptions", "ProviderPlugin.catalog", "ProviderPlugin.staticCatalog", "ProviderPlugin.suppressBuiltInModel", "ProviderPlugin.augmentModelCatalog", "ProviderBuiltInModelSuppressionContext"];
readonly diagnostics: readonly ["TypeScript @deprecated annotations on plugin manifest and provider catalog aliases", "plugin boundary report compatibility inventory"];
readonly tests: readonly ["src/plugins/contracts/package-manifest.contract.test.ts", "src/plugins/contracts/provider-catalog-deprecation.contract.test.ts", "src/plugins/compat/registry.test.ts"];
readonly releaseNote: "Runtime plugin kind/setup metadata and provider catalog hooks remain available while plugins migrate ownership into manifests and catalog registrations.";
}, {
readonly code: "media-legacy-projection";
readonly status: "deprecated";
readonly owner: "sdk";
readonly introduced: "2026-07-24";
readonly deprecated: "2026-07-24";
readonly warningStarts: "2026-07-24";
readonly removeAfter: "2026-10-01";
readonly replacement: "ordered `MsgContext.media` / `InboundMediaFacts[]`; typed hook `media` and `originalMedia`; `Attachment*` template variables; and `openclaw/plugin-sdk/media-local-roots`";
readonly docsPath: "/plugins/sdk-migration#media-legacy-projection";
readonly surfaces: readonly ["MsgContext MediaPath/MediaUrl/MediaType and plural/staging fields", "openclaw/plugin-sdk/agent-media-payload", "ChannelInboundMediaPayload and buildChannelInboundMediaPayload", "MediaPayload and buildMediaPayload", "message hook mediaPath/mediaUrl/mediaType and plural/original metadata aliases", "MediaPath/MediaUrl/MediaType/MediaDir template variables"];
readonly diagnostics: readonly ["TypeScript @deprecated annotations naming the facts-first replacement", "plugin boundary report compatibility inventory with the approved removeAfter date", "SDK, hook, and media template migration documentation"];
readonly tests: readonly ["src/sessions/user-turn-transcript.media.test.ts", "src/hooks/message-hook-mappers.test.ts", "src/media-understanding/runner.cli-audio.test.ts", "src/plugins/compat/registry.test.ts", "src/plugins/contracts/plugin-sdk-subpaths.test.ts"];
readonly releaseNote: "Legacy parallel media projections remain available as deprecated compatibility while plugins move to ordered facts, typed hook media, Attachment templates, and the focused media-local-roots SDK.";
}, {
readonly code: "memory-read-result-statusless-success";
readonly status: "deprecated";
readonly owner: "sdk";
readonly introduced: "2026-04-28";
readonly deprecated: "2026-08-19";
readonly warningStarts: "2026-08-19";
readonly removalGate: "next-plugin-sdk-major";
readonly replacement: "`MemoryReadResult` with explicit `status: \"ok\" | \"not_found\"`";
readonly docsPath: "/plugins/sdk-migration#memory-read-missing-results";
readonly surfaces: readonly ["statusless external memory manager read results"];
readonly diagnostics: readonly ["host memory-manager acquisition adapter"];
readonly tests: readonly ["src/plugins/memory-runtime.test.ts", "src/plugins/compat/registry.test.ts"];
readonly releaseNote: "External memory managers must return explicit not-found status for absence; statusless results retain legacy successful-read semantics through the next Plugin SDK major.";
}, {
readonly code: "context-engine-legacy-host-param-default";
readonly status: "removed";
readonly owner: "sdk";
readonly introduced: "2026-07-29";
readonly replacement: "`ContextEngineInfo.acceptedHostParams` for restricted projection; omitted declarations receive full host params";
readonly docsPath: "/concepts/context-engine#the-contextengine-interface";
readonly surfaces: readonly ["ContextEngineInfo.acceptedHostParams and undeclared-engine default projection"];
readonly diagnostics: readonly ["plugin compatibility registry and context engine guide"];
readonly tests: readonly ["src/context-engine/host-param-projection.test.ts"];
readonly releaseNote: "The undeclared context-engine host-parameter compatibility default was removed; engines without `acceptedHostParams` now receive all current host fields.";
}, {
readonly code: "removed-global-api-provider-publication";
readonly status: "removed";
readonly owner: "sdk";
readonly introduced: "2026-05-27";
readonly replacement: "provider plugins via `api.registerProvider(...)`; host/runtime code registers against its lifecycle-owned `ApiRegistry`";
readonly docsPath: "/plugins/sdk-migration#process-global-api-provider-publication";
readonly surfaces: readonly ["openclaw/plugin-sdk/llm registerApiProvider", "openclaw/plugin-sdk/llm unregisterApiProviders"];
readonly diagnostics: readonly ["plugin SDK compatibility registry and migration guide"];
readonly tests: readonly ["src/plugins/compat/registry.test.ts"];
readonly releaseNote: "The process-global API-provider publication facade was removed; provider plugins now publish through their lifecycle-owned registration, and host runtimes register directly on their prepared ApiRegistry.";
}, {
readonly code: "legacy-deactivate-hook-alias";
readonly status: "removed";
readonly owner: "sdk";
readonly introduced: "2026-05-16";
readonly replacement: "`gateway_stop` hook";
readonly docsPath: "/plugins/sdk-migration#deactivate-hook-alias";
readonly surfaces: readonly ["api.on(\"deactivate\", ...)", "plugin typed hook registration"];
readonly diagnostics: readonly ["plugin compatibility registry and migration guide"];
readonly tests: readonly ["src/plugins/compat/registry.test.ts"];
readonly releaseNote: "The deprecated `api.on(\"deactivate\", ...)` hook alias was removed; plugins must register cleanup with `gateway_stop`.";
}, {
readonly code: "legacy-subagent-spawning-hook";
readonly status: "removed";
readonly owner: "sdk";
readonly introduced: "2026-05-30";
readonly replacement: "`subagent_spawned` for post-launch observation; core session-binding adapters for thread routing";
readonly docsPath: "/plugins/hooks#upcoming-deprecations";
readonly surfaces: readonly ["api.on(\"subagent_spawning\", ...)", "PluginHookSubagentSpawningEvent", "PluginHookSubagentSpawningResult", "SubagentLifecycleHookRunner.runSubagentSpawning"];
readonly diagnostics: readonly ["plugin compatibility registry and migration guide"];
readonly tests: readonly ["src/plugins/compat/registry.test.ts"];
readonly releaseNote: "`api.on(\"subagent_spawning\", ...)` was removed; core now owns thread-bound subagent routing, and `subagent_spawned` remains available for observation.";
}, {
readonly code: "hook-only-plugin-shape";
readonly status: "active";
readonly owner: "sdk";
readonly introduced: "2026-04-24";
readonly replacement: "explicit capability registration";
readonly docsPath: "/plugins/sdk-migration";
readonly surfaces: readonly ["plugin shape inspection", "plugins inspect", "status diagnostics"];
readonly diagnostics: readonly ["plugin compatibility notice"];
readonly tests: readonly ["src/plugins/status.test.ts", "src/plugins/contracts/shape.contract.test.ts"];
}, {
readonly code: "deprecated-memory-embedding-provider-api";
readonly status: "removed";
readonly owner: "sdk";
readonly introduced: "2026-05-21";
readonly replacement: "`api.registerEmbeddingProvider(...)` and `contracts.embeddingProviders`";
readonly docsPath: "/plugins/sdk-migration#memory-embedding-provider-api";
readonly surfaces: readonly ["api.registerMemoryEmbeddingProvider(...)", "contracts.memoryEmbeddingProviders", "openclaw/plugin-sdk/memory-core-host-engine-embeddings registerMemoryEmbeddingProvider", "plugin compatibility registry and migration guide"];
readonly diagnostics: readonly ["plugin compatibility registry and migration guide"];
readonly tests: readonly ["src/plugins/compat/registry.test.ts"];
readonly releaseNote: "Memory-specific embedding provider registration was removed; plugins now use the generic embedding provider contract.";
}, {
readonly code: "deprecated-session-store-beta5-api";
readonly status: "deprecated";
readonly owner: "sdk";
readonly introduced: "2026-05-21";
readonly deprecated: "2026-07-12";
readonly warningStarts: "2026-07-12";
readonly removeAfter: "2026-10-12";
readonly replacement: "`getSessionEntry(...)`, `listSessionEntries(...)`, and row-level session mutations";
readonly docsPath: "/plugins/sdk-migration#removed-session-and-transcript-file-apis";
readonly surfaces: readonly ["openclaw/plugin-sdk/session-store-runtime loadSessionStore", "openclaw/plugin-sdk/session-store-runtime updateSessionStore", "openclaw/plugin-sdk/session-store-runtime resolveSessionFilePath", "openclaw/plugin-sdk/session-store-runtime resolveSessionStoreEntry", "openclaw package root loadSessionStore", "openclaw package root saveSessionStore"];
readonly diagnostics: readonly ["plugin SDK deprecation"];
readonly tests: readonly ["src/plugin-sdk/session-store-runtime.test.ts", "src/index.test.ts", "src/plugins/compat/registry.test.ts"];
readonly releaseNote: "The beta.5 session-store import set and package-root whole-store aliases remain available while official plugins and package consumers migrate to row-level session access.";
}, {
readonly code: "plugin-sdk-session-agent-resolution-aliases";
readonly status: "deprecated";
readonly owner: "sdk";
readonly introduced: "2026-08-29";
readonly deprecated: "2026-08-29";
readonly warningStarts: "2026-08-29";
readonly removeAfter: "2026-11-29";
readonly replacement: "`resolveSessionAgentIdsStrict` and `resolveSessionAgentIdStrict` with an explicit agent, agent-scoped session key, prepared fallback, or persisted owner";
readonly docsPath: "/plugins/compatibility#session-agent-resolution-aliases";
readonly surfaces: readonly ["openclaw/plugin-sdk/agent-scope-runtime resolveSessionAgentIds and resolveSessionAgentId", "openclaw/plugin-sdk/agent-runtime session-agent resolver aliases", "openclaw/plugin-sdk/agent-harness-runtime session-agent resolver aliases", "openclaw/plugin-sdk/memory-core-host-runtime-core session-agent resolver alias", "openclaw/plugin-sdk/memory-host-core session-agent resolver alias"];
readonly diagnostics: readonly ["TypeScript deprecated SDK alias annotations", "plugin compatibility registry"];
readonly tests: readonly ["src/plugin-sdk/agent-scope-runtime.test.ts", "src/plugins/compat/registry.test.ts"];
readonly releaseNote: "Legacy Plugin SDK session-agent resolver names preserve ambient system-agent fallback while published plugins migrate to strict owner-required aliases.";
}, {
readonly code: "removed-session-transcript-file-api";
readonly status: "removed";
readonly owner: "sdk";
readonly introduced: "2026-07-01";
readonly replacement: "session identity (`sessionKey`/`sessionId`), `SessionTranscriptUpdate.target`, and Gateway/runtime session helpers";
readonly docsPath: "/plugins/sdk-migration#removed-session-and-transcript-file-apis";
readonly surfaces: readonly ["saveSessionStore", "resolveSessionTranscriptPathInDir", "resolveAndPersistSessionFile", "readLatestAssistantTextFromSessionTranscript", "SessionTranscriptUpdate.sessionFile", "sessionFiles", "transcriptPath", "sessionFile", "plugins inspect compatibility notices"];
readonly diagnostics: readonly ["plugin compatibility notice"];
readonly tests: readonly ["src/plugins/status.test.ts", "src/plugins/compat/registry.test.ts"];
readonly releaseNote: "Session/transcript file APIs were removed with the SQLite session storage flip; plugins now use session identity and Gateway/runtime session helpers.";
}, {
readonly code: "hook.before_tool_call.terminal-block-approval";
readonly status: "active";
readonly owner: "agent-runtime";
readonly introduced: "2026-04-29";
readonly docsPath: "/plugins/hooks";
readonly surfaces: readonly ["before_tool_call block result", "before_tool_call approval result"];
readonly diagnostics: readonly ["hook runner contract probe"];
readonly tests: readonly ["src/plugins/hooks.security.test.ts", "src/agents/agent-tools.before-tool-call.e2e.test.ts"];
}, {
readonly code: "hook.llm-observer.privacy-payload";
readonly status: "active";
readonly owner: "agent-runtime";
readonly introduced: "2026-04-29";
readonly docsPath: "/plugins/hooks";
readonly surfaces: readonly ["llm_input", "llm_output", "agent_end", "allowConversationAccess"];
readonly diagnostics: readonly ["conversation access hook contract probe"];
readonly tests: readonly ["src/agents/cli-runner.reliability.test.ts", "src/config/schema.help.quality.test.ts"];
}, {
readonly code: "api.capture.runtime-registrars";
readonly status: "active";
readonly owner: "plugin-execution";
readonly introduced: "2026-04-29";
readonly docsPath: "/plugins/architecture-internals";
readonly surfaces: readonly ["createCapturedPluginRegistration", "capturePluginRegistration", "OpenClawPluginApi"];
readonly diagnostics: readonly ["runtime registration capture contract probe"];
readonly tests: readonly ["src/plugins/captured-registration.test.ts"];
}, {
readonly code: "channel.runtime.envelope-config-metadata";
readonly status: "active";
readonly owner: "channel";
readonly introduced: "2026-04-29";
readonly docsPath: "/plugins/sdk-channel-plugins";
readonly surfaces: readonly ["api.registerChannel", "channel setup metadata", "channel message envelope"];
readonly diagnostics: readonly ["channel runtime contract probe"];
readonly tests: readonly ["src/plugin-sdk/channel-entry-contract.test.ts", "src/plugins/captured-registration.test.ts"];
}, {
readonly code: "whatsapp-web-inbound-flat-message-aliases";
readonly status: "removed";
readonly owner: "channel";
readonly introduced: "2026-05-30";
readonly replacement: "WhatsApp `WebInboundCallbackMessage` nested contexts: `event`, `payload`, `quote`, `group`, and `platform`";
readonly docsPath: "/plugins/compatibility";
readonly surfaces: readonly ["@openclaw/whatsapp WebInboundMessage flat fields", "WhatsApp monitorWebInbox onMessage callback", "WhatsApp monitorWebChannel listenerFactory injected messages"];
readonly diagnostics: readonly ["plugin compatibility registry and compatibility guide"];
readonly tests: readonly ["src/plugins/compat/registry.test.ts"];
readonly releaseNote: "WhatsApp WebInboundMessage flat fields were removed; callbacks now receive only nested inbound contexts.";
}, {
readonly code: "whatsapp-web-inbound-admission-top-level-fields";
readonly status: "removed";
readonly owner: "channel";
readonly introduced: "2026-06-14";
readonly replacement: "WhatsApp `WebInboundMessage.admission` fields: `conversation.id`, `accountId`, `ingress.decision`, and `conversation.kind`";
readonly docsPath: "/plugins/compatibility";
readonly surfaces: readonly ["@openclaw/whatsapp WebInboundMessage top-level admission fields", "WhatsApp monitorWebInbox onMessage callback", "WhatsApp monitorWebChannel listenerFactory injected messages"];
readonly diagnostics: readonly ["plugin compatibility registry and compatibility guide"];
readonly tests: readonly ["src/plugins/compat/registry.test.ts"];
readonly releaseNote: "WhatsApp WebInboundMessage top-level admission fields were removed; callbacks now read the canonical admission envelope.";
}, {
readonly code: "sdk-untrusted-context-identifier-aliases";
readonly status: "deprecated";
readonly owner: "sdk";
readonly introduced: "2026-07-22";
readonly deprecated: "2026-07-22";
readonly warningStarts: "2026-07-22";
readonly removeAfter: "2026-09-08";
readonly replacement: "`MsgContext.ChannelPromptContext`, `MsgContext.ChannelStructuredContext`, `ChannelStructuredContextEntry`, `SupplementalContextFacts.channelStructuredContext`, and `buildChannelMetadata`";
readonly docsPath: "/plugins/compatibility";
readonly surfaces: readonly ["openclaw/plugin-sdk reply-runtime MsgContext.UntrustedContext and UntrustedStructuredContext", "openclaw/plugin-sdk reply-runtime UntrustedStructuredContextEntry", "openclaw/plugin-sdk channel-inbound SupplementalContextFacts.untrustedContext", "openclaw/plugin-sdk security-runtime buildUntrustedChannelMetadata"];
readonly diagnostics: readonly ["TypeScript deprecated SDK alias annotations"];
readonly tests: readonly ["src/auto-reply/reply/inbound-context.test.ts"];
readonly releaseNote: "Untrusted-named prompt-context SDK identifiers remain wired as deprecated aliases of the channel-named fields while plugins migrate.";
}, {
readonly code: "bundled-channel-sdk-compat-facades";
readonly status: "active";
readonly owner: "sdk";
readonly introduced: "2026-04-28";
readonly replacement: "generic channel SDK subpaths or plugin-local `api.ts` / `runtime-api.ts` barrels for new plugins";
readonly docsPath: "/plugins/sdk-overview";
readonly surfaces: readonly ["openclaw/plugin-sdk/discord component message helpers", "openclaw/plugin-sdk/telegram-account resolveTelegramAccount"];
readonly diagnostics: readonly ["plugin SDK compatibility registry"];
readonly tests: readonly ["src/plugin-sdk/discord.test.ts", "src/plugin-sdk/telegram-account.test.ts", "src/plugins/contracts/plugin-sdk-package-contract-guardrails.test.ts"];
}, {
readonly code: "channel-explicit-target-parser";
readonly status: "removed";
readonly owner: "sdk";
readonly introduced: "2026-04-28";
readonly replacement: "`messaging.targetResolver` for target normalization and `messaging.resolveOutboundSessionRoute` for session/thread identity";
readonly docsPath: "/plugins/sdk-migration";
readonly surfaces: readonly ["ChannelMessagingAdapter.parseExplicitTarget", "openclaw/plugin-sdk/channel-route ChannelRouteExplicitTarget", "openclaw/plugin-sdk/channel-route ChannelRouteExplicitTargetParser", "openclaw/plugin-sdk/channel-route resolveChannelRouteTargetWithParser"];
readonly diagnostics: readonly ["plugin SDK compatibility warning"];
readonly tests: readonly ["src/channels/plugins/contracts/test-helpers/surface-contract-suite.ts", "src/plugins/compat/registry.test.ts"];
readonly releaseNote: "The deprecated channel explicit-target parser was removed; plugins must normalize targets with `messaging.targetResolver` and project session identity with `messaging.resolveOutboundSessionRoute`.";
}, {
readonly code: "channel-messaging-targets-subpath";
readonly status: "removed";
readonly owner: "sdk";
readonly introduced: "2026-04-28";
readonly replacement: "`openclaw/plugin-sdk/channel-targets`";
readonly docsPath: "/plugins/sdk-migration";
readonly surfaces: readonly ["openclaw/plugin-sdk/messaging-targets"];
readonly diagnostics: readonly ["plugin SDK compatibility warning"];
readonly tests: readonly ["src/plugins/compat/registry.test.ts", "src/plugins/contracts/plugin-sdk-subpaths.test.ts"];
readonly releaseNote: "The deprecated `openclaw/plugin-sdk/messaging-targets` subpath was removed; import target helpers from `openclaw/plugin-sdk/channel-targets`.";
}, {
readonly code: "bundled-plugin-allowlist";
readonly status: "active";
readonly owner: "config";
readonly introduced: "2026-04-24";
readonly replacement: "manifest-owned plugin enablement and scoped load plans";
readonly docsPath: "/plugins/architecture";
readonly surfaces: readonly ["plugins.allow", "bundled provider startup", "plugins status"];
readonly diagnostics: readonly ["plugin status report"];
readonly tests: readonly ["src/plugins/status.test.ts", "src/plugins/config-state.test.ts"];
}, {
readonly code: "bundled-plugin-enablement";
readonly status: "active";
readonly owner: "config";
readonly introduced: "2026-04-24";
readonly replacement: "manifest-owned plugin defaults and scoped load plans";
readonly docsPath: "/plugins/architecture";
readonly surfaces: readonly ["plugins.entries", "bundled provider startup", "plugins status"];
readonly diagnostics: readonly ["plugin status report"];
readonly tests: readonly ["src/plugins/status.test.ts", "src/plugins/config-state.test.ts"];
}, {
readonly code: "activation-agent-harness-hint";
readonly status: "active";
readonly owner: "plugin-execution";
readonly introduced: "2026-04-24";
readonly replacement: "top-level `cliBackends[]` for CLI aliases and future `agentRuntime` ownership metadata";
readonly docsPath: "/plugins/manifest";
readonly surfaces: readonly ["activation.onAgentHarnesses", "activation planner"];
readonly diagnostics: readonly ["activation plan compat reason"];
readonly tests: readonly ["src/plugins/activation-planner.test.ts"];
}, {
readonly code: "activation-provider-hint";
readonly status: "active";
readonly owner: "plugin-execution";
readonly introduced: "2026-04-24";
readonly replacement: "`providers[]` manifest ownership";
readonly docsPath: "/plugins/manifest";
readonly surfaces: readonly ["activation.onProviders", "activation planner"];
readonly diagnostics: readonly ["activation plan compat reason"];
readonly tests: readonly ["src/plugins/activation-planner.test.ts"];
}, {
readonly code: "activation-channel-hint";
readonly status: "active";
readonly owner: "plugin-execution";
readonly introduced: "2026-04-24";
readonly replacement: "`channels[]` manifest ownership";
readonly docsPath: "/plugins/manifest";
readonly surfaces: readonly ["activation.onChannels", "activation planner"];
readonly diagnostics: readonly ["activation plan compat reason"];
readonly tests: readonly ["src/plugins/activation-planner.test.ts"];
}, {
readonly code: "activation-command-hint";
readonly status: "active";
readonly owner: "plugin-execution";
readonly introduced: "2026-04-24";
readonly replacement: "`commandAliases` or command contribution metadata";
readonly docsPath: "/plugins/manifest";
readonly surfaces: readonly ["activation.onCommands", "activation planner"];
readonly diagnostics: readonly ["activation plan compat reason"];
readonly tests: readonly ["src/plugins/activation-planner.test.ts"];
}, {
readonly code: "activation-route-hint";
readonly status: "active";
readonly owner: "plugin-execution";
readonly introduced: "2026-04-24";
readonly replacement: "HTTP route contribution metadata";
readonly docsPath: "/plugins/manifest";
readonly surfaces: readonly ["activation.onRoutes", "activation planner"];
readonly diagnostics: readonly ["activation plan compat reason"];
readonly tests: readonly ["src/plugins/activation-planner.test.ts"];
}, {
readonly code: "activation-config-path-hint";
readonly status: "active";
readonly owner: "plugin-execution";
readonly introduced: "2026-04-27";
readonly replacement: "manifest contribution ownership for root config surfaces";
readonly docsPath: "/plugins/manifest";
readonly surfaces: readonly ["activation.onConfigPaths", "startup plugin selection"];
readonly diagnostics: readonly ["activation plan compat reason"];
readonly tests: readonly ["src/plugins/channel-plugin-ids.test.ts"];
}, {
readonly code: "activation-capability-hint";
readonly status: "active";
readonly owner: "plugin-execution";
readonly introduced: "2026-04-24";
readonly replacement: "manifest contribution ownership";
readonly docsPath: "/plugins/manifest";
readonly surfaces: readonly ["activation.onCapabilities", "activation planner"];
readonly diagnostics: readonly ["activation plan compat reason"];
readonly tests: readonly ["src/plugins/activation-planner.test.ts"];
}, {
readonly code: "agent-harness-sdk-alias";
readonly status: "deprecated";
readonly owner: "agent-runtime";
readonly introduced: "2026-04-24";
readonly deprecated: "2026-04-25";
readonly warningStarts: "2026-04-25";
readonly replacement: "none yet; retain until a harness subpath ships and external migration is proven";
readonly docsPath: "/plugins/sdk-agent-harness";
readonly surfaces: readonly ["openclaw/plugin-sdk/agent-harness", "openclaw/plugin-sdk/agent-harness-runtime"];
readonly diagnostics: readonly ["plugin SDK compatibility warning"];
readonly tests: readonly ["src/plugins/contracts/plugin-sdk-subpaths.test.ts"];
}, {
readonly code: "embedded-pi-agent-sdk-aliases";
readonly status: "removed";
readonly owner: "agent-runtime";
readonly introduced: "2026-05-21";
readonly replacement: "`runEmbeddedAgent` and `EmbeddedAgent*` SDK/runtime names";
readonly docsPath: "/plugins/sdk-runtime";
readonly surfaces: readonly ["api.runtime.agent.runEmbeddedPiAgent", "openclaw/extension-api runEmbeddedPiAgent", "openclaw/plugin-sdk/agent-harness-runtime EmbeddedPi* aliases"];
readonly diagnostics: readonly ["plugin SDK compatibility registry"];
readonly tests: readonly ["src/plugins/runtime/index.test.ts", "src/plugins/contracts/plugin-sdk-subpaths.test.ts"];
readonly releaseNote: "The legacy `runEmbeddedPiAgent` and `EmbeddedPi*` plugin aliases were removed; plugins must use the neutral embedded-agent names.";
}, {
readonly code: "plugin-sdk-shipped-channel-setup-exports";
readonly status: "deprecated";
readonly owner: "channel";
readonly introduced: "2026-07-23";
readonly deprecated: "2026-07-23";
readonly warningStarts: "2026-07-23";
readonly replacement: "retain until supported published packages migrate to plugin-owned config schemas plus generic `openclaw/plugin-sdk/channel-config-schema` and `openclaw/plugin-sdk/setup-runtime` primitives";
readonly docsPath: "/plugins/sdk-migration#published-channel-setup-compatibility";
readonly surfaces: readonly ["openclaw/plugin-sdk/bundled-channel-config-schema SlackConfigSchema", "openclaw/plugin-sdk/bundled-channel-config-schema DiscordConfigSchema", "openclaw/plugin-sdk/bundled-channel-config-schema SignalConfigSchema", "openclaw/plugin-sdk/bundled-channel-config-schema MSTeamsConfigSchema", "openclaw/plugin-sdk/setup-runtime createLegacyCompatChannelDmPolicy", "openclaw/plugin-sdk/setup-runtime promptLegacyChannelAllowFromForAccount"];
readonly diagnostics: readonly ["repository deprecated API usage guard for core and bundled plugins; no external runtime import warning"];
readonly tests: readonly ["src/plugin-sdk/shipped-channel-compat.test.ts", "src/plugins/compat/registry.test.ts"];
readonly releaseNote: "Published OpenClaw channel packages through 2026.7.1 remain loadable while they migrate to plugin-owned config and setup helpers.";
}, {
readonly code: "generated-bundled-channel-config-fallback";
readonly status: "active";
readonly owner: "channel";
readonly introduced: "2026-04-24";
readonly replacement: "manifest registry `channelConfigs` metadata";
readonly docsPath: "/plugins/manifest";
readonly surfaces: readonly ["generated bundled channel config metadata", "channel config validation"];
readonly diagnostics: readonly ["channel config metadata fallback"];
readonly tests: readonly ["src/plugins/contracts/config-footprint-guardrails.test.ts"];
}, {
readonly code: "setup-runtime-fallback";
readonly status: "active";
readonly owner: "setup";
readonly introduced: "2026-04-24";
readonly replacement: "`setup.requiresRuntime: false` with complete setup descriptors";
readonly docsPath: "/plugins/manifest#setup-reference";
readonly surfaces: readonly ["setup-api runtime fallback", "setup.requiresRuntime omitted"];
readonly diagnostics: readonly ["setup registry runtime diagnostic"];
readonly tests: readonly ["src/plugins/setup-registry.test.ts", "src/plugins/setup-registry.runtime.test.ts"];
}];
//#endregion
//#region src/plugins/compat/registry.d.ts
type PluginCompatCode = (typeof PLUGIN_COMPAT_RECORDS)[number]["code"];
//#endregion
//#region src/infra/npm-registry-spec.d.ts
/**
* Parsed registry-only npm spec accepted by plugin install flows.
* Selectors are limited to exact versions and dist-tags; URL/git/file specs
* are rejected before they can execute on the gateway host.
*/
type ParsedRegistryNpmSpec = {
name: string;
raw: string;
selector?: string;
selectorKind: "none" | "exact-version" | "tag";
selectorIsPrerelease: boolean;
};
//#endregion
//#region src/plugins/install-source-info.types.d.ts
/** Warning emitted while describing plugin package install source metadata. */
type PluginInstallSourceWarning = "invalid-clawhub-spec" | "invalid-npm-spec" | "invalid-default-choice" | "default-choice-missing-source" | "clawhub-spec-floating" | "npm-integrity-without-source" | "npm-spec-floating" | "npm-spec-missing-integrity" | "npm-spec-package-name-mismatch";
/** Pinning state for npm plugin install metadata. */
type PluginInstallNpmPinState = "exact-with-integrity" | "exact-without-integrity" | "floating-with-integrity" | "floating-without-integrity";
/** Parsed npm install source metadata for a plugin package. */
type PluginInstallNpmSourceInfo = {
spec: string;
packageName: string;
expectedPackageName?: string;
selector?: string;
selectorKind: ParsedRegistryNpmSpec["selectorKind"];
exactVersion: boolean;
expectedIntegrity?: string;
pinState: PluginInstallNpmPinState;
};
/** Parsed local install source metadata for a plugin package. */
type PluginInstallLocalSourceInfo = {
path: string;
};
/** Parsed ClawHub install source metadata for a plugin package. */
type PluginInstallClawHubSourceInfo = {
spec: string;
packageName: string;
version?: string;
exactVersion: boolean;
};
/** Parsed plugin install sources plus validation warnings. */
type PluginInstallSourceInfo = {
defaultChoice?: PluginPackageInstall["defaultChoice"];
clawhub?: PluginInstallClawHubSourceInfo;
npm?: PluginInstallNpmSourceInfo;
local?: PluginInstallLocalSourceInfo;
warnings: readonly PluginInstallSourceWarning[];
};
//#endregion
//#region src/plugins/installed-plugin-index-hash.d.ts
/** File metadata signature used to skip unchanged installed plugin files. */
type InstalledPluginFileSignature = {
size: number;
mtimeMs: number;
ctimeMs?: number;
};
//#endregion
//#region src/plugins/plugin-trust.d.ts
/** Captured beside the trust decision; consumers never rediscover installation facts. */
type PluginTrust = {
reason: "bundled" | "trusted-official" | "record-missing" | "owner-ambiguous" | "origin-path" | "install-path-mismatch" | "provenance-missing" | "provenance-invalid";
registryPath: string | null;
origin: PluginOrigin | "unknown";
installSource?: PluginInstallRecord["source"];
installSpec?: string;
};
//#endregion
//#region src/plugins/manifest-registry.types.d.ts
type PluginManifestRecord = {
id: string;
/** Process-local source selection, never persisted in the installed index. */
sourcePreferred?: true;
backupResources?: PluginManifestBackupResource[];
name?: string;
description?: string;
catalog?: PluginManifestCatalog;
iconPath?: string;
version?: string;
packageName?: string;
packageVersion?: string;
packageDescription?: string;
enabledByDefault?: boolean;
enabledByDefaultOnPlatforms?: string[];
autoEnableWhenConfiguredProviders?: string[];
legacyPluginIds?: string[];
format?: PluginFormat;
bundleFormat?: PluginBundleFormat;
bundleCapabilities?: string[];
kind?: PluginKind | PluginKind[];
channels: string[];
providers: string[];
providerDiscoverySource?: string;
/** Undefined is undeclared; null retains a rejected declaration without enabling full-entry fallback. */
capabilityCatalogSource?: string | null;
modelSupport?: PluginManifestModelSupport;
modelCatalog?: PluginManifestModelCatalog;
modelPricing?: PluginManifestModelPricing;
modelIdNormalization?: PluginManifestModelIdNormalization;
providerEndpoints?: PluginManifestProviderEndpoint[];
providerRequest?: PluginManifestProviderRequest;
secretProviderIntegrations?: Record<string, PluginManifestSecretProviderIntegration>;
cliBackends: string[];
syntheticAuthRefs?: string[];
nonSecretAuthMarkers?: string[];
commandAliases?: PluginManifestCommandAlias[];
cliCommands?: PluginManifest["cliCommands"];
providerUsageAuthEnvVars?: Record<string, string[]>;
providerAuthAliases?: Record<string, string>;
providerAuthChoices?: PluginManifest["providerAuthChoices"];
activation?: PluginManifestActivation;
setup?: PluginManifestSetup;
doctorContract?: PluginManifestDoctorContract;
doctorHealthChecks?: boolean;
sessionRouteStateOwners?: DoctorSessionRouteStateOwner[];
packageManifest?: OpenClawPackageManifest;
packageDependencies?: PluginDependencySpecMap;
packageOptionalDependencies?: PluginDependencySpecMap;
packageChannel?: PluginPackageChannel;
packageInstall?: PluginPackageInstall;
trustedOfficialInstall?: boolean;
trust?: PluginTrust;
qaRunners?: PluginManifestQaRunner[];
dashboard?: PluginManifestDashboard;
controlUi?: PluginManifestControlUi;
mcpServers?: Record<string, PluginManifestMcpServer>;
skills: string[];
settingsFiles?: string[];
hooks: string[];
origin: PluginOrigin;
workspaceDir?: string;
rootDir: string;
source: string;
setupSource?: string;
manifestPath: string;
schemaCacheKey?: string;
configSchema?: Record<string, unknown>;
configUiHints?: Record<string, PluginConfigUiHint>;
contracts?: PluginManifestContracts;
mediaUnderstandingProviderMetadata?: Record<string, PluginManifestMediaUnderstandingProviderMetadata>;
imageGenerationProviderMetadata?: Record<string, PluginManifestCapabilityProviderMetadata>;
videoGenerationProviderMetadata?: Record<string, PluginManifestCapabilityProviderMetadata>;
musicGenerationProviderMetadata?: Record<string, PluginManifestCapabilityProviderMetadata>;
toolMetadata?: Record<string, PluginManifestToolMetadata>;
configContracts?: PluginManifestConfigContracts;
channelConfigs?: Record<string, PluginManifestChannelConfig>;
channelCatalogMeta?: {
id: string;
label?: string;
blurb?: string;
preferOver?: readonly string[];
commands?: PluginManifestChannelCommandDefaults;
};
};
type PluginManifestRegistry = {
plugins: PluginManifestRecord[];
diagnostics: PluginDiagnostic[];
};
//#endregion
//#region src/plugins/installed-plugin-index-types.d.ts
/** Schema version for installed plugin index files. */
declare const INSTALLED_PLUGIN_INDEX_VERSION = 1;
declare const INSTALLED_PLUGIN_INDEX_MIGRATION_VERSION = 1;
type InstalledPluginIndexRefreshReason = "missing" | "stale-manifest" | "stale-package" | "source-changed" | "policy-changed" | "migration" | "host-contract-changed" | "compat-registry-changed" | "manual";
type InstalledPluginStartupInfo = {
sidecar: boolean;
memory: boolean;
agentHarnesses: readonly string[];
/**
* Manifest activation.onConfigPaths copied into the installed index for
* pre-manifest startup scoping. Missing on older persisted index files.
*/
configPaths?: readonly string[];
};
type InstalledPluginContributionInfo = {
channels: readonly string[];
channelConfigs: readonly string[];
providers: readonly string[];
modelCatalogProviders: readonly string[];
modelSupportPrefixes: readonly string[];
modelSupportPatterns: readonly string[];
autoEnableProviderIds: readonly string[];
commandAliases: readonly string[];
contracts: Readonly<Record<string, readonly string[]>>;
};
type InstalledPluginInstallRecordInfo = Pick<PluginInstallRecord, "source" | "spec" | "sourcePath" | "installPath" | "version" | "resolvedName" | "resolvedVersion" | "resolvedSpec" | "integrity" | "shasum" | "resolvedAt" | "installedAt" | "clawhubUrl" | "clawhubPackage" | "clawhubFamily" | "clawhubChannel" | "clawhubTrustDisposition" | "clawhubTrustScanStatus" | "clawhubTrustModerationState" | "clawhubTrustReasons" | "clawhubTrustPending" | "clawhubTrustStale" | "clawhubTrustCheckedAt" | "clawhubTrustAcknowledgedAt" | "artifactKind" | "artifactFormat" | "npmIntegrity" | "npmShasum" | "npmTarballName" | "clawpackSha256" | "clawpackSpecVersion" | "clawpackManifestSha256" | "clawpackSize" | "gitUrl" | "gitRef" | "gitCommit" | "marketplaceName" | "marketplaceSource" | "marketplacePlugin" | "acceptedSurface" | "acceptedSurfaceHash" | "acceptedSurfaceAt" | "acceptedSurfaceIntegrity">;
type InstalledPluginPackageChannelInfo = PluginPackageChannel;
/** One manifest-backed plugin entry in the generated installed plugin index. */
type InstalledPluginIndexRecord = {
pluginId: string;
packageName?: string;
packageVersion?: string;
/**
* Legacy embedded install record accepted when reading earlier index files.
* New index writes keep install records in InstalledPluginIndex.installRecords.
*/
installRecord?: InstalledPluginInstallRecordInfo;
/** Hash of the top-level installRecords entry; used to detect source-changed invalidation. */
installRecordHash?: string;
/**
* Package-authored openclaw.install metadata. This describes catalog/package
* install intent and must not be treated as the durable install record.
*/
packageInstall?: PluginInstallSourceInfo;
packageChannel?: InstalledPluginPackageChannelInfo;
packageBuild?: OpenClawPackageBuild;
manifestPath: string;
manifestHash: string;
/** Hash of the doctor-contract artifact selected by the runtime resolver. */
doctorContractHash?: string;
doctorContractFile?: InstalledPluginFileSignature;
manifestFile?: InstalledPluginFileSignature;
format?: PluginManifestRecord["format"];
bundleFormat?: PluginManifestRecord["bundleFormat"];
source?: string;
setupSource?: string;
packageJson?: {
path: string;
hash: string;
fileSignature?: InstalledPluginFileSignature;
};
rootDir: string;
origin: PluginManifestRecord["origin"];
enabled: boolean;
enabledByDefault?: boolean;
enabledByDefaultOnPlatforms?: readonly string[];
syntheticAuthRefs?: readonly string[];
startup: InstalledPluginStartupInfo;
contributions?: InstalledPluginContributionInfo;
compat: readonly PluginCompatCode[];
};
/** Full installed-index payload used by control-plane plugin registry loading. */
type InstalledPluginIndex = {
version: typeof INSTALLED_PLUGIN_INDEX_VERSION;
warning?: string;
hostContractVersion: string;
compatRegistryVersion: string;
migrationVersion: typeof INSTALLED_PLUGIN_INDEX_MIGRATION_VERSION;
policyHash: string;
generatedAtMs: number;
/** Selected workspace used to build this index. Missing for omitted and legacy scopes. */
workspaceDir?: string;
refreshReason?: InstalledPluginIndexRefreshReason;
installRecords: Readonly<Record<string, InstalledPluginInstallRecordInfo>>;
plugins: readonly InstalledPluginIndexRecord[];
diagnostics: readonly PluginDiagnostic[];
};
//#endregion
//#region src/plugins/plugin-registry-snapshot.types.d.ts
/** Source class for plugin registry snapshots used by diagnostics and cache decisions. */
type PluginRegistrySnapshotSource = "provided" | "persisted" | "derived";
type PluginRegistryDifference = {
pluginId: string;
persistedSource: string | null;
derivedSource: string | null;
};
type PluginRegistrySnapshotDiagnostic = {
level: "info" | "warn";
code: "persisted-registry-missing" | "persisted-registry-stale-policy" | "persisted-registry-stale-source";
message: string;
differences?: readonly PluginRegistryDifference[];
};
//#endregion
//#region src/plugins/plugin-metadata-snapshot.types.d.ts
type PluginProviderAuthAliasCandidate = {
plugin: PluginManifestRecord;
target: string;
/** First eligible declaration owns public map order, even if a later candidate wins. */
order: number;
};
type PluginMetadataSnapshotOwnerMaps = {
channels: ReadonlyMap<string, readonly string[]>;
channelConfigs: ReadonlyMap<string, readonly string[]>;
providers: ReadonlyMap<string, readonly string[]>;
modelCatalogProviders: ReadonlyMap<string, readonly string[]>;
cliBackends: ReadonlyMap<string, readonly string[]>;
setupProviders: ReadonlyMap<string, readonly string[]>;
commandAliases: ReadonlyMap<string, readonly string[]>;
contracts: ReadonlyMap<string, readonly string[]>;
/** Empty views must not fall through to process-current model normalization policies. */
modelIdNormalizationPolicies: ReadonlyMap<string, PluginManifestModelIdNormalizationProvider>;
providerAuthAliases?: ReadonlyMap<string, readonly PluginProviderAuthAliasCandidate[]>;
providerEndpoints?: readonly PluginManifestProviderEndpoint[];
providerRequests?: ReadonlyMap<string, PluginManifestProviderRequestProvider>;
};
type PluginMetadataSnapshotMetrics = {
registrySnapshotMs: number;
manifestRegistryMs: number;
ownerMapsMs: number;
totalMs: number;
indexPluginCount: number;
manifestPluginCount: number;
};
type PluginMetadataSnapshot = {
policyHash: string;
configFingerprint?: string;
pluginIds?: readonly string[];
registrySource?: PluginRegistrySnapshotSource;
workspaceDir?: string;
index: InstalledPluginIndex;
/** The original workspace-scoped index described by registrySource, before runtime unions. */
registryIndex: InstalledPluginIndex;
registryDiagnostics: readonly PluginRegistrySnapshotDiagnostic[];
manifestRegistry: PluginManifestRegistry;
/** Independently validated bundled owners, including packages shadowed by active plugins. */
bundledManifestRegistry?: PluginManifestRegistry;
plugins: readonly PluginManifestRecord[];
diagnostics: readonly PluginDiagnostic[];
byPluginId: ReadonlyMap<string, PluginManifestRecord>;
normalizePluginId: (pluginId: string) => string;
owners: PluginMetadataSnapshotOwnerMaps;
metrics: PluginMetadataSnapshotMetrics;
discovery?: PluginDiscoveryResult;
};
type PluginMetadataRegistryView = Pick<PluginMetadataSnapshot, "index" | "manifestRegistry" | "discovery">;
//#endregion
//#region src/config/runtime-snapshot.d.ts
type ConfigWriteAfterWrite = {
mode: "auto";
} | {
mode: "restart";
reason: string;
} | {
mode: "none";
reason: string;
};
type ConfigWriteFollowUp = {
mode: "auto";
requiresRestart: false;
} | {
mode: "none";
reason: string;
requiresRestart: false;
} | {
mode: "restart";
reason: string;
requiresRestart: true;
};
//#endregion
//#region src/config/mutate.d.ts
type ConfigReplaceResult = {
path: string;
previousHash: string | null;
snapshot: ConfigFileSnapshot;
nextConfig: OpenClawConfig;
persistedHash: string | null;
afterWrite: ConfigWriteAfterWrite;
followUp: ConfigWriteFollowUp;
};
//#endregion
//#region src/config/paths.d.ts
/**
* State directory for mutable data (sessions, logs, caches).
* Can be overridden via OPENCLAW_STATE_DIR.
* Default: ~/.openclaw
*/
declare function resolveStateDir(env?: NodeJS.ProcessEnv, homedir?: () => string): string;
//#endregion
//#region packages/normalization-core/src/result.d.ts
/** Result of a fallible operation. Expected failures use the `ok: false` arm. */
type Result<TValue, TError> = {
ok: true;
value: TValue;
} | {
ok: false;
error: TError;
};
//#endregion
//#region src/channels/ids.d.ts
/**
* Canonical chat channel id used by core routing, plugin config, and channel catalogs.
*/
type ChatChannelId = string;
//#endregion
//#region src/channels/plugins/channel-id.types.d.ts
/**
* Channel id accepted by plugin helpers, covering built-in chat ids and external plugin ids.
*/
type ChannelId = ChatChannelId | (string & {});
//#endregion
//#region packages/gateway-protocol/src/schema/skill-library.d.ts
declare const SkillLibraryFileSchema: Type.TObject<{
path: Type.TString;
content: Type.TString;
encoding: Type.TOptional<Type.TUnion<[Type.TLiteral<"utf8">, Type.TLiteral<"base64">]>>;
executable: Type.TOptional<Type.TBoolean>;
}>;
declare const SkillLibrarySelectionSchema: Type.TObject<{
skillId: Type.TString;
revision: Type.TString;
/** Persisted command identity: library collisions never shadow workspace names. */
name: Type.TString;
ownerProfileId: Type.TUnion<[Type.TString, Type.TNull]>;
}>;
type SkillLibraryFile = Static<typeof SkillLibraryFileSchema>;
type SkillLibrarySelection = Static<typeof SkillLibrarySelectionSchema>;
type SkillLibraryEntry = {
skillId: string;
slug: string;
name: string;
description: string;
ownerProfileId: string | null;
ownerLabel: string;
authorProfileId: string;
shared: boolean;
enabled: boolean;
removed: boolean;
revision: string;
createdAt: number;
updatedAt: number;
canEdit: boolean;
};
type SkillsLibraryListResult = {
entries: SkillLibraryEntry[];
profileId: string | null;
multipleProfiles: boolean;
defaultTarget: "workspace" | "personal" | "unavailable";
canManageWorkspace: boolean;
defaultSelectionLimit: number;
defaultSelectionNotice?: string;
session?: {
sessionKey: string;
selections: Array<SkillLibrarySelection & {
slug: string;
description: string;
ownerLabel: string;
}>;
attachable: SkillLibraryEntry[];
};
};
type SkillsLibraryReadResult = {
entry: SkillLibraryEntry;
content: string;
files: SkillLibraryFile[];
revisions: Array<{
revision: string;
createdAt: number;
}>;
};
type SkillsLibraryReceipt = {
state: "published" | "unchanged" | "removed";
target: "personal" | "team";
entry: SkillLibraryEntry;
sessionActivation: "new-sessions";
nextAction: string;
};
type SkillsLibraryActivateResult = {
sessionKey: string;
selections: SkillLibrarySelection[];
sessionActivation: "next-turn";
};
//#endregion
//#region src/config/sessions/session-diff-baseline-capture.d.ts
type SessionDiffBaselineCapture = {
version: 1;
captureId: string;
status: "pending" | "unavailable";
};
//#endregion
//#region packages/acp-core/src/types.d.ts
type SessionAcpIdentitySource = "ensure" | "status" | "event";
type SessionAcpIdentityState = "pending" | "resolved";
type SessionAcpIdentity = {
/** Pending identities may expose provisional ids; resolved identities are safe for resume output. */
state: SessionAcpIdentityState;
acpxRecordId?: string;
acpxSessionId?: string;
agentSessionId?: string;
/** Runtime lifecycle point that last supplied the identity fields. */
source: SessionAcpIdentitySource;
lastUpdatedAt: number;
};
type AcpSessionRuntimeOptions = {
/**
* ACP runtime mode set via session/set_mode (for example: "plan", "normal", "auto").
*/
runtimeMode?: string;
/** ACP runtime config option: model id. */
model?: string;
/** ACP runtime config option: thinking/reasoning effort. */
thinking?: string;
/** Working directory override for ACP session turns. */
cwd?: string;
/** ACP runtime config option: permission profile id. */
permissionProfile?: string;
/** ACP runtime config option: per-turn timeout in seconds. */
timeoutSeconds?: number;
/** Backend-specific option bag mapped through session/set_config_option. */
backendExtras?: Record<string, string>;
};
type SessionAcpMeta = {
backend: string;
agent: string;
runtimeSessionName: string;
/** Canonical backend/agent ids used for resume hints and thread/status details. */
identity?: SessionAcpIdentity;
mode: "persistent" | "oneshot";
runtimeOptions?: AcpSessionRuntimeOptions;
cwd?: string;
state: "idle" | "running" | "error";
lastActivityAt: number;
lastError?: string;
};
//#endregion
//#region packages/gateway-protocol/src/schema/frames.d.ts
/** Initial client hello/connect payload sent before the gateway accepts frames. */
declare const ConnectParamsSchema: Type.TObject<{
minProtocol: Type.TInteger;
maxProtocol: Type.TInteger;
client: Type.TObject<{
id: Type.TEnum<["openclaw-android", "openclaw-browser-copilot", "cli", "openclaw-control-ui", "fingerprint", "gateway-client", "openclaw-ios", "openclaw-linux", "openclaw-macos", "node-host", "openclaw-probe", "test", "openclaw-tui", "openclaw-watchos", "webchat", "webchat-ui", "openclaw-worker"]>;
displayName: Type.TOptional<Type.TString>;
version: Type.TString;
buildId: Type.TOptional<Type.TString>;
platform: Type.TString;
deviceFamily: Type.TOptional<Type.TString>;
modelIdentifier: Type.TOptional<Type.TString>;
/** Self-reported IANA zone. Bounded because the longest real name is well under this cap. */
timeZone: Type.TOptional<Type.TString>;
mode: Type.TEnum<["backend", "cli", "node", "probe", "test", "ui", "webchat", "worker"]>;
instanceId: Type.TOptional<Type.TString>;
}>;
caps: Type.TOptional<Type.TArray<Type.TString>>;
commands: Type.TOptional<Type.TArray<Type.TString>>;
/** Additive Computer Use declaration; the owning core contract validates its bounded shape. */
computerUse: Type.TOptional<Type.TUnknown>;
/** @deprecated Accepted for the shipped v1 node-host envelope; current hosts use runner inventory. */
workerRuns: Type.TOptional<Type.TObject<{
bundleHash: Type.TString;
openclawVersion: Type.TString;
protocolFeatures: Type.TArray<Type.TString>;
bundlePrewarm: Type.TOptional<Type.TInteger>;
}>>;
permissions: Type.TOptional<Type.TRecord<"^.*$", Type.TBoolean>>;
pathEnv: Type.TOptional<Type.TString>;
role: Type.TOptional<Type.TString>;
scopes: Type.TOptional<Type.TArray<Type.TString>>;
device: Type.TOptional<Type.TObject<{
id: Type.TString;
publicKey: Type.TString;
signature: Type.TString;
signedAt: Type.TInteger;
nonce: Type.TString;
}>>;
auth: Type.TOptional<Type.TObject<{
token: Type.TOptional<Type.TString>;
bootstrapToken: Type.TOptional<Type.TString>;
deviceToken: Type.TOptional<Type.TString>;
password: Type.TOptional<Type.TString>;
approvalRuntimeToken: Type.TOptional<Type.TString>;
agentRuntimeIdentityToken: Type.TOptional<Type.TString>;
}>>;
locale: Type.TOptional<Type.TString>;
userAgent: Type.TOptional<Type.TString>;
}>;
/** Standard structured error shape used in response frames and connect failures. */
declare const ErrorShapeSchema: Type.TObject<{
code: Type.TString;
message: Type.TString;
details: Type.TOptional<Type.TUnknown>;
retryable: Type.TOptional<Type.TBoolean>;
retryAfterMs: Type.TOptional<Type.TInteger>;
}>;
/** Client request frame envelope; `method` selects the payload validator. */
declare const RequestFrameSchema: Type.TObject<{
type: Type.TLiteral<"req">;
id: Type.TString;
method: Type.TString;
params: Type.TOptional<Type.TUnknown>;
traceparent: Type.TOptional<Type.TString>;
}>;
type ConnectParams = Static<typeof ConnectParamsSchema>;
type ErrorShape = Static<typeof ErrorShapeSchema>;
type RequestFrame = Static<typeof RequestFrameSchema>;
//#endregion
//#region packages/gateway-protocol/src/schema/session-github-publication.d.ts
declare const GitHubPublicationPublisherSchema: Type.TObject<{
accountId: Type.TInteger;
login: Type.TString;
source: Type.TUnion<[Type.TLiteral<"personal">, Type.TLiteral<"system-detected">, Type.TLiteral<"system-configured">, Type.TLiteral<"agent-override">]>;
}>;
declare const SessionGitHubPublishParamsSchema: Type.TObject<{
sessionKey: Type.TOptional<Type.TString>;
agentId: Type.TOptional<Type.TString>;
idempotencyKey: Type.TString;
title: Type.TOptional<Type.TString>;
body: Type.TOptional<Type.TString>;
selection: Type.TOptional<Type.TUnion<[Type.TObject<{
source: Type.TLiteral<"shared">;
expected: Type.TOptional<Type.TObject<{
accountId: Type.TInteger;
login: Type.TString;
source: Type.TUnion<[Type.TLiteral<"system-detected">, Type.TLiteral<"system-configured">, Type.TLiteral<"agent-override">]>;
}>>;
}>, Type.TObject<{
source: Type.TLiteral<"personal">;
generation: Type.TString;
account: Type.TObject<{
accountId: Type.TInteger;
login: Type.TString;
}>;
}>]>>;
}>;
declare const SessionGitHubPublicationResultSchema: Type.TUnion<[Type.TObject<{
requestId: Type.TString;
publisher: Type.TOptional<Type.TObject<{
accountId: Type.TInteger;
login: Type.TString;
source: Type.TUnion<[Type.TLiteral<"personal">, Type.TLiteral<"system-detected">, Type.TLiteral<"system-configured">, Type.TLiteral<"agent-override">]>;
}>>;
effect: Type.TOptional<Type.TObject<{
kind: Type.TUnion<[Type.TLiteral<"push">, Type.TLiteral<"pull_request">]>;
status: Type.TUnion<[Type.TLiteral<"dispatched">, Type.TLiteral<"observed">]>;
headCommit: Type.TOptional<Type.TString>;
url: Type.TOptional<Type.TString>;
}>>;
status: Type.TLiteral<"requested">;
message: Type.TString;
}>, Type.TObject<{
requestId: Type.TString;
publisher: Type.TOptional<Type.TObject<{
accountId: Type.TInteger;
login: Type.TString;
source: Type.TUnion<[Type.TLiteral<"personal">, Type.TLiteral<"system-detected">, Type.TLiteral<"system-configured">, Type.TLiteral<"agent-override">]>;
}>>;
effect: Type.TOptional<Type.TObject<{
kind: Type.TUnion<[Type.TLiteral<"push">, Type.TLiteral<"pull_request">]>;
status: Type.TUnion<[Type.TLiteral<"dispatched">, Type.TLiteral<"observed">]>;
headCommit: Type.TOptional<Type.TString>;
url: Type.TOptional<Type.TString>;
}>>;
status: Type.TLiteral<"publishing">;
message: Type.TString;
}>, Type.TObject<{
requestId: Type.TString;
publisher: Type.TOptional<Type.TObject<{
accountId: Type.TInteger;
login: Type.TString;
source: Type.TUnion<[Type.TLiteral<"personal">, Type.TLiteral<"system-detected">, Type.TLiteral<"system-configured">, Type.TLiteral<"agent-override">]>;
}>>;
effect: Type.TOptional<Type.TObject<{
kind: Type.TUnion<[Type.TLiteral<"push">, Type.TLiteral<"pull_request">]>;
status: Type.TUnion<[Type.TLiteral<"dispatched">, Type.TLiteral<"observed">]>;
headCommit: Type.TOptional<Type.TString>;
url: Type.TOptional<Type.TString>;
}>>;
status: Type.TLiteral<"published">;
url: Type.TString;
repository: Type.TString;
branch: Type.TString;
headCommit: Type.TString;
}>, Type.TObject<{
requestId: Type.TString;
publisher: Type.TOptional<Type.TObject<{
accountId: Type.TInteger;
login: Type.TString;
source: Type.TUnion<[Type.TLiteral<"personal">, Type.TLiteral<"system-detected">, Type.TLiteral<"system-configured">, Type.TLiteral<"agent-override">]>;
}>>;
effect: Type.TOptional<Type.TObject<{
kind: Type.TUnion<[Type.TLiteral<"push">, Type.TLiteral<"pull_request">]>;
status: Type.TUnion<[Type.TLiteral<"dispatched">, Type.TLiteral<"observed">]>;
headCommit: Type.TOptional<Type.TString>;
url: Type.TOptional<Type.TString>;
}>>;
status: Type.TLiteral<"failed">;
code: Type.TUnion<[Type.TLiteral<"identity_changed">, Type.TLiteral<"identity_unavailable">, Type.TLiteral<"session_changed">, Type.TLiteral<"workspace_changed">, Type.TLiteral<"not_git">, Type.TLiteral<"not_github">, Type.TLiteral<"no_changes">, Type.TLiteral<"push_rejected">, Type.TLiteral<"github_rejected">, Type.TLiteral<"unavailable">]>;
message: Type.TString;
nextAction: Type.TString;
}>, Type.TObject<{
requestId: Type.TString;
publisher: Type.TOptional<Type.TObject<{
accountId: Type.TInteger;
login: Type.TString;
source: Type.TUnion<[Type.TLiteral<"personal">, Type.TLiteral<"system-detected">, Type.TLiteral<"system-configured">, Type.TLiteral<"agent-override">]>;
}>>;
effect: Type.TOptional<Type.TObject<{
kind: Type.TUnion<[Type.TLiteral<"push">, Type.TLiteral<"pull_request">]>;
status: Type.TUnion<[Type.TLiteral<"dispatched">, Type.TLiteral<"observed">]>;
headCommit: Type.TOptional<Type.TString>;
url: Type.TOptional<Type.TString>;
}>>;
status: Type.TLiteral<"needs_confirmation">;
message: Type.TString;
}>]>;
declare const SessionGitHubConfirmParamsSchema: Type.TObject<{
sessionKey: Type.TString;
agentId: Type.TOptional<Type.TString>;
requestId: Type.TString;
generation: Type.TString;
account: Type.TObject<{
accountId: Type.TInteger;
login: Type.TString;
}>;
requestDigest: Type.TString;
}>;
type GitHubPublicationPublisher = Static<typeof GitHubPublicationPublisherSchema>;
type SessionGitHubConfirmParams = Static<typeof SessionGitHubConfirmParamsSchema>;
type SessionGitHubPublishParams = Static<typeof SessionGitHubPublishParamsSchema>;
type SessionGitHubPublicationResult = Static<typeof SessionGitHubPublicationResultSchema>;
//#endregion
//#region packages/gateway-protocol/src/session-agent-status.d.ts
declare const SESSION_AGENT_ATTENTION_ICON_IDS: readonly ["hand", "key", "alert", "flag", "lock", "hourglass"];
type SessionAgentAttentionIconId = (typeof SESSION_AGENT_ATTENTION_ICON_IDS)[number];
type SessionAgentStatus = {
note: string;
expiresAt: number;
attention?: SessionAgentAttentionIconId;
};
//#endregion
//#region packages/gateway-protocol/src/schema/approvals.d.ts
/**
* Owner-declared blast-radius facts for a pending approval. Variants are
* named schemas so native protocol generators emit the discriminated union.
*/
declare const ApprovalScopeSchema: Type.TUnion<[Type.TObject<{
kind: Type.TLiteral<"message-send">;
target: Type.TString;
recipientCount: Type.TInteger;
recipients: Type.TOptional<Type.TArray<Type.TString>>;
audience: Type.TOptional<Type.TUnion<[Type.TLiteral<"internal">, Type.TLiteral<"external">]>>;
}>, Type.TObject<{
kind: Type.TLiteral<"payment">;
amount: Type.TString;
currency: Type.TString;
target: Type.TString;
}>, Type.TObject<{
kind: Type.TLiteral<"external-post">;
target: Type.TString;
visibility: Type.TUnion<[Type.TLiteral<"public">, Type.TLiteral<"restricted">]>;
}>, Type.TObject<{
kind: Type.TLiteral<"standing-grant">;
automation: Type.TString;
command: Type.TString;
expiresInDays: Type.TOptional<Type.TInteger>;
}>]>;
/** Reviewer-safe presentation discriminated by the approval owner. */
declare const ApprovalPresentationSchema: Type.TUnion<[Type.TObject<{
kind: Type.TLiteral<"exec">;
commandText: Type.TString;
commandPreview: Type.TOptional<Type.TUnion<[Type.TString, Type.TNull]>>;
warningText: Type.TOptional<Type.TUnion<[Type.TString, Type.TNull]>>;
host: Type.TOptional<Type.TUnion<[Type.TString, Type.TNull]>>;
nodeId: Type.TOptional<Type.TUnion<[Type.TString, Type.TNull]>>;
agentId: Type.TOptional<Type.TUnion<[Type.TString, Type.TNull]>>;
scope: Type.TOptional<Type.TUnion<[Type.TObject<{
kind: Type.TLiteral<"message-send">;
target: Type.TString;
recipientCount: Type.TInteger;
recipients: Type.TOptional<Type.TArray<Type.TString>>;
audience: Type.TOptional<Type.TUnion<[Type.TLiteral<"internal">, Type.TLiteral<"external">]>>;
}>, Type.TObject<{
kind: Type.TLiteral<"payment">;
amount: Type.TString;
currency: Type.TString;
target: Type.TString;
}>, Type.TObject<{
kind: Type.TLiteral<"external-post">;
target: Type.TString;
visibility: Type.TUnion<[Type.TLiteral<"public">, Type.TLiteral<"restricted">]>;
}>, Type.TObject<{
kind: Type.TLiteral<"standing-grant">;
automation: Type.TString;
command: Type.TString;
expiresInDays: Type.TOptional<Type.TInteger>;
}>]>>;
allowedDecisions: Type.TArray<Type.TUnion<[Type.TLiteral<"allow-once">, Type.TLiteral<"allow-always">, Type.TLiteral<"deny">]>>;
}>, Type.TObject<{
kind: Type.TLiteral<"plugin">;
title: Type.TString;
description: Type.TString;
detail: Type.TOptional<Type.TString>;
severity: Type.TUnion<[Type.TLiteral<"info">, Type.TLiteral<"warning">, Type.TLiteral<"critical">]>;
pluginId: Type.TOptional<Type.TUnion<[Type.TString, Type.TNull]>>;
toolName: Type.TOptional<Type.TUnion<[Type.TString, Type.TNull]>>;
agentId: Type.TOptional<Type.TUnion<[Type.TString, Type.TNull]>>;
scope: Type.TOptional<Type.TUnion<[Type.TObject<{
kind: Type.TLiteral<"message-send">;
target: Type.TString;
recipientCount: Type.TInteger;
recipients: Type.TOptional<Type.TArray<Type.TString>>;
audience: Type.TOptional<Type.TUnion<[Type.TLiteral<"internal">, Type.TLiteral<"external">]>>;
}>, Type.TObject<{
kind: Type.TLiteral<"payment">;
amount: Type.TString;
currency: Type.TString;
target: Type.TString;
}>, Type.TObject<{
kind: Type.TLiteral<"external-post">;
target: Type.TString;
visibility: Type.TUnion<[Type.TLiteral<"public">, Type.TLiteral<"restricted">]>;
}>, Type.TObject<{
kind: Type.TLiteral<"standing-grant">;
automation: Type.TString;
command: Type.TString;
expiresInDays: Type.TOptional<Type.TInteger>;
}>]>>;
allowedDecisions: Type.TArray<Type.TUnion<[Type.TLiteral<"allow-once">, Type.TLiteral<"allow-always">, Type.TLiteral<"deny">]>>;
externalResolution: Type.TOptional<Type.TObject<{
label: Type.TString;
decisions: Type.TArray<Type.TUnion<[Type.TLiteral<"allow-once">, Type.TLiteral<"allow-always">]>>;
}>>;
}>, Type.TObject<{
kind: Type.TLiteral<"system-agent">;
title: Type.TString;
description: Type.TString;
proposalHash: Type.TString;
agentId: Type.TOptional<Type.TUnion<[Type.TString, Type.TNull]>>;
allowedDecisions: Type.TTuple<[Type.TLiteral<"allow-once">, Type.TLiteral<"deny">]>;
}>]>;
/** Authoritative pending approval set returned when a session stream subscribes. */
declare const SessionApprovalReplaySchema: Type.TObject<{
sessionKey: Type.TString;
updatedAtMs: Type.TInteger;
approvals: Type.TArray<Type.TObject<{
id: Type.TString;
urlPath: Type.TString;
createdAtMs: Type.TInteger;
expiresAtMs: Type.TInteger;
presentation: Type.TUnion<[Type.TObject<{
kind: Type.TLiteral<"exec">;
commandText: Type.TString;
commandPreview: Type.TOptional<Type.TUnion<[Type.TString, Type.TNull]>>;
warningText: Type.TOptional<Type.TUnion<[Type.TString, Type.TNull]>>;
host: Type.TOptional<Type.TUnion<[Type.TString, Type.TNull]>>;
nodeId: Type.TOptional<Type.TUnion<[Type.TString, Type.TNull]>>;
agentId: Type.TOptional<Type.TUnion<[Type.TString, Type.TNull]>>;
scope: Type.TOptional<Type.TUnion<[Type.TObject<{
kind: Type.TLiteral<"message-send">;
target: Type.TString;
recipientCount: Type.TInteger;
recipients: Type.TOptional<Type.TArray<Type.TString>>;
audience: Type.TOptional<Type.TUnion<[Type.TLiteral<"internal">, Type.TLiteral<"external">]>>;
}>, Type.TObject<{
kind: Type.TLiteral<"payment">;
amount: Type.TString;
currency: Type.TString;
target: Type.TString;
}>, Type.TObject<{
kind: Type.TLiteral<"external-post">;
target: Type.TString;
visibility: Type.TUnion<[Type.TLiteral<"public">, Type.TLiteral<"restricted">]>;
}>, Type.TObject<{
kind: Type.TLiteral<"standing-grant">;
automation: Type.TString;
command: Type.TString;
expiresInDays: Type.TOptional<Type.TInteger>;
}>]>>;
allowedDecisions: Type.TArray<Type.TUnion<[Type.TLiteral<"allow-once">, Type.TLiteral<"allow-always">, Type.TLiteral<"deny">]>>;
}>, Type.TObject<{
kind: Type.TLiteral<"plugin">;
title: Type.TString;
description: Type.TString;
detail: Type.TOptional<Type.TString>;
severity: Type.TUnion<[Type.TLiteral<"info">, Type.TLiteral<"warning">, Type.TLiteral<"critical">]>;
pluginId: Type.TOptional<Type.TUnion<[Type.TString, Type.TNull]>>;
toolName: Type.TOptional<Type.TUnion<[Type.TString, Type.TNull]>>;
agentId: Type.TOptional<Type.TUnion<[Type.TString, Type.TNull]>>;
scope: Type.TOptional<Type.TUnion<[Type.TObject<{
kind: Type.TLiteral<"message-send">;
target: Type.TString;
recipientCount: Type.TInteger;
recipients: Type.TOptional<Type.TArray<Type.TString>>;
audience: Type.TOptional<Type.TUnion<[Type.TLiteral<"internal">, Type.TLiteral<"external">]>>;
}>, Type.TObject<{
kind: Type.TLiteral<"payment">;
amount: Type.TString;
currency: Type.TString;
target: Type.TString;
}>, Type.TObject<{
kind: Type.TLiteral<"external-post">;
target: Type.TString;
visibility: Type.TUnion<[Type.TLiteral<"public">, Type.TLiteral<"restricted">]>;
}>, Type.TObject<{
kind: Type.TLiteral<"standing-grant">;
automation: Type.TString;
command: Type.TString;
expiresInDays: Type.TOptional<Type.TInteger>;
}>]>>;
allowedDecisions: Type.TArray<Type.TUnion<[Type.TLiteral<"allow-once">, Type.TLiteral<"allow-always">, Type.TLiteral<"deny">]>>;
externalResolution: Type.TOptional<Type.TObject<{
label: Type.TString;
decisions: Type.TArray<Type.TUnion<[Type.TLiteral<"allow-once">, Type.TLiteral<"allow-always">]>>;
}>>;
}>, Type.TObject<{
kind: Type.TLiteral<"system-agent">;
title: Type.TString;
description: Type.TString;
proposalHash: Type.TString;
agentId: Type.TOptional<Type.TUnion<[Type.TString, Type.TNull]>>;
allowedDecisions: Type.TTuple<[Type.TLiteral<"allow-once">, Type.TLiteral<"deny">]>;
}>]>;
status: Type.TLiteral<"pending">;
/** Canonical raising session when projected into a session-scoped reviewer surface. */
sourceSessionKey: Type.TOptional<Type.TString>;
}>>;
truncated: Type.TBoolean;
}>;
type ApprovalPresentation = Static<typeof ApprovalPresentationSchema>;
type SessionApprovalReplay = Static<typeof SessionApprovalReplaySchema>;
//#endregion
//#region packages/gateway-protocol/src/schema/worker-inference.d.ts
declare const WorkerInferenceModelRefSchema: Type.TObject<{
readonly provider: Type.TString;
readonly model: Type.TString;
}>;
declare const WorkerInferenceOptionsSchema: Type.TObject<{
readonly temperature: Type.TOptional<Type.TNumber>;
readonly maxTokens: Type.TOptional<Type.TInteger>;
readonly reasoning: Type.TOptional<Type.TUnion<[Type.TLiteral<"off">, Type.TLiteral<"minimal">, Type.TLiteral<"low">, Type.TLiteral<"medium">, Type.TLiteral<"high">, Type.TLiteral<"xhigh">, Type.TLiteral<"adaptive">, Type.TLiteral<"max">]>>;
readonly thinkingBudgets: Type.TOptional<Type.TObject<{
readonly minimal: Type.TOptional<Type.TInteger>;
readonly low: Type.TOptional<Type.TInteger>;
readonly medium: Type.TOptional<Type.TInteger>;
readonly high: Type.TOptional<Type.TInteger>;
readonly max: Type.TOptional<Type.TInteger>;
}>>;
}>;
type WorkerInferenceModelRef = Static<typeof WorkerInferenceModelRefSchema>;
type WorkerInferenceOptions = Static<typeof WorkerInferenceOptionsSchema>;
//#endregion
//#region packages/gateway-protocol/src/schema/sessions-row.d.ts
declare const SessionPermissionModeSchema: Type.TUnion<[Type.TLiteral<"read-only">, Type.TLiteral<"guarded">, Type.TLiteral<"workspace">, Type.TLiteral<"full">]>;
declare const SessionRunStatusSchema: Type.TUnion<[Type.TLiteral<"queued">, Type.TLiteral<"running">, Type.TLiteral<"done">, Type.TLiteral<"failed">, Type.TLiteral<"killed">, Type.TLiteral<"timeout">]>;
declare const SessionEntryArchiveReasonSchema: Type.TUnion<[Type.TLiteral<"manual">, Type.TLiteral<"active-session-cap">, Type.TLiteral<"stale-dashboard">, Type.TLiteral<"restart-recovery">]>;
/** Stable Gateway session row fields; mutation envelopes may add null tombstones. */
declare const SessionRowSchema: Type.TObject<{
key: Type.TString;
sessionId: Type.TOptional<Type.TString>;
incognito: Type.TOptional<Type.TLiteral<true>>;
kind: Type.TUnion<[Type.TLiteral<"direct">, Type.TLiteral<"group">, Type.TLiteral<"global">, Type.TLiteral<"unknown">]>;
label: Type.TOptional<Type.TString>;
icon: Type.TOptional<Type.TString>;
/** Named sidebar tint from SESSION_COLOR_IDS; clients map names to theme hues. */
color: Type.TOptional<Type.TString>;
channelAvatarUrl: Type.TOptional<Type.TString>;
boardFace: Type.TOptional<Type.TUnion<[Type.TLiteral<"chat">, Type.TLiteral<"dashboard">]>>;
displayName: Type.TOptional<Type.TString>;
derivedTitle: Type.TOptional<Type.TString>;
lastMessagePreview: Type.TOptional<Type.TString>;
channel: Type.TOptional<Type.TString>;
/** Stable non-sensitive facts derived from the canonical session route. */
classification: Type.TOptional<Type.TString>;
agentId: Type.TOptional<Type.TString>;
accountId: Type.TOptional<Type.TString>;
peerKind: Type.TOptional<Type.TString>;
isMain: Type.TOptional<Type.TBoolean>;
isBackground: Type.TOptional<Type.TBoolean>;
chatType: Type.TOptional<Type.TUnion<[Type.TLiteral<"direct">, Type.TLiteral<"group">, Type.TLiteral<"channel">]>>;
updatedAt: Type.TOptional<Type.TUnion<[Type.TNumber, Type.TNull]>>;
archived: Type.TOptional<Type.TBoolean>;
archivedAt: Type.TOptional<Type.TNumber>;
archivedBy: Type.TOptional<Type.TObject<{
type: Type.TUnion<[Type.TLiteral<"human">, Type.TLiteral<"agent">, Type.TLiteral<"system">]>;
id: Type.TOptional<Type.TString>;
label: Type.TOptional<Type.TString>;
/** Durable profile avatar route; absent for actors without a stored profile avatar. */
avatarUrl: Type.TOptional<Type.TString>;
/** Display identity is separate from the actor fields used by ownership policy. */
identity: Type.TOptional<Type.TUnion<[Type.TObject<{
type: Type.TLiteral<"profile">;
id: Type.TString;
}>, Type.TObject<{
type: Type.TLiteral<"agent">;
id: Type.TString;
}>, Type.TObject<{
type: Type.TLiteral<"remote">;
pluginId: Type.TString;
domain: Type.TString;
idKind: Type.TString;
id: Type.TString;
}>, Type.TObject<{
type: Type.TLiteral<"observation">;
pluginId: Type.TUnion<[Type.TString, Type.TNull]>;
accountId: Type.TUnion<[Type.TString, Type.TNull]>;
senderKind: Type.TUnion<[Type.TLiteral<"human">, Type.TLiteral<"bot">, Type.TLiteral<"unknown">]>;
id: Type.TString;
}>, Type.TObject<{
type: Type.TLiteral<"legacy">;
actorType: Type.TString;
source: Type.TUnion<[Type.TString, Type.TNull]>;
id: Type.TString;
}>]>>;
}>>;
archiveReason: Type.TOptional<Type.TUnion<[Type.TLiteral<"manual">, Type.TLiteral<"active-session-cap">, Type.TLiteral<"stale-dashboard">, Type.TLiteral<"restart-recovery">]>>;
pinned: Type.TOptional<Type.TBoolean>;
pinnedAt: Type.TOptional<Type.TNumber>;
unread: Type.TOptional<Type.TBoolean>;
lastReadAt: Type.TOptional<Type.TNumber>;
markedUnreadAt: Type.TOptional<Type.TNumber>;
lastActivityAt: Type.TOptional<Type.TNumber>;
lastInteractionAt: Type.TOptional<Type.TNumber>;
status: Type.TOptional<Type.TUnion<[Type.TLiteral<"queued">, Type.TLiteral<"running">, Type.TLiteral<"done">, Type.TLiteral<"failed">, Type.TLiteral<"killed">, Type.TLiteral<"timeout">]>>;
lastRunError: Type.TOptional<Type.TString>;
/** Exact run that produced the latest terminal lifecycle projection. */
lastRunId: Type.TOptional<Type.TString>;
restartRecoveryStatus: Type.TOptional<Type.TLiteral<"tombstoned">>;
activeLeafEntryId: Type.TOptional<Type.TUnion<[Type.TString, Type.TNull]>>;
spawnedBy: Type.TOptional<Type.TString>;
parentSessionKey: Type.TOptional<Type.TString>;
controlOwnerSessionKey: Type.TOptional<Type.TString>;
childSessions: Type.TOptional<Type.TArray<Type.TString>>;
forkedFromParent: Type.TOptional<Type.TBoolean>;
spawnDepth: Type.TOptional<Type.TNumber>;
subagentRole: Type.TOptional<Type.TUnion<[Type.TLiteral<"orchestrator">, Type.TLiteral<"leaf">]>>;
subagentControlScope: Type.TOptional<Type.TUnion<[Type.TLiteral<"children">, Type.TLiteral<"none">]>>;
swarmGroupId: Type.TOptional<Type.TString>;
worktree: Type.TOptional<Type.TObject<{
id: Type.TString;
branch: Type.TString;
repoRoot: Type.TString;
}>>;
execNode: Type.TOptional<Type.TString>;
execCwd: Type.TOptional<Type.TString>;
spawnedWorkspaceDir: Type.TOptional<Type.TString>;
spawnedCwd: Type.TOptional<Type.TString>;
permissionMode: Type.TOptional<Type.TUnion<[Type.TLiteral<"read-only">, Type.TLiteral<"guarded">, Type.TLiteral<"workspace">, Type.TLiteral<"full">]>>;
permissionModePending: Type.TOptional<Type.TBoolean>;
sessionRoot: Type.TOptional<Type.TString>;
createdVia: Type.TOptional<Type.TUnion<[Type.TLiteral<"operator">, Type.TLiteral<"spawn">, Type.TLiteral<"channel">, Type.TLiteral<"cron">, Type.TLiteral<"talk">, Type.TLiteral<"run">, Type.TLiteral<"plugin">, Type.TLiteral<"internal">]>>;
createdActor: Type.TOptional<Type.TObject<{
type: Type.TUnion<[Type.TLiteral<"human">, Type.TLiteral<"agent">, Type.TLiteral<"system">]>;
id: Type.TOptional<Type.TString>;
label: Type.TOptional<Type.TString>;
/** Durable profile avatar route; absent for actors without a stored profile avatar. */
avatarUrl: Type.TOptional<Type.TString>;
/** Display identity is separate from the actor fields used by ownership policy. */
identity: Type.TOptional<Type.TUnion<[Type.TObject<{
type: Type.TLiteral<"profile">;
id: Type.TString;
}>, Type.TObject<{
type: Type.TLiteral<"agent">;
id: Type.TString;
}>, Type.TObject<{
type: Type.TLiteral<"remote">;
pluginId: Type.TString;
domain: Type.TString;
idKind: Type.TString;
id: Type.TString;
}>, Type.TObject<{
type: Type.TLiteral<"observation">;
pluginId: Type.TUnion<[Type.TString, Type.TNull]>;
accountId: Type.TUnion<[Type.TString, Type.TNull]>;
senderKind: Type.TUnion<[Type.TLiteral<"human">, Type.TLiteral<"bot">, Type.TLiteral<"unknown">]>;
id: Type.TString;
}>, Type.TObject<{
type: Type.TLiteral<"legacy">;
actorType: Type.TString;
source: Type.TUnion<[Type.TString, Type.TNull]>;
id: Type.TString;
}>]>>;
}>>;
owner: Type.TOptional<Type.TObject<{
actor: Type.TObject<{
type: Type.TUnion<[Type.TLiteral<"human">, Type.TLiteral<"agent">, Type.TLiteral<"system">]>;
id: Type.TOptional<Type.TString>;
label: Type.TOptional<Type.TString>;
/** Durable profile avatar route; absent for actors without a stored profile avatar. */
avatarUrl: Type.TOptional<Type.TString>;
/** Display identity is separate from the actor fields used by ownership policy. */
identity: Type.TOptional<Type.TUnion<[Type.TObject<{
type: Type.TLiteral<"profile">;
id: Type.TString;
}>, Type.TObject<{
type: Type.TLiteral<"agent">;
id: Type.TString;
}>, Type.TObject<{
type: Type.TLiteral<"remote">;
pluginId: Type.TString;
domain: Type.TString;
idKind: Type.TString;
id: Type.TString;
}>, Type.TObject<{
type: Type.TLiteral<"observation">;
pluginId: Type.TUnion<[Type.TString, Type.TNull]>;
accountId: Type.TUnion<[Type.TString, Type.TNull]>;
senderKind: Type.TUnion<[Type.TLiteral<"human">, Type.TLiteral<"bot">, Type.TLiteral<"unknown">]>;
id: Type.TString;
}>, Type.TObject<{
type: Type.TLiteral<"legacy">;
actorType: Type.TString;
source: Type.TUnion<[Type.TString, Type.TNull]>;
id: Type.TString;
}>]>>;
}>;
assignedBy: Type.TOptional<Type.TObject<{
type: Type.TUnion<[Type.TLiteral<"human">, Type.TLiteral<"agent">, Type.TLiteral<"system">]>;
id: Type.TOptional<Type.TString>;
label: Type.TOptional<Type.TString>;
/** Durable profile avatar route; absent for actors without a stored profile avatar. */
avatarUrl: Type.TOptional<Type.TString>;
/** Display identity is separate from the actor fields used by ownership policy. */
identity: Type.TOptional<Type.TUnion<[Type.TObject<{
type: Type.TLiteral<"profile">;
id: Type.TString;
}>, Type.TObject<{
type: Type.TLiteral<"agent">;
id: Type.TString;
}>, Type.TObject<{
type: Type.TLiteral<"remote">;
pluginId: Type.TString;
domain: Type.TString;
idKind: Type.TString;
id: Type.TString;
}>, Type.TObject<{
type: Type.TLiteral<"observation">;
pluginId: Type.TUnion<[Type.TString, Type.TNull]>;
accountId: Type.TUnion<[Type.TString, Type.TNull]>;
senderKind: Type.TUnion<[Type.TLiteral<"human">, Type.TLiteral<"bot">, Type.TLiteral<"unknown">]>;
id: Type.TString;
}>, Type.TObject<{
type: Type.TLiteral<"legacy">;
actorType: Type.TString;
source: Type.TUnion<[Type.TString, Type.TNull]>;
id: Type.TString;
}>]>>;
}>>;
assignedAt: Type.TOptional<Type.TNumber>;
}>>;
participants: Type.TOptional<Type.TArray<Type.TObject<{
identity: Type.TUnion<[Type.TObject<{
type: Type.TLiteral<"profile">;
id: Type.TString;
}>, Type.TObject<{
type: Type.TLiteral<"agent">;
id: Type.TString;
}>, Type.TObject<{
type: Type.TLiteral<"remote">;
pluginId: Type.TString;
domain: Type.TString;
idKind: Type.TString;
id: Type.TString;
}>, Type.TObject<{
type: Type.TLiteral<"observation">;
pluginId: Type.TUnion<[Type.TString, Type.TNull]>;
accountId: Type.TUnion<[Type.TString, Type.TNull]>;
senderKind: Type.TUnion<[Type.TLiteral<"human">, Type.TLiteral<"bot">, Type.TLiteral<"unknown">]>;
id: Type.TString;
}>, Type.TObject<{
type: Type.TLiteral<"legacy">;
actorType: Type.TString;
source: Type.TUnion<[Type.TString, Type.TNull]>;
id: Type.TString;
}>]>;
label: Type.TOptional<Type.TString>;
avatarUrl: Type.TOptional<Type.TString>;
}>>>;
expandedParticipants: Type.TOptional<Type.TArray<Type.TObject<{
identity: Type.TUnion<[Type.TObject<{
type: Type.TLiteral<"profile">;
id: Type.TString;
}>, Type.TObject<{
type: Type.TLiteral<"agent">;
id: Type.TString;
}>, Type.TObject<{
type: Type.TLiteral<"remote">;
pluginId: Type.TString;
domain: Type.TString;
idKind: Type.TString;
id: Type.TString;
}>, Type.TObject<{
type: Type.TLiteral<"observation">;
pluginId: Type.TUnion<[Type.TString, Type.TNull]>;
accountId: Type.TUnion<[Type.TString, Type.TNull]>;
senderKind: Type.TUnion<[Type.TLiteral<"human">, Type.TLiteral<"bot">, Type.TLiteral<"unknown">]>;
id: Type.TString;
}>, Type.TObject<{
type: Type.TLiteral<"legacy">;
actorType: Type.TString;
source: Type.TUnion<[Type.TString, Type.TNull]>;
id: Type.TString;
}>]>;
label: Type.TOptional<Type.TString>;
avatarUrl: Type.TOptional<Type.TString>;
}>>>;
participantCount: Type.TOptional<Type.TInteger>;
visibility: Type.TOptional<Type.TUnion<[Type.TLiteral<"shared">, Type.TLiteral<"read-only">, Type.TLiteral<"suggest">, Type.TLiteral<"draft">]>>;
sharingRole: Type.TOptional<Type.TUnion<[Type.TLiteral<"admin">, Type.TLiteral<"owner">, Type.TLiteral<"member">, Type.TLiteral<"viewer">]>>;
createdAt: Type.TOptional<Type.TNumber>;
forkSource: Type.TOptional<Type.TObject<{
sessionKey: Type.TString;
sessionId: Type.TString;
entryId: Type.TOptional<Type.TString>;
}>>;
previousSessionId: Type.TOptional<Type.TString>;
inputTokens: Type.TOptional<Type.TNumber>;
outputTokens: Type.TOptional<Type.TNumber>;
totalTokens: Type.TOptional<Type.TNumber>;
totalTokensFresh: Type.TOptional<Type.TBoolean>;
contextTokens: Type.TOptional<Type.TNumber>;
estimatedCostUsd: Type.TOptional<Type.TNumber>;
model: Type.TOptional<Type.TString>;
modelProvider: Type.TOptional<Type.TString>;
/** Runtime model serving this session while it differs from the selected model. */
activeModel: Type.TOptional<Type.TString>;
activeModelProvider: Type.TOptional<Type.TString>;
/** Persisted override provenance; null means inherited, omission means not projected. */
modelOverrideSource: Type.TOptional<Type.TUnion<[Type.TLiteral<"user">, Type.TLiteral<"auto">, Type.TNull]>>;
toolOverrides: Type.TOptional<Type.TObject<{
mcpServers: Type.TOptional<Type.TRecord<"^.*$", Type.TBoolean>>;
mcpToolsDeny: Type.TOptional<Type.TRecord<"^.*$", Type.TArray<Type.TString>>>;
skills: Type.TOptional<Type.TRecord<"^.*$", Type.TBoolean>>;
webSearch: Type.TOptional<Type.TBoolean>;
}>>;
}>;
type SessionPermissionMode = Static<typeof SessionPermissionModeSchema>;
type SessionRunStatus = Static<typeof SessionRunStatusSchema>;
type SessionRow = Static<typeof SessionRowSchema>;
type SessionEntryArchiveReason = Static<typeof SessionEntryArchiveReasonSchema>;
//#endregion
//#region packages/gateway-protocol/src/schema/session-participant.d.ts
/** Product identity, independent of display metadata and authorization. */
declare const SessionParticipantIdentitySchema: Type.TUnion<[Type.TObject<{
type: Type.TLiteral<"profile">;
id: Type.TString;
}>, Type.TObject<{
type: Type.TLiteral<"agent">;
id: Type.TString;
}>, Type.TObject<{
type: Type.TLiteral<"remote">;
pluginId: Type.TString;
domain: Type.TString;
idKind: Type.TString;
id: Type.TString;
}>, Type.TObject<{
type: Type.TLiteral<"observation">;
pluginId: Type.TUnion<[Type.TString, Type.TNull]>;
accountId: Type.TUnion<[Type.TString, Type.TNull]>;
senderKind: Type.TUnion<[Type.TLiteral<"human">, Type.TLiteral<"bot">, Type.TLiteral<"unknown">]>;
id: Type.TString;
}>, Type.TObject<{
type: Type.TLiteral<"legacy">;
actorType: Type.TString;
source: Type.TUnion<[Type.TString, Type.TNull]>;
id: Type.TString;
}>]>;
declare const SessionParticipantSchema: Type.TObject<{
identity: Type.TUnion<[Type.TObject<{
type: Type.TLiteral<"profile">;
id: Type.TString;
}>, Type.TObject<{
type: Type.TLiteral<"agent">;
id: Type.TString;
}>, Type.TObject<{
type: Type.TLiteral<"remote">;
pluginId: Type.TString;
domain: Type.TString;
idKind: Type.TString;
id: Type.TString;
}>, Type.TObject<{
type: Type.TLiteral<"observation">;
pluginId: Type.TUnion<[Type.TString, Type.TNull]>;
accountId: Type.TUnion<[Type.TString, Type.TNull]>;
senderKind: Type.TUnion<[Type.TLiteral<"human">, Type.TLiteral<"bot">, Type.TLiteral<"unknown">]>;
id: Type.TString;
}>, Type.TObject<{
type: Type.TLiteral<"legacy">;
actorType: Type.TString;
source: Type.TUnion<[Type.TString, Type.TNull]>;
id: Type.TString;
}>]>;
label: Type.TOptional<Type.TString>;
avatarUrl: Type.TOptional<Type.TString>;
}>;
type SessionParticipantIdentity = Static<typeof SessionParticipantIdentitySchema>;
type SessionParticipant = Static<typeof SessionParticipantSchema>;
//#endregion
//#region packages/gateway-protocol/src/schema/sessions-goal.d.ts
declare const SessionGoalSchema: Type.TObject<{
schemaVersion: Type.TLiteral<1>;
id: Type.TString;
objective: Type.TString;
status: Type.TUnion<[Type.TLiteral<"active">, Type.TLiteral<"paused">, Type.TLiteral<"blocked">, Type.TLiteral<"usage_limited">, Type.TLiteral<"budget_limited">, Type.TLiteral<"complete">]>;
createdAt: Type.TNumber;
updatedAt: Type.TNumber;
tokenStart: Type.TNumber;
tokenStartFresh: Type.TOptional<Type.TBoolean>;
tokensUsed: Type.TNumber;
tokenBudget: Type.TOptional<Type.TNumber>;
continuationTurns: Type.TNumber;
lastStatusNote: Type.TOptional<Type.TString>;
pausedAt: Type.TOptional<Type.TNumber>;
blockedAt: Type.TOptional<Type.TNumber>;
completedAt: Type.TOptional<Type.TNumber>;
usageLimitedAt: Type.TOptional<Type.TNumber>;
budgetLimitedAt: Type.TOptional<Type.TNumber>;
}>;
type SessionGoal = Static<typeof SessionGoalSchema>;
declare const SessionsGoalMutationResultSchema: Type.TObject<{
operationId: Type.TString;
action: Type.TUnion<[Type.TLiteral<"start">, Type.TLiteral<"edit">, Type.TLiteral<"pause">, Type.TLiteral<"resume">, Type.TLiteral<"complete">, Type.TLiteral<"block">, Type.TLiteral<"clear">]>;
sessionId: Type.TString;
goalId: Type.TString;
goal: Type.TOptional<Type.TObject<{
schemaVersion: Type.TLiteral<1>;
id: Type.TString;
objective: Type.TString;
status: Type.TUnion<[Type.TLiteral<"active">, Type.TLiteral<"paused">, Type.TLiteral<"blocked">, Type.TLiteral<"usage_limited">, Type.TLiteral<"budget_limited">, Type.TLiteral<"complete">]>;
createdAt: Type.TNumber;
updatedAt: Type.TNumber;
tokenStart: Type.TNumber;
tokenStartFresh: Type.TOptional<Type.TBoolean>;
tokensUsed: Type.TNumber;
tokenBudget: Type.TOptional<Type.TNumber>;
continuationTurns: Type.TNumber;
lastStatusNote: Type.TOptional<Type.TString>;
pausedAt: Type.TOptional<Type.TNumber>;
blockedAt: Type.TOptional<Type.TNumber>;
completedAt: Type.TOptional<Type.TNumber>;
usageLimitedAt: Type.TOptional<Type.TNumber>;
budgetLimitedAt: Type.TOptional<Type.TNumber>;
}>>;
runId: Type.TOptional<Type.TString>;
replayed: Type.TOptional<Type.TLiteral<true>>;
status: Type.TUnion<[Type.TLiteral<"started">, Type.TLiteral<"updated">, Type.TLiteral<"cleared">]>;
}>;
type SessionsGoalMutationResult = Static<typeof SessionsGoalMutationResultSchema>;
//#endregion
//#region packages/gateway-protocol/src/schema/sessions-catalog.d.ts
declare const SessionCatalogShareRouteSchema: Type.TObject<{
kind: Type.TLiteral<"thread-id-prefix">;
routeSegment: Type.TString;
hostId: Type.TString;
identifierAlphabet: Type.TLiteral<"lowercase-hex">;
fullLength: Type.TLiteral<32>;
minPrefixLength: Type.TLiteral<12>;
lookup: Type.TLiteral<"catalog-list-search-by-thread-id-prefix">;
ambiguity: Type.TLiteral<"multiple-results-or-next-cursor">;
}>;
declare const SessionCatalogHostSchema: Type.TObject<{
hostId: Type.TString;
label: Type.TString;
kind: Type.TUnion<[Type.TLiteral<"gateway">, Type.TLiteral<"node">]>;
connected: Type.TBoolean;
nodeId: Type.TOptional<Type.TString>;
canStartTerminal: Type.TOptional<Type.TBoolean>;
sessions: Type.TArray<Type.TObject<{
threadId: Type.TString;
sourceHomeId: Type.TOptional<Type.TString>;
name: Type.TOptional<Type.TString>;
/** Named tint imported from the source CLI session (SESSION_COLOR_IDS). */
color: Type.TOptional<Type.TString>;
cwd: Type.TOptional<Type.TString>;
status: Type.TString;
createdAt: Type.TOptional<Type.TNumber>;
updatedAt: Type.TOptional<Type.TNumber>;
recencyAt: Type.TOptional<Type.TNumber>;
source: Type.TOptional<Type.TString>;
modelProvider: Type.TOptional<Type.TString>;
cliVersion: Type.TOptional<Type.TString>;
gitBranch: Type.TOptional<Type.TString>;
customGroup: Type.TOptional<Type.TString>;
pullRequest: Type.TOptional<Type.TObject<{
numbers: Type.TArray<Type.TInteger>;
state: Type.TUnion<[Type.TLiteral<"open">, Type.TLiteral<"draft">, Type.TLiteral<"merged">, Type.TLiteral<"closed">]>;
}>>;
archived: Type.TBoolean;
sessionKey: Type.TOptional<Type.TString>;
createdActor: Type.TOptional<Type.TObject<{
type: Type.TUnion<[Type.TLiteral<"human">, Type.TLiteral<"agent">, Type.TLiteral<"system">]>;
id: Type.TOptional<Type.TString>;
label: Type.TOptional<Type.TString>;
avatarUrl: Type.TOptional<Type.TString>;
identity: Type.TOptional<Type.TUnion<[Type.TObject<{
type: Type.TLiteral<"profile">;
id: Type.TString;
}>, Type.TObject<{
type: Type.TLiteral<"agent">;
id: Type.TString;
}>, Type.TObject<{
type: Type.TLiteral<"remote">;
pluginId: Type.TString;
domain: Type.TString;
idKind: Type.TString;
id: Type.TString;
}>, Type.TObject<{
type: Type.TLiteral<"observation">;
pluginId: Type.TUnion<[Type.TString, Type.TNull]>;
accountId: Type.TUnion<[Type.TString, Type.TNull]>;
senderKind: Type.TUnion<[Type.TLiteral<"human">, Type.TLiteral<"bot">, Type.TLiteral<"unknown">]>;
id: Type.TString;
}>, Type.TObject<{
type: Type.TLiteral<"legacy">;
actorType: Type.TString;
source: Type.TUnion<[Type.TString, Type.TNull]>;
id: Type.TString;
}>]>>;
}>>;
canContinue: Type.TBoolean;
canArchive: Type.TBoolean;
canOpenTerminal: Type.TOptional<Type.TBoolean>;
}>>;
nextCursor: Type.TOptional<Type.TString>;
error: Type.TOptional<Type.TObject<{
code: Type.TString;
message: Type.TString;
}>>;
}>;
declare const SessionsCatalogReadParamsSchema: Type.TObject<{
catalogId: Type.TString;
hostId: Type.TString;
threadId: Type.TString;
agentId: Type.TOptional<Type.TString>;
sourceHomeId: Type.TOptional<Type.TString>;
limit: Type.TOptional<Type.TInteger>;
cursor: Type.TOptional<Type.TString>;
}>;
declare const SessionsCatalogReadResultSchema: Type.TObject<{
hostId: Type.TString;
label: Type.TOptional<Type.TString>;
threadId: Type.TString;
items: Type.TArray<Type.TObject<{
id: Type.TOptional<Type.TString>;
type: Type.TUnion<[Type.TLiteral<"userMessage">, Type.TLiteral<"agentMessage">, Type.TLiteral<"reasoning">, Type.TLiteral<"toolCall">, Type.TLiteral<"toolResult">, Type.TLiteral<"other">]>;
text: Type.TOptional<Type.TString>;
timestamp: Type.TOptional<Type.TString>;
model: Type.TOptional<Type.TString>;
/** Source-supplied attribution, independent of the viewer and session adopter. */
sender: Type.TOptional<Type.TObject<{
identity: Type.TUnion<[Type.TObject<{
type: Type.TLiteral<"profile">;
id: Type.TString;
}>, Type.TObject<{
type: Type.TLiteral<"agent">;
id: Type.TString;
}>, Type.TObject<{
type: Type.TLiteral<"remote">;
pluginId: Type.TString;
domain: Type.TString;
idKind: Type.TString;
id: Type.TString;
}>, Type.TObject<{
type: Type.TLiteral<"observation">;
pluginId: Type.TUnion<[Type.TString, Type.TNull]>;
accountId: Type.TUnion<[Type.TString, Type.TNull]>;
senderKind: Type.TUnion<[Type.TLiteral<"human">, Type.TLiteral<"bot">, Type.TLiteral<"unknown">]>;
id: Type.TString;
}>, Type.TObject<{
type: Type.TLiteral<"legacy">;
actorType: Type.TString;
source: Type.TUnion<[Type.TString, Type.TNull]>;
id: Type.TString;
}>]>;
label: Type.TOptional<Type.TString>;
avatarUrl: Type.TOptional<Type.TString>;
}>>;
truncated: Type.TOptional<Type.TBoolean>;
raw: Type.TOptional<Type.TUnknown>;
}>>;
nextCursor: Type.TOptional<Type.TString>;
}>;
declare const SessionsCatalogContinueParamsSchema: Type.TObject<{
catalogId: Type.TString;
hostId: Type.TString;
threadId: Type.TString;
agentId: Type.TOptional<Type.TString>;
sourceHomeId: Type.TOptional<Type.TString>;
}>;
declare const SessionsCatalogArchiveParamsSchema: Type.TObject<{
catalogId: Type.TString;
hostId: Type.TString;
threadId: Type.TString;
agentId: Type.TOptional<Type.TString>;
sourceHomeId: Type.TOptional<Type.TString>;
confirmNoOtherRunner: Type.TLiteral<true>;
}>;
type SessionCatalogShareRoute = Static<typeof SessionCatalogShareRouteSchema>;
type SessionCatalogHost = Static<typeof SessionCatalogHostSchema>;
type SessionsCatalogReadParams = Static<typeof SessionsCatalogReadParamsSchema>;
type SessionsCatalogReadResult = Static<typeof SessionsCatalogReadResultSchema>;
type SessionsCatalogContinueParams = Static<typeof SessionsCatalogContinueParamsSchema>;
type SessionsCatalogArchiveParams = Static<typeof SessionsCatalogArchiveParamsSchema>;
//#endregion
//#region packages/gateway-protocol/src/schema/agent.d.ts
/** Waits for a submitted agent run to complete or time out. */
declare const AgentWaitParamsSchema: Type.TObject<{
runId: Type.TString;
timeoutMs: Type.TOptional<Type.TInteger>;
}>;
type AgentWaitParams = Static<typeof AgentWaitParamsSchema>;
//#endregion
//#region packages/gateway-protocol/src/schema/agents-models-skills.d.ts
declare const ToolsGitHubAuthorizeStartResultSchema: Type.TObject<{
requestId: Type.TString;
userCode: Type.TString;
verificationUri: Type.TLiteral<"https://github.com/login/device">;
expiresInMs: Type.TInteger;
pollAfterMs: Type.TInteger;
}>;
declare const ToolsGitHubAuthorizePollResultSchema: Type.TUnion<[Type.TObject<{
status: Type.TLiteral<"pending">;
retryAfterMs: Type.TInteger;
}>, Type.TObject<{
status: Type.TLiteral<"slow_down">;
retryAfterMs: Type.TInteger;
}>, Type.TObject<{
status: Type.TLiteral<"access_denied">;
}>, Type.TObject<{
status: Type.TLiteral<"expired">;
}>, Type.TObject<{
status: Type.TLiteral<"incorrect_device_code">;
}>, Type.TObject<{
status: Type.TLiteral<"network_error">;
retryAfterMs: Type.TInteger;
}>, Type.TObject<{
status: Type.TLiteral<"failed">;
reason: Type.TUnion<[Type.TLiteral<"identity_changed">, Type.TLiteral<"setup_failed">]>;
}>, Type.TObject<{
status: Type.TLiteral<"success">;
githubStatus: Type.TObject<{
agentId: Type.TString;
selectedScope: Type.TUnion<[Type.TLiteral<"system">, Type.TLiteral<"agent">]>;
selected: Type.TObject<{
scope: Type.TUnion<[Type.TLiteral<"system">, Type.TLiteral<"agent">]>;
configured: Type.TBoolean;
identity: Type.TUnion<[Type.TObject<{
source: Type.TUnion<[Type.TLiteral<"system-detected">, Type.TLiteral<"system-configured">, Type.TLiteral<"agent-override">]>;
credentialKind: Type.TUnion<[Type.TLiteral<"native">, Type.TLiteral<"managed-pat">, Type.TLiteral<"managed-oauth">]>;
credentialState: Type.TUnion<[Type.TLiteral<"available">, Type.TLiteral<"unavailable">, Type.TLiteral<"configured_unavailable">, Type.TLiteral<"unverified">, Type.TLiteral<"rate_limited">]>;
account: Type.TUnion<[Type.TObject<{
login: Type.TString;
}>, Type.TNull]>;
gitAuthor: Type.TObject<{
name: Type.TUnion<[Type.TString, Type.TNull]>;
email: Type.TUnion<[Type.TString, Type.TNull]>;
}>;
evidence: Type.TUnion<[Type.TLiteral<"github-api">, Type.TLiteral<"none">, Type.TLiteral<"unverified">, Type.TLiteral<"rate-limited">]>;
accessExpiresAtMs: Type.TUnion<[Type.TInteger, Type.TNull]>;
refreshState: Type.TUnion<[Type.TLiteral<"not_applicable">, Type.TLiteral<"available">, Type.TLiteral<"expired">, Type.TLiteral<"unavailable">, Type.TLiteral<"refreshing">, Type.TLiteral<"failed">]>;
oauthScopes: Type.TArray<Type.TString>;
repositoryGrants: Type.TLiteral<"unknown">;
}>, Type.TNull]>;
}>;
effective: Type.TObject<{
source: Type.TUnion<[Type.TLiteral<"system-detected">, Type.TLiteral<"system-configured">, Type.TLiteral<"agent-override">]>;
credentialKind: Type.TUnion<[Type.TLiteral<"native">, Type.TLiteral<"managed-pat">, Type.TLiteral<"managed-oauth">]>;
credentialState: Type.TUnion<[Type.TLiteral<"available">, Type.TLiteral<"unavailable">, Type.TLiteral<"configured_unavailable">, Type.TLiteral<"unverified">, Type.TLiteral<"rate_limited">]>;
account: Type.TUnion<[Type.TObject<{
login: Type.TString;
}>, Type.TNull]>;
gitAuthor: Type.TObject<{
name: Type.TUnion<[Type.TString, Type.TNull]>;
email: Type.TUnion<[Type.TString, Type.TNull]>;
}>;
evidence: Type.TUnion<[Type.TLiteral<"github-api">, Type.TLiteral<"none">, Type.TLiteral<"unverified">, Type.TLiteral<"rate-limited">]>;
accessExpiresAtMs: Type.TUnion<[Type.TInteger, Type.TNull]>;
refreshState: Type.TUnion<[Type.TLiteral<"not_applicable">, Type.TLiteral<"available">, Type.TLiteral<"expired">, Type.TLiteral<"unavailable">, Type.TLiteral<"refreshing">, Type.TLiteral<"failed">]>;
oauthScopes: Type.TArray<Type.TString>;
repositoryGrants: Type.TLiteral<"unknown">;
}>;
}>;
}>]>;
type ToolsGitHubAuthorizeStartResult = Static<typeof ToolsGitHubAuthorizeStartResultSchema>;
type ToolsGitHubAuthorizePollResult = Static<typeof ToolsGitHubAuthorizePollResultSchema>;
//#endregion
//#region packages/gateway-protocol/src/schema/users.d.ts
declare const UsersListModelAccountsResultSchema: Type.TObject<{
profileId: Type.TString;
accounts: Type.TArray<Type.TObject<{
authProfileId: Type.TString;
provider: Type.TString;
label: Type.TString;
authType: Type.TUnion<[Type.TLiteral<"api_key">, Type.TLiteral<"oauth">, Type.TLiteral<"token">]>;
selected: Type.TBoolean;
}>>;
nextCursor: Type.TOptional<Type.TString>;
links: Type.TArray<Type.TObject<{
provider: Type.TString;
authProfileId: Type.TString;
updatedAt: Type.TInteger;
}>>;
}>;
declare const UsersSelectModelAccountResultSchema: Type.TObject<{
links: Type.TArray<Type.TObject<{
provider: Type.TString;
authProfileId: Type.TString;
updatedAt: Type.TInteger;
}>>;
}>;
/** Configured preference only; provider failover can use a different account. */
declare const ChatAccountSelectionSchema: Type.TUnion<[Type.TObject<{
kind: Type.TLiteral<"automatic">;
label: Type.TString;
}>, Type.TObject<{
kind: Type.TLiteral<"personal">;
label: Type.TString;
authProfileId: Type.TOptional<Type.TString>;
source: Type.TOptional<Type.TUnion<[Type.TLiteral<"auto">, Type.TLiteral<"user">, Type.TLiteral<"user-link">]>>;
}>, Type.TObject<{
kind: Type.TLiteral<"shared">;
label: Type.TString;
authProfileId: Type.TString;
source: Type.TOptional<Type.TUnion<[Type.TLiteral<"auto">, Type.TLiteral<"user">, Type.TLiteral<"user-link">]>>;
}>]>;
declare const UsersListAuthLinksResultSchema: Type.TObject<{
links: Type.TArray<Type.TObject<{
provider: Type.TString;
authProfileId: Type.TString;
updatedAt: Type.TInteger;
}>>;
}>;
declare const UsersLinkAuthProfileResultSchema: Type.TObject<{
links: Type.TArray<Type.TObject<{
provider: Type.TString;
authProfileId: Type.TString;
updatedAt: Type.TInteger;
}>>;
}>;
declare const UsersUnlinkAuthProfileResultSchema: Type.TObject<{
links: Type.TArray<Type.TObject<{
provider: Type.TString;
authProfileId: Type.TString;
updatedAt: Type.TInteger;
}>>;
}>;
declare const UsersAuthConnectCatalogResultSchema: Type.TObject<{
providers: Type.TArray<Type.TObject<{
id: Type.TString;
label: Type.TString;
methods: Type.TArray<Type.TObject<{
id: Type.TString;
label: Type.TString;
hint: Type.TOptional<Type.TString>;
}>>;
}>>;
}>;
declare const UsersAuthConnectStartResultSchema: Type.TObject<{
connectId: Type.TString;
expiresAtMs: Type.TInteger;
}>;
declare const UsersAuthConnectStatusResultSchema: Type.TUnion<[Type.TObject<{
status: Type.TLiteral<"pending">;
step: Type.TOptional<Type.TObject<{
id: Type.TString;
type: Type.TUnion<[Type.TLiteral<"note">, Type.TLiteral<"select">, Type.TLiteral<"text">, Type.TLiteral<"confirm">, Type.TLiteral<"multiselect">, Type.TLiteral<"progress">, Type.TLiteral<"action">]>;
title: Type.TOptional<Type.TString>;
message: Type.TOptional<Type.TString>;
format: Type.TOptional<Type.TUnion<[Type.TLiteral<"plain">]>>;
options: Type.TOptional<Type.TArray<Type.TObject<{
value: Type.TUnknown;
label: Type.TString;
hint: Type.TOptional<Type.TString>;
}>>>;
initialValue: Type.TOptional<Type.TUnknown>;
placeholder: Type.TOptional<Type.TString>;
sensitive: Type.TOptional<Type.TBoolean>;
executor: Type.TOptional<Type.TUnion<[Type.TLiteral<"gateway">, Type.TLiteral<"client">]>>;
externalUrl: Type.TOptional<Type.TString>;
deviceCode: Type.TOptional<Type.TObject<{
code: Type.TString;
expiresInMinutes: Type.TOptional<Type.TInteger>;
message: Type.TOptional<Type.TString>;
}>>;
}>>;
error: Type.TOptional<Type.TString>;
}>, Type.TObject<{
status: Type.TLiteral<"connected">;
authProfileId: Type.TString;
links: Type.TArray<Type.TObject<{
provider: Type.TString;
authProfileId: Type.TString;
updatedAt: Type.TInteger;
}>>;
}>, Type.TObject<{
status: Type.TLiteral<"cancelled">;
}>, Type.TObject<{
status: Type.TLiteral<"expired">;
}>, Type.TObject<{
status: Type.TLiteral<"failed">;
reason: Type.TUnion<[Type.TLiteral<"exchange">, Type.TLiteral<"identity">, Type.TLiteral<"authority">, Type.TLiteral<"unavailable">]>;
}>]>;
type UsersListModelAccountsResult = Static<typeof UsersListModelAccountsResultSchema>;
type UsersSelectModelAccountResult = Static<typeof UsersSelectModelAccountResultSchema>;
type ChatAccountSelection = Static<typeof ChatAccountSelectionSchema>;
type UsersAuthConnectStartResult = Static<typeof UsersAuthConnectStartResultSchema>;
type UsersAuthConnectCatalogResult = Static<typeof UsersAuthConnectCatalogResultSchema>;
type UsersAuthConnectStatusResult = Static<typeof UsersAuthConnectStatusResultSchema>;
type UsersListAuthLinksResult = Static<typeof UsersListAuthLinksResultSchema>;
type UsersLinkAuthProfileResult = Static<typeof UsersLinkAuthProfileResultSchema>;
type UsersUnlinkAuthProfileResult = Static<typeof UsersUnlinkAuthProfileResultSchema>;
declare const UsersGitHubAuthorizeStartResultSchema: Type.TObject<{
requestId: Type.TString;
userCode: Type.TString;
verificationUri: Type.TLiteral<"https://github.com/login/device">;
expiresInMs: Type.TInteger;
pollAfterMs: Type.TInteger;
}>;
declare const PersonalGitHubStatusSchema: Type.TObject<{
state: Type.TUnion<[Type.TLiteral<"connected">, Type.TLiteral<"disconnected">, Type.TLiteral<"unavailable">]>;
generation: Type.TUnion<[Type.TString, Type.TNull]>;
account: Type.TUnion<[Type.TObject<{
accountId: Type.TInteger;
login: Type.TString;
}>, Type.TNull]>;
accessExpiresAtMs: Type.TUnion<[Type.TInteger, Type.TNull]>;
refreshState: Type.TUnion<[Type.TLiteral<"available">, Type.TLiteral<"refreshing">, Type.TLiteral<"expired">, Type.TLiteral<"failed">, Type.TLiteral<"not_applicable">]>;
pending: Type.TUnion<[Type.TObject<{
requestId: Type.TString;
userCode: Type.TString;
verificationUri: Type.TLiteral<"https://github.com/login/device">;
expiresInMs: Type.TInteger;
pollAfterMs: Type.TInteger;
}>, Type.TNull]>;
}>;
declare const UsersGitHubAuthorizePollResultSchema: Type.TUnion<[Type.TObject<{
status: Type.TLiteral<"pending">;
retryAfterMs: Type.TInteger;
}>, Type.TObject<{
status: Type.TLiteral<"slow_down">;
retryAfterMs: Type.TInteger;
}>, Type.TObject<{
status: Type.TLiteral<"access_denied">;
}>, Type.TObject<{
status: Type.TLiteral<"expired">;
}>, Type.TObject<{
status: Type.TLiteral<"incorrect_device_code">;
}>, Type.TObject<{
status: Type.TLiteral<"network_error">;
retryAfterMs: Type.TInteger;
}>, Type.TObject<{
status: Type.TLiteral<"failed">;
reason: Type.TUnion<[Type.TLiteral<"identity_changed">, Type.TLiteral<"setup_failed">]>;
}>, Type.TObject<{
status: Type.TLiteral<"success">;
personal: Type.TObject<{
state: Type.TUnion<[Type.TLiteral<"connected">, Type.TLiteral<"disconnected">, Type.TLiteral<"unavailable">]>;
generation: Type.TUnion<[Type.TString, Type.TNull]>;
account: Type.TUnion<[Type.TObject<{
accountId: Type.TInteger;
login: Type.TString;
}>, Type.TNull]>;
accessExpiresAtMs: Type.TUnion<[Type.TInteger, Type.TNull]>;
refreshState: Type.TUnion<[Type.TLiteral<"available">, Type.TLiteral<"refreshing">, Type.TLiteral<"expired">, Type.TLiteral<"failed">, Type.TLiteral<"not_applicable">]>;
pending: Type.TUnion<[Type.TObject<{
requestId: Type.TString;
userCode: Type.TString;
verificationUri: Type.TLiteral<"https://github.com/login/device">;
expiresInMs: Type.TInteger;
pollAfterMs: Type.TInteger;
}>, Type.TNull]>;
}>;
}>]>;
type PersonalGitHubStatus = Static<typeof PersonalGitHubStatusSchema>;
type UsersGitHubAuthorizeStartResult = Static<typeof UsersGitHubAuthorizeStartResultSchema>;
type UsersGitHubAuthorizePollResult = Static<typeof UsersGitHubAuthorizePollResultSchema>;
//#endregion
//#region packages/gateway-protocol/src/schema/openclaw.d.ts
declare const SystemAgentWizardCancelSchema: Type.TObject<{
/** The visible step this action belongs to; stale controls must not affect a newer step. */
stepId: Type.TString;
}>;
/**
* Structured choice attached to a chat reply. Card-capable clients render the
* options and send back `reply` (default: `label`) as the next message; text
* clients ignore this and use the reply prose, which always stands alone.
*/
declare const SystemAgentChatQuestionSchema: Type.TObject<{
id: Type.TString;
header: Type.TString;
question: Type.TString;
options: Type.TArray<Type.TObject<{
label: Type.TString;
description: Type.TOptional<Type.TString>;
recommended: Type.TOptional<Type.TBoolean>;
/** Message text a client sends when this option is chosen; defaults to label. */
reply: Type.TOptional<Type.TString>;
}>>;
/** Free-text answers are also accepted for this question. */
isOther: Type.TOptional<Type.TBoolean>;
/** Client-owned action for the visible skip control; omitted means send a reply. */
skipAction: Type.TOptional<Type.TLiteral<"exit">>;
}>;
type SystemAgentWizardCancel = Static<typeof SystemAgentWizardCancelSchema>;
type SystemAgentChatQuestion = Static<typeof SystemAgentChatQuestionSchema>;
//#endregion
//#region packages/gateway-protocol/src/schema/cron.d.ts
/** One persisted cron run history entry. */
declare const CronRunLogEntrySchema: Type.TObject<{
ts: Type.TInteger;
jobId: Type.TString;
action: Type.TLiteral<"finished">;
status: Type.TOptional<Type.TUnion<[Type.TLiteral<"ok">, Type.TLiteral<"error">, Type.TLiteral<"skipped">]>>;
completionStatus: Type.TOptional<Type.TUnion<[Type.TLiteral<"succeeded">, Type.TLiteral<"failed">, Type.TLiteral<"unknown">]>>;
error: Type.TOptional<Type.TString>;
errorReason: Type.TOptional<Type.TUnion<[Type.TLiteral<"auth">, Type.TLiteral<"auth_permanent">, Type.TLiteral<"format">, Type.TLiteral<"rate_limit">, Type.TLiteral<"overloaded">, Type.TLiteral<"billing">, Type.TLiteral<"server_error">, Type.TLiteral<"timeout">, Type.TLiteral<"tls_certificate">, Type.TLiteral<"context_overflow">, Type.TLiteral<"model_not_found">, Type.TLiteral<"session_expired">, Type.TLiteral<"empty_response">, Type.TLiteral<"no_error_details">, Type.TLiteral<"unclassified">, Type.TLiteral<"unknown">]>>;
summary: Type.TOptional<Type.TString>;
diagnostics: Type.TOptional<Type.TObject<{
summary: Type.TOptional<Type.TString>;
entries: Type.TArray<Type.TObject<{
ts: Type.TInteger;
source: Type.TUnion<[Type.TLiteral<"cron-preflight">, Type.TLiteral<"cron-setup">, Type.TLiteral<"model-preflight">, Type.TLiteral<"agent-run">, Type.TLiteral<"tool">, Type.TLiteral<"exec">, Type.TLiteral<"delivery">]>;
severity: Type.TUnion<[Type.TLiteral<"info">, Type.TLiteral<"warn">, Type.TLiteral<"error">]>;
message: Type.TString;
toolName: Type.TOptional<Type.TString>;
exitCode: Type.TOptional<Type.TUnion<[Type.TNumber, Type.TNull]>>;
truncated: Type.TOptional<Type.TBoolean>;
}>>;
}>>;
delivered: Type.TOptional<Type.TBoolean>;
deliveryStatus: Type.TOptional<Type.TUnion<[Type.TLiteral<"delivered">, Type.TLiteral<"not-delivered">, Type.TLiteral<"unknown">, Type.TLiteral<"not-requested">]>>;
deliveryError: Type.TOptional<Type.TString>;
deliverySuppressionReason: Type.TOptional<Type.TString>;
failureNotificationDelivery: Type.TOptional<Type.TObject<{
delivered: Type.TOptional<Type.TBoolean>;
status: Type.TUnion<[Type.TLiteral<"delivered">, Type.TLiteral<"not-delivered">, Type.TLiteral<"unknown">, Type.TLiteral<"not-requested">]>;
error: Type.TOptional<Type.TString>;
}>>;
delivery: Type.TOptional<Type.TObject<{
intended: Type.TOptional<Type.TObject<{
channel: Type.TOptional<Type.TString>;
to: Type.TOptional<Type.TUnion<[Type.TString, Type.TNull]>>;
accountId: Type.TOptional<Type.TString>;
threadId: Type.TOptional<Type.TUnion<[Type.TString, Type.TNumber]>>;
source: Type.TOptional<Type.TUnion<[Type.TLiteral<"explicit">, Type.TLiteral<"last">]>>;
}>>;
resolved: Type.TOptional<Type.TObject<{
channel: Type.TOptional<Type.TString>;
to: Type.TOptional<Type.TUnion<[Type.TString, Type.TNull]>>;
accountId: Type.TOptional<Type.TString>;
threadId: Type.TOptional<Type.TUnion<[Type.TString, Type.TNumber]>>;
source: Type.TOptional<Type.TUnion<[Type.TLiteral<"explicit">, Type.TLiteral<"last">]>>;
ok: Type.TBoolean;
error: Type.TOptional<Type.TString>;
}>>;
messageToolSentTo: Type.TOptional<Type.TArray<Type.TObject<{
channel: Type.TString;
to: Type.TOptional<Type.TString>;
accountId: Type.TOptional<Type.TString>;
threadId: Type.TOptional<Type.TString>;
}>>>;
fallbackUsed: Type.TOptional<Type.TBoolean>;
delivered: Type.TOptional<Type.TBoolean>;
}>>;
sessionId: Type.TOptional<Type.TString>;
sessionKey: Type.TOptional<Type.TString>;
runId: Type.TOptional<Type.TString>;
runAtMs: Type.TOptional<Type.TInteger>;
durationMs: Type.TOptional<Type.TInteger>;
nextRunAtMs: Type.TOptional<Type.TInteger>;
triggerFired: Type.TOptional<Type.TBoolean>;
model: Type.TOptional<Type.TString>;
provider: Type.TOptional<Type.TString>;
usage: Type.TOptional<Type.TObject<{
input_tokens: Type.TOptional<Type.TNumber>;
output_tokens: Type.TOptional<Type.TNumber>;
total_tokens: Type.TOptional<Type.TNumber>;
cache_read_tokens: Type.TOptional<Type.TNumber>;
cache_write_tokens: Type.TOptional<Type.TNumber>;
}>>;
jobName: Type.TOptional<Type.TString>;
}>;
//#endregion
//#region packages/gateway-protocol/src/schema/cron.types.d.ts
type CronRunLogEntry = Static<typeof CronRunLogEntrySchema>;
//#endregion
//#region packages/gateway-protocol/src/schema/environments.d.ts
/** Durable lifecycle states for plugin-provisioned worker environments. */
declare const WorkerEnvironmentStateSchema: Type.TUnion<[Type.TLiteral<"requested">, Type.TLiteral<"provisioning">, Type.TLiteral<"bootstrapping">, Type.TLiteral<"ready">, Type.TLiteral<"attached">, Type.TLiteral<"idle">, Type.TLiteral<"draining">, Type.TLiteral<"destroying">, Type.TLiteral<"destroyed">, Type.TLiteral<"failed">, Type.TLiteral<"orphaned">]>;
/** Process-local SSH tunnel connectivity for a worker environment. */
declare const WorkerTunnelStatusSchema: Type.TUnion<[Type.TLiteral<"stopped">, Type.TLiteral<"connecting">, Type.TLiteral<"connected">, Type.TLiteral<"reconnecting">]>;
type WorkerEnvironmentState = Static<typeof WorkerEnvironmentStateSchema>;
type WorkerTunnelStatus = Static<typeof WorkerTunnelStatusSchema>;
//#endregion
//#region packages/gateway-protocol/src/schema/devices.d.ts
/** Returns the terminal scope-upgrade state to the identity-bound waiter. */
declare const ScopeUpgradeResultSchema: Type.TUnion<[Type.TObject<{
status: Type.TLiteral<"approved">;
requestId: Type.TString;
deviceToken: Type.TString;
scopes: Type.TArray<Type.TString>;
}>, Type.TObject<{
status: Type.TLiteral<"rejected">;
requestId: Type.TString;
}>, Type.TObject<{
status: Type.TLiteral<"expired">;
requestId: Type.TString;
}>]>;
type ScopeUpgradeResult = Static<typeof ScopeUpgradeResultSchema>;
//#endregion
//#region packages/gateway-protocol/src/schema/human-mentions.d.ts
/** Explicit selections bound to UTF-16 offsets in the submitted message text. */
declare const HumanMentionSchema: Type.TObject<{
profileId: Type.TString;
start: Type.TInteger;
end: Type.TInteger;
}>;
declare const UsersMentionableParamsSchema: Type.TUnion<[Type.TObject<{
sessionKey: Type.TString;
agentId: Type.TOptional<Type.TString>;
query: Type.TOptional<Type.TString>;
}>, Type.TObject<{
agentId: Type.TString;
visibility: Type.TOptional<Type.TUnion<[Type.TLiteral<"shared">, Type.TLiteral<"read-only">, Type.TLiteral<"suggest">, Type.TLiteral<"draft">]>>;
query: Type.TOptional<Type.TString>;
}>]>;
declare const UsersMentionableResultSchema: Type.TObject<{
users: Type.TArray<Type.TObject<{
profileId: Type.TString;
displayName: Type.TString;
avatarUrl: Type.TOptional<Type.TString>;
online: Type.TBoolean;
}>>;
truncated: Type.TBoolean;
}>;
declare const MentionsListResultSchema: Type.TObject<{
gatewayInstanceId: Type.TString;
revision: Type.TInteger;
items: Type.TArray<Type.TObject<{
id: Type.TString;
senderProfileId: Type.TString;
senderLabel: Type.TString;
senderAvatarUrl: Type.TOptional<Type.TString>;
sessionKey: Type.TString;
agentId: Type.TString;
sessionTitle: Type.TString;
messageId: Type.TString;
createdAt: Type.TInteger;
expiresAt: Type.TInteger;
excerpt: Type.TOptional<Type.TString>;
}>>;
}>;
type HumanMention = Static<typeof HumanMentionSchema>;
type UsersMentionableParams = Static<typeof UsersMentionableParamsSchema>;
type UsersMentionableResult = Static<typeof UsersMentionableResultSchema>;
type MentionsListResult = Static<typeof MentionsListResultSchema>;
//#endregion
//#region packages/gateway-protocol/src/schema/nodes.d.ts
declare const NodeHostStatsPayloadSchema: Type.TRefine<Type.TObject<{
cpuCount: Type.TInteger;
loadAverage: Type.TOptional<Type.TTuple<[Type.TNumber, Type.TNumber, Type.TNumber]>>;
memoryTotalBytes: Type.TInteger;
memoryFreeBytes: Type.TInteger;
diskTotalBytes: Type.TOptional<Type.TInteger>;
diskAvailableBytes: Type.TOptional<Type.TInteger>;
}>>;
/** Agent-visible tool descriptor advertised by a connected node. */
declare const NodePluginToolDescriptorSchema: Type.TObject<{
pluginId: Type.TString;
name: Type.TString;
description: Type.TString;
parameters: Type.TOptional<Type.TRecord<"^.*$", Type.TUnknown>>;
command: Type.TOptional<Type.TString>;
mcp: Type.TOptional<Type.TObject<{
server: Type.TString;
tool: Type.TString;
}>>;
}>;
type NodePluginToolDescriptor = Static<typeof NodePluginToolDescriptorSchema>;
/** Agent-visible skill descriptor advertised by a connected node. */
declare const NodeSkillDescriptorSchema: Type.TObject<{
name: Type.TString;
description: Type.TString;
content: Type.TString;
}>;
type NodeSkillDescriptor = Static<typeof NodeSkillDescriptorSchema>;
type NodeHostStatsPayload = Static<typeof NodeHostStatsPayloadSchema>;
//#endregion
//#region packages/gateway-protocol/src/schema/questions.d.ts
/** Canonical normalized question shown to an operator. */
declare const QuestionSchema: Type.TObject<{
questionId: Type.TString;
header: Type.TString;
question: Type.TString;
options: Type.TArray<Type.TObject<{
label: Type.TString;
description: Type.TOptional<Type.TString>;
}>>;
multiSelect: Type.TOptional<Type.TBoolean>;
isOther: Type.TOptional<Type.TBoolean>;
isSecret: Type.TOptional<Type.TBoolean>;
secretStore: Type.TOptional<Type.TObject<{
name: Type.TString;
kind: Type.TUnion<[Type.TLiteral<"secret">, Type.TLiteral<"env">]>;
allowedHosts: Type.TOptional<Type.TArray<Type.TString>>;
reason: Type.TOptional<Type.TString>;
}>>;
secretStoreExisting: Type.TOptional<Type.TObject<{
updatedAtMs: Type.TInteger;
updatedBy: Type.TOptional<Type.TString>;
}>>;
}>;
declare const QuestionAnswersSchema: Type.TObject<{
answers: Type.TRecord<"^.*$", Type.TArray<Type.TString>>;
}>;
/**
* One pending or recently resolved transient question request. Flat object with
* optional terminal fields (exec-approval record precedent): native protocol
* codegen cannot emit per-status object unions, and the manager owns the
* status/answers invariant (answers present only when status is "answered").
*/
declare const QuestionRecordSchema: Type.TObject<{
id: Type.TString;
questions: Type.TArray<Type.TObject<{
questionId: Type.TString;
header: Type.TString;
question: Type.TString;
options: Type.TArray<Type.TObject<{
label: Type.TString;
description: Type.TOptional<Type.TString>;
}>>;
multiSelect: Type.TOptional<Type.TBoolean>;
isOther: Type.TOptional<Type.TBoolean>;
isSecret: Type.TOptional<Type.TBoolean>;
secretStore: Type.TOptional<Type.TObject<{
name: Type.TString;
kind: Type.TUnion<[Type.TLiteral<"secret">, Type.TLiteral<"env">]>;
allowedHosts: Type.TOptional<Type.TArray<Type.TString>>;
reason: Type.TOptional<Type.TString>;
}>>;
secretStoreExisting: Type.TOptional<Type.TObject<{
updatedAtMs: Type.TInteger;
updatedBy: Type.TOptional<Type.TString>;
}>>;
}>>;
agentId: Type.TOptional<Type.TString>;
sessionKey: Type.TOptional<Type.TString>;
runId: Type.TOptional<Type.TString>;
createdAtMs: Type.TInteger;
expiresAtMs: Type.TInteger;
status: Type.TUnion<[Type.TLiteral<"pending">, Type.TLiteral<"answered">, Type.TLiteral<"cancelled">, Type.TLiteral<"expired">]>;
answers: Type.TOptional<Type.TObject<{
answers: Type.TRecord<"^.*$", Type.TArray<Type.TString>>;
}>>;
resolvedBy: Type.TOptional<Type.TString>;
}>;
declare const QuestionWaitAnswerResultSchema: Type.TUnion<[Type.TObject<{
status: Type.TLiteral<"pending">;
}>, Type.TObject<{
status: Type.TLiteral<"answered">;
answers: Type.TObject<{
answers: Type.TRecord<"^.*$", Type.TArray<Type.TString>>;
}>;
resolutionId: Type.TOptional<Type.TString>;
}>, Type.TObject<{
status: Type.TLiteral<"cancelled">;
}>, Type.TObject<{
status: Type.TLiteral<"expired">;
}>]>;
declare const QuestionResolveResultSchema: Type.TUnion<[Type.TObject<{
status: Type.TLiteral<"answered">;
answers: Type.TObject<{
answers: Type.TRecord<"^.*$", Type.TArray<Type.TString>>;
}>;
}>, Type.TObject<{
status: Type.TLiteral<"cancelled">;
}>]>;
declare const QuestionResolvedEventSchema: Type.TUnion<[Type.TObject<{
id: Type.TString;
status: Type.TLiteral<"answered">;
answers: Type.TObject<{
answers: Type.TRecord<"^.*$", Type.TArray<Type.TString>>;
}>;
}>, Type.TObject<{
id: Type.TString;
status: Type.TLiteral<"cancelled">;
}>, Type.TObject<{
id: Type.TString;
status: Type.TLiteral<"expired">;
}>]>;
type Question = Static<typeof QuestionSchema>;
type QuestionAnswers = Static<typeof QuestionAnswersSchema>;
type QuestionRecord = Static<typeof QuestionRecordSchema>;
type QuestionWaitAnswerResult = Static<typeof QuestionWaitAnswerResultSchema>;
type QuestionResolveResult = Static<typeof QuestionResolveResultSchema>;
type QuestionResolvedEvent = Static<typeof QuestionResolvedEventSchema>;
//#endregion
//#region packages/gateway-protocol/src/schema/session-placement.d.ts
declare const SessionPlacementDiskSpaceSchema: Type.TObject<{
status: Type.TUnion<[Type.TLiteral<"ok">, Type.TLiteral<"warning">, Type.TLiteral<"critical">]>;
availableBytes: Type.TInteger;
totalBytes: Type.TInteger;
observedAtMs: Type.TInteger;
}>;
declare const SessionPlacementRunnerSchema: Type.TObject<{
kind: Type.TLiteral<"device">;
status: Type.TUnion<[Type.TLiteral<"available">, Type.TLiteral<"offline">]>;
deviceId: Type.TOptional<Type.TString>;
}>;
/** Closed destination union for session placement moves. */
declare const SessionMoveTargetSchema: Type.TUnion<[Type.TObject<{
kind: Type.TLiteral<"gateway">;
}>, Type.TObject<{
kind: Type.TLiteral<"profile">;
profileId: Type.TString;
machineClass: Type.TOptional<Type.TString>;
}>, Type.TObject<{
kind: Type.TLiteral<"device">;
deviceId: Type.TString;
}>]>;
type SessionPlacementDiskSpace = Static<typeof SessionPlacementDiskSpaceSchema>;
type SessionPlacementRunner = Static<typeof SessionPlacementRunnerSchema>;
type SessionMoveTarget = Static<typeof SessionMoveTargetSchema>;
//#endregion
//#region packages/gateway-protocol/src/schema/sessions.d.ts
/** Live session status judgment broadcast to subscribed operator clients. */
declare const SessionObserverDigestSchema: Type.TObject<{
sessionKey: Type.TString;
agentId: Type.TOptional<Type.TString>;
runId: Type.TOptional<Type.TString>;
revision: Type.TInteger;
updatedAt: Type.TInteger;
headline: Type.TString;
assessment: Type.TOptional<Type.TString>;
health: Type.TUnion<[Type.TLiteral<"on-track">, Type.TLiteral<"grinding">, Type.TLiteral<"stuck">, Type.TLiteral<"waiting-on-user">, Type.TLiteral<"wrapping-up">, Type.TLiteral<"done">, Type.TLiteral<"failed">]>;
planProgress: Type.TOptional<Type.TObject<{
completed: Type.TInteger;
total: Type.TInteger;
}>>;
}>;
/** Companion answer returned only to the requesting operator. */
declare const SessionsCompanionAskResultSchema: Type.TObject<{
answer: Type.TString;
ts: Type.TInteger;
}>;
/** Current bounded exchanges for one session companion thread. */
declare const SessionsCompanionStateResultSchema: Type.TObject<{
exchanges: Type.TArray<Type.TObject<{
question: Type.TString;
answer: Type.TString;
ts: Type.TInteger;
}>>;
}>;
type SessionObserverDigest = Static<typeof SessionObserverDigestSchema>;
type SessionsCompanionAskResult = Static<typeof SessionsCompanionAskResultSchema>;
type SessionsCompanionStateResult = Static<typeof SessionsCompanionStateResultSchema>;
//#endregion
//#region packages/gateway-protocol/src/schema/snapshot.d.ts
/** Initial and incremental gateway state snapshot payload. */
declare const SnapshotSchema: Type.TObject<{
suspension: Type.TOptional<Type.TObject<{
phase: Type.TUnion<[Type.TLiteral<"accepting">, Type.TLiteral<"preparing">, Type.TLiteral<"draining">, Type.TLiteral<"prepared">]>;
}>>;
presence: Type.TArray<Type.TObject<{
host: Type.TOptional<Type.TString>;
ip: Type.TOptional<Type.TString>;
version: Type.TOptional<Type.TString>;
platform: Type.TOptional<Type.TString>;
deviceFamily: Type.TOptional<Type.TString>;
modelIdentifier: Type.TOptional<Type.TString>;
timeZone: Type.TOptional<Type.TString>;
mode: Type.TOptional<Type.TString>;
lastInputSeconds: Type.TOptional<Type.TInteger>;
reason: Type.TOptional<Type.TString>;
tags: Type.TOptional<Type.TArray<Type.TString>>;
text: Type.TOptional<Type.TString>;
/** Heartbeat freshness, not online duration or user activity. */
ts: Type.TInteger;
/** Server timestamps for the person's continuous online interval and last accepted activity. */
onlineSince: Type.TOptional<Type.TInteger>;
lastActivityAt: Type.TOptional<Type.TInteger>;
deviceId: Type.TOptional<Type.TString>;
roles: Type.TOptional<Type.TArray<Type.TString>>;
scopes: Type.TOptional<Type.TArray<Type.TString>>;
instanceId: Type.TOptional<Type.TString>;
user: Type.TOptional<Type.TObject<{
/** Canonical profile id when resolved, otherwise authenticated identity; grouping also uses identity qualification. */
id: Type.TString;
identity: Type.TOptional<Type.TObject<{
type: Type.TLiteral<"profile">;
id: Type.TString;
}>>;
email: Type.TOptional<Type.TString>;
name: Type.TOptional<Type.TString>;
avatarUrl: Type.TOptional<Type.TString>;
}>>;
/** Sessions this connection declares it is viewing, independent of transport subscriptions. Sorted lexicographically. */
watchedSessions: Type.TOptional<Type.TArray<Type.TString>>;
}>>;
health: Type.TObject<{
ok: Type.TOptional<Type.TLiteral<true>>;
ts: Type.TOptional<Type.TInteger>;
durationMs: Type.TOptional<Type.TInteger>;
eventLoop: Type.TOptional<Type.TObject<{
degraded: Type.TBoolean;
degradedSinceMs: Type.TOptional<Type.TUnion<[Type.TInteger, Type.TNull]>>;
reasons: Type.TArray<Type.TUnion<[Type.TLiteral<"event_loop_delay">, Type.TLiteral<"event_loop_utilization">, Type.TLiteral<"cpu">]>>;
intervalMs: Type.TNumber;
delayP99Ms: Type.TNumber;
delayMaxMs: Type.TNumber;
utilization: Type.TNumber;
cpuCoreRatio: Type.TNumber;
}>>;
plugins: Type.TOptional<Type.TObject<{
loaded: Type.TArray<Type.TString>;
errors: Type.TArray<Type.TObject<{
id: Type.TString;
origin: Type.TString;
activated: Type.TBoolean;
activationSource: Type.TOptional<Type.TString>;
activationReason: Type.TOptional<Type.TString>;
failurePhase: Type.TOptional<Type.TString>;
error: Type.TString;
}>>;
unavailable: Type.TOptional<Type.TArray<Type.TObject<{
id: Type.TString;
state: Type.TLiteral<"configured-unavailable">;
diagnostic: Type.TObject<{
kind: Type.TLiteral<"plugin-verification">;
reason: Type.TString;
detail: Type.TString;
}>;
}>>>;
}>>;
contextEngines: Type.TOptional<Type.TObject<{
quarantined: Type.TArray<Type.TObject<{
engineId: Type.TString;
owner: Type.TOptional<Type.TString>;
operation: Type.TString;
reason: Type.TString;
failedAt: Type.TInteger;
}>>;
}>>;
deliveryQueues: Type.TOptional<Type.TObject<{
failed: Type.TArray<Type.TObject<{
queueName: Type.TString;
count: Type.TInteger;
oldestFailedAt: Type.TOptional<Type.TInteger>;
}>>;
ingressFailed: Type.TOptional<Type.TArray<Type.TObject<{
channelId: Type.TString;
accountId: Type.TString;
count: Type.TInteger;
oldestFailedAt: Type.TOptional<Type.TInteger>;
}>>>;
ingressPressure: Type.TOptional<Type.TArray<Type.TObject<{
channelId: Type.TString;
accountId: Type.TString;
laneCount: Type.TInteger;
pendingCount: Type.TInteger;
claimedCount: Type.TInteger;
blockedCount: Type.TInteger;
oldestReceivedAt: Type.TInteger;
}>>>;
}>>;
modelPricing: Type.TOptional<Type.TObject<{
state: Type.TUnion<[Type.TLiteral<"ok">, Type.TLiteral<"degraded">, Type.TLiteral<"disabled">]>;
sources: Type.TArray<Type.TObject<{
source: Type.TUnion<[Type.TLiteral<"openrouter">, Type.TLiteral<"litellm">, Type.TLiteral<"bootstrap">, Type.TLiteral<"refresh">]>;
state: Type.TUnion<[Type.TLiteral<"ok">, Type.TLiteral<"degraded">]>;
lastFailureAt: Type.TOptional<Type.TInteger>;
detail: Type.TOptional<Type.TString>;
}>>;
lastFailureAt: Type.TOptional<Type.TInteger>;
detail: Type.TOptional<Type.TString>;
}>>;
configReload: Type.TOptional<Type.TObject<{
hotReloadStatus: Type.TUnion<[Type.TLiteral<"active">, Type.TLiteral<"disabled">]>;
}>>;
channels: Type.TOptional<Type.TRecord<"^.*$", Type.TUnknown>>;
channelOrder: Type.TOptional<Type.TArray<Type.TString>>;
channelLabels: Type.TOptional<Type.TRecord<"^.*$", Type.TString>>;
heartbeatSeconds: Type.TOptional<Type.TInteger>;
defaultAgentId: Type.TOptional<Type.TString>;
agents: Type.TOptional<Type.TArray<Type.TObject<{
agentId: Type.TString;
name: Type.TOptional<Type.TString>;
isDefault: Type.TBoolean;
heartbeat: Type.TObject<{
enabled: Type.TBoolean;
every: Type.TString;
everyMs: Type.TUnion<[Type.TInteger, Type.TNull]>;
prompt: Type.TString;
target: Type.TString;
model: Type.TOptional<Type.TString>;
session: Type.TOptional<Type.TString>;
ackMaxChars: Type.TInteger;
}>;
sessions: Type.TObject<{
path: Type.TString;
count: Type.TInteger;
recent: Type.TArray<Type.TObject<{
key: Type.TString;
updatedAt: Type.TUnion<[Type.TInteger, Type.TNull]>;
age: Type.TUnion<[Type.TInteger, Type.TNull]>;
}>>;
}>;
}>>>;
sessions: Type.TOptional<Type.TObject<{
path: Type.TString;
count: Type.TInteger;
recent: Type.TArray<Type.TObject<{
key: Type.TString;
updatedAt: Type.TUnion<[Type.TInteger, Type.TNull]>;
age: Type.TUnion<[Type.TInteger, Type.TNull]>;
}>>;
}>>;
}>;
stateVersion: Type.TObject<{
presence: Type.TInteger;
health: Type.TInteger;
}>;
uptimeMs: Type.TInteger;
/** Resolved source-config revision accepted by the active Gateway runtime. */
appliedConfigHash: Type.TOptional<Type.TUnion<[Type.TString, Type.TNull]>>;
configPath: Type.TOptional<Type.TString>;
stateDir: Type.TOptional<Type.TString>;
sessionDefaults: Type.TOptional<Type.TObject<{
defaultAgentId: Type.TString;
modelConfigured: Type.TOptional<Type.TBoolean>;
ownership: Type.TOptional<Type.TUnion<[Type.TLiteral<"sole">, Type.TLiteral<"legacy">, Type.TLiteral<"explicit">]>>;
selectionRequired: Type.TOptional<Type.TBoolean>;
mainKey: Type.TString;
mainSessionKey: Type.TString;
scope: Type.TOptional<Type.TString>;
}>>;
/** Credential-free browser sign-in endpoint advertised to authenticated operators. */
controlUiIdentityUrl: Type.TOptional<Type.TString>;
authMode: Type.TOptional<Type.TUnion<[Type.TLiteral<"none">, Type.TLiteral<"token">, Type.TLiteral<"password">, Type.TLiteral<"trusted-proxy">]>>;
updateAvailable: Type.TOptional<Type.TObject<{
currentVersion: Type.TString;
latestVersion: Type.TString;
channel: Type.TString;
currentSha: Type.TOptional<Type.TString>;
upstreamRef: Type.TOptional<Type.TString>;
upstreamSha: Type.TOptional<Type.TString>;
commitsBehind: Type.TOptional<Type.TInteger>;
commits: Type.TOptional<Type.TArray<Type.TObject<{
sha: Type.TString;
subject: Type.TString;
}>>>;
}>>;
updateSchedule: Type.TOptional<Type.TObject<{
channel: Type.TString;
autoEnabled: Type.TBoolean;
install: Type.TOptional<Type.TObject<{
kind: Type.TUnion<[Type.TLiteral<"package">, Type.TLiteral<"git">, Type.TLiteral<"unknown">]>;
git: Type.TOptional<Type.TUnion<[Type.TObject<{
currentSha: Type.TOptional<Type.TString>;
commitAtMs: Type.TOptional<Type.TInteger>;
installedAtMs: Type.TOptional<Type.TInteger>;
status: Type.TLiteral<"current">;
}>, Type.TObject<{
currentSha: Type.TOptional<Type.TString>;
commitAtMs: Type.TOptional<Type.TInteger>;
installedAtMs: Type.TOptional<Type.TInteger>;
status: Type.TLiteral<"behind">;
commitsBehind: Type.TInteger;
}>, Type.TObject<{
currentSha: Type.TOptional<Type.TString>;
commitAtMs: Type.TOptional<Type.TInteger>;
installedAtMs: Type.TOptional<Type.TInteger>;
status: Type.TLiteral<"ahead">;
commitsAhead: Type.TInteger;
}>, Type.TObject<{
currentSha: Type.TOptional<Type.TString>;
commitAtMs: Type.TOptional<Type.TInteger>;
installedAtMs: Type.TOptional<Type.TInteger>;
status: Type.TLiteral<"diverged">;
commitsAhead: Type.TInteger;
commitsBehind: Type.TInteger;
}>, Type.TObject<{
currentSha: Type.TOptional<Type.TString>;
commitAtMs: Type.TOptional<Type.TInteger>;
installedAtMs: Type.TOptional<Type.TInteger>;
status: Type.TLiteral<"unavailable">;
reason: Type.TUnion<[Type.TLiteral<"fetch-failed">, Type.TLiteral<"no-upstream">, Type.TLiteral<"no-upstream-sha">, Type.TLiteral<"comparison-failed">, Type.TLiteral<"git-unavailable">]>;
}>]>>;
}>>;
target: Type.TOptional<Type.TUnion<[Type.TObject<{
kind: Type.TLiteral<"package">;
version: Type.TString;
}>, Type.TObject<{
kind: Type.TLiteral<"git">;
upstreamRef: Type.TString;
upstreamSha: Type.TString;
commitsBehind: Type.TInteger;
}>]>>;
campaign: Type.TOptional<Type.TObject<{
id: Type.TString;
state: Type.TUnion<[Type.TLiteral<"waiting-for-idle">, Type.TLiteral<"countdown">, Type.TLiteral<"applying">]>;
announcedAtMs: Type.TInteger;
applyAtMs: Type.TOptional<Type.TInteger>;
holdUntilMs: Type.TOptional<Type.TInteger>;
forceAtMs: Type.TInteger;
updatedAtMs: Type.TInteger;
}>>;
}>>;
}>;
type Snapshot = Static<typeof SnapshotSchema>;
//#endregion
//#region packages/gateway-protocol/src/schema/portals.d.ts
declare const PortalSummarySchema: Type.TObject<{
id: Type.TString;
title: Type.TString;
port: Type.TInteger;
listenPort: Type.TInteger;
publicUrl: Type.TString;
path: Type.TOptional<Type.TString>;
description: Type.TOptional<Type.TString>;
origin: Type.TOptional<Type.TString>;
createdAtMs: Type.TInteger;
tokenQuery: Type.TOptional<Type.TString>;
url: Type.TOptional<Type.TString>;
}>;
declare const PortalOpenResultSchema: Type.TObject<{
id: Type.TString;
title: Type.TString;
port: Type.TInteger;
listenPort: Type.TInteger;
publicUrl: Type.TString;
path: Type.TOptional<Type.TString>;
description: Type.TOptional<Type.TString>;
origin: Type.TOptional<Type.TString>;
createdAtMs: Type.TInteger;
tokenQuery: Type.TString;
url: Type.TString;
}>;
type PortalSummary = Static<typeof PortalSummarySchema>;
type PortalOpenResult = Static<typeof PortalOpenResultSchema>;
//#endregion
//#region packages/gateway-protocol/src/schema/wizard.d.ts
/** Client answer payload for the current wizard step. */
declare const WizardAnswerSchema: Type.TObject<{
stepId: Type.TString;
value: Type.TOptional<Type.TUnknown>;
}>;
/** UI contract for one wizard step rendered by gateway clients. */
declare const WizardStepSchema: Type.TObject<{
id: Type.TString;
type: Type.TUnion<[Type.TLiteral<"note">, Type.TLiteral<"select">, Type.TLiteral<"text">, Type.TLiteral<"confirm">, Type.TLiteral<"multiselect">, Type.TLiteral<"progress">, Type.TLiteral<"action">]>;
title: Type.TOptional<Type.TString>;
message: Type.TOptional<Type.TString>;
format: Type.TOptional<Type.TUnion<[Type.TLiteral<"plain">]>>;
options: Type.TOptional<Type.TArray<Type.TObject<{
value: Type.TUnknown;
label: Type.TString;
hint: Type.TOptional<Type.TString>;
}>>>;
initialValue: Type.TOptional<Type.TUnknown>;
placeholder: Type.TOptional<Type.TString>;
sensitive: Type.TOptional<Type.TBoolean>;
executor: Type.TOptional<Type.TUnion<[Type.TLiteral<"gateway">, Type.TLiteral<"client">]>>;
externalUrl: Type.TOptional<Type.TString>;
deviceCode: Type.TOptional<Type.TObject<{
code: Type.TString;
expiresInMinutes: Type.TOptional<Type.TInteger>;
message: Type.TOptional<Type.TString>;
}>>;
}>;
/** Result after advancing a wizard session. */
declare const WizardNextResultSchema: Type.TObject<{
done: Type.TBoolean;
step: Type.TOptional<Type.TObject<{
id: Type.TString;
type: Type.TUnion<[Type.TLiteral<"note">, Type.TLiteral<"select">, Type.TLiteral<"text">, Type.TLiteral<"confirm">, Type.TLiteral<"multiselect">, Type.TLiteral<"progress">, Type.TLiteral<"action">]>;
title: Type.TOptional<Type.TString>;
message: Type.TOptional<Type.TString>;
format: Type.TOptional<Type.TUnion<[Type.TLiteral<"plain">]>>;
options: Type.TOptional<Type.TArray<Type.TObject<{
value: Type.TUnknown;
label: Type.TString;
hint: Type.TOptional<Type.TString>;
}>>>;
initialValue: Type.TOptional<Type.TUnknown>;
placeholder: Type.TOptional<Type.TString>;
sensitive: Type.TOptional<Type.TBoolean>;
executor: Type.TOptional<Type.TUnion<[Type.TLiteral<"gateway">, Type.TLiteral<"client">]>>;
externalUrl: Type.TOptional<Type.TString>;
deviceCode: Type.TOptional<Type.TObject<{
code: Type.TString;
expiresInMinutes: Type.TOptional<Type.TInteger>;
message: Type.TOptional<Type.TString>;
}>>;
}>>;
status: Type.TOptional<Type.TUnion<[Type.TLiteral<"running">, Type.TLiteral<"done">, Type.TLiteral<"cancelled">, Type.TLiteral<"error">]>>;
error: Type.TOptional<Type.TString>;
channels: Type.TOptional<Type.TArray<Type.TString>>;
accounts: Type.TOptional<Type.TArray<Type.TObject<{
channel: Type.TString;
accountId: Type.TString;
}>>>;
preparedModelRef: Type.TOptional<Type.TString>;
modelActivation: Type.TOptional<Type.TObject<{
modelRef: Type.TString;
gatewayRestartRequired: Type.TOptional<Type.TLiteral<true>>;
}>>;
activationRejection: Type.TOptional<Type.TObject<{
disposition: Type.TLiteral<"rejected-before-promotion">;
status: Type.TUnion<[Type.TLiteral<"auth">, Type.TLiteral<"rate_limit">, Type.TLiteral<"billing">, Type.TLiteral<"timeout">, Type.TLiteral<"format">, Type.TLiteral<"unavailable">, Type.TLiteral<"unknown">]>;
}>>;
}>;
type WizardAnswer = Static<typeof WizardAnswerSchema>;
type WizardStep = Static<typeof WizardStepSchema>;
type WizardNextResult = Static<typeof WizardNextResultSchema>;
//#endregion
//#region packages/gateway-protocol/src/schema/worker-admission.d.ts
/** Dedicated first-frame payload accepted only on the worker ingress. */
declare const WorkerConnectParamsSchema: Type.TObject<{
minProtocol: Type.TInteger;
maxProtocol: Type.TInteger;
client: Type.TObject<{
id: Type.TLiteral<"openclaw-worker">;
version: Type.TString;
platform: Type.TString;
mode: Type.TLiteral<"worker">;
}>;
role: Type.TLiteral<"worker">;
admission: Type.TUnion<[Type.TObject<{
environmentId: Type.TString;
credential: Type.TString;
ownerEpoch: Type.TInteger;
rpcSetVersion: Type.TInteger;
handshake: Type.TObject<{
bundleHash: Type.TString;
openclawVersion: Type.TString;
protocolFeatures: Type.TArray<Type.TString>;
bundlePrewarm: Type.TOptional<Type.TInteger>;
}>;
sessionId: Type.TNull;
runId: Type.TNull;
}>, Type.TObject<{
environmentId: Type.TString;
credential: Type.TString;
ownerEpoch: Type.TInteger;
rpcSetVersion: Type.TInteger;
handshake: Type.TObject<{
bundleHash: Type.TString;
openclawVersion: Type.TString;
protocolFeatures: Type.TArray<Type.TString>;
bundlePrewarm: Type.TOptional<Type.TInteger>;
}>;
sessionId: Type.TString;
runId: Type.TString;
}>]>;
}>;
declare const WorkerTranscriptMessageSchema: Type.TUnion<[Type.TObject<{
role: Type.TLiteral<"user">;
content: Type.TArray<Type.TUnion<[Type.TObject<{
type: Type.TLiteral<"text">;
text: Type.TString;
textSignature: Type.TOptional<Type.TString>;
}>, Type.TObject<{
type: Type.TLiteral<"image">;
data: Type.TString;
mimeType: Type.TString;
}>]>>;
timestamp: Type.TInteger;
}>, Type.TObject<{
role: Type.TLiteral<"assistant">;
content: Type.TArray<Type.TUnion<[Type.TObject<{
type: Type.TLiteral<"text">;
text: Type.TString;
textSignature: Type.TOptional<Type.TString>;
}>, Type.TObject<{
type: Type.TLiteral<"thinking">;
thinking: Type.TString;
thinkingSignature: Type.TOptional<Type.TString>;
redacted: Type.TOptional<Type.TBoolean>;
}>, Type.TObject<{
type: Type.TLiteral<"toolCall">;
id: Type.TString;
name: Type.TString;
arguments: Type.TRecord<"^.*$", Type.TUnknown>;
thoughtSignature: Type.TOptional<Type.TString>;
executionMode: Type.TOptional<Type.TUnion<[Type.TLiteral<"sequential">, Type.TLiteral<"parallel">]>>;
}>]>>;
api: Type.TString;
provider: Type.TString;
model: Type.TString;
responseModel: Type.TOptional<Type.TString>;
responseId: Type.TOptional<Type.TString>;
providerReplay: Type.TOptional<Type.TObject<{
v: Type.TLiteral<1>;
type: Type.TString;
id: Type.TOptional<Type.TString>;
data: Type.TString;
replayIndex: Type.TOptional<Type.TInteger>;
provider: Type.TString;
api: Type.TString;
model: Type.TString;
baseUrlHash: Type.TOptional<Type.TString>;
sessionHash: Type.TOptional<Type.TString>;
authProfileHash: Type.TOptional<Type.TString>;
}>>;
diagnostics: Type.TOptional<Type.TArray<Type.TObject<{
type: Type.TString;
timestamp: Type.TInteger;
error: Type.TOptional<Type.TObject<{
name: Type.TOptional<Type.TString>;
message: Type.TString;
stack: Type.TOptional<Type.TString>;
code: Type.TOptional<Type.TUnion<[Type.TString, Type.TNumber]>>;
}>>;
details: Type.TOptional<Type.TRecord<"^.*$", Type.TUnknown>>;
}>>>;
usage: Type.TObject<{
input: Type.TNumber;
output: Type.TNumber;
cacheRead: Type.TNumber;
cacheWrite: Type.TNumber;
contextUsage: Type.TOptional<Type.TUnion<[Type.TObject<{
state: Type.TLiteral<"available">;
promptTokens: Type.TNumber;
totalTokens: Type.TNumber;
}>, Type.TObject<{
state: Type.TLiteral<"unavailable">;
}>]>>;
totalTokens: Type.TNumber;
cost: Type.TObject<{
input: Type.TNumber;
output: Type.TNumber;
cacheRead: Type.TNumber;
cacheWrite: Type.TNumber;
total: Type.TNumber;
totalOrigin: Type.TOptional<Type.TLiteral<"provider-billed">>;
}>;
}>;
stopReason: Type.TUnion<[Type.TLiteral<"stop">, Type.TLiteral<"length">, Type.TLiteral<"toolUse">, Type.TLiteral<"error">, Type.TLiteral<"aborted">]>;
errorMessage: Type.TOptional<Type.TString>;
errorCode: Type.TOptional<Type.TString>;
errorType: Type.TOptional<Type.TString>;
errorBody: Type.TOptional<Type.TString>;
timestamp: Type.TInteger;
}>, Type.TObject<{
role: Type.TLiteral<"toolResult">;
toolCallId: Type.TString;
toolName: Type.TString;
content: Type.TArray<Type.TUnion<[Type.TObject<{
type: Type.TLiteral<"text">;
text: Type.TString;
textSignature: Type.TOptional<Type.TString>;
}>, Type.TObject<{
type: Type.TLiteral<"image">;
data: Type.TString;
mimeType: Type.TString;
}>]>>;
details: Type.TOptional<Type.TUnknown>;
isError: Type.TBoolean;
timestamp: Type.TInteger;
}>]>;
declare const WorkerTranscriptCommitParamsSchema: Type.TObject<{
runEpoch: Type.TInteger;
seq: Type.TInteger;
baseLeafId: Type.TUnion<[Type.TString, Type.TNull]>;
messages: Type.TArray<Type.TUnion<[Type.TObject<{
role: Type.TLiteral<"user">;
content: Type.TArray<Type.TUnion<[Type.TObject<{
type: Type.TLiteral<"text">;
text: Type.TString;
textSignature: Type.TOptional<Type.TString>;
}>, Type.TObject<{
type: Type.TLiteral<"image">;
data: Type.TString;
mimeType: Type.TString;
}>]>>;
timestamp: Type.TInteger;
}>, Type.TObject<{
role: Type.TLiteral<"assistant">;
content: Type.TArray<Type.TUnion<[Type.TObject<{
type: Type.TLiteral<"text">;
text: Type.TString;
textSignature: Type.TOptional<Type.TString>;
}>, Type.TObject<{
type: Type.TLiteral<"thinking">;
thinking: Type.TString;
thinkingSignature: Type.TOptional<Type.TString>;
redacted: Type.TOptional<Type.TBoolean>;
}>, Type.TObject<{
type: Type.TLiteral<"toolCall">;
id: Type.TString;
name: Type.TString;
arguments: Type.TRecord<"^.*$", Type.TUnknown>;
thoughtSignature: Type.TOptional<Type.TString>;
executionMode: Type.TOptional<Type.TUnion<[Type.TLiteral<"sequential">, Type.TLiteral<"parallel">]>>;
}>]>>;
api: Type.TString;
provider: Type.TString;
model: Type.TString;
responseModel: Type.TOptional<Type.TString>;
responseId: Type.TOptional<Type.TString>;
providerReplay: Type.TOptional<Type.TObject<{
v: Type.TLiteral<1>;
type: Type.TString;
id: Type.TOptional<Type.TString>;
data: Type.TString;
replayIndex: Type.TOptional<Type.TInteger>;
provider: Type.TString;
api: Type.TString;
model: Type.TString;
baseUrlHash: Type.TOptional<Type.TString>;
sessionHash: Type.TOptional<Type.TString>;
authProfileHash: Type.TOptional<Type.TString>;
}>>;
diagnostics: Type.TOptional<Type.TArray<Type.TObject<{
type: Type.TString;
timestamp: Type.TInteger;
error: Type.TOptional<Type.TObject<{
name: Type.TOptional<Type.TString>;
message: Type.TString;
stack: Type.TOptional<Type.TString>;
code: Type.TOptional<Type.TUnion<[Type.TString, Type.TNumber]>>;
}>>;
details: Type.TOptional<Type.TRecord<"^.*$", Type.TUnknown>>;
}>>>;
usage: Type.TObject<{
input: Type.TNumber;
output: Type.TNumber;
cacheRead: Type.TNumber;
cacheWrite: Type.TNumber;
contextUsage: Type.TOptional<Type.TUnion<[Type.TObject<{
state: Type.TLiteral<"available">;
promptTokens: Type.TNumber;
totalTokens: Type.TNumber;
}>, Type.TObject<{
state: Type.TLiteral<"unavailable">;
}>]>>;
totalTokens: Type.TNumber;
cost: Type.TObject<{
input: Type.TNumber;
output: Type.TNumber;
cacheRead: Type.TNumber;
cacheWrite: Type.TNumber;
total: Type.TNumber;
totalOrigin: Type.TOptional<Type.TLiteral<"provider-billed">>;
}>;
}>;
stopReason: Type.TUnion<[Type.TLiteral<"stop">, Type.TLiteral<"length">, Type.TLiteral<"toolUse">, Type.TLiteral<"error">, Type.TLiteral<"aborted">]>;
errorMessage: Type.TOptional<Type.TString>;
errorCode: Type.TOptional<Type.TString>;
errorType: Type.TOptional<Type.TString>;
errorBody: Type.TOptional<Type.TString>;
timestamp: Type.TInteger;
}>, Type.TObject<{
role: Type.TLiteral<"toolResult">;
toolCallId: Type.TString;
toolName: Type.TString;
content: Type.TArray<Type.TUnion<[Type.TObject<{
type: Type.TLiteral<"text">;
text: Type.TString;
textSignature: Type.TOptional<Type.TString>;
}>, Type.TObject<{
type: Type.TLiteral<"image">;
data: Type.TString;
mimeType: Type.TString;
}>]>>;
details: Type.TOptional<Type.TUnknown>;
isError: Type.TBoolean;
timestamp: Type.TInteger;
}>]>>;
}>;
type WorkerConnectParams = Static<typeof WorkerConnectParamsSchema>;
type WorkerTranscriptMessage = Static<typeof WorkerTranscriptMessageSchema>;
type WorkerTranscriptCommitParams = Static<typeof WorkerTranscriptCommitParamsSchema>;
//#endregion
//#region src/cron/scheduled-tool-policy.d.ts
/** Closed, server-authored origin of an account-scoped scheduled tool cap. */
type CronScheduledToolCallerOrigin = {
kind: "external";
channel: string;
} | {
kind: "local";
} | {
kind: "unknown";
};
/**
* Restrict-only execution target for a job's exec grant, captured from a
* creator surface whose only exec capability was host-pinned. New pinned jobs
* persist this as part of a grant-coupled envelope; unmarked legacy jobs keep
* baseline exec behavior.
*/
type CronToolsAllowExecTarget = {
version: 1;
host: "gateway";
/** Mandatory approval floor inherited from the captured creator surface. */
ask?: "always";
};
/** Persisted proof that this job was created with an exact exec restriction. */
type CronToolsAllowExecTargetRequirement = {
version: 1;
target: CronToolsAllowExecTarget;
grantIndex: number;
recoveryRequired?: never;
} | {
version: 1;
target?: never;
recoveryRequired: true;
};
/** Server-authored provenance for a persisted scheduled tool-cap authority envelope. */
type CronScheduledToolPolicy = {
version: 1;
mode: "trusted";
ownerSessionKey?: never;
ownerAccountId?: never;
} | {
version: 1;
mode: "account";
ownerSessionKey: string;
ownerAccountId: string;
};
//#endregion
//#region src/plugin-sdk/channel-route.d.ts
/** Coarse chat shape used when a channel can distinguish direct, group, and broadcast targets. */
type ChannelRouteChatType = "direct" | "group" | "channel";
/** Provider-specific thread kind carried with normalized channel routes. */
type ChannelRouteThreadKind = "topic" | "thread" | "reply";
/** Describes which runtime surface supplied a channel route thread id. */
type ChannelRouteThreadSource = "explicit" | "target" | "session" | "turn";
/** Normalized channel route used for comparison, binding, and dedupe helpers. */
type ChannelRouteRef = {
/** Lowercase channel id such as `slack`, `telegram`, or `discord`. */
channel?: string;
/** Normalized account/profile id when a channel supports multiple accounts. */
accountId?: string;
target?: {
/** Canonical destination id used for route equality and delivery. */
to: string;
/** Original destination text when provider target grammar differs from the canonical id. */
rawTo?: string;
/** Coarse destination shape used by channels with different direct/group/broadcast rules. */
chatType?: ChannelRouteChatType;
};
thread?: {
/** Provider thread/topic/root id; strings are preserved when providers use opaque ids. */
id: string | number;
/** Provider-specific thread family for channels that distinguish topics, replies, and threads. */
kind?: ChannelRouteThreadKind;
/** Runtime source that supplied the thread id, used when callers need route provenance. */
source?: ChannelRouteThreadSource;
};
};
/** Loose route input accepted at SDK boundaries before normalization. */
type ChannelRouteRefInput = {
/** Raw channel id; normalized to lowercase. */
channel?: unknown;
/** Raw account/profile id; normalized with account-id rules when string. */
accountId?: unknown;
/** Raw destination id before trimming and route-key normalization. */
to?: unknown;
/** Provider-specific target text retained when different from `to`. */
rawTo?: unknown;
/** Coarse destination shape supplied by channels that distinguish target kinds. */
chatType?: ChannelRouteChatType;
/** Raw provider thread/topic/root id before route-key normalization. */
threadId?: unknown;
/** Provider-specific thread family carried with the normalized thread id. */
threadKind?: ChannelRouteThreadKind;
/** Runtime surface that supplied the thread id. */
threadSource?: ChannelRouteThreadSource;
};
/** Raw outbound target input shape used by helpers that do not need thread metadata source. */
type ChannelRouteTargetInput = Pick<ChannelRouteRefInput, "channel" | "accountId" | "to" | "rawTo" | "chatType" | "threadId">;
//#endregion
//#region src/shared/session-types.d.ts
/** Per-session Control UI face preference carried by session list rows. */
type SessionBoardFace = "chat" | "dashboard";
//#endregion
//#region src/utils/delivery-context.types.d.ts
/** Deferred outbound delivery intent attached to a session or task. */
type DeliveryIntentRef = {
/** Stable queue/work item id. */
id: string;
/** Intent family; currently scoped to outbound queue delivery. */
kind: "outbound_queue";
/** Whether queueing is mandatory or best-effort for this delivery. */
queuePolicy?: "required" | "best_effort";
};
/** Canonical channel delivery target shared by sessions, cron, tasks, and plugins. */
type DeliveryContext = Pick<ChannelRouteTargetInput, "accountId" | "channel" | "threadId" | "to"> & {
/** Channel/plugin id that owns the delivery target. */
channel?: string;
/** Channel-local destination id, preserved with channel-specific casing. */
to?: string;
/** Optional channel account/workspace id. */
accountId?: string;
/** Optional thread/topic id nested under `to`. */
threadId?: string | number;
/** Optional queued-delivery intent associated with this context. */
deliveryIntent?: DeliveryIntentRef;
};
//#endregion
//#region src/config/sessions/main-session-recovery.types.d.ts
type MainRestartRecoveryState = {
/** Stable identity for one interrupted episode; prevents clear-and-rewedge ABA matches. */
cycleId: string;
/** Monotonic identity for observations within the current recovery cycle. */
revision: number;
/** Attempts charged when their reservation is persisted, before dispatch. */
chargedAttempts: number;
/** Last attempt observed starting a backend turn; later startup failures get a fresh budget. */
startedAttempt?: number;
/** Private safe token for one recovered outer turn; raw identity refs never enter session state. */
executionIdentity?: {
tokenVersion: 1;
contextId: string;
executionId: string;
runId: string;
createdAt: number;
};
reservation?: {
runId: string;
attempt: number;
lifecycleGeneration: string;
};
foregroundClaims?: {
lifecycleGeneration: string;
tokens: string[];
/** Run identity for claims that have crossed the actual agent-run boundary. */
runIdsByClaimId?: Record<string, string>;
};
tombstone?: {
reason: string;
/** Durable successor returned when an explicit rollover request is retried. */
recoveredSessionId?: string;
recoveredSessionKey?: string;
};
};
//#endregion
//#region src/config/sessions/pending-final-delivery-types.d.ts
type PendingFinalDeliveryState = {
createdAt: number;
context?: DeliveryContext;
intentId?: string;
deliveries?: Array<{
id: string;
state: "prepared" | "queued" | "delivered" | "suppressed" | "unknown";
}>;
} & ({
kind: "replayable";
text: string;
} | {
kind: "transport-only";
});
/**
* Owed user-visible notice that a final's delivery outcome stayed unknown.
* Settled unknown custody records the debt here; the next same-route turn
* sends it once, so an ambiguous loss never ends silently.
*/
type PendingDeliveryNoticeState = {
createdAt: number;
context: DeliveryContext;
intentId: string;
state: "owed" | "unresolved" | "acknowledged";
};
//#endregion
//#region src/auto-reply/source-reply-delivery-mode.types.d.ts
/** Per-turn authority for automatic replies versus explicit message-tool sends. */
type SourceReplyDeliveryMode = "automatic" | "message_tool_only";
//#endregion
//#region src/config/sessions/restart-recovery-types.d.ts
type RestartRecoveryBeforeAgentReplyState = "admitted" | "pending" | "continue" | "handled-silent" | "handled-reply" | "handled-unrecoverable";
type RestartRecoveryTerminalDeliveryEvidenceResult = {
/** The terminal result was captured even when it contained no visible or delivery evidence. */
captured?: true;
payloads?: Array<{
mediaUrls?: string[];
visible?: boolean;
}>;
payloadsTruncated?: true;
deliveryStatus?: {
status: "failed" | "partial_failed" | "sent" | "suppressed";
errorMessage?: string;
payloadOutcomes?: Array<{
index: number;
status: "failed" | "sent" | "suppressed";
sentBeforeError?: boolean;
}>;
};
messagingToolSentTargets?: Array<{
provider?: string;
accountId?: string;
to?: string;
threadId?: string;
threadImplicit?: boolean;
threadSuppressed?: boolean;
mediaUrls?: string[];
visible?: boolean;
}>;
messagingToolSentTargetsTruncated?: true;
/** Aggregate committed sends were not all represented by route-checkable target records. */
messagingToolAggregateEvidenceUnaccounted?: true;
/** The terminal run reported a committed effect that makes fresh replay unsafe. */
restartUnsafeSideEffectsDetected?: true;
};
type RestartRecoveryTerminalDeliveryEvidence = RestartRecoveryTerminalDeliveryEvidenceResult & {
runId: string;
};
/** Durable ownership and idempotency state for gateway restart recovery. */
type SessionRestartRecoveryState = {
restartRecoveryBeforeAgentReplyState?: RestartRecoveryBeforeAgentReplyState;
/** Durable pre/post boundary around the terminal external send. */
restartRecoveryDeliveryReceiptState?: "terminal-pending" | "delivered-terminal";
/** Exact agent tool call whose terminal external send owns the receipt. */
restartRecoveryDeliveryToolCallId?: string;
restartRecoveryDeliveryContext?: DeliveryContext;
/** Exact host-owned media allowlist for a generated-media recovery run. */
restartRecoveryDeliveryMediaUrls?: string[];
/** Keeps the message tool absent while a generated-media recovery run is resumed. */
restartRecoveryDisableMessageTool?: true;
/** Suppresses visible text when a recovery attempt repairs only missing media. */
restartRecoverySuppressTextDelivery?: true;
restartRecoveryDeliveryRequestFingerprint?: string;
restartRecoveryDeliveryRunId?: string;
restartRecoveryDeliverySourceRunId?: string;
restartRecoveryRequesterAccountId?: string;
restartRecoveryRequesterSenderId?: string;
restartRecoverySameChannelThreadRequired?: true;
restartRecoverySourceIngress?: "channel" | "control-ui" | "internal";
restartRecoverySourceReplyDeliveryMode?: SourceReplyDeliveryMode;
restartRecoveryTerminalDeliveryEvidence?: RestartRecoveryTerminalDeliveryEvidence[];
restartRecoveryTerminalRunIds?: string[];
};
//#endregion
//#region src/security/external-content-source.d.ts
/** Hook session sources that carry untrusted external content into agent prompts. */
type HookExternalContentSource = "email" | "gmail" | "webhook";
//#endregion
//#region src/config/sessions/session-entry-provenance.d.ts
/** Kept aligned with SessionStateActorType (src/sessions/session-state-event-kinds.ts); not imported to avoid layering config/sessions onto src/sessions. */
type SessionActor = {
type: "human" | "agent" | "system";
id?: string;
label?: string;
};
/** Only trusted creation owners may stamp a Gateway profile namespace. */
type SessionCreatedActor = SessionActor & ({
type: "human";
source: "profile" | "channel" | "unknown";
} | {
type: "agent" | "system";
});
type SessionOwnerAssignment = {
actor: SessionActor;
assignedBy?: SessionActor;
assignedAt?: number;
};
type SessionCreatedVia = "operator" | "spawn" | "channel" | "cron" | "talk" | "run" | "plugin" | "internal";
type SessionEntryProvenance = {
/** Plugin id that owns this session through a trusted runtime creation seam. */
pluginOwnerId?: string;
/** External hook source that has contributed content to this transcript. */
hookExternalContentSource?: HookExternalContentSource;
};
//#endregion
//#region src/config/sessions/session-model-fallback.d.ts
type AgentPatchedSessionModelFallback = {
prevModel: string;
prevProvider: string;
prevModelOverride?: string;
prevProviderOverride?: string;
prevModelOverrideSource?: "auto" | "user";
prevModelOverrideRouteResolution?: "resolved";
prevModelOverrideFallbackOriginProvider?: string;
prevModelOverrideFallbackOriginModel?: string;
prevAuthProfileOverride?: string;
prevAuthProfileOverrideSource?: "auto" | "user" | "user-link";
prevAuthProfileOverrideCompactionCount?: number;
prevContextWindow?: string;
prevThinkingLevel?: string;
lastValidatedPatchTs?: number;
ts: number;
source: "agent-patch";
};
//#endregion
//#region src/agents/sessions/source-info.d.ts
type SourceScope = "user" | "project" | "temporary";
type SourceOrigin = "package" | "top-level";
interface SourceInfo {
path: string;
source: string;
scope: SourceScope;
origin: SourceOrigin;
baseDir?: string;
}
//#endregion
//#region src/skills/loading/skill-contract.d.ts
interface Skill {
name: string;
/** Human-readable title from the first Markdown H1, falling back to the identifier. */
displayName?: string;
description: string;
/** Additional loading guidance rendered with the location in full and compact catalogs. */
locationNote?: string;
/** Prepared instructions for transferred bundles or non-filesystem locators such as node://. */
readContent?: string;
filePath: string;
baseDir: string;
sourceInfo: SourceInfo;
disableModelInvocation: boolean;
source: string;
}
//#endregion
//#region src/config/sessions/session-prompt-types.d.ts
type SessionSkillPromptRef = {
version: 1;
algorithm: "sha256";
hash: string;
bytes: number;
};
type SessionSkillSnapshot = {
librarySelections?: SkillLibrarySelection[];
prompt: string;
/** Persisted stores may replace large duplicate prompts with a content-addressed blob ref. */
promptRef?: SessionSkillPromptRef;
skills: Array<{
name: string;
primaryEnv?: string;
requiredEnv?: string[];
}>;
/** Normalized agent-level filter used to build this snapshot; undefined means unrestricted. */
skillFilter?: string[];
/** Effective node-exec eligibility used to select connected node-hosted skills. */
nodeSkillsEligibility?: {
canExec: boolean;
node?: string;
};
/**
* Runtime-only, never persisted. Carries the full parsed Skill[] (including
* each SKILL.md body) so the embedded runner can skip a workspace skill
* scan within a turn. Persistence projections strip it before committing
* session state. On a cold session resume this is undefined and
* src/skills/runtime/embedded-run-entries.ts rebuilds it from disk.
*/
resolvedSkills?: Skill[];
version?: number;
};
//#endregion
//#region src/config/sessions/session-system-prompt-report.d.ts
/** Persisted size and provenance summary for one assembled system prompt. */
type SessionSystemPromptReport = {
source: "run" | "estimate";
generatedAt: number;
sessionId?: string;
sessionKey?: string;
provider?: string;
model?: string;
workspaceDir?: string;
bootstrapMaxChars?: number;
bootstrapTotalMaxChars?: number;
bootstrapTruncation?: {
warningMode?: "off" | "once" | "always";
warningShown?: boolean;
promptWarningSignature?: string;
warningSignaturesSeen?: string[];
truncatedFiles?: number;
nearLimitFiles?: number;
totalNearLimit?: boolean;
};
sandbox?: {
mode?: string;
sandboxed?: boolean;
};
systemPrompt: {
chars: number;
projectContextChars: number;
nonProjectContextChars: number;
hash?: string;
};
currentTurn?: {
kind?: "user_request" | "room_event";
promptChars: number;
runtimeContextChars: number;
modelOnlyPromptChars?: number;
};
injectedWorkspaceFiles: Array<{
name: string;
path: string;
missing: boolean;
rawChars: number;
} & ({
injectionStatus?: "verified";
injectedChars: number;
truncated: boolean;
} | {
injectionStatus: "native_unverified";
injectedChars: null;
truncated: null;
})>;
skills: {
promptChars: number;
hash?: string;
entries: Array<{
name: string;
blockChars: number;
}>;
};
tools: {
listChars: number;
schemaChars: number;
entries: Array<{
name: string;
summaryChars: number;
summaryHash?: string;
schemaChars: number;
schemaHash?: string;
propertiesCount?: number | null;
}>;
};
};
//#endregion
//#region src/config/sessions/session-tool-overrides.d.ts
type SessionToolOverrides = {
mcpServers?: Record<string, boolean>;
mcpToolsDeny?: Record<string, string[]>;
skills?: Record<string, boolean>;
webSearch?: boolean;
};
//#endregion
//#region src/config/sessions/types.d.ts
type SessionChatType = ChatType;
declare const SESSION_TOTAL_TOKENS_VERSION: 1;
type SessionVisibility = "shared" | "read-only" | "suggest" | "draft";
type SessionOrigin = {
label?: string;
provider?: string;
surface?: string;
chatType?: SessionChatType;
from?: string;
to?: string;
nativeChannelId?: string;
nativeDirectUserId?: string;
avatar?: string;
accountId?: string;
threadId?: string | number;
};
/** Canonical persisted delivery ownership for one session. */
type SessionDeliveryState = {
kind: "none";
} | {
kind: "internal";
} | {
kind: "external";
route: ChannelRouteRef;
context: DeliveryContext;
origin: SessionOrigin;
};
/**
* Durable transcript-repair record: an assistant final that was delivered to
* the user but could not be appended to the canonical transcript. Kept
* separate from `pendingFinalDelivery` so transport-replay cleanup never drops
* the only copy of the missing assistant turn.
*/
type PendingTranscriptRepairState = {
/** Stable identity for retry-safe transcript insertion. */
id: string;
text: string;
provider?: string;
model?: string;
createdAt: number;
};
type FallbackNoticeState = {
kind: "active";
selectedModel: string;
activeModel: string;
reason?: string;
};
type MemoryFlushState = {
kind: "succeeded";
compactionCount: number;
} | {
kind: "failed";
compactionCount?: number;
failureCount: number;
};
type CliSessionReseedReceipt = {
version: 1;
promptHash: string;
localSessionId: string;
userTurnDisposition: "persisted" | "omitted";
};
type SessionDiffBaseline = {
version: 1;
sessionId: string;
root: string;
files: Array<{
path: string;
fingerprint: string;
}>;
/** Some checkout entries could not be fingerprinted without exceeding diff safety caps. */
truncated?: true;
};
type CliSessionBinding = {
sessionId: string;
/** Last successful assistant boundary accepted by the backend's resume contract. */
resumeCheckpointId?: string;
/** Resume with the backend's fork argument once, then clear before process start. */
forkNextResume?: true;
/** Trust an explicitly attached CLI session even when auth, prompt, or MCP fingerprints drift. */
forceReuse?: boolean;
authProfileId?: string;
authEpoch?: string;
authEpochVersion?: number;
extraSystemPromptHash?: string;
messageToolPolicyHash?: string;
promptToolNamesHash?: string;
cwdHash?: string;
mcpConfigHash?: string;
mcpResumeHash?: string;
/** Identifies one synthetic history prompt and the trusted local handling of its user turn. */
reseedReceipt?: CliSessionReseedReceipt;
};
type AcpSessionBinding = {
acpBackendId: string;
acpAgentId: string;
agentSessionId: string;
};
type SessionCompactionCheckpointReason = "manual" | "auto-threshold" | "overflow-retry" | "timeout-retry";
type SessionCompactionTranscriptReference = {
sessionId: string;
sessionFile?: string;
leafId?: string;
entryId?: string;
};
type SessionCompactionCheckpoint = {
checkpointId: string;
sessionKey: string;
sessionId: string;
createdAt: number;
reason: SessionCompactionCheckpointReason;
tokensBefore?: number;
tokensAfter?: number;
tokensVersion?: typeof SESSION_TOTAL_TOKENS_VERSION;
summary?: string;
firstKeptEntryId?: string;
preCompaction: SessionCompactionTranscriptReference;
postCompaction: SessionCompactionTranscriptReference;
};
type SessionContextBudgetStatusRoute = "fits" | "compact_only" | "truncate_tool_results_only" | "compact_then_truncate";
type SessionContextBudgetStatus = {
schemaVersion: 1;
source: "pre-prompt-estimate";
updatedAt: number;
provider: string;
model: string;
route: SessionContextBudgetStatusRoute;
shouldCompact: boolean;
estimatedPromptTokens: number;
contextTokenBudget: number;
promptBudgetBeforeReserve: number;
reserveTokens: number;
effectiveReserveTokens: number;
remainingPromptBudgetTokens: number;
overflowTokens: number;
toolResultReducibleChars: number;
messageCount: number;
unwindowedMessageCount: number;
sessionId?: string;
};
type AmbientTranscriptWatermark = {
sessionId: string;
messageId: string;
timestampMs?: number;
updatedAt: number;
};
type SessionPluginDebugEntry = {
pluginId: string;
lines: string[];
};
type SessionPluginJsonValue = string | number | boolean | null | SessionPluginJsonValue[] | {
[key: string]: SessionPluginJsonValue;
};
type SessionPluginNextTurnInjection = {
id: string;
pluginId: string;
pluginName?: string;
text: string;
idempotencyKey?: string;
placement: "prepend_context" | "append_context";
ttlMs?: number;
createdAt: number;
metadata?: SessionPluginJsonValue;
};
type SubagentRecoveryState = {
/** Consecutive accepted automatic orphan-recovery resumes in the rapid re-wedge window. */
automaticAttempts?: number;
/** Timestamp (ms) of the latest accepted automatic orphan-recovery resume. */
lastAttemptAt?: number;
/** Registry run id that triggered the latest automatic orphan-recovery resume. */
lastRunId?: string;
/** Timestamp (ms) when automatic recovery was tombstoned for this session. */
wedgedAt?: number;
/** Human-readable reason automatic recovery was tombstoned. */
wedgedReason?: string;
};
type LaneExecutionState = "active" | "draining" | "suspended" | "resuming" | "circuit_open" | "failed_handoff";
interface QuotaSuspension {
schemaVersion: 1;
suspendedAt: number;
reason: "quota_exhausted" | "manual" | "circuit_open";
failedProvider: string;
failedModel: string;
/** Recovery briefing text injected into the next attempt when state === "resuming". */
summary?: string;
/** Opaque pointer to an external snapshot blob (path/key); not the briefing text itself. */
snapshotRef?: string;
/**
* @deprecated Lane suspension was removed; nothing writes this anymore. Kept only to
* hold the shipped SDK surface stable; drop at the next surface window.
*/
laneId?: string;
expectedResumeBy?: number;
state: LaneExecutionState;
}
type RestartRecoveryRun = {
runId: string;
lifecycleGeneration: string;
};
type SessionEntryCore = SessionRestartRecoveryState & SessionEntryProvenance & Pick<SessionRow, "permissionMode" | "sessionRoot"> & {
/** Collaboration mode. Missing legacy values are equivalent to "shared". */
visibility?: SessionVisibility;
/**
* Last delivered heartbeat payload (used to suppress duplicate heartbeat notifications).
* Stored on the main session entry.
*/
lastHeartbeatText?: string;
/** Timestamp (ms) when lastHeartbeatText was delivered. */
lastHeartbeatSentAt?: number;
/**
* Base session key for heartbeat-created isolated sessions.
* When present, `<base>:heartbeat` is a synthetic isolated session rather than
* a real user/session-scoped key that merely happens to end with `:heartbeat`.
*/
heartbeatIsolatedBaseSessionKey?: string;
/** Legacy heartbeat task timestamps consumed and cleared only by doctor migration. */
heartbeatTaskState?: Record<string, number>;
/** Plugin-owned session state, grouped by plugin id then extension namespace. */
pluginExtensions?: Record<string, Record<string, SessionPluginJsonValue>>;
/** Trusted session initialization is incomplete; all work admission stays blocked. */
initializationPending?: true;
/** Top-level SessionEntry mirror slots owned by plugin session extensions. */
pluginExtensionSlotKeys?: Record<string, Record<string, string>>;
/** Durable one-shot prompt additions drained before the next agent turn. */
pluginNextTurnInjections?: Record<string, SessionPluginNextTurnInjection[]>;
sessionId: string;
updatedAt: number;
/** Process-lifetime session whose entry and transcript stay in the in-memory agent database. */
incognito?: true;
/** Opaque owner revision used to reject stale lifecycle mutations. */
lifecycleRevision?: string;
/** Timestamp (ms) when the session was archived from active session lists. */
archivedAt?: number;
/** Actor that archived the session; cleared when the session is restored. */
archivedBy?: SessionActor;
/** Stable lifecycle cause; absent values are legacy archives and remain manually protected. */
archiveReason?: SessionEntryArchiveReason;
/** Timestamp (ms) when the session was pinned for quick access. */
pinnedAt?: number;
/** Timestamp (ms) when an operator client last marked the session read. */
lastReadAt?: number;
/** Agent-declared sidebar presence; projection drops it after expiresAt. */
agentStatus?: SessionAgentStatus;
/** Latest utility-model status judgment for idle session status surfaces. */
observerDigest?: SessionObserverDigest;
/** Timestamp (ms) when an operator explicitly marked the session unread; cleared on read. */
markedUnreadAt?: number;
/** Timestamp (ms) of the latest completed agent run; metadata patches do not update it. */
lastActivityAt?: number;
/** Parent session key that spawned this session (used for sandbox session-tool scoping). */
spawnedBy?: string;
/** Immutable session key authorized to receive this child's completion handoff. */
completionOwnerSessionKey?: string;
/** Workspace inherited by spawned sessions and reused on later turns for the same child session. */
spawnedWorkspaceDir?: string;
/** Task working directory inherited by spawned sessions and reused on later turns. */
spawnedCwd?: string;
/** Content-free fingerprints for checkout changes that predate this session generation. */
sessionDiffBaseline?: SessionDiffBaseline;
/**
* Managed worktree bound to this session; set with spawnedCwd at worktree
* creation and cleared together when a plain New Chat detaches the checkout.
*/
worktree?: {
id: string;
branch: string;
repoRoot: string;
/** Durable skill workspace prepared when this session runs from a managed worktree. */
canonicalWorkspaceDir?: string;
};
/** Project registry id selected when this logical session node was created. */
projectId?: string;
/** Explicit parent session linkage for dashboard-created child sessions. */
parentSessionKey?: string;
/** Exact parent incarnation captured when this child was created. */
parentSessionId?: string;
/** How this session node came to exist; written once and retained across sessionId rotations. */
createdVia?: SessionCreatedVia;
/** Actor that caused node creation, with an optional profile, session, or sender id; written once. */
createdActor?: SessionCreatedActor;
/** Creation-only sandbox requirement; existing unstamped sessions always remain unstamped. */
sandbox?: "required";
/** Mutable responsibility, projected from SQLite; absent means createdActor owns the session. */
owner?: SessionOwnerAssignment;
/** Retained identities, projected from the participant table before display truncation. */
participants?: SessionParticipant[];
/** Raw retained identity count, including the owner, for admission-bound coverage. */
participantCount?: number;
/** Node creation time (ms); unlike sessionStartedAt, survives sessionId rotations. */
createdAt?: number;
/** Exact source generation and optional cut entry for an actual transcript-copy fork. */
forkSource?: {
sessionKey: string;
sessionId: string;
entryId?: string;
};
/** Session id of the prior transcript generation under this same session key. */
previousSessionId?: string;
/** Thread parent-seeding settled marker; also set when seeding is deliberately skipped. */
forkedFromParent?: boolean;
/** Subagent spawn depth (0 = main, 1 = sub-agent, 2 = sub-sub-agent). */
spawnDepth?: number;
/** Explicit role assigned at spawn time for subagent tool policy/control decisions. */
subagentRole?: "orchestrator" | "leaf";
/** Explicit control scope assigned at spawn time for subagent control decisions. */
subagentControlScope?: "children" | "none";
/** Version of the requester tool-policy snapshot captured when this child was spawned. */
inheritedToolPolicyVersion?: 1;
/** Session-scoped tool deny entries inherited from the caller that created this session. */
inheritedToolDeny?: string[];
/** Session-scoped tool allow entries inherited from the caller that created this session. */
inheritedToolAllow?: string[];
systemSent?: boolean;
abortedLastRun?: boolean;
/** Interrupted run generations whose late lifecycle events must be ignored. */
restartRecoveryRuns?: RestartRecoveryRun[];
/** Keeps automatic restart recovery limited to replay-safe tools until the run terminates. */
restartRecoveryForceSafeTools?: true;
/** Durable guard state for automatic subagent orphan recovery. */
subagentRecovery?: SubagentRecoveryState;
/** Quota cascade protection and state-aware failover status. */
quotaSuspension?: QuotaSuspension;
/** Core-owned durable goal state for this thread/session. */
goal?: SessionGoal;
/** Timestamp (ms) when the current sessionId first became active. */
sessionStartedAt?: number;
/** Stable usage lineage key for transcript-backed rollups across sessionId rotations. */
usageFamilyKey?: string;
/** Session ids known to belong to this usage lineage, including archived predecessors. */
usageFamilySessionIds?: string[];
/** Timestamp (ms) of the last user/channel interaction that should extend idle lifetime. */
lastInteractionAt?: number;
/** Stable first-run start time for subagent sessions, persisted after completion. */
startedAt?: number;
/** Latest completed run end time for subagent sessions, persisted after completion. */
endedAt?: number;
/** Accumulated runtime across subagent follow-up runs, persisted after completion. */
runtimeMs?: number;
/** Final persisted subagent run status, used after in-memory run archival. */
status?: SessionRunStatus;
/** Compact user-facing reason for the latest failed or timed-out run. */
lastRunError?: string;
/**
* Session-level stop cutoff captured when /stop is received.
* Messages at/before this boundary are skipped to avoid replaying
* queued pre-stop backlog.
*/
abortCutoffMessageSid?: string;
/** Epoch ms cutoff paired with abortCutoffMessageSid when available. */
abortCutoffTimestamp?: number;
chatType?: SessionChatType;
contextWindow?: string;
thinkingLevel?: string;
/**
* Exact isolated-cron continuation policy. Only hidden `:run:` session rows
* carry this while detached generated-media work may still wake the run.
*/
cronRunContinuation?: {
lifecycleRevision: string;
phase: "running" | "ready" | "continuing";
/** True only after this row's session changes were projected to the stable cron row. */
basePersisted?: boolean;
ownerRunId?: string;
/** Gateway lifecycle generation that owns a continuing claim. */
ownerLifecycleGeneration?: string;
/** CLI backend whose native session must exist before media work detaches. */
cliExecutionProvider?: string;
toolsAllow?: string[];
toolsAllowIsDefault?: boolean;
/** Exact server-stamped authority provenance copied from the owning cron job. */
scheduledToolPolicy?: CronScheduledToolPolicy;
/** Restrict-only exec pin copied from the owning cron job's cap. */
toolsAllowExecTarget?: CronToolsAllowExecTarget;
/** Expected pin copied with the cap so detached continuation loss fails closed. */
toolsAllowExecTargetRequirement?: CronToolsAllowExecTargetRequirement;
/** Store-private origin paired with an account scheduled-tool policy. */
scheduledToolCallerOrigin?: CronScheduledToolCallerOrigin;
cliSessionBindingFacts?: {
extraSystemPromptStatic?: string;
sourceReplyDeliveryMode?: "automatic" | "message_tool_only";
requireExplicitMessageTarget?: boolean;
};
};
fastMode?: FastMode;
toolOverrides?: SessionToolOverrides;
/** Swarm group for collector-mode child sessions. */
swarmGroupId?: string;
/** Marks non-interactive collector-mode child sessions. */
swarmCollector?: boolean;
/** JSON Schema exposed through the synthetic structured_output tool. */
swarmOutputSchema?: Record<string, unknown>;
verboseLevel?: string;
traceLevel?: string;
reasoningLevel?: string;
elevatedLevel?: string;
ttsAuto?: TtsAutoMode;
/** Hash of the latest assistant reply that was sent through `/tts latest`. */
lastTtsReadLatestHash?: string;
/** Timestamp (ms) when `/tts latest` last sent audio for this session. */
lastTtsReadLatestAt?: number;
execHost?: string;
execNode?: string;
/** Working directory interpreted only by the bound exec node. */
execCwd?: string;
responseUsage?: "on" | "off" | "tokens" | "full";
providerOverride?: string;
modelOverride?: string;
/** Session-scoped agent runtime/harness override selected with the model picker. */
agentRuntimeOverride?: string;
/**
* Tracks whether the persisted model override came from an explicit user
* action (`/model`, `sessions.patch`) or from a temporary runtime fallback.
* Resets only preserve user-driven overrides.
*/
modelOverrideSource?: "auto" | "user";
/** Present only when providerOverride/modelOverride are a canonical route pair. */
modelOverrideRouteResolution?: "resolved";
/** Selected model that produced the current auto fallback override. */
modelOverrideFallbackOriginProvider?: string;
modelOverrideFallbackOriginModel?: string;
/** One-run rollback guard for a model selected by the agent sessions tool. */
modelFallback?: AgentPatchedSessionModelFallback;
authProfileOverride?: string;
authProfileOverrideSource?: "auto" | "user" | "user-link";
authProfileOverrideCompactionCount?: number;
/**
* Set on explicit user-driven session model changes (for example `/model`
* and `sessions.patch`) during an active run. The embedded runner checks
* this flag to decide whether to throw `LiveSessionModelSwitchError`.
* System-initiated fallbacks (rate-limit retry rotation) never set this
* flag, so they are never mistaken for user-initiated switches.
*/
liveModelSwitchPending?: boolean;
groupActivation?: "mention" | "always";
groupActivationNeedsSystemIntro?: boolean;
sendPolicy?: "allow" | "deny";
queueMode?: QueueMode;
queueDebounceMs?: number;
queueCap?: number;
queueDrop?: "old" | "new" | "summarize";
inputTokens?: number;
outputTokens?: number;
totalTokens?: number;
pendingFinalDelivery?: PendingFinalDeliveryState;
pendingDeliveryNotice?: PendingDeliveryNoticeState;
/**
* Ordered durable backlog of delivered assistant finals that failed to
* reach the canonical transcript. Session admission restores each item
* before another turn can extend that transcript. Kept as a list so
* independently admitted writers never overwrite an earlier reply.
*/
pendingTranscriptRepair?: PendingTranscriptRepairState[];
/**
* Whether totalTokens reflects a fresh context snapshot for the latest run.
* Undefined means legacy/unknown freshness; false forces consumers to treat
* totalTokens as stale/unknown for context-utilization displays.
*/
totalTokensFresh?: boolean;
/** Version 1 records totalTokens as the current prompt/context snapshot only. */
totalTokensVersion?: typeof SESSION_TOTAL_TOKENS_VERSION;
estimatedCostUsd?: number;
cacheRead?: number;
cacheWrite?: number;
modelProvider?: string;
model?: string;
/**
* Prevents OpenClaw model changes and automatic maintenance eviction until
* the owning harness explicitly retires the session.
*/
modelSelectionLocked?: boolean;
/**
* Embedded agent harness selected for this session id.
* Prevents config/env changes from moving an existing transcript between
* incompatible runtime harnesses.
*/
agentHarnessId?: string;
fallbackNotice?: FallbackNoticeState;
contextTokens?: number;
/** Origin of the persisted context window; `resolved` is legacy/unverified. */
contextTokensSource?: "runtime" | "runtime-configured" | "resolved" | "resolved-v1";
contextBudgetStatus?: SessionContextBudgetStatus;
compactionCount?: number;
compactionCheckpoints?: SessionCompactionCheckpoint[];
memoryFlush?: MemoryFlushState;
cliSessionIds?: Record<string, string>;
cliSessionBindings?: Record<string, CliSessionBinding>;
/** Initialization fence for seeding canonical ACP metadata; cleared after creation. */
acpSessionBinding?: AcpSessionBinding;
claudeCliSessionId?: string;
label?: string;
/** Persistent operator/agent-set sidebar emoji icon (single grapheme). */
icon?: string;
/** Named sidebar tint (SESSION_COLOR_IDS); palette mirrors Claude Code /color for import. */
color?: string;
/** User-defined organization bucket for session lists; unrelated to chat groupId/groupChannel. */
category?: string;
/** Preferred Control UI face when a caller opens this session without explicit face intent. */
boardFace?: SessionBoardFace;
displayName?: string;
/** Canonical delivery state. Legacy delivery fields are migrated by `openclaw doctor --fix`. */
delivery?: SessionDeliveryState;
groupId?: string;
subject?: string;
groupChannel?: string;
space?: string;
/** Last ambient room message durably appended to this transcript, keyed by channel scope. */
ambientTranscriptWatermarks?: Record<string, AmbientTranscriptWatermark>;
skillsSnapshot?: SessionSkillSnapshot;
/** Explicit authorized immutable library pins; current speakers never replace this selection. */
skillLibrarySelections?: SkillLibrarySelection[];
systemPromptReport?: SessionSystemPromptReport;
/**
* Generic plugin-owned runtime debug entries shown in verbose status surfaces.
* Each plugin owns and may overwrite only its own entry between turns.
*/
pluginDebugEntries?: SessionPluginDebugEntry[];
acp?: SessionAcpMeta;
};
interface SessionEntry extends SessionEntryCore {}
/** Internal durable fields excluded from public/plugin session projections. */
type InternalSessionEntryCore = SessionEntryCore & {
/** Run that owns the current non-terminal Gateway lifecycle projection. */
lifecycleRunId?: string;
/** Exact run that produced the latest terminal Gateway lifecycle projection. */
lastRunId?: string;
/** Run admitted by the session lane; overwritten at admission and checked by transcript writes. */
activeWriterRunId?: string;
/** Canonical remote repository awaiting preparation by this exact session generation. */
pendingProjectGitUrl?: string;
/** Authorized worktree intent awaiting preparation by an admitted turn. */
pendingWorktree?: {
workspace?: string;
name?: string;
baseRef?: string;
titleSource: string;
};
/** Suppresses repeated byte-triggered compaction after an oversized successor was observed. */
transcriptByteCompactionLatch?: {
activeBytes: number;
sessionId: string;
maxBytes: number;
};
/** Private per-generation ownership for the pre-runtime checkout baseline capture. */
sessionDiffBaselineCapture?: SessionDiffBaselineCapture;
mainRestartRecovery?: MainRestartRecoveryState;
};
interface InternalSessionEntry extends InternalSessionEntryCore {}
type GroupKeyResolution = {
key: string;
channel?: string;
id?: string;
chatType?: SessionChatType;
};
//#endregion
//#region src/agents/auth-profiles/credential-schema.d.ts
/** Provider-owned fields retained with OAuth material through storage and refresh. */
declare const oauthCredentialMetadataSchema: z.ZodObject<{
idToken: z.ZodOptional<z.ZodString>;
clientId: z.ZodOptional<z.ZodString>;
enterpriseUrl: z.ZodOptional<z.ZodString>;
projectId: z.ZodOptional<z.ZodString>;
accountId: z.ZodOptional<z.ZodString>;
chatgptPlanType: z.ZodOptional<z.ZodString>;
subscriptionType: z.ZodOptional<z.ZodString>;
rateLimitTier: z.ZodOptional<z.ZodString>;
tokenEndpoint: z.ZodOptional<z.ZodString>;
deviceAuthorizationEndpoint: z.ZodOptional<z.ZodString>;
issuer: z.ZodOptional<z.ZodString>;
authFlow: z.ZodOptional<z.ZodString>;
}, z.core.$strict>;
type OAuthCredentialMetadata = z.infer<typeof oauthCredentialMetadataSchema>;
//#endregion
//#region src/agents/auth-profiles/legacy-oauth-ref.d.ts
/** Legacy OAuth ref source persisted by older credential stores. */
declare const LEGACY_OAUTH_REF_SOURCE = "openclaw-credentials";
/** Legacy OAuth ref provider persisted by older credential stores. */
declare const LEGACY_OAUTH_REF_PROVIDER = "openai-codex";
type LegacyOAuthRef = {
source: typeof LEGACY_OAUTH_REF_SOURCE;
provider: typeof LEGACY_OAUTH_REF_PROVIDER;
id: string;
};
//#endregion
//#region src/agents/auth-profiles/types.d.ts
/** Provider identifier recorded on auth profile credentials. */
type OAuthProvider = string;
/** Refreshable OAuth credential fields persisted for provider auth profiles. */
type OAuthCredentials = OAuthCredentialMetadata & {
access: string;
refresh: string;
expires: number;
provider?: OAuthProvider;
email?: string;
};
/** API-key credential with optional secret reference indirection. */
type ApiKeyCredential = {
type: "api_key";
provider: string;
key?: string;
keyRef?: SecretRef;
/** Explicit opt-out for copying this profile when creating another agent. */
copyToAgents?: boolean;
email?: string;
displayName?: string;
/** Optional provider-specific metadata (e.g., account IDs, gateway IDs). */
metadata?: Record<string, string>;
};
/** Static token credential that OpenClaw does not refresh. */
type TokenCredential = {
/**
* Static bearer-style token (often OAuth access token / PAT).
* Not refreshable by OpenClaw (unlike `type: "oauth"`).
*/
type: "token";
provider: string;
token?: string;
tokenRef?: SecretRef;
/** Explicit opt-out for copying this profile when creating another agent. */
copyToAgents?: boolean;
/** Optional expiry timestamp (ms since epoch). */
expires?: number;
email?: string;
displayName?: string;
};
/** Refreshable OAuth credential plus provider metadata and legacy references. */
type OAuthCredential = OAuthCredentials & {
type: "oauth";
provider: string;
oauthRef?: LegacyOAuthRef;
/**
* OAuth refresh tokens are not portable by default. Provider-owned flows may
* set this only when copying refresh material across agents is known safe.
*/
copyToAgents?: boolean;
email?: string;
displayName?: string;
};
/** Credential variants supported by auth profiles. */
type AuthProfileCredential = ApiKeyCredential | TokenCredential | OAuthCredential;
/** Closed reasons that drive cooldown, disable, and failure counters. */
type AuthProfileFailureReason = "auth" | "auth_permanent" | "format" | "overloaded" | "rate_limit" | "billing" | "timeout" | "model_not_found" | "session_expired" | "empty_response" | "no_error_details" | "unclassified" | "unknown";
/** Optional host diagnostic attached to a canonical cooldown reason. */
type AuthProfileCooldownClassification = "wham_token_expired" | "wham_account_dead";
/** Profile-wide blocked reason reported by provider usage probes. */
type AuthProfileBlockedReason = "subscription_limit";
/** Source that marked a profile as blocked. */
type AuthProfileBlockedSource = "codex_rate_limits" | "wham";
/** Per-profile usage statistics for round-robin and cooldown tracking */
type ProfileUsageStats = {
lastUsed?: number;
blockedUntil?: number;
blockedReason?: AuthProfileBlockedReason;
blockedSource?: AuthProfileBlockedSource;
blockedModel?: string;
blockedScope?: "model";
cooldownUntil?: number;
cooldownReason?: AuthProfileFailureReason;
cooldownClassification?: AuthProfileCooldownClassification;
cooldownModel?: string;
disabledUntil?: number;
disabledReason?: AuthProfileFailureReason;
errorCount?: number;
failureCounts?: Partial<Record<AuthProfileFailureReason, number>>;
lastFailureAt?: number;
lastProbeAt?: number;
};
/** Durable, non-secret auth profile selection state. */
type AuthProfileState = {
/**
* Optional per-agent preferred profile order overrides.
* This lets you lock/override auth rotation for a specific agent without
* changing the global config.
*/
order?: Record<string, string[]>;
lastGood?: Record<string, string>;
/** Usage statistics per profile for round-robin rotation */
usageStats?: Record<string, ProfileUsageStats>;
};
/** Persisted credential payload without runtime-only selection state. */
type AuthProfileSecretsStore = {
version: number;
profiles: Record<string, AuthProfileCredential>;
};
/** Effective in-memory auth store combining credentials, state, and overlays. */
type AuthProfileStore = AuthProfileSecretsStore & AuthProfileState & {
/** Runtime-only provenance for credentials cloned from persisted auth stores. */
runtimePersistedProfileIds?: string[];
/** Runtime-only provenance for external OAuth profiles overlaid onto this store. */
runtimeExternalProfileIds?: string[];
/** True when the runtime external profile set was freshly resolved, even if empty. */
runtimeExternalProfileIdsAuthoritative?: boolean;
};
//#endregion
//#region src/agents/agent-scope-config.d.ts
declare function resolveAgentWorkspaceDir(cfg: OpenClawConfig, agentId: string, env?: NodeJS.ProcessEnv): string;
declare function resolveAgentDir(cfg: OpenClawConfig, agentId: string, env?: NodeJS.ProcessEnv): string;
//#endregion
//#region packages/media-understanding-common/src/types.d.ts
/** Kind of media-understanding output produced for an attachment. */
type MediaUnderstandingKind = "audio.transcription" | "video.description" | "image.description";
/** Capability exposed by a media-understanding provider. */
type MediaUnderstandingCapability = "image" | "audio" | "video";
/** Normalized text output produced by media understanding. */
type MediaUnderstandingOutput = {
kind: MediaUnderstandingKind;
attachmentIndex: number;
text: string;
provider: string;
model?: string;
requestedBackend?: string;
observedBackend?: string;
};
//#endregion
//#region src/media-understanding/types.d.ts
/** Agent-owned runtime handle carried opaquely through media provider requests. */
type MediaPreparedModelRuntime = Readonly<{
agentDir: string;
workspaceDir?: string;
config: OpenClawConfig;
createStores: () => unknown;
}>;
type MediaUnderstandingDecisionOutcome = "success" | "failed" | "skipped" | "disabled" | "no-attachment" | "scope-deny";
type MediaUnderstandingModelDecision = {
provider?: string;
model?: string;
requestedBackend?: string;
observedBackend?: string;
type: "provider" | "cli";
outcome: "success" | "skipped" | "failed";
reason?: string;
};
type MediaUnderstandingAttachmentDecision = {
attachmentIndex: number;
attempts: MediaUnderstandingModelDecision[];
chosen?: MediaUnderstandingModelDecision;
};
type MediaAttachmentDisposition = {
kind: "handled";
} | {
kind: "handed-to-native-vision";
} | {
kind: "not-selected";
} | {
kind: "capability-disabled";
} | {
kind: "no-model";
} | {
kind: "scope-denied";
} | {
kind: "failed";
reason?: string;
};
type MediaUnderstandingDecision = {
capability: MediaUnderstandingCapability;
outcome: MediaUnderstandingDecisionOutcome;
attachments: MediaUnderstandingAttachmentDecision[];
attachmentDispositions?: Record<number, MediaAttachmentDisposition>;
nativeVisionActive?: boolean;
};
type MediaUnderstandingProviderRequestAuthOverride = {
mode: "provider-default";
} | {
mode: "authorization-bearer";
token: string;
} | {
mode: "header";
headerName: string;
value: string;
prefix?: string;
};
type MediaUnderstandingProviderRequestTlsOverride = {
ca?: string;
cert?: string;
key?: string;
passphrase?: string;
serverName?: string;
insecureSkipVerify?: boolean;
};
type MediaUnderstandingProviderRequestProxyOverride = {
mode: "env-proxy";
tls?: MediaUnderstandingProviderRequestTlsOverride;
} | {
mode: "explicit-proxy";
url: string;
tls?: MediaUnderstandingProviderRequestTlsOverride;
};
type MediaUnderstandingProviderRequestTransportOverrides = {
headers?: Record<string, string>;
auth?: MediaUnderstandingProviderRequestAuthOverride;
proxy?: MediaUnderstandingProviderRequestProxyOverride;
tls?: MediaUnderstandingProviderRequestTlsOverride;
/** Runtime-only flag from trusted model-provider config; media config rejects it. */
allowPrivateNetwork?: boolean;
};
type MediaUnderstandingProviderRequestAuth = {
kind: "api-key";
apiKey: string;
source?: string;
} | {
kind: "none";
source: string;
};
type AudioTranscriptionRequest = {
buffer: Buffer;
fileName: string;
mime?: string;
/** Compatibility field for existing providers; prefer auth.kind/apiKey. */
apiKey: string;
auth?: MediaUnderstandingProviderRequestAuth;
baseUrl?: string;
headers?: Record<string, string>;
request?: MediaUnderstandingProviderRequestTransportOverrides;
model?: string;
language?: string;
prompt?: string;
query?: Record<string, string | number | boolean>;
timeoutMs: number;
signal?: AbortSignal;
fetchFn?: typeof fetch;
};
type AudioTranscriptionResult = {
text: string;
model?: string;
};
type AudioTranscriptionContext = Omit<AudioTranscriptionRequest, "apiKey" | "auth"> & {
cfg: OpenClawConfig;
agentDir?: string;
workspaceDir?: string;
profile?: string;
preferredProfile?: string;
};
type VideoDescriptionRequest = {
buffer: Buffer;
fileName: string;
mime?: string;
/** Compatibility field for existing providers; prefer auth.kind/apiKey. */
apiKey: string;
auth?: MediaUnderstandingProviderRequestAuth;
baseUrl?: string;
headers?: Record<string, string>;
request?: MediaUnderstandingProviderRequestTransportOverrides;
model?: string;
prompt?: string;
timeoutMs: number;
signal?: AbortSignal;
fetchFn?: typeof fetch;
};
type VideoDescriptionResult = {
text: string;
model?: string;
};
type ImageDescriptionRequest = {
buffer: Buffer;
fileName: string;
mime?: string;
prompt?: string;
maxTokens?: number;
timeoutMs: number;
signal?: AbortSignal;
profile?: string;
preferredProfile?: string;
authStore?: AuthProfileStore;
agentId?: string;
agentDir: string;
workspaceDir?: string;
preparedModelRuntime?: MediaPreparedModelRuntime;
cfg: OpenClawConfig;
model: string;
provider: string;
};
type ImagesDescriptionInput = {
buffer: Buffer;
fileName: string;
mime?: string;
};
type ImagesDescriptionRequest = {
images: ImagesDescriptionInput[];
model: string;
provider: string;
prompt?: string;
maxTokens?: number;
timeoutMs: number;
signal?: AbortSignal;
profile?: string;
preferredProfile?: string;
authStore?: AuthProfileStore;
agentId?: string;
agentDir: string;
workspaceDir?: string;
preparedModelRuntime?: MediaPreparedModelRuntime;
cfg: OpenClawConfig;
};
type ImageDescriptionResult = {
text: string;
model?: string;
};
type ImagesDescriptionResult = {
text: string;
model?: string;
};
type StructuredExtractionTextInput = {
type: "text";
text: string;
};
type StructuredExtractionImageInput = {
type: "image";
buffer: Buffer;
fileName: string;
mime?: string;
};
type StructuredExtractionInput = StructuredExtractionTextInput | StructuredExtractionImageInput;
type StructuredExtractionRequest = {
/** Image-first extraction input; callers must include at least one image. */
input: StructuredExtractionInput[];
instructions: string;
schemaName?: string;
jsonSchema?: unknown;
jsonMode?: boolean;
timeoutMs: number;
signal?: AbortSignal;
profile?: string;
preferredProfile?: string;
authStore?: AuthProfileStore;
agentDir: string;
cfg: OpenClawConfig;
model: string;
provider: string;
};
type StructuredExtractionResult = {
text: string;
parsed?: unknown;
model?: string;
provider?: string;
contentType?: "json" | "text";
};
type MediaUnderstandingDocumentModelDefaults = {
textExtraction?: string;
image?: string | false;
};
type MediaUnderstandingProviderAuthContext = {
config?: OpenClawConfig;
provider: string;
providerConfig?: ModelProviderConfig;
};
type MediaUnderstandingProviderAuthResult = {
kind: "none";
source: string;
} | {
kind: "api-key";
apiKey: string;
source: string;
mode?: "api-key";
};
type MediaUnderstandingProviderSyntheticAuthResult = {
apiKey: string;
source: string;
mode: "api-key";
};
type MediaUnderstandingProvider = {
id: string;
capabilities?: MediaUnderstandingCapability[];
defaultModels?: Partial<Record<MediaUnderstandingCapability, string>>;
autoPriority?: Partial<Record<MediaUnderstandingCapability, number>>;
nativeDocumentInputs?: Array<"pdf">;
documentModels?: Partial<Record<"pdf", MediaUnderstandingDocumentModelDefaults>>;
resolveAuth?: (ctx: MediaUnderstandingProviderAuthContext) => MediaUnderstandingProviderAuthResult | null | undefined;
/** @deprecated Use resolveAuth. */
resolveSyntheticAuth?: (ctx: MediaUnderstandingProviderAuthContext) => MediaUnderstandingProviderSyntheticAuthResult | null | undefined;
transcribeAudio?: (req: AudioTranscriptionRequest) => Promise<AudioTranscriptionResult>;
/** Called after file loading. Result.error is only a rejection before audio upload;
* upload/HTTP failures must throw and stop automatic provider selection. */
transcribeAudioWithContext?: (req: AudioTranscriptionContext) => Promise<Result<AudioTranscriptionResult, unknown>>;
describeVideo?: (req: VideoDescriptionRequest) => Promise<VideoDescriptionResult>;
describeImage?: (req: ImageDescriptionRequest) => Promise<ImageDescriptionResult>;
describeImages?: (req: ImagesDescriptionRequest) => Promise<ImagesDescriptionResult>;
extractStructured?: (req: StructuredExtractionRequest) => Promise<StructuredExtractionResult>;
};
//#endregion
//#region src/channels/location.d.ts
/** Normalized source kind for channel-provided geographic locations. */
type LocationSource = "pin" | "place" | "live";
/** Channel-neutral location payload passed from plugins into shared prompt rendering. */
type NormalizedLocation = {
latitude: number;
longitude: number;
accuracy?: number;
name?: string;
address?: string;
isLive?: boolean;
source?: LocationSource;
caption?: string;
};
/** Portable outbound location fields supported by channel send adapters. */
type OutboundLocation = Pick<NormalizedLocation, "latitude" | "longitude" | "accuracy" | "name" | "address">;
//#endregion
//#region src/infra/approval-scope.d.ts
type ApprovalScope = Static<typeof ApprovalScopeSchema>;
//#endregion
//#region src/infra/command-analysis/explain.d.ts
/** Compact command explanation summary shown in approval UI. */
type CommandExplanationSummary = {
commandCount: number;
nestedCommandCount: number;
riskKinds: string[];
warningLines: string[];
};
//#endregion
//#region src/infra/exec-approval-policy-snapshot.d.ts
type ExecApprovalPolicyRule = {
pattern: string;
argPattern?: string;
source?: "allow-always";
};
type ExecApprovalPolicySnapshot = {
security: "deny" | "allowlist" | "full";
ask: "off" | "on-miss" | "always";
askFallback: "deny" | "allowlist" | "full";
autoAllowSkills: boolean;
allowlistRules: readonly ExecApprovalPolicyRule[];
};
//#endregion
//#region src/infra/exec-approvals-core.d.ts
type ExecHost = "sandbox" | "gateway" | "node";
type ExecTarget = "auto" | ExecHost;
type ExecSecurity = "deny" | "allowlist" | "full";
type ExecAsk = "off" | "on-miss" | "always";
type ExecMode = "deny" | "allowlist" | "ask" | "auto" | "full";
type ExecApprovalDecision = "allow-once" | "allow-always" | "deny";
type ExecApprovalUnavailableDecision = "allow-always";
type SystemRunApprovalBinding = {
argv: string[];
cwd: string | null;
agentId: string | null;
sessionKey: string | null;
envHash: string | null;
};
type SystemRunApprovalFileOperand = {
argvIndex: number;
path: string;
sha256: string;
};
type SystemRunApprovalPlan = {
argv: string[];
cwd: string | null;
commandText: string;
commandPreview?: string | null;
agentId: string | null;
sessionKey: string | null;
policySnapshot?: ExecApprovalPolicySnapshot;
mutableFileOperand?: SystemRunApprovalFileOperand | null;
};
type ExecApprovalCommandSpan = {
startIndex: number;
endIndex: number;
};
/** Cron job identity recorded at approval creation for a cron isolated run. */
type ExecApprovalCronExecutionSource = {
jobId: string;
jobConfigRevision: string;
};
type ExecApprovalRequestPayload = {
command: string;
commandPreview?: string | null;
commandArgv?: string[];
envKeys?: string[];
systemRunBinding?: SystemRunApprovalBinding | null;
systemRunPlan?: SystemRunApprovalPlan | null;
cwd?: string | null;
nodeId?: string | null;
host?: string | null;
security?: string | null;
ask?: string | null;
warningText?: string | null;
/** Owner-declared blast-radius facts; display-only, never authorization. */
scope?: ApprovalScope | null;
commandAnalysis?: CommandExplanationSummary | null;
commandSpans?: ExecApprovalCommandSpan[];
unavailableDecisions?: readonly ExecApprovalUnavailableDecision[];
allowedDecisions?: readonly ExecApprovalDecision[];
agentId?: string | null;
resolvedPath?: string | null;
sessionKey?: string | null;
sessionId?: string | null;
runId?: string | null;
toolCallId?: string | null;
turnSourceChannel?: string | null;
turnSourceTo?: string | null;
turnSourceAccountId?: string | null;
turnSourceThreadId?: string | number | null;
/** Gateway-recorded cron source; never taken from client request params. */
cronExecutionSource?: ExecApprovalCronExecutionSource | null;
/** Exact operation binding prepared at creation for standing-grant minting. */
cronOperationBinding?: string | null;
};
type ExecApprovalRequest = {
/** Descriptive wire metadata; readers derive it from the payload when absent. */
approvalKind?: "exec";
id: string;
request: ExecApprovalRequestPayload;
createdAtMs: number;
expiresAtMs: number;
};
type ExecApprovalResolved = {
id: string;
decision: ExecApprovalDecision;
resolvedBy?: string | null;
ts: number;
request?: ExecApprovalRequest["request"];
};
//#endregion
//#region src/infra/plugin-approvals.d.ts
/** Button/action metadata shown with a plugin approval request. */
type PluginApprovalActionView = {
kind?: "command" | "decision";
label: string;
command: string;
decision?: ExecApprovalDecision;
style?: "primary" | "secondary" | "success" | "danger";
};
/** Gateway-minted placement identity; plugin and RPC callers never supply this authority. */
type PluginApprovalPlacementGrantBinding = {
pluginId: string;
command: string;
approvalScope: string;
agentId: string;
sessionKey: string;
sessionId: string;
nodeId: string;
pairingGeneration: string;
environmentId: string;
ownerEpoch: number;
placementGeneration: number;
cwd: string;
};
/** Request payload supplied by plugin approval callers. */
type PluginApprovalRequestPayload = {
pluginId?: string | null;
title: string;
description: string;
detail?: string | null;
severity?: "info" | "warning" | "critical" | null;
/** Owner-declared blast-radius facts; display-only, never authorization. */
scope?: ApprovalScope | null;
toolName?: string | null;
toolCallId?: string | null;
/** Exact MCP persistence intent; the host separately binds live tool-call proof. */
mcpTool?: {
server: string;
tool: string;
};
allowedDecisions?: readonly ExecApprovalDecision[] | null;
/** Trusted in-process metadata; public Gateway callers cannot submit this field. */
externalResolution?: {
label: string;
decisions?: readonly ("allow-once" | "allow-always")[];
} | null;
actions?: readonly PluginApprovalActionView[] | null;
agentId?: string | null;
sessionKey?: string | null;
/** Host-derived source run; never accepted from plugin approval RPC params. */
runId?: string | null;
/** Host-derived grant binding; never accepted from plugin approval RPC params. */
placementGrant?: PluginApprovalPlacementGrantBinding | null;
turnSourceChannel?: string | null;
turnSourceTo?: string | null;
turnSourceAccountId?: string | null;
turnSourceThreadId?: string | number | null;
};
/** Timed plugin approval request persisted while awaiting a decision. */
type PluginApprovalRequest = {
/** Descriptive wire metadata; readers derive it from the payload when absent. */
approvalKind?: "plugin";
id: string;
request: PluginApprovalRequestPayload;
createdAtMs: number;
expiresAtMs: number;
};
/** Resolved plugin approval decision plus optional request snapshot. */
type PluginApprovalResolved = {
id: string;
decision: ExecApprovalDecision;
resolvedBy?: string | null;
ts: number;
request?: PluginApprovalRequestPayload;
};
//#endregion
//#region src/infra/system-agent-approvals.d.ts
type SystemAgentApprovalRequestPayload = {
title: string;
description: string;
command: string;
proposalHash: string;
allowedDecisions: readonly ExecApprovalDecision[];
agentId?: string | null;
sessionKey?: string | null;
sessionId: string;
runId?: string | null;
turnSourceChannel?: string | null;
turnSourceTo?: string | null;
turnSourceAccountId?: string | null;
turnSourceThreadId?: string | number | null;
};
type SystemAgentApprovalRequest = {
approvalKind?: "system-agent";
id: string;
request: SystemAgentApprovalRequestPayload;
createdAtMs: number;
expiresAtMs: number;
};
type SystemAgentApprovalApplicationStatus = "applied" | "not-applied";
type SystemAgentApprovalResolved = {
id: string;
decision: ExecApprovalDecision;
resolvedBy?: string | null;
ts: number;
request?: SystemAgentApprovalRequestPayload;
applicationStatus?: SystemAgentApprovalApplicationStatus;
terminalStatus?: "expired" | "cancelled";
};
//#endregion
//#region src/infra/approval-types.d.ts
type ChannelApprovalKind = "exec" | "plugin" | "system-agent";
/** Backward-compatible request shape accepted from Gateway events and replay. */
type ApprovalRequestInput = ExecApprovalRequest | PluginApprovalRequest | SystemAgentApprovalRequest;
//#endregion
//#region src/interactive/payload.d.ts
type InteractiveButtonStyle = "primary" | "secondary" | "success" | "danger";
/** Visual tone for a portable message presentation. */
type MessagePresentationTone = "info" | "success" | "warning" | "danger" | "neutral";
type QuestionPresentationAction = {
/** Resolve one declared choice. */
type: "question";
questionId: string;
optionValue: string;
} | {
/** Switch this question to its free-text answer path. */
type: "question";
questionId: string;
intent: "custom-input";
};
/** Core-owned model-picker action; channels serialize it only inside private envelopes. */
type ModelPickerAction = ({
type: "model-picker";
version: 1;
snapshotToken: string;
intent: "show-providers";
cursor?: string;
} | {
type: "model-picker";
version: 1;
snapshotToken: string;
intent: "show-models";
providerToken: string;
cursor?: string;
} | {
type: "model-picker";
version: 1;
snapshotToken: string;
intent: "show-recents";
cursor?: string;
} | {
type: "model-picker";
version: 1;
snapshotToken: string;
intent: "choose-model";
providerToken: string;
modelToken: string;
} | {
type: "model-picker";
version: 1;
snapshotToken: string;
intent: "choose-runtime";
providerToken: string;
modelToken: string;
runtimeToken: string;
} | {
type: "model-picker";
version: 1;
snapshotToken: string;
intent: "reset";
} | {
type: "model-picker";
version: 1;
snapshotToken: string;
intent: "cancel";
}) & {
/** Legacy command/callback payload fields are deliberately unavailable on picker actions. */
readonly command?: never;
readonly value?: never;
};
/** Portable typed action behind a button or select option. */
type MessagePresentationAction = {
/** Run a core/plugin slash command through the target channel's native command path. */
type: "command";
command: string;
} | {
/** Opaque callback value interpreted by the target channel/plugin. */
type: "callback";
value: string;
} | ModelPickerAction | {
/** Resolve one durable operator approval without exposing transport callback data. */
type: "approval";
approvalId: string;
approvalKind: ChannelApprovalKind;
decision: "allow-once" | "allow-always" | "deny";
} | QuestionPresentationAction | {
/** Open a normal external link. */
type: "url";
url: string;
} | {
/** Launch a channel-native web app. */
type: "web-app";
/** External web app URL for channels that launch web apps by URL. */
url: string;
/** OpenClaw hosted-widget ID whose launch mechanics are owned by the channel. */
widgetId?: string;
} | {
/** Launch a channel-native web app. */
type: "web-app";
/** External web app URL for channels that launch web apps by URL. */
url?: string;
/** OpenClaw hosted-widget ID whose launch mechanics are owned by the channel. */
widgetId: string;
};
/** Portable action control rendered as a button or link by channel adapters. */
type MessagePresentationButton = {
/** User-visible button label. */
label: string;
/** Typed action sent when the button is pressed. */
action?: MessagePresentationAction;
/**
* Legacy opaque callback value sent when the button is pressed.
* Prefer action for new presentation controls.
* @deprecated Use action.
*/
value?: string;
/** @deprecated Use an action with type "url". */
url?: string;
/** @deprecated Use an action with type "web-app". */
webApp?: {
url: string;
};
/**
* @deprecated Use an action with type "web-app". Accepted for legacy JSON payloads only.
*/
web_app?: {
url: string;
};
/** Higher-priority buttons are kept first when channel limits require truncation. */
priority?: number;
/** Disable the button when the target channel supports disabled controls. */
disabled?: boolean;
/** Keep this action available after a successful interaction when the target channel supports it. */
reusable?: boolean;
/** Optional visual style hint; unsupported channels ignore or normalize it. */
style?: InteractiveButtonStyle;
};
/** Portable select/menu option. */
type MessagePresentationOption = {
/** User-visible option label. */
label: string;
/** Typed action sent when the option is selected. */
action?: Extract<MessagePresentationAction, {
type: "command" | "callback" | "model-picker";
}>;
/** @deprecated Use action. */
value?: string;
};
type LegacyInteractiveReplyOption = MessagePresentationOption;
type LegacyInteractiveReplyTextBlock = {
type: "text";
text: string;
};
type LegacyInteractiveReplySelectBlock = {
type: "select";
placeholder?: string;
options: LegacyInteractiveReplyOption[];
};
type LegacyInteractiveReplyBlock = LegacyInteractiveReplyTextBlock | MessagePresentationButtonsBlock | LegacyInteractiveReplySelectBlock;
type LegacyInteractiveReply = {
blocks: LegacyInteractiveReplyBlock[];
};
/** @deprecated Use MessagePresentation. */
type InteractiveReply = LegacyInteractiveReply;
type MessagePresentationTextBlock = {
type: "text";
/** Primary markdown-ish text rendered in the message body. */
text: string;
};
type MessagePresentationContextBlock = {
type: "context";
/** Lower-emphasis contextual text, or normal text on channels without context support. */
text: string;
};
type MessagePresentationDividerBlock = {
type: "divider";
};
type MessagePresentationButtonsBlock = {
type: "buttons";
/** Button row candidates; core may split or truncate them for channel limits. */
buttons: MessagePresentationButton[];
};
type MessagePresentationSelectBlock = {
type: "select";
/** Optional prompt shown above or inside the select control. */
placeholder?: string;
/** Menu options; core may truncate them for channel limits. */
options: MessagePresentationOption[];
};
type MessagePresentationChartSegment = {
/** Category label shown in the chart legend. */
label: string;
/** Positive segment magnitude. */
value: number;
};
type MessagePresentationChartSeries = {
/** Unique series name shown in the chart legend. */
name: string;
/** One finite value for each chart category, in category order. */
values: number[];
};
type MessagePresentationChartBlock = {
type: "chart";
chartType: "pie";
/** Short chart heading. */
title: string;
segments: MessagePresentationChartSegment[];
} | {
type: "chart";
chartType: "bar" | "area" | "line";
/** Short chart heading. */
title: string;
/** Ordered categories shared by every series. */
categories: string[];
series: MessagePresentationChartSeries[];
xLabel?: string;
yLabel?: string;
};
/** Scalar cell value supported by portable table presentations. */
type MessagePresentationTableCell = string | number;
/** Portable table rendered natively where supported and linearly elsewhere. */
type MessagePresentationTableBlock = {
type: "table";
/** Short table heading used by native renderers and fallback text. */
caption: string;
/** Unique ordered column labels shared by every row. */
headers: string[];
/** Rows whose width exactly matches the header count. */
rows: MessagePresentationTableCell[][];
/** Optional column whose cells should be rendered as row headers. */
rowHeaderColumnIndex?: number;
};
type MessagePresentationBlock = MessagePresentationTextBlock | MessagePresentationContextBlock | MessagePresentationDividerBlock | MessagePresentationButtonsBlock | MessagePresentationSelectBlock | MessagePresentationChartBlock | MessagePresentationTableBlock;
type MessagePresentation = {
/** Optional short heading rendered before blocks when the channel supports it. */
title?: string;
/** Optional severity/status tone for renderers that support toned presentations. */
tone?: MessagePresentationTone;
/** Ordered portable blocks rendered or downgraded by the target channel adapter. */
blocks: MessagePresentationBlock[];
};
type ReplyPayloadDeliveryPin = {
enabled: boolean;
notify?: boolean;
required?: boolean;
};
type ReplyPayloadDelivery = {
pin?: boolean | ReplyPayloadDeliveryPin;
};
//#endregion
//#region src/auto-reply/reply-payload.d.ts
type ReplyMediaAttachment = {
type?: "image" | "audio" | "video" | "file";
path?: string;
url?: string;
mediaUrl?: string;
filePath?: string;
mimeType?: string;
name?: string;
sizeBytes?: number;
durationMs?: number;
width?: number;
height?: number;
/** Internal per-URL trust carried until mixed media is split for history projection. */
trustedLocalMedia?: boolean;
};
/** Channel-agnostic assistant reply payload. */
type ReplyPayload = {
text?: string;
/** Visible body a channel adapter may use when native structured content requires text. */
fallbackText?: {
text: string;
/** Batch payload replaced when the adapter adopts this fallback body. */
replacesPayloadIndex?: number;
};
mediaUrl?: string;
mediaUrls?: string[];
/** Prepared metadata aligned with mediaUrls for client-facing history projection. */
attachments?: ReplyMediaAttachment[];
/** Internal-only trust signal for gateway webchat local media embedding. */
trustedLocalMedia?: boolean;
/** Treat media as live-only content and avoid persisting the underlying media reference. */
sensitiveMedia?: boolean;
/** Channel-agnostic rich presentation. Core degrades or asks the channel renderer to map it. */
presentation?: MessagePresentation;
/** Runtime-authored text is the exact fallback, not additional native presentation content. */
presentationTextMode?: "fallback";
/** Channel-agnostic delivery preferences, e.g. pin the sent message when supported. */
delivery?: ReplyPayloadDelivery;
/**
* @deprecated Use presentation.
*
* Internal legacy representation used by existing approval/reply helpers during migration.
*/
interactive?: InteractiveReply;
btw?: {
question: string;
};
replyToId?: string;
replyToTag?: boolean;
/** True when [[reply_to_current]] was present but not yet mapped to a message id. */
replyToCurrent?: boolean;
/** Send audio as voice message (bubble) instead of audio file. Defaults to false. */
audioAsVoice?: boolean;
/** Send video media as a round video note when the channel supports it. */
videoAsNote?: boolean;
/** Channel-neutral geographic location or named place. */
location?: OutboundLocation;
/**
* Text synthesized into an audio-only TTS payload. Exposed to hooks for
* archival/search use when no visible channel text is sent.
*/
spokenText?: string;
/**
* Marks a TTS media payload as supplemental audio for assistant text that is
* already visible through streaming or transcript projection.
*/
ttsSupplement?: ReplyPayloadTtsSupplement;
isError?: boolean;
/** Marks this payload as a reasoning/thinking block. Channels that do not
* have a dedicated reasoning lane (e.g. WhatsApp, web) should suppress it. */
isReasoning?: boolean;
/** Marks pre-tool commentary (💬) — a display lane, suppressed unless the channel opts in. */
isCommentary?: boolean;
/** Reasoning stream text is a complete replacement snapshot, not a delta. */
isReasoningSnapshot?: boolean;
/** Marks this payload as a compaction status notice (start/end).
* Should be excluded from TTS transcript accumulation so compaction
* status lines are not synthesised into the spoken assistant reply. */
isCompactionNotice?: boolean;
/** Marks this payload as a model-fallback transition/recovery notice. */
isFallbackNotice?: boolean;
/** Marks this payload as transient status, not assistant answer content. */
isStatusNotice?: boolean;
/** Channel-specific payload data (per-channel envelope). */
channelData?: Record<string, unknown>;
};
/** Metadata for audio-only media that supplements already-visible assistant text. */
type ReplyPayloadTtsSupplement = {
spokenText: string;
visibleTextAlreadyDelivered?: boolean;
};
/** Reply policy facts that provider adapters use to resolve the final transport route. */
type ReplyDeliveryContext = {
chatType?: "direct" | "group" | "channel" | null;
replyToMode: ReplyToMode;
};
/** WeakMap-backed metadata attached to payload objects without changing wire shape. */
type SessionWriterDeliveryAuthority = {
agentId?: string;
expectedLifecycleRevision?: string;
expectedSessionId: string;
expectedWriterRunId?: string;
sessionKey: string;
storePath?: string;
};
//#endregion
//#region packages/agent-core/src/types.d.ts
/**
* Stream function used by the agent loop.
*
* Contract:
* - Must not throw or return a rejected promise for request/model/runtime failures.
* - Must return an AssistantMessageEventStream.
* - Failures must be encoded in the returned stream via protocol events and a
* final AssistantMessage with stopReason "error" or "aborted" and errorMessage.
*/
type StreamFn = StreamFn$1;
/**
* Configuration for how tool calls from a single assistant message are executed.
*
* - "sequential": each tool call is prepared, checked for steering, executed, and finalized before the next one starts.
* - "parallel": tool calls are prepared sequentially, checked for steering once, then allowed tools execute concurrently.
* `tool_execution_end` is emitted in tool completion order after each tool is finalized,
* while tool-result message artifacts are emitted later in assistant source order.
*/
type ToolExecutionMode = "sequential" | "parallel";
/** Bucketed feedback for an admitted call, not a veto or recovery attempt. */
interface ToolLoopWarning {
kind: "tool-loop-warning";
toolCallId: string;
count: number;
}
interface BashExecutionMessage {
/** Harness role for shell command transcripts. */
role: "bashExecution";
/** Command line that was executed. */
command: string;
/** Captured command output, usually already truncated for context. */
output: string;
/** Process exit code when the command reached process exit. */
exitCode: number | undefined;
/** True when the command was interrupted before normal completion. */
cancelled: boolean;
/** True when output was shortened for transcript/context storage. */
truncated: boolean;
/** Optional path containing the complete output when truncation occurred. */
fullOutputPath?: string;
/** Millisecond timestamp for transcript ordering. */
timestamp: number;
/** Exclude this command transcript from model context while keeping it in session history. */
excludeFromContext?: boolean;
}
interface CustomMessage<T = unknown> {
/** Harness role for application-defined transcript content. */
role: "custom";
/** Application-defined discriminator for rendering or handling this message. */
customType: string;
/** Content replayed into model context when this message is included. */
content: string | (TextContent | ImageContent)[];
/** Whether UI surfaces should display this message. */
display: boolean;
/** Keep display-only application activity out of future model context. */
excludeFromContext?: boolean;
/** Optional application-specific metadata. */
details?: T;
/** Millisecond timestamp for transcript ordering. */
timestamp: number;
}
interface BranchSummaryMessage {
/** Harness role for summaries produced when returning from another branch. */
role: "branchSummary";
/** Summary text inserted back into model context. */
summary: string;
/** Entry id of the branch root or source leaf being summarized. */
fromId: string;
/** Millisecond timestamp for transcript ordering. */
timestamp: number;
}
interface CompactionSummaryMessage {
/** Harness role for summaries that replace compacted transcript history. */
role: "compactionSummary";
/** Summary text inserted back into model context. */
summary: string;
/** Estimated context tokens before compaction. */
tokensBefore: number;
/** Timestamp may be numeric in memory or string when loaded from older persisted rows. */
timestamp: number | string;
/** Optional estimated context tokens after compaction. */
tokensAfter?: number;
/** Optional first retained entry id from the compaction range. */
firstKeptEntryId?: string;
/** Optional implementation-specific compaction metadata. */
details?: unknown;
}
/**
* Extensible interface for custom app and harness messages.
* Apps can extend via declaration merging.
*/
interface CustomAgentMessages {
bashExecution: BashExecutionMessage;
custom: CustomMessage;
branchSummary: BranchSummaryMessage;
compactionSummary: CompactionSummaryMessage;
}
/**
* AgentMessage: Union of LLM messages + custom messages.
* This abstraction allows apps to add custom message types while maintaining
* type safety and compatibility with the base LLM messages.
*/
type AgentMessage = Message | CustomAgentMessages[keyof CustomAgentMessages];
/** Channel-safe progress text emitted by a running tool. */
interface AgentToolProgress {
/** Public text suitable for user-facing progress surfaces. */
text: string;
/** Tool progress is rendered by channel progress UIs. */
visibility: "channel";
/** Progress text must not contain secrets, private args, or fetched content. */
privacy: "public";
/** Optional stable id for progress line replacement. */
id?: string;
}
/** Final or partial result produced by a tool. */
interface AgentToolResult<T> {
/** Text or image content returned to the model. */
content: (TextContent | ImageContent)[];
/** Arbitrary structured details for logs or UI rendering. */
details: T;
/** Optional public progress hint for partial tool updates; never model content. */
progress?: AgentToolProgress;
/**
* Hint that the agent should stop after the current tool batch.
* Early termination only happens when every finalized tool result in the batch sets this to true.
*/
terminate?: boolean;
}
/** Callback used by tools to stream partial execution updates. */
type AgentToolUpdateCallback<T = unknown> = (partialResult: AgentToolResult<T>) => void;
/** Origin class for tool output that can taint later model-authored content in the same turn. */
type ToolResultContentSource = "network";
/** Tool definition used by the agent runtime. */
interface AgentTool<TParameters extends TSchema = TSchema, TDetails = unknown> extends Tool<TParameters> {
/** Human-readable label for UI display. */
label: string;
/** Optional schema for the structured `AgentToolResult.details` value. */
outputSchema?: TSchema;
/** Preserve lifecycle telemetry without rendering transient channel progress. */
hideFromChannelProgress?: boolean;
/** Tool results contain externally controlled network content. */
resultContentSource?: ToolResultContentSource;
/**
* Optional compatibility shim for raw tool-call arguments before schema validation.
* Must return an object that matches `TParameters`.
*/
prepareArguments?: (args: unknown) => Static<TParameters>;
/** Execute the tool call. Throw on failure instead of encoding errors in `content`. */
execute: (toolCallId: string, params: Static<TParameters>, signal?: AbortSignal, onUpdate?: AgentToolUpdateCallback<TDetails>) => Promise<AgentToolResult<TDetails>>;
/**
* Per-tool execution mode override.
* - "sequential": this tool must execute one at a time with other tool calls.
* - "parallel": this tool can execute concurrently with other tool calls.
*
* If omitted, the default execution mode applies.
*/
executionMode?: ToolExecutionMode;
}
//#endregion
//#region packages/agent-core/src/harness/compaction/compaction.d.ts
/** Generated compaction data ready to be persisted as a compaction entry. */
interface CompactionResult<T = unknown> {
/** Summary text that replaces compacted history in future context. */
summary: string;
/** Entry id where retained history starts. */
firstKeptEntryId: string;
/** Estimated context tokens before compaction. */
tokensBefore: number;
/** Optional implementation-specific details stored with the compaction entry. */
details?: T;
}
//#endregion
//#region src/agents/run-timeout-attribution.d.ts
/** Agent run phases used when attributing timeout/cancellation sources. */
declare const AGENT_RUN_TIMEOUT_PHASES: readonly ["queue", "preflight", "provider", "post_turn", "gateway_draining"];
/** Timeout attribution phase for agent run lifecycle spans. */
type AgentRunTimeoutPhase = (typeof AGENT_RUN_TIMEOUT_PHASES)[number];
//#endregion
//#region src/agents/agent-run-terminal-outcome.types.d.ts
/** Wait status reported by agent run terminal wait paths. */
type AgentRunWaitStatus = "ok" | "error" | "timeout";
/** Normalized terminal reason for an agent run. */
type AgentRunTerminalReason = "completed" | "hard_timeout" | "timed_out" | "superseded" | "cancelled" | "aborted" | "blocked" | "abandoned" | "failed";
/** Normalized terminal outcome for an agent run. */
type AgentRunTerminalOutcome = {
reason: AgentRunTerminalReason;
status: AgentRunWaitStatus;
error?: string;
stopReason?: string;
livenessState?: string;
timeoutPhase?: AgentRunTimeoutPhase;
providerStarted?: boolean;
startedAt?: number;
endedAt?: number;
};
//#endregion
//#region src/audit/execution-identity-admission.d.ts
declare const ExecutionIdentityAdmissionEnvelopeSchema: Type.TObject<{
envelopeVersion: Type.TLiteral<1>;
contextId: Type.TString;
executionId: Type.TString;
runId: Type.TString;
createdAt: Type.TInteger;
runtimeInstanceId: Type.TString;
agentId: Type.TString;
ingress: Type.TObject<{
kind: Type.TUnion<[Type.TLiteral<"local-cli">, Type.TLiteral<"gateway-client">, Type.TLiteral<"channel">, Type.TLiteral<"api">, Type.TLiteral<"schedule">, Type.TLiteral<"webhook">, Type.TLiteral<"task">, Type.TLiteral<"subagent">, Type.TLiteral<"acp">, Type.TLiteral<"worker">, Type.TLiteral<"plugin">, Type.TLiteral<"recovery">, Type.TLiteral<"system">]>;
boundary: Type.TString;
state: Type.TUnion<[Type.TLiteral<"present">, Type.TLiteral<"absent">, Type.TLiteral<"unknown">, Type.TLiteral<"unsupported">]>;
rawSourceRef: Type.TOptional<Type.TString>;
}>;
runtime: Type.TObject<{
kind: Type.TUnion<[Type.TLiteral<"gateway">, Type.TLiteral<"embedded">, Type.TLiteral<"worker">, Type.TLiteral<"plugin-harness">, Type.TLiteral<"acp">]>;
}>;
invoker: Type.TOptional<Type.TUnion<[Type.TObject<{
state: Type.TLiteral<"present">;
kind: Type.TUnion<[Type.TLiteral<"person">, Type.TLiteral<"agent">, Type.TLiteral<"service">, Type.TLiteral<"schedule">, Type.TLiteral<"webhook">, Type.TLiteral<"system">, Type.TLiteral<"local-account">, Type.TLiteral<"runtime">]>;
rawPrincipalRef: Type.TString;
displayLabel: Type.TOptional<Type.TString>;
}>, Type.TObject<{
state: Type.TLiteral<"unknown">;
}>]>>;
applicableGrants: Type.TArray<Type.TObject<{
rawGrantRef: Type.TString;
state: Type.TUnion<[Type.TLiteral<"present">, Type.TLiteral<"absent">, Type.TLiteral<"unknown">, Type.TLiteral<"unsupported">]>;
}>>;
assurance: Type.TArray<Type.TObject<{
kind: Type.TUnion<[Type.TLiteral<"durable-profile">, Type.TLiteral<"trusted-proxy">, Type.TLiteral<"tailscale-whois">, Type.TLiteral<"device-proof">, Type.TLiteral<"channel-admission">, Type.TLiteral<"local-process">, Type.TLiteral<"spawn-lineage">, Type.TLiteral<"worker-admission">, Type.TLiteral<"runtime-binding">, Type.TLiteral<"other">]>;
rawEvidenceRef: Type.TString;
strength: Type.TUnion<[Type.TLiteral<"self-asserted">, Type.TLiteral<"boundary-verified">, Type.TLiteral<"cryptographic">]>;
}>>;
}>;
declare const ExecutionIdentityAdmissionTokenSchema: Type.TObject<{
tokenVersion: Type.TLiteral<1>;
contextId: Type.TString;
executionId: Type.TString;
runId: Type.TString;
createdAt: Type.TInteger;
}>;
type ExecutionIdentityAdmissionEnvelope = Static<typeof ExecutionIdentityAdmissionEnvelopeSchema>;
type ExecutionIdentityAdmissionFacts = Omit<ExecutionIdentityAdmissionEnvelope, "envelopeVersion" | "contextId" | "executionId" | "createdAt" | "runtimeInstanceId" | "ingress" | "applicableGrants" | "assurance"> & {
ingress: Omit<ExecutionIdentityAdmissionEnvelope["ingress"], "state"> & {
state?: ExecutionIdentityAdmissionEnvelope["ingress"]["state"];
};
applicableGrants?: ExecutionIdentityAdmissionEnvelope["applicableGrants"];
assurance?: ExecutionIdentityAdmissionEnvelope["assurance"];
};
type ExecutionIdentityAdmissionToken = Static<typeof ExecutionIdentityAdmissionTokenSchema>;
//#endregion
//#region src/channels/streaming.d.ts
type AgentPlanStepStatus = "pending" | "in_progress" | "completed";
type AgentPlanStep = {
step: string;
status: AgentPlanStepStatus;
};
//#endregion
//#region src/config/sessions/transcript-entry-anchor.d.ts
/** Immutable transcript identity issued by the SQLite append transaction. */
type TranscriptEntryAnchor = Readonly<{
agentId: string;
sessionId: string;
sessionKey: string;
storePath: string;
generation: string;
entryId: string;
rawSeq: number;
effectiveParentId: string | null;
activeMessagePosition: number;
idempotencyKey?: string;
}>;
/** Current user row bound to one recorder-owned logical turn. */
type TranscriptTurnAdmission = TranscriptEntryAnchor & Readonly<{
logicalTurnId: string;
role: "user";
}>;
/** Exact accepted transcript range, inclusive of admission and terminal. */
type TranscriptTurnBoundary = Readonly<{
admission: TranscriptTurnAdmission;
terminal: TranscriptEntryAnchor;
}>;
//#endregion
//#region packages/media-core/src/constants.d.ts
/** Canonical media families used by attachment facts, routing, and MIME classification. */
type MediaKind = "image" | "audio" | "video" | "document" | "sticker" | "unknown";
/** Maps a MIME type to the media family used for size limits and routing. */
declare function mediaKindFromMime(mime?: string | null): MediaKind | undefined;
//#endregion
//#region src/media/prompt-image-order.d.ts
/** Tracks whether prompt images stayed inline or were offloaded while preserving model order. */
type PromptImageOrderEntry = "inline" | "offloaded";
//#endregion
//#region src/media/media-facts.d.ts
/** One ordered runtime attachment; array position is its alignment identity. */
type MediaFact = {
path?: string;
url?: string;
contentType?: string;
kind?: MediaKind;
fileName?: string;
sizeBytes?: number;
durationMs?: number;
width?: number;
height?: number;
transcribed?: boolean;
messageId?: string;
workspaceDir?: string;
/** Internal proof that this exact fact was covered by a legacy staged projection. */
staged?: boolean;
hydrationSuppressed?: boolean;
};
type MediaFactInput = { [Key in keyof MediaFact]?: MediaFact[Key] | null; };
declare const LEGACY_MEDIA_CONTEXT_KEYS: readonly ["MediaPath", "MediaPaths", "MediaUrl", "MediaUrls", "MediaType", "MediaTypes", "MediaDir", "MediaTranscribedIndexes", "MediaStaged", "MediaWorkspaceDir"];
type LegacyMediaContextKey = (typeof LEGACY_MEDIA_CONTEXT_KEYS)[number];
//#endregion
//#region src/chat/sender-identity.d.ts
type TranscriptSenderIdentity = Extract<SessionParticipantIdentity, {
type: "profile" | "remote" | "observation";
}>;
//#endregion
//#region src/config/sessions/goals-operations.types.d.ts
type SessionGoalOperationResult = Omit<SessionsGoalMutationResult, "replayed">;
type SessionTranscriptTurnMutationResult = {
result: SessionGoalOperationResult;
replayed: boolean;
};
//#endregion
//#region src/config/sessions/session-transcript-turn-lifecycle.types.d.ts
/** Authoritative lifecycle snapshot required for an atomic transcript admission. */
type SessionTranscriptTurnExpectedState = {
/** Rejects a run-owned turn after another admitted run takes writer ownership. */
expectedWriterRunId?: string;
abortedLastRun: boolean | undefined;
/** Fences recovery-only transcript writes against concurrent ownership changes. */
mainRestartRecoveryCycleId: string | undefined;
mainRestartRecoveryRevision: number | undefined;
restartRecoveryBeforeAgentReplyState: SessionRestartRecoveryState["restartRecoveryBeforeAgentReplyState"];
restartRecoveryDeliveryReceiptState: SessionRestartRecoveryState["restartRecoveryDeliveryReceiptState"];
restartRecoveryDeliveryToolCallId: SessionRestartRecoveryState["restartRecoveryDeliveryToolCallId"];
restartRecoveryDeliveryRequestFingerprint: SessionRestartRecoveryState["restartRecoveryDeliveryRequestFingerprint"];
restartRecoveryDeliveryRunId: SessionRestartRecoveryState["restartRecoveryDeliveryRunId"];
restartRecoveryDeliverySourceRunId: SessionRestartRecoveryState["restartRecoveryDeliverySourceRunId"];
restartRecoveryRequesterAccountId: SessionRestartRecoveryState["restartRecoveryRequesterAccountId"];
restartRecoveryRequesterSenderId: SessionRestartRecoveryState["restartRecoveryRequesterSenderId"];
restartRecoverySameChannelThreadRequired: SessionRestartRecoveryState["restartRecoverySameChannelThreadRequired"];
restartRecoverySourceIngress: SessionRestartRecoveryState["restartRecoverySourceIngress"];
restartRecoverySourceReplyDeliveryMode: SessionRestartRecoveryState["restartRecoverySourceReplyDeliveryMode"];
restartRecoveryTerminalRunIds: SessionRestartRecoveryState["restartRecoveryTerminalRunIds"];
status: SessionRunStatus | undefined;
};
/** Lifecycle fields committed with an accepted transcript turn. */
type SessionTranscriptTurnLifecyclePatch = {
abortedLastRun?: boolean;
endedAt?: number;
lifecycleRunId?: InternalSessionEntry["lifecycleRunId"];
lastRunId?: InternalSessionEntry["lastRunId"];
lastRunError?: InternalSessionEntry["lastRunError"];
pendingFinalDelivery?: InternalSessionEntry["pendingFinalDelivery"];
mainRestartRecovery?: InternalSessionEntry["mainRestartRecovery"];
restartRecoveryBeforeAgentReplyState?: SessionRestartRecoveryState["restartRecoveryBeforeAgentReplyState"];
restartRecoveryDeliveryReceiptState?: SessionRestartRecoveryState["restartRecoveryDeliveryReceiptState"];
restartRecoveryDeliveryToolCallId?: SessionRestartRecoveryState["restartRecoveryDeliveryToolCallId"];
restartRecoveryDeliveryContext?: SessionRestartRecoveryState["restartRecoveryDeliveryContext"];
restartRecoveryDeliveryRequestFingerprint?: SessionRestartRecoveryState["restartRecoveryDeliveryRequestFingerprint"];
restartRecoveryDeliveryRunId?: SessionRestartRecoveryState["restartRecoveryDeliveryRunId"];
restartRecoveryDeliverySourceRunId?: SessionRestartRecoveryState["restartRecoveryDeliverySourceRunId"];
restartRecoveryRequesterAccountId?: SessionRestartRecoveryState["restartRecoveryRequesterAccountId"];
restartRecoveryRequesterSenderId?: SessionRestartRecoveryState["restartRecoveryRequesterSenderId"];
restartRecoverySameChannelThreadRequired?: SessionRestartRecoveryState["restartRecoverySameChannelThreadRequired"];
restartRecoverySourceIngress?: SessionRestartRecoveryState["restartRecoverySourceIngress"];
restartRecoverySourceReplyDeliveryMode?: SessionRestartRecoveryState["restartRecoverySourceReplyDeliveryMode"];
restartRecoveryForceSafeTools?: InternalSessionEntry["restartRecoveryForceSafeTools"];
restartRecoveryRuns?: InternalSessionEntry["restartRecoveryRuns"];
/** Durable tombstones merged with the fresh row inside the SQLite write transaction. */
restartRecoveryTerminalRunIds?: SessionRestartRecoveryState["restartRecoveryTerminalRunIds"];
runtimeMs?: number;
startedAt?: number;
status?: SessionRunStatus;
updatedAt?: number;
};
//#endregion
//#region src/sessions/input-provenance.d.ts
declare const INPUT_PROVENANCE_KIND_VALUES: readonly ["external_user", "inter_session", "internal_system"];
type InputProvenanceKind = (typeof INPUT_PROVENANCE_KIND_VALUES)[number];
type InputProvenance = {
kind: InputProvenanceKind;
originSessionId?: string;
sourceSessionKey?: string;
sourceChannel?: string;
sourceTool?: string;
};
//#endregion
//#region src/sessions/user-turn-transcript.types.d.ts
type UserTurnSessionEntry = SessionEntry;
type PersistedUserTurnMediaInput = Pick<MediaFactInput, "contentType" | "durationMs" | "fileName" | "height" | "hydrationSuppressed" | "messageId" | "path" | "sizeBytes" | "transcribed" | "url" | "width"> & {
kind?: string | null;
workspaceDir?: string | null;
};
type PersistedUserTurnMessage = Extract<AgentMessage, {
role: "user";
}> & {
display?: false;
excludeFromContext?: true;
/** Private transcript correlation; never authorizes an execution. */
idempotencyKey?: string;
provenance?: InputProvenance;
__openclaw?: Record<string, unknown> & {
humanMentions?: readonly HumanMention[];
};
};
type UserTurnInput = Pick<PersistedUserTurnMessage, "display" | "excludeFromContext"> & {
text?: string | null;
/** Explicit human selections bound to UTF-16 offsets in text. */
mentions?: readonly HumanMention[];
media?: readonly PersistedUserTurnMediaInput[] | null;
/** Restart-safe native image placement; model-visible prompt bytes remain separate. */
mediaImageLayout?: {
slots: readonly {
kind: "inline" | "offloaded";
factIndex?: number;
}[];
suppressedFactIndexes?: readonly number[];
} | null;
timestamp?: number;
idempotencyKey?: string;
/** Durable transcript message reference used to render and hydrate replies. */
replyToId?: string;
/** Bounded display fallback for replies whose target is outside loaded history. */
replyToPreview?: {
text: string;
senderLabel?: string | null;
} | null;
senderIsOwner?: boolean;
provenance?: InputProvenance;
/** Identity is producer-owned attribution; labels remain editable display metadata. */
sender?: {
id?: string | null;
name?: string | null;
username?: string | null;
identity?: TranscriptSenderIdentity;
} | null;
/** Durable transport correlation; stored privately and never rendered into model input. */
transport?: {
channel?: string;
conversationRef?: string;
messageId?: string;
replyToId?: string;
threadId?: string;
};
};
type UserTurnTranscriptUpdateMode = "inline" | "none";
type UserTurnBeforeMessageWrite = (params: {
message: PersistedUserTurnMessage;
agentId?: string;
sessionKey?: string;
}) => AgentMessage | null;
type UserTurnTranscriptPersistenceTarget = {
sessionId: string;
expectedSessionId?: string;
initialSessionEntry?: SessionEntry;
sessionKey: string;
sessionEntry: UserTurnSessionEntry | undefined;
sessionStore?: Record<string, UserTurnSessionEntry>;
storePath?: string;
agentId: string;
threadId?: string | number;
cwd?: string;
config?: unknown;
beforeMessageWrite?: UserTurnBeforeMessageWrite;
};
type UserTurnTranscriptTarget = UserTurnTranscriptPersistenceTarget;
type UserTurnTranscriptAdmissionReceipt = TranscriptTurnAdmission;
/** Native producer facts for the current host-admitted prompt; never a message replacement. */
type UserTurnTranscriptAnnotation = Readonly<{
mirrorIdentity: string;
upstreamUserText: string;
mirrorOrigin: string;
mirrorSourceFingerprint: string;
}>;
type UserTurnTranscriptPersistResult = {
sessionTurnMutationResult?: SessionTranscriptTurnMutationResult;
/** True only when this call inserted the transcript message. */
appended?: boolean;
sessionFile: string;
sessionEntry: UserTurnSessionEntry | undefined;
messageId: string;
message: PersistedUserTurnMessage;
admission: UserTurnTranscriptAdmissionReceipt;
};
type UserTurnTranscriptTargetResolver = UserTurnTranscriptTarget | (() => UserTurnTranscriptTarget | undefined | Promise<UserTurnTranscriptTarget | undefined>);
type UserTurnTranscriptRecorder = {
readonly message: PersistedUserTurnMessage | undefined;
resolveMessage: () => Promise<PersistedUserTurnMessage | undefined>;
/** Durable input custody leaves the active transcript unchanged until execution owns it. */
stageApproved?: (options: {
runId: string;
assertCurrent: () => void;
}) => Promise<boolean>;
getPendingInputMessage?: () => PersistedUserTurnMessage | undefined;
isPendingInputConsumed?: () => boolean;
withPendingInput?: <T>(run: () => T) => T;
finishPendingInput?: (disposition: "cancelled" | "interrupted") => void;
/** Replaces generated current-turn text before runtime persistence/provider submission. */
replaceTextBeforePersistence?: (text: string) => void;
/** Confirms exact-run steering provenance after transcript commitment is proven. */
confirmSteerTargetRunIdForPersistence?: (targetRunId: string) => Promise<void>;
getPersistedMessage?: () => PersistedUserTurnMessage | undefined;
getAdmissionReceipt: () => UserTurnTranscriptAdmissionReceipt | undefined;
setAdmissionHandler?: (handler: (admission: UserTurnTranscriptAdmissionReceipt) => void) => void;
markSentToProvider?: () => void;
markRuntimePersistencePending: (pending: Promise<void>) => void;
markRuntimePersisted: (message?: PersistedUserTurnMessage, anchor?: TranscriptEntryAnchor | UserTurnTranscriptAdmissionReceipt, persistence?: {
appended: boolean;
}) => void;
markBlocked: () => void;
hasPersisted: () => boolean;
isBlocked: () => boolean;
hasRuntimePersistencePending: () => boolean;
waitForRuntimePersistence: () => Promise<void>;
persistApproved: (params?: {
target?: UserTurnTranscriptTargetResolver;
updateMode?: UserTurnTranscriptUpdateMode;
cwd?: string;
expectedSessionId?: string;
expectedSessionState?: SessionTranscriptTurnExpectedState;
sessionLifecyclePatch?: SessionTranscriptTurnLifecyclePatch;
/** Allow a later explicit persistence attempt when this attempt appends nothing. */
retryIfUnpersisted?: boolean;
}) => Promise<UserTurnTranscriptPersistResult | undefined>;
persistBlocked: (message: PersistedUserTurnMessage, params?: {
target?: UserTurnTranscriptTargetResolver;
updateMode?: UserTurnTranscriptUpdateMode;
cwd?: string;
}) => Promise<UserTurnTranscriptPersistResult | undefined>;
persistFallback: (params?: {
target?: UserTurnTranscriptTargetResolver;
updateMode?: UserTurnTranscriptUpdateMode;
cwd?: string;
}) => Promise<UserTurnTranscriptPersistResult | undefined>;
};
//#endregion
//#region src/auto-reply/reply/typing.d.ts
/** Controller for channel typing indicator lifecycle during a reply run. */
type TypingController = {
onReplyStart: () => Promise<void>;
startTypingLoop: () => Promise<void>;
startTypingOnText: (text?: string) => Promise<void>;
refreshTypingTtl: () => void;
isActive: () => boolean;
markRunComplete: () => void;
markDispatchIdle: () => void;
cleanup: () => void;
};
//#endregion
//#region src/auto-reply/get-reply-options.types.d.ts
/** A successful runtime append, independent of optional active-path projection anchors. */
type ReplyDispatchAssistantTranscript = Pick<TranscriptEntryAnchor, "agentId" | "sessionId" | "sessionKey" | "storePath"> & {
messageId: string;
anchor?: TranscriptEntryAnchor;
idempotencyKey: string;
};
type ReplyDispatchRun = {
completionSource: "reply-dispatch";
getResult: () => {
assistantTranscript?: ReplyDispatchAssistantTranscript;
terminalOutcome?: AgentRunTerminalOutcome;
};
};
type BlockReplyContext = {
abortSignal?: AbortSignal;
timeoutMs?: number;
/** Source assistant message index from the upstream stream, when available. */
assistantMessageIndex?: number;
/** @internal Stable durable outbound intent owned by the producing runtime. */
deliveryIntentId?: string;
};
/** Context passed to onModelSelected callback with actual model used. */
type ModelSelectedContext = {
provider: string;
model: string;
thinkLevel: string | undefined;
};
/** Typing indicator class for channel-owned UX policy. */
type TypingPolicy = "auto" | "user_message" | "system_event" | "internal_webchat" | "heartbeat";
/** Per-turn policy for source-message reply threading. */
type ReplyThreadingPolicy = {
/** Override implicit reply-to-current behavior for the current turn. */
implicitCurrentMessage?: "default" | "allow" | "deny";
};
/** Action sink available for model-proposed follow-up tasks during this turn. */
type TaskSuggestionDeliveryMode = "gateway";
/** Correlates queued reply ownership transfer with later delivery drains. */
type QueuedReplyDeliveryCorrelation = {
begin: () => (() => void) | void;
};
/**
* Exclusive: each lifecycle is its own collect-admission identity.
* Cancel-only: share collect identity via ownerKey (gateway chat.send).
*/
type TurnAdoptionAdmission = "exclusive" | "cancel-only";
/**
* Canonical turn-ownership lifecycle (adopt / defer / abandon / settle).
* Single surface for durable ingress, gateway cancel identity, and reply-lane transfer.
*/
type TurnAdoptionLifecycle = {
/**
* Admission isolation mode (closed). Exclusive isolates collect identity per
* lifecycle; cancel-only shares via ownerKey. Never inferred from onAbandoned.
* Durable ingress sets exclusive; gateway cancel identity sets cancel-only.
*/
admission?: TurnAdoptionAdmission;
/** Transcript branch leaf from which this turn was admitted. */
originatingLeafEntryId?: string | null;
onAdopted: () => void | Promise<void>;
/** Return false to reject followup enqueue. */
onDeferred?: () => boolean | void;
/** Reports that a deferred turn is still queued behind an active turn. */
onDeferredHeartbeat?: () => void;
/** Deferred turn finished without owning the reply lane. */
onAbandoned?: () => void;
/** Always fires when the followup ownership cycle ends (admitted or not). Gateway cleanup. */
onSettled?: () => void;
/** Retires cancellation ownership while retaining live identity. */
onCancellationRetired?: () => void;
/** Stable cancellation owner for collect-mode batches. */
ownerKey?: string;
abortSignal?: AbortSignal;
/** Ephemeral fact: a direct local operator turn lost fresh cron authority when queued. */
cronCreatorAuthorityUnavailable?: "queued-local-operator";
};
/** Partial assistant payload emitted during streaming or replacement updates. */
type PartialReplyPayload = {
/**
* Sanitized text, which may be an enumerable memoized getter. Content materializes on first
* read: direct-delivery consumers pay per partial, while throttled consumers pay per flush.
*/
text?: ReplyPayload["text"];
mediaUrls?: ReplyPayload["mediaUrls"];
delta?: string;
replace?: true;
};
type ReasoningStreamPayload = Pick<ReplyPayload, "text" | "mediaUrls" | "isReasoning" | "isReasoningSnapshot"> & {
requiresReasoningProgressOptIn?: boolean;
};
type ReasoningProgressPayload = {
progressTokens: number;
};
/** Return false until the channel has accepted operator-visible progress. */
type ProgressCallbackResult = boolean | void;
/** Reply generation options shared by auto-reply, webchat, channels, and tests. */
type GetReplyOptions = {
/** Override run id for agent events (defaults to random UUID). */
runId?: string;
/** Stable provider prompt-cache affinity key; distinct from run id/idempotency. */
promptCacheKey?: string;
/** Abort signal for the underlying agent run. */
abortSignal?: AbortSignal;
/** Ephemeral channel owner check for a targeted Stop; never serialized as authority. */
isCommandTargetCurrent?: () => boolean;
/** Optional inbound images (used for webchat attachments). */
images?: ImageContent[];
/** Original inline/offloaded attachment order for inbound images. */
imageOrder?: PromptImageOrderEntry[];
/** Ordered media facts whose model-facing text projection is already present in the prompt. */
media?: MediaFact[];
/**
* Notifies when an agent run starts. Return "reply-dispatch" synchronously to accept
* completion ownership offered in options; all other legacy callback results are ignored.
*/
onAgentRunStart?: (runId: string, executionIdentityToken?: ExecutionIdentityAdmissionToken, options?: ReplyDispatchRun) => unknown;
/** Reports the terminal agent-run classification to the shared dispatch owner. */
onAgentRunTerminalOutcome?: (outcome: "completed" | "failed") => void;
/**
* Canonical adoption lifecycle (adopted / deferred / abandoned / settled + pre-adoption abort).
*/
turnAdoptionLifecycle?: TurnAdoptionLifecycle;
/** Shared lifecycle owner for the current user-turn transcript append. */
userTurnTranscriptRecorder?: UserTurnTranscriptRecorder;
/** Gateway-owned start-or-steer decision for this turn. */
messageInjectionDisposition?: "none" | "accepted" | "rejected";
/** Current user turn is already durable; replay it without appending another copy. */
suppressNextUserMessagePersistence?: boolean;
onReplyStart?: () => Promise<void> | void;
/** Called when the typing controller cleans up (e.g., run ended with NO_REPLY). */
onTypingCleanup?: () => void;
onTypingController?: (typing: TypingController) => void;
/** If false, send only the initial typing signal without periodic keepalive refreshes. */
typingKeepalive?: boolean;
isHeartbeat?: boolean;
/** Policy-level typing control for run classes (user/system/internal/heartbeat). */
typingPolicy?: TypingPolicy;
/** Force-disable typing indicators for this run (system/internal/cross-channel routes). */
suppressTyping?: boolean;
/** Resolved heartbeat model override (provider/model string from merged per-agent config). */
heartbeatModelOverride?: string;
/** One-shot thinking level override for this run; does not persist to the session. */
thinkingLevelOverride?: string;
/** One-shot fast-mode override for this run; does not persist to the session. */
fastModeOverride?: FastMode;
/** One-shot auto fast-mode cutoff override in seconds; does not persist to the session. */
fastModeAutoOnSecondsOverride?: number;
/** Controls bootstrap workspace context injection (default: full). */
bootstrapContextMode?: "full" | "lightweight";
/** If true, run the model without OpenClaw tools for this turn. */
disableTools?: boolean;
/** Runtime tool allow-list for this turn. Empty means no tools. */
toolsAllow?: string[];
/** If true, include the heartbeat response tool for structured heartbeat outcomes. */
enableHeartbeatTool?: boolean;
/** If true, keep the heartbeat response tool available even under narrow tool profiles. */
forceHeartbeatTool?: boolean;
/**
* @deprecated Ignored. The tool-failure warning is delivered whenever a run ends
* without a reply and cannot be suppressed. Kept only so plugin-sdk callers that
* still pass it keep compiling; removed in the first stable release after 2026.10.
*/
suppressToolErrorWarnings?: boolean;
/**
* If true, dispatch skips default tool/progress text messages and expects the
* channel to surface progress via its own streaming/edit UX.
*/
suppressDefaultToolProgressMessages?: boolean;
/** Suppress standalone tool/progress text even when verbose progress is enabled. */
suppressToolProgressMessages?: boolean;
/** Allow channel-owned tool lifecycle feedback while text progress remains hidden. */
allowToolLifecycleWhenProgressHidden?: boolean;
/**
* Called before dispatch with a live getter for whether verbose standalone
* progress messages are active for this run. Channels that render tool or
* commentary progress inside an ephemeral streaming draft should yield those
* draft lines while the getter returns true, so progress is not rendered in
* both lanes at once.
*/
onVerboseProgressVisibility?: (isActive: () => boolean) => void;
/** Preserve source-event callback start order for stateful channel progress renderers. */
preserveProgressCallbackStartOrder?: boolean;
onPartialReply?: (payload: PartialReplyPayload) => Promise<ProgressCallbackResult> | ProgressCallbackResult;
onReasoningStream?: (payload: ReasoningStreamPayload) => Promise<ProgressCallbackResult> | ProgressCallbackResult;
onReasoningProgress?: (payload: ReasoningProgressPayload) => Promise<void> | void;
streamReasoningInNonStreamModes?: boolean;
/** Called when a thinking/reasoning block ends. */
onReasoningEnd?: () => Promise<ProgressCallbackResult> | ProgressCallbackResult;
/** Called when a new assistant message starts (e.g., after tool call or thinking block). */
onAssistantMessageStart?: () => Promise<ProgressCallbackResult> | ProgressCallbackResult;
/** Called synchronously when a block reply is logically emitted, before async
* delivery drains. Useful for channels that need to rotate preview state at
* block boundaries without waiting for transport acks. */
onBlockReplyQueued?: (payload: ReplyPayload, context?: BlockReplyContext) => Promise<ProgressCallbackResult> | ProgressCallbackResult;
onBlockReply?: (payload: ReplyPayload, context?: BlockReplyContext) => Promise<void> | void;
onToolResult?: (payload: ReplyPayload) => Promise<ProgressCallbackResult> | ProgressCallbackResult;
/** Called when a tool phase starts/updates, before summary payloads are emitted. */
onToolStart?: (payload: {
itemId?: string;
toolCallId?: string;
name?: string;
phase?: string;
args?: Record<string, unknown>;
detailMode?: "explain" | "raw";
}) => Promise<ProgressCallbackResult> | ProgressCallbackResult;
/** Called when a concrete work item starts, updates, or completes. */
onItemEvent?: (payload: {
itemId?: string;
toolCallId?: string;
kind?: string;
title?: string;
name?: string;
phase?: string;
status?: string;
summary?: string;
progressText?: string;
meta?: string;
commandBearing?: boolean;
approvalId?: string;
approvalSlug?: string;
suppressDurableProgress?: true;
}) => Promise<ProgressCallbackResult> | ProgressCallbackResult;
/**
* Called when the utility-model narration of the in-progress turn changes.
* Providing this callback opts the channel into progress narration; core
* only generates narration when a utility model resolves (explicit
* config or the provider-declared default; utilityModel: "" disables).
* An empty text clears narration; a retained model preamble still wins before
* the channel falls back to raw tool progress.
*/
onNarrationUpdate?: (payload: {
text: string;
}) => Promise<void> | void;
/** Channel-owned final and queued-turn boundaries for the current narrator. */
onProgressNarratorLifecycle?: (lifecycle: {
beginTurn: () => void;
stopTurn: () => void;
}) => void;
/** False while utility-model narration has no visible progress draft. */
isProgressDraftVisible?: () => boolean;
/**
* Omit exec/bash command text from narration model input, mirroring the
* channel's `streaming.progress.commandText: "status"` display policy so
* narration never receives more command detail than the draft shows.
*/
narrationHideCommandText?: boolean;
/** In progress mode, classify Claude pre-tool text; true also renders it as commentary. */
commentaryProgressEnabled?: boolean;
/** Bridge typed preambles to a channel-owned progress headline without commentary. */
progressPreambleEnabled?: boolean;
/** Deliver durable reasoning payloads to channels that own a separate reasoning lane. */
reasoningPayloadsEnabled?: boolean;
/** Deliver durable commentary (💬) payloads to channels that own a separate commentary lane. */
commentaryPayloadsEnabled?: boolean;
/** Optional turn-frozen commentary owner; visibility is live by default.
* With the static opt-in and this callback, core freezes, evaluates once, and snapshots. */
shouldDeliverCommentaryPayloads?: () => boolean;
/** Called when the agent emits a structured plan update. */
onPlanUpdate?: (payload: {
phase?: string;
title?: string;
explanation?: string;
steps?: AgentPlanStep[];
source?: string;
}) => Promise<ProgressCallbackResult> | ProgressCallbackResult;
/** Called when an approval becomes pending or resolves. */
onApprovalEvent?: (payload: {
phase?: string;
kind?: string;
status?: string;
title?: string;
itemId?: string;
toolCallId?: string;
approvalId?: string;
approvalSlug?: string;
command?: string;
host?: string;
reason?: string;
scope?: "turn" | "session";
message?: string;
}) => Promise<ProgressCallbackResult> | ProgressCallbackResult;
/** Called when command output streams or completes. */
onCommandOutput?: (payload: {
itemId?: string;
phase?: string;
title?: string;
toolCallId?: string;
name?: string;
output?: string;
status?: string;
exitCode?: number | null;
durationMs?: number;
cwd?: string;
}) => Promise<ProgressCallbackResult> | ProgressCallbackResult;
/** Called when a patch completes with a file summary. */
onPatchSummary?: (payload: {
itemId?: string;
phase?: string;
title?: string;
toolCallId?: string;
name?: string;
added?: string[];
modified?: string[];
deleted?: string[];
summary?: string;
}) => Promise<ProgressCallbackResult> | ProgressCallbackResult;
/** Called when context auto-compaction starts (allows UX feedback during the pause). */
onCompactionStart?: () => Promise<ProgressCallbackResult> | ProgressCallbackResult;
/** Called when context auto-compaction ends; omitted outcome means completed for legacy callers. */
onCompactionEnd?: (payload?: {
completed: boolean;
}) => Promise<ProgressCallbackResult> | ProgressCallbackResult;
/** Called when the actual model is selected (including after fallback).
* Use this to get model/provider/thinkLevel for responsePrefix template interpolation. */
onModelSelected?: (ctx: ModelSelectedContext) => void;
/**
* Controls whether normal assistant replies are automatically delivered to
* the source conversation. `message_tool_only` prefers message-tool visible
* delivery and keeps normal final text, block output, and preview output
* private unless dispatch explicitly marks a source reply as deliverable.
*/
sourceReplyDeliveryMode?: SourceReplyDeliveryMode;
/** Enables task-suggestion tools only when the initiating surface can action Gateway events. */
taskSuggestionDeliveryMode?: TaskSuggestionDeliveryMode;
/** Starts delivery tracking when this turn later drains as a queued followup. */
queuedDeliveryCorrelations?: QueuedReplyDeliveryCorrelation[];
/** Called after a queued followup owns the reply lane, before its model run starts. */
onQueuedFollowupAdmitted?: () => Promise<void> | void;
/** Called after an admitted queued followup finishes, including failed attempts. */
onQueuedFollowupSettled?: () => Promise<void> | void;
/** Allow channel-owned progress UI while final/source reply delivery remains message-tool-only. */
allowProgressCallbacksWhenSourceDeliverySuppressed?: boolean;
/** Called when a suppressed source reply mode observes visible delivery through another path. */
onObservedReplyDelivery?: () => Promise<void> | void;
/** Emit tool result summaries for channel-owned progress UI even when verbose is off. */
forceToolResultProgress?: boolean;
disableBlockStreaming?: boolean;
/** Timeout for block reply delivery (ms). */
blockReplyTimeoutMs?: number;
/** If provided, only load these skills for this session (empty = no skills). */
skillFilter?: string[];
/** Mutable ref to track if a reply was sent (for Slack "first" threading mode). */
hasRepliedRef?: {
value: boolean;
};
/** Override agent timeout in seconds (0 = no timeout). Threads through to resolveAgentTimeoutMs. */
timeoutOverrideSeconds?: number;
};
//#endregion
//#region src/channels/inbound-event/kind.d.ts
/**
* High-level inbound event class used to separate actionable user requests from room activity.
*/
type InboundEventKind = "user_request" | "room_event";
//#endregion
//#region src/plugins/hook-channel-context.types.d.ts
interface PluginHookChannelSenderContext {
/** Channel-scoped sender ID, matching `ctx.senderId` when both are present. */
id?: string;
[key: string]: unknown;
}
interface PluginHookChannelChatContext {
/** Transport-native conversation ID, matching `ctx.chatId` when both are present. */
id?: string;
[key: string]: unknown;
}
interface PluginHookChannelContext {
/** Sender metadata supplied by the originating channel. */
sender?: PluginHookChannelSenderContext;
/** Chat/conversation metadata supplied by the originating channel. */
chat?: PluginHookChannelChatContext;
}
//#endregion
//#region src/auto-reply/command-turn-context.d.ts
type CommandTurnKind = "native" | "text-slash" | "normal";
type BaseCommandTurnContext = {
commandName?: string;
body?: string;
};
type NativeCommandTurnContext = BaseCommandTurnContext & {
kind: "native";
source: "native";
authorized: boolean;
};
type TextSlashCommandTurnContext = BaseCommandTurnContext & {
kind: "text-slash";
source: "text";
authorized: boolean;
};
type NormalCommandTurnContext = BaseCommandTurnContext & {
kind: "normal";
source: "message";
authorized: false;
};
type CommandTurnContext = NativeCommandTurnContext | TextSlashCommandTurnContext | NormalCommandTurnContext;
//#endregion
//#region src/auto-reply/commands-args.types.d.ts
/** Primitive values accepted by parsed auto-reply command args. */
type CommandArgValue = string | number | boolean | bigint;
/** Named parsed auto-reply command values. */
type CommandArgValues = Record<string, CommandArgValue>;
/** Parsed command argument bundle with raw source and structured values. */
type CommandArgs = {
raw?: string;
values?: CommandArgValues;
};
//#endregion
//#region src/auto-reply/reply/history.types.d.ts
/** Normalized history message used when building reply context. */
type HistoryEntry = {
sender: string;
body: string;
timestamp?: number;
messageId?: string;
media?: HistoryMediaEntry[];
};
/** Media metadata attached to a normalized history message. */
type HistoryMediaEntry = Pick<MediaFact, "contentType" | "durationMs" | "height" | "kind" | "messageId" | "path" | "url" | "width">;
//#endregion
//#region src/auto-reply/templating.d.ts
/** Valid message channels for routing. */
type OriginatingChannelType = string & {
readonly __originatingChannelBrand?: never;
};
type MentionSource = "explicit_bot" | "subteam" | "mention_pattern" | "implicit_thread" | "command_bypass" | "none";
type InboundSourceModality = "text" | "voice" | "audio" | "image" | "video" | "document";
type StickerContextMetadata = {
cachedDescription?: string;
emoji?: string;
setName?: string;
description?: string;
fileId?: string;
fileUniqueId?: string;
uniqueFileId?: string;
isAnimated?: boolean;
isVideo?: boolean;
} & Record<string, unknown>;
type ChannelStructuredContextEntry = {
label: string;
source?: string;
type?: string;
payload: unknown;
/** Internal exact-id hints for canonical transcript/live-cache deduplication. */
sessionTranscriptDedupeMessageIds?: string[];
/** Internal visible-text hints for legacy assistant rows without transcript ids. */
sessionTranscriptAssistantTextDedupeKeys?: string[];
};
type SessionTranscriptContext = {
chatWindow?: boolean;
historyLimit: number;
beforeTimestampMs?: number;
minTimestampMs?: number;
senderLabels?: {
assistant: string;
user: string;
};
};
/** @deprecated Use ChannelStructuredContextEntry. Removal: after 2026-09-08 (see sdk-untrusted-context-identifier-aliases). */
type UntrustedStructuredContextEntry = ChannelStructuredContextEntry;
/** Structured supplemental facts projected into prompt context by inbound finalization. */
type SupplementalContextFacts = {
quote?: {
id?: string;
fullId?: string;
body?: string;
sender?: string;
senderAllowed?: boolean;
isExternal?: boolean;
isQuote?: boolean;
};
forwarded?: {
from?: string;
fromType?: string;
fromId?: string;
date?: number;
senderAllowed?: boolean;
};
thread?: {
id?: string;
starterBody?: string;
historyBody?: string;
label?: string;
parentSessionKey?: string;
modelParentSessionKey?: string;
senderAllowed?: boolean;
};
channelStructuredContext?: ChannelStructuredContextEntry[];
/** @deprecated Use channelStructuredContext. Removal: after 2026-09-08 (see sdk-untrusted-context-identifier-aliases). */
untrustedContext?: ChannelStructuredContextEntry[];
groupSystemPrompt?: string;
/** Prompt-like group metadata from user-controlled sources; never enters the system prompt. */
untrustedGroupSystemPrompt?: string;
};
/** Canonical normalized inbound text populated once by `finalizeInboundContext`. */
type CanonicalInboundText = {
/** Clean text used for command and directive parsing. */
commandText: string;
/** Prompt-facing text used for the agent turn. */
agentText: string;
/** Normalized visible/raw inbound text before command-specific projection. */
rawText: string;
};
/** Raw inbound message context accepted from channels before finalization. */
type MsgContext = Partial<CanonicalInboundText> & {
Body?: string;
InboundEventKind?: InboundEventKind;
/**
* Agent prompt body (may include envelope/history/context). Prefer this for prompt shaping.
* Should use real newlines (`\n`), not escaped `\\n`.
*/
BodyForAgent?: string;
/**
* Recent chat history for context (untrusted user content). Prefer passing this
* as structured context blocks in the user prompt rather than rendering plaintext envelopes.
*/
InboundHistory?: HistoryEntry[];
/** Internal facts used to merge canonical transcript turns before dispatch. */
SessionTranscriptContext?: SessionTranscriptContext;
/**
* @deprecated Use CommandBody.
*
* Raw message body without structural context (history, sender labels).
* Legacy alias for CommandBody. Falls back to Body if not set.
*/
RawBody?: string;
/**
* Prefer for command detection; RawBody is treated as legacy alias.
*/
CommandBody?: string;
/**
* Command parsing body. Prefer this over CommandBody/RawBody when set.
* Should be the "clean" text (no history/sender context).
*/
BodyForCommands?: string;
CommandArgs?: CommandArgs;
From?: string;
To?: string;
SessionKey?: string;
/**
* Resolved agent scope for canonical session keys that do not encode the agent
* id, such as selected-agent global sessions.
*/
AgentId?: string;
/** Effective routed DM scope, including binding overrides. */
DmScope?: DmScope;
/**
* Session-like key used for runtime policy (sandbox/tool policy) when the
* conversation key intentionally remains broader, such as a main-session DM.
*/
RuntimePolicySessionKey?: string;
/** Provider account id (multi-account). */
AccountId?: string;
ParentSessionKey?: string;
/**
* Session key used only for inheriting session-scoped model/provider
* overrides. Unlike ParentSessionKey, this must not trigger transcript
* forking or parent-session lifecycle behavior.
*/
ModelParentSessionKey?: string;
MessageSid?: string;
/** Provider-specific full message id when MessageSid is a shortened alias. */
MessageSidFull?: string;
MessageSids?: string[];
MessageSidFirst?: string;
MessageSidLast?: string;
AmbientTranscriptWatermarkKey?: string;
AmbientTranscriptBody?: string;
AmbientTranscriptMessageId?: string;
AmbientTranscriptTimestampMs?: number;
AmbientTranscriptPreviousMessageId?: string;
AmbientTranscriptPreviousTimestampMs?: number;
/** Per-turn reply-threading overrides. */
ReplyThreading?: ReplyThreadingPolicy;
/** Effective channel reply mode prepared for this turn. */
ReplyToMode?: ReplyToMode;
ReplyToId?: string;
/**
* Root message id for thread reconstruction (used by Feishu for root_id).
* When a message is part of a thread, this is the id of the first message.
*/
RootMessageId?: string;
/** Provider-specific full reply-to id when ReplyToId is a shortened alias. */
ReplyToIdFull?: string;
ReplyToBody?: string;
ReplyToQuoteText?: string;
ReplyToSender?: string;
ReplyChain?: Array<{
messageId?: string;
threadId?: string;
sender?: string;
senderId?: string;
senderUsername?: string;
timestamp?: number;
body?: string;
isQuote?: boolean;
mediaType?: string;
mediaPath?: string;
mediaRef?: string;
replyToId?: string;
forwardedFrom?: string;
forwardedFromId?: string;
forwardedFromUsername?: string;
forwardedDate?: number;
}>;
ReplyToIsQuote?: boolean;
/** Forward origin from the reply target (when reply_to_message is a forwarded message). */
ReplyToForwardedFrom?: string;
ReplyToForwardedFromType?: string;
ReplyToForwardedFromId?: string;
ReplyToForwardedFromUsername?: string;
ReplyToForwardedFromTitle?: string;
ReplyToForwardedDate?: number;
ForwardedFrom?: string;
ForwardedFromType?: string;
ForwardedFromId?: string;
ForwardedFromUsername?: string;
ForwardedFromTitle?: string;
ForwardedFromSignature?: string;
ForwardedFromChatType?: string;
ForwardedFromMessageId?: number;
ForwardedDate?: number;
ThreadStarterBody?: string;
/** Full thread history when starting a new thread session. */
ThreadHistoryBody?: string;
IsFirstThreadTurn?: boolean;
ThreadLabel?: string;
/** @deprecated Use `media?.[0]?.path`. */
MediaPath?: string;
/** @deprecated Use `media?.[0]?.url`. */
MediaUrl?: string;
/** @deprecated Use `media?.[0]?.contentType` or `.kind`. */
MediaType?: string;
/** @deprecated Derive the directory from `media?.[0]?.path` at the consuming boundary. */
MediaDir?: string;
/** @deprecated Use `media?.map((entry) => entry.path)`. */
MediaPaths?: string[];
/** @deprecated Use `media?.map((entry) => entry.url)`. */
MediaUrls?: string[];
/** @deprecated Use `media?.map((entry) => entry.contentType ?? entry.kind)`. */
MediaTypes?: string[];
/** Ordered current-turn media facts; array position is attachment identity. */
media?: MediaFact[];
/** Original message modality before transcription or other media normalization. */
SourceModality?: InboundSourceModality;
/** @deprecated Use each media fact's `workspaceDir`. */
MediaWorkspaceDir?: string;
/** Attachment indexes whose audio was already transcribed before media understanding runs. */
/** @deprecated Use each media fact's `transcribed` field. */
MediaTranscribedIndexes?: number[];
/**
* Marker: skip downstream stageSandboxMedia. chat.send RPC sets this so
* staging runs synchronously before respond() and surfaces 5xx to the
* client; any later failure only reaches the broadcast channel.
*/
/** @deprecated Use each media fact's `workspaceDir` or `staged` proof. */
MediaStaged?: boolean;
/** Telegram sticker metadata (emoji, set name, file IDs, cached description). */
Sticker?: StickerContextMetadata;
/** True when current-turn sticker media is present in structured facts. */
StickerMediaIncluded?: boolean;
/** Skip automatic understanding for the current sticker because its cached description is used. */
SkipStickerMediaUnderstanding?: boolean;
OutputDir?: string;
OutputBase?: string;
/** Remote host for SCP when media lives on a different machine (e.g., openclaw@192.168.64.3). */
MediaRemoteHost?: string;
Transcript?: string;
MediaUnderstanding?: MediaUnderstandingOutput[];
MediaUnderstandingDecisions?: MediaUnderstandingDecision[];
LinkUnderstanding?: string[];
Prompt?: string;
MaxChars?: number;
ChatType?: string;
/** Trusted channel-configured policy for this admitted conversation turn. */
ConversationToolPolicy?: GroupToolPolicyConfig;
/** Human label for envelope headers (conversation label, not sender). */
ConversationLabel?: string;
GroupSubject?: string;
/** Human label for channel-like group conversations (e.g. #general, #support). */
GroupChannel?: string;
GroupSpace?: string;
/** Trusted provider role ids for the sender in this group turn. */
MemberRoleIds?: string[];
GroupMembers?: string;
GroupSystemPrompt?: string;
/**
* Canonical inbound supplemental facts for new channel code. `finalizeInboundContext`
* projects these to the existing flat reply/forward/thread/group prompt fields.
*/
SupplementalContext?: SupplementalContextFacts;
/** Channel-provided metadata that must not be treated as system instructions. */
ChannelPromptContext?: string[];
/** @deprecated Use ChannelPromptContext. Removal: after 2026-09-08 (see sdk-untrusted-context-identifier-aliases). */
UntrustedContext?: string[];
/** Structured channel metadata rendered by prompt assembly as fenced JSON. */
ChannelStructuredContext?: ChannelStructuredContextEntry[];
/** @deprecated Use ChannelStructuredContext. Removal: after 2026-09-08 (see sdk-untrusted-context-identifier-aliases). */
UntrustedStructuredContext?: UntrustedStructuredContextEntry[];
/** System-attached provenance for the current inbound message. */
InputProvenance?: InputProvenance;
/** Internal wake cause, independent of transport, transcript provenance, and execution authority. */
InternalTurnSource?: "heartbeat" | "cron" | "exec";
/** Explicit owner allowlist overrides (trusted, configuration-derived). */
OwnerAllowFrom?: Array<string | number>;
SenderName?: string;
SenderId?: string;
/** Trusted in-process creation provenance; never populated from channel payloads. */
SessionCreation?: {
skillLibrarySelections?: SkillLibrarySelection[];
via: SessionCreatedVia;
actor?: SessionCreatedActor;
sandbox?: "required";
};
SenderUsername?: string;
SenderTag?: string;
SenderE164?: string;
SenderIsBot?: boolean;
/** Channel-ingress fact: sender is the operator's own account (from-me). */
SenderIsSelf?: boolean;
Timestamp?: number;
LocationLat?: number;
LocationLon?: number;
LocationAccuracy?: number;
LocationName?: string;
LocationAddress?: string;
LocationSource?: string;
LocationIsLive?: boolean;
LocationLivePeriodSeconds?: number;
LocationCaption?: string;
/** Stable identity of the provider update that carried this message. */
ProviderUpdateId?: string;
/** Provider update kind, for example `message` or `edited_message`. */
ProviderUpdateKind?: string;
/** Provider-native timestamp for the original message. */
ProviderMessageTimestamp?: number;
/** Provider-native timestamp for an edited message update. */
ProviderEditTimestamp?: number;
/** Provider label. */
Provider?: string;
/** Provider surface label. Prefer this over `Provider` when available. */
Surface?: string;
/** Platform bot username when command mentions should be normalized. */
BotUsername?: string;
WasMentioned?: boolean;
/** Effective channel-owned mention policy before any plugin-binding bypass. */
GroupRequireMention?: boolean;
/** True when this turn explicitly mentioned the current bot target. */
ExplicitlyMentionedBot?: boolean;
/** Provider-native explicit user mention ids present on this turn. */
MentionedUserIds?: string[];
/** Provider-native explicit user-group/subteam mention ids present on this turn. */
MentionedSubteamIds?: string[];
/** Provider-native implicit mention wake reasons present on this turn. */
ImplicitMentionKinds?: string[];
/** Provider-native source that caused the current mention decision. */
MentionSource?: MentionSource;
CommandAuthorized?: boolean;
CommandTurn?: CommandTurnContext;
CommandSource?: "text" | "native";
CommandInterpretationSuppressed?: boolean;
CommandTargetSessionKey?: string;
/**
* Internal flag: command handling prepared trailing prompt text for ACP dispatch.
* Used for `/new <prompt>` and `/reset <prompt>` on ACP-bound sessions.
*/
AcpDispatchTailAfterReset?: boolean;
/** Gateway client scopes when the message originates from the gateway. */
GatewayClientScopes?: string[];
/** Gateway client capabilities when the message originates from the gateway. */
GatewayClientCaps?: string[];
/** Run-scoped plugin tool bindings; never rendered into prompt text. */
GatewayRunToolBindings?: Readonly<Record<string, unknown>>;
/** Gateway device id allowed to review approvals initiated by this turn. */
ApprovalReviewerDeviceId?: string;
/** Thread identifier (Telegram topic id or Matrix thread event id). */
MessageThreadId?: string | number;
/** Provider-native thread target for reply delivery without making the session thread-scoped. */
TransportThreadId?: string | number;
/** Platform-native channel/conversation id (e.g. Slack DM channel "D…" id). */
NativeChannelId?: string;
/** Channel-owned local conversation image reference; never rendered into prompt text. */
ConversationAvatar?: string;
/** Channel-owned metadata exposed to plugin hook context, not prompt text. */
ChannelContext?: PluginHookChannelContext;
/** Provider-native chat/conversation id used by channel plugins that expose `chat_id`. */
ChatId?: string;
/** Stable provider-native direct-peer id when a DM room/user mapping must survive later writes. */
NativeDirectUserId?: string;
/** Telegram forum supergroup marker. */
IsForum?: boolean;
/** Human-readable Telegram forum topic name (cached from service messages). */
TopicName?: string;
/** Warning: DM has topics enabled but this message is not in a topic. */
TopicRequiredButMissing?: boolean;
/**
* Originating channel for reply routing.
* When set, replies should be routed back to this provider
* instead of using lastChannel from the session.
*/
OriginatingChannel?: OriginatingChannelType;
/**
* Originating destination for reply routing.
* The chat/channel/user ID where the reply should be sent.
*/
OriginatingTo?: string;
/**
* True when the current turn intentionally requested external delivery to
* OriginatingChannel/OriginatingTo, rather than inheriting stale session route metadata.
*/
ExplicitDeliverRoute?: boolean;
/**
* Internal proof that the channel ingress owner admitted this sender/event.
* Correlation interceptors must fail closed when this proof is absent.
*/
InboundAccessAuthorized?: boolean;
/** Internal marker that channel ingress authoritatively observed route-context facts. */
ConversationRouteContextObserved?: boolean;
/** Canonical peer used by route selection; delivery targets may use a different namespace. */
ConversationRoutePeerId?: string;
/**
* Internal flag for channels that emit message_received through a channel-specific
* privacy gate before entering the shared reply dispatcher.
*/
SuppressMessageReceivedHooks?: boolean;
/**
* Provider-specific parent conversation id for threaded contexts.
* For Discord threads, this is the parent channel id.
*/
ThreadParentId?: string;
/**
* Messages from hooks to be included in the response.
* Used for hook confirmation messages like "Session context saved to memory".
*/
HookMessages?: string[];
};
type FinalizedMsgContext = Omit<MsgContext, "CommandAuthorized"> & {
/**
* Always set by finalizeInboundContext().
* Default-deny: missing/undefined becomes false.
*/
CommandAuthorized: boolean;
/**
* Populated by finalizeInboundContext(); optional for public SDK
* compatibility with existing plugin-constructed finalized contexts.
*/
CommandTurn?: CommandTurnContext;
};
type RuntimeMediaContextKey = "MediaPath" | "MediaUrl" | "MediaType" | "MediaDir" | "MediaPaths" | "MediaUrls" | "MediaTypes" | "MediaWorkspaceDir" | "MediaTranscribedIndexes" | "MediaStaged";
/** Internal inbound context; legacy media fields exist only on the shipped SDK adapter. */
type RuntimeMsgContext = Omit<MsgContext, RuntimeMediaContextKey>;
type FinalizedRuntimeMsgContext = Omit<RuntimeMsgContext, "CommandAuthorized" | keyof CanonicalInboundText> & CanonicalInboundText & {
CommandAuthorized: boolean;
CommandTurn?: CommandTurnContext;
};
type NonTemplateContextKey = "ConversationAvatar";
type TemplateContext = Omit<RuntimeMsgContext, NonTemplateContextKey> & {
BodyStripped?: string;
SessionId?: string;
IsNewSession?: string;
/** Local path for the attachment currently being processed. */
AttachmentPath?: string;
/** Original URL/reference for the attachment currently being processed. */
AttachmentUrl?: string;
/** MIME content type for the attachment currently being processed. */
AttachmentContentType?: string;
/** Directory containing AttachmentPath. */
AttachmentDir?: string;
/** Stable zero-based source fact index for the attachment currently being processed. */
AttachmentIndex?: number;
/** @deprecated Use AttachmentPath. */
MediaPath?: string;
/** @deprecated Use AttachmentUrl. */
MediaUrl?: string;
/** @deprecated Use AttachmentContentType. */
MediaType?: string;
/** @deprecated Use AttachmentDir. */
MediaDir?: string;
};
//#endregion
//#region src/channels/plugins/message-action-names.d.ts
/**
* Deliberately closed, core-owned vocabulary so every transport can render every action.
* Plugins add names through a core PR; runtime registration is intentionally unsupported.
*/
declare const CHANNEL_MESSAGE_ACTION_NAMES: readonly ["send", "broadcast", "poll", "poll-vote", "react", "reactions", "read", "edit", "unsend", "reply", "sendWithEffect", "renameGroup", "setGroupIcon", "addParticipant", "removeParticipant", "leaveGroup", "sendAttachment", "delete", "pin", "unpin", "list-pins", "permissions", "thread-create", "thread-list", "thread-reply", "search", "sticker", "sticker-search", "member-info", "role-info", "emoji-list", "emoji-upload", "sticker-upload", "role-add", "role-remove", "channel-info", "channel-list", "channel-create", "conversation-open", "channel-edit", "channel-delete", "channel-move", "category-create", "category-edit", "category-delete", "topic-create", "topic-edit", "voice-status", "event-list", "event-create", "timeout", "kick", "ban", "set-profile", "set-presence", "download-file", "upload-file"];
/**
* Message action name union derived from the canonical action list.
*/
type ChannelMessageActionName$1 = (typeof CHANNEL_MESSAGE_ACTION_NAMES)[number];
//#endregion
//#region packages/gateway-protocol/src/client-info.d.ts
/** Canonical client ids accepted in gateway hello/connect payloads. */
declare const GATEWAY_CLIENT_IDS: {
readonly WEBCHAT_UI: "webchat-ui";
readonly CONTROL_UI: "openclaw-control-ui";
readonly BROWSER_COPILOT: "openclaw-browser-copilot";
readonly TUI: "openclaw-tui";
readonly WEBCHAT: "webchat";
readonly CLI: "cli";
readonly GATEWAY_CLIENT: "gateway-client";
readonly MACOS_APP: "openclaw-macos";
readonly LINUX_APP: "openclaw-linux";
readonly IOS_APP: "openclaw-ios";
readonly WATCHOS_APP: "openclaw-watchos";
readonly ANDROID_APP: "openclaw-android";
readonly NODE_HOST: "node-host";
readonly WORKER: "openclaw-worker";
readonly TEST: "test";
readonly FINGERPRINT: "fingerprint";
readonly PROBE: "openclaw-probe";
};
/** Stable gateway client ids used on the wire during hello/connect handshakes. */
type GatewayClientId = (typeof GATEWAY_CLIENT_IDS)[keyof typeof GATEWAY_CLIENT_IDS];
/** Compatibility alias for internal callers that still use "name" terminology. */
type GatewayClientName = GatewayClientId;
/** Coarse modes let policy group clients without matching every product id. */
declare const GATEWAY_CLIENT_MODES: {
readonly WEBCHAT: "webchat";
readonly CLI: "cli";
readonly UI: "ui";
readonly BACKEND: "backend";
readonly NODE: "node";
readonly WORKER: "worker";
readonly PROBE: "probe";
readonly TEST: "test";
};
/** Coarse client category used for gateway policy and diagnostics. */
type GatewayClientMode = (typeof GATEWAY_CLIENT_MODES)[keyof typeof GATEWAY_CLIENT_MODES];
//#endregion
//#region src/media/load-options.d.ts
/** Host callback used to read an already-authorized outbound media file. */
type OutboundMediaReadFile = (filePath: string) => Promise<Buffer>;
/** Host-provided file access used when a runtime can read outbound media from local disk. */
type OutboundMediaAccess = {
localRoots?: readonly string[];
readFile?: OutboundMediaReadFile;
/** Agent workspace directory for resolving relative media paths. */
workspaceDir?: string;
};
//#endregion
//#region src/channels/message-access/identifier-authentication.d.ts
/** Ordered strength of one identifier-authentication claim. */
type IdentifierAuthentication = "verified" | "asserted" | "unverified" | "mutable";
//#endregion
//#region src/infra/outbound/send-deps.d.ts
/**
* Dynamic bag of per-channel send functions, keyed by channel ID.
* Each outbound adapter resolves its own function from this record and
* falls back to a direct import when the key is absent.
*/
type OutboundSendDeps = {
[channelId: string]: unknown;
};
//#endregion
//#region src/polls.d.ts
type PollInput = {
question: string;
options: string[];
maxSelections?: number;
/**
* Poll duration in seconds.
* Channel-specific limits apply in each owning plugin.
*/
durationSeconds?: number;
/**
* Poll duration in hours.
* Used by channels that model duration in hours.
*/
durationHours?: number;
};
declare function resolvePollMaxSelections(optionCount: number, allowMultiselect: boolean | undefined): number;
//#endregion
//#region src/channels/message/types.d.ts
type OutboundReplyFacts = Readonly<{
source: "explicit";
replyToId: string;
}> | Readonly<{
source: "implicit";
replyToId: string;
mode: "first" | "all";
}>;
/** Capability names a channel must advertise before core can rely on durable final delivery. */
declare const durableFinalDeliveryCapabilities: readonly ["text", "media", "poll", "payload", "silent", "replyTo", "thread", "nativeQuote", "messageSendingHooks", "batch", "reconcileUnknownSend", "afterSendSuccess", "afterCommit"];
/** Durable final delivery capability key understood by message-channel adapters. */
type DurableFinalDeliveryCapability = (typeof durableFinalDeliveryCapabilities)[number];
/** Capability map used by adapters to declare which final-send guarantees they support. */
type DurableFinalDeliveryRequirementMap = Partial<Record<DurableFinalDeliveryCapability, boolean>>;
/** Raw platform result shape normalized into a message receipt. */
type MessageReceiptSourceResult = {
/** Provider-confirmed intentional omission before dispatch, never an ambiguous send. */
outcome?: "not_sent";
channel?: string;
messageId?: string;
target?: {
kind: "chat" | "channel" | "room" | "conversation";
id: string;
};
chatId?: string;
channelId?: string;
roomId?: string;
conversationId?: string;
toJid?: string;
pollId?: string;
timestamp?: number;
meta?: Record<string, unknown>;
};
/** Logical part kind for multi-part rendered messages. */
type MessageReceiptPartKind = "text" | "media" | "voice" | "poll" | "card" | "preview" | "unknown";
/** One platform message produced by a logical outbound send. */
type MessageReceiptPart = {
platformMessageId: string;
kind: MessageReceiptPartKind;
index: number;
threadId?: string;
replyToId?: string;
raw?: MessageReceiptSourceResult;
};
/** Normalized receipt for all platform messages that make up a logical send. */
type MessageReceipt = {
primaryPlatformMessageId?: string;
platformMessageIds: string[];
parts: MessageReceiptPart[];
threadId?: string;
replyToId?: string;
editToken?: string;
deleteToken?: string;
sentAt: number;
raw?: readonly MessageReceiptSourceResult[];
};
/** Render-plan item category used before adapter-specific send execution. */
type RenderedMessageBatchPlanKind = "text" | "media" | "voice" | "presentation" | "interactive" | "channelData" | "empty";
/** Render plan for a single reply payload after text/media/presentation splitting. */
type RenderedMessageBatchPlanItem = {
index: number;
kinds: readonly RenderedMessageBatchPlanKind[];
text?: string;
mediaUrls: readonly string[];
audioAsVoice?: boolean;
presentationBlockCount?: number;
hasInteractive?: boolean;
hasChannelData?: boolean;
};
/** Aggregate render plan for a batch of reply payloads. */
type RenderedMessageBatchPlan = {
payloadCount: number;
textCount: number;
mediaCount: number;
voiceCount: number;
presentationCount: number;
interactiveCount: number;
channelDataCount: number;
items: readonly RenderedMessageBatchPlanItem[];
};
/** Common text-send context shared by text, media, payload, and poll adapter calls. */
type ChannelMessageSendTextContext<TConfig = OpenClawConfig> = {
cfg: TConfig;
to: string;
text: string;
accountId?: string | null;
deps?: OutboundSendDeps;
replyToId?: string | null;
replyToIdSource?: "explicit" | "implicit";
replyToMode?: ReplyToMode;
threadId?: string | number | null;
silent?: boolean;
signal?: AbortSignal;
gatewayClientScopes?: readonly string[];
/** @internal Opaque durable intent id for exact provider-side send reconciliation. */
deliveryQueueId?: string;
/** @internal Stable platform-send index within one durable payload. */
deliveryPartIndex?: number;
/** @internal Exact platform-send count within one durable payload. */
deliveryPartCount?: number;
/** @internal Channel-valid id reserved before a correlated conversation turn is sent. */
preparedMessageId?: string;
/** @internal Refresh durable timing before recipient-visible or finalizing platform I/O. */
onPlatformSendDispatch?: () => Promise<void>;
/** @internal Synchronously fence custody after refresh and immediately before provider I/O. */
assertDirectAdapterHandoff?: () => void;
/** @internal Report each completed platform sub-send before another fallible step. */
onDeliveryResult?: (result: ChannelMessageSendResult) => Promise<void> | void;
};
/** Media send context with validated access hooks and media presentation hints. */
type ChannelMessageSendMediaContext<TConfig = OpenClawConfig> = ChannelMessageSendTextContext<TConfig> & {
mediaUrl: string;
mediaAccess?: OutboundMediaAccess;
mediaLocalRoots?: readonly string[];
mediaReadFile?: (filePath: string) => Promise<Buffer>;
audioAsVoice?: boolean;
gifPlayback?: boolean;
forceDocument?: boolean;
};
/** Rich reply payload send context used when adapters can consume structured payloads. */
type ChannelMessageSendPayloadContext<TConfig = OpenClawConfig> = ChannelMessageSendTextContext<TConfig> & {
payload: ReplyPayload;
mediaUrl?: string;
mediaAccess?: OutboundMediaAccess;
mediaLocalRoots?: readonly string[];
mediaReadFile?: (filePath: string) => Promise<Buffer>;
audioAsVoice?: boolean;
gifPlayback?: boolean;
forceDocument?: boolean;
};
/** Poll send context; thread ids stay string-like because poll APIs do not accept numeric ids. */
type ChannelMessageSendPollContext<TConfig = OpenClawConfig> = Omit<ChannelMessageSendTextContext<TConfig>, "text" | "threadId"> & {
poll: PollInput;
threadId?: string | null;
isAnonymous?: boolean;
};
/** Adapter send result normalized to a receipt plus optional legacy message id. */
type ChannelMessageSendResult = {
outcome?: MessageReceiptSourceResult["outcome"];
receipt: MessageReceipt;
messageId?: string;
target?: MessageReceiptSourceResult["target"];
};
/** Concrete send shapes an adapter can reconcile after an unknown platform outcome. */
declare const unknownSendReconciliationKinds: readonly ["text", "media", "payload", "poll", "batch"];
type UnknownSendReconciliationKind = (typeof unknownSendReconciliationKinds)[number];
/** Send-attempt context tagged with the adapter method core is about to call. */
type ChannelMessageSendAttemptContext<TConfig = OpenClawConfig> = (ChannelMessageSendTextContext<TConfig> & {
kind: "text";
}) | (ChannelMessageSendMediaContext<TConfig> & {
kind: "media";
}) | (ChannelMessageSendPayloadContext<TConfig> & {
kind: "payload";
}) | (ChannelMessageSendPollContext<TConfig> & {
kind: "poll";
});
/** Lifecycle context emitted after an adapter send succeeds but before commit finishes. */
type ChannelMessageSendSuccessContext<TConfig = OpenClawConfig, TSendResult extends ChannelMessageSendResult = ChannelMessageSendResult> = ChannelMessageSendAttemptContext<TConfig> & {
result: TSendResult;
attemptToken?: unknown;
};
/** Lifecycle context emitted after an adapter send throws or rejects. */
type ChannelMessageSendFailureContext<TConfig = OpenClawConfig> = ChannelMessageSendAttemptContext<TConfig> & {
error: unknown;
attemptToken?: unknown;
};
/** Lifecycle context emitted when a successful send is being durably committed. */
type ChannelMessageSendCommitContext<TConfig = OpenClawConfig, TSendResult extends ChannelMessageSendResult = ChannelMessageSendResult> = ChannelMessageSendSuccessContext<TConfig, TSendResult>;
/** Durable queue context used to reconcile a send whose platform state is unknown. */
type ChannelMessageUnknownSendContext<TConfig = OpenClawConfig> = {
cfg: TConfig;
queueId: string;
channel: string;
to: string;
accountId?: string | null;
enqueuedAt: number;
retryCount: number;
platformSendStartedAt?: number;
/** Canonical reply target persisted after hooks and before platform I/O. */
effectiveReplyToId?: string | null;
payloads: readonly ReplyPayload[];
renderedBatchPlan?: RenderedMessageBatchPlan;
replyToId?: string | null;
replyToMode?: ReplyToMode;
threadId?: string | number | null;
silent?: boolean;
};
/** Adapter verdict for whether an unknown queued send reached the platform. */
type ChannelMessageUnknownSendReconciliationResult = {
status: "sent";
receipt: MessageReceipt;
messageId?: string;
} | {
status: "not_sent";
} | {
status: "unresolved";
error?: string;
retryable?: boolean;
};
/** Provider decision made before core persists or replays a deferred delivery. */
type ChannelMessageDeferredDeliveryAdmissionResult = {
status: "allowed";
} | {
status: "permanent_rejection";
reason: string;
};
/** Minimal context available at deferred-delivery admission boundaries. */
type ChannelMessageDeferredDeliveryAdmissionContext<TConfig = OpenClawConfig> = {
cfg: TConfig;
channel: string;
to: string;
accountId?: string | null;
phase: "live" | "recovery";
};
/** Optional hooks around adapter send attempts, platform success/failure, and commit. */
type ChannelMessageSendLifecycleAdapter<TConfig = OpenClawConfig, TSendResult extends ChannelMessageSendResult = ChannelMessageSendResult> = {
beforeSendAttempt?: (ctx: ChannelMessageSendAttemptContext<TConfig>) => unknown;
afterSendSuccess?: (ctx: ChannelMessageSendSuccessContext<TConfig, TSendResult>) => Promise<void> | void;
afterSendFailure?: (ctx: ChannelMessageSendFailureContext<TConfig>) => Promise<void> | void;
afterCommit?: (ctx: ChannelMessageSendCommitContext<TConfig, TSendResult>) => Promise<void> | void;
};
/** Adapter methods a message channel can implement for outbound text/media/payload/poll sends. */
type ChannelMessageSendAdapter<TConfig = OpenClawConfig, TSendResult extends ChannelMessageSendResult = ChannelMessageSendResult> = {
text?: (ctx: ChannelMessageSendTextContext<TConfig>) => Promise<TSendResult>;
media?: (ctx: ChannelMessageSendMediaContext<TConfig>) => Promise<TSendResult>;
payload?: (ctx: ChannelMessageSendPayloadContext<TConfig>) => Promise<TSendResult>;
poll?: (ctx: ChannelMessageSendPollContext<TConfig>) => Promise<TSendResult>;
lifecycle?: ChannelMessageSendLifecycleAdapter<TConfig, TSendResult>;
};
/** Durable final-delivery extension for queue reconciliation and capability declaration. */
type ChannelMessageDurableFinalAdapter = {
capabilities?: DurableFinalDeliveryRequirementMap;
/** Opt into provider reconciliation for ordinary single-payload queued sends. */
automaticUnknownSendReconciliation?: boolean;
/**
* Synchronous provider admission before a durable intent is created or replayed.
* Providers must not perform I/O from this hook.
*/
admitDeferredDelivery?: (ctx: ChannelMessageDeferredDeliveryAdmissionContext) => ChannelMessageDeferredDeliveryAdmissionResult;
/** Send shapes for which reconciliation can prove the complete durable intent. */
reconcileUnknownSendKinds?: Partial<Record<UnknownSendReconciliationKind, boolean>>;
reconcileUnknownSend?: (ctx: ChannelMessageUnknownSendContext) => Promise<ChannelMessageUnknownSendReconciliationResult | null> | ChannelMessageUnknownSendReconciliationResult | null;
/** Cleanup after core authoritatively retires an ambiguous send as failed. */
afterUnknownSendTerminal?: (ctx: ChannelMessageUnknownSendContext) => Promise<void> | void;
};
/** Live-message feature key declared by adapters that support preview or streaming behavior. */
type ChannelMessageLiveCapability = "draftPreview" | "previewFinalization" | "progressUpdates" | "nativeStreaming" | "quietFinalization";
/** Capability keys for turning a preview into a final platform message. */
declare const livePreviewFinalizerCapabilities: readonly ["finalEdit", "normalFallback", "discardPending", "previewReceipt", "retainOnAmbiguousFailure"];
/** Finalizer capability key understood by live-message adapters. */
type LivePreviewFinalizerCapability = (typeof livePreviewFinalizerCapabilities)[number];
/** Capability map for preview finalization behavior. */
type LivePreviewFinalizerCapabilityMap = Partial<Record<LivePreviewFinalizerCapability, boolean>>;
/** Adapter shape for finalizing live previews. */
type ChannelMessageLiveFinalizerAdapterShape = {
capabilities?: LivePreviewFinalizerCapabilityMap;
};
/** Adapter shape for live preview and streaming message features. */
type ChannelMessageLiveAdapterShape = {
capabilities?: Partial<Record<ChannelMessageLiveCapability, boolean>>;
finalizer?: ChannelMessageLiveFinalizerAdapterShape;
};
/** Receive acknowledgement timing policy for durable inbound message records. */
type ChannelMessageReceiveAckPolicy = "after_receive_record" | "after_agent_dispatch" | "after_durable_send" | "manual";
/** Adapter receive shape for default and supported inbound acknowledgement policies. */
type ChannelMessageReceiveAdapterShape = {
defaultAckPolicy?: ChannelMessageReceiveAckPolicy;
supportedAckPolicies?: readonly ChannelMessageReceiveAckPolicy[];
};
/** Full message adapter shape composed from send, durable-final, live, and receive facets. */
type ChannelMessageAdapterShape<TConfig = OpenClawConfig, TSendResult extends ChannelMessageSendResult = ChannelMessageSendResult> = {
id?: string;
durableFinal?: ChannelMessageDurableFinalAdapter;
send?: ChannelMessageSendAdapter<TConfig, TSendResult>;
live?: ChannelMessageLiveAdapterShape;
receive?: ChannelMessageReceiveAdapterShape;
};
//#endregion
//#region src/channels/plugins/conversation-read-origin.d.ts
/**
* Server-owned origin for one tool or message-action invocation.
*
* Missing and unknown values must remain delegated; callers must never derive
* this from model arguments, provider parameters, config, or persisted state.
*/
type ConversationReadInvocationOrigin = "delegated" | "direct-operator";
//#endregion
//#region src/channels/plugins/message-capabilities.d.ts
/**
* Channel message capabilities advertised through plugin discovery hooks.
*/
declare const CHANNEL_MESSAGE_CAPABILITIES: readonly ["presentation", "delivery-pin"];
/**
* Message capability union derived from the canonical capability list.
*/
type ChannelMessageCapability = (typeof CHANNEL_MESSAGE_CAPABILITIES)[number];
//#endregion
//#region src/channels/plugins/legacy-state-migration.types.d.ts
type ChannelLegacyStateMigrationPlan = {
kind: "copy" | "move";
label: string;
sourcePath: string;
targetPath: string;
} | {
kind: "plugin-state-import";
label: string;
sourcePath: string;
targetPath: string;
pluginId: string;
namespace: string;
maxEntries: number;
defaultTtlMs?: number;
scopeKey: string;
stateDir?: string;
cleanupSource?: "rename" | "remove";
cleanupWhenEmpty?: boolean;
/** Deletes a non-file legacy source (e.g. plugin-state rows) once all entries are covered. */
removeSource?: () => void | Promise<void>;
preview?: string;
shouldReplaceExistingEntry?: (params: {
key: string;
existingValue: unknown;
incomingValue: unknown;
}) => boolean | Promise<boolean>;
/**
* `timestamp` (epoch ms) and `ttlMs` order entries newest-first when capacity forces a
* partial import; `timestamp` is also persisted as the migrated row's creation time so
* cap eviction keeps treating imported rows as old as their legacy source.
*/
readEntries: () => Array<{
key: string;
value: unknown;
ttlMs?: number;
timestamp?: number;
}> | Promise<Array<{
key: string;
value: unknown;
ttlMs?: number;
timestamp?: number;
}>>;
};
//#endregion
//#region src/channels/plugins/types.core.d.ts
type ChannelExposure = {
configured?: boolean;
setup?: boolean;
docs?: boolean;
};
type ChannelOutboundTargetMode = "explicit" | "implicit" | "heartbeat";
/** Agent tool registered by a channel plugin. */
type ChannelAgentTool = AgentTool;
/** Lazy agent-tool factory used when tool availability depends on config. */
type ChannelAgentToolFactory = (params: {
cfg?: OpenClawConfig;
}) => ChannelAgentTool[];
/**
* Discovery-time inputs passed to channel action adapters when the core is
* asking what an agent should be allowed to see. This is intentionally
* smaller than execution context: it carries routing/account scope, but no
* tool params or runtime handles.
*/
type ChannelMessageActionDiscoveryContext = {
cfg: OpenClawConfig;
chatType?: ChatType | null;
currentChannelId?: string | null;
currentChannelProvider?: string | null;
currentThreadTs?: string | null;
currentMessageId?: string | number | null;
accountId?: string | null;
sessionKey?: string | null;
sessionId?: string | null;
agentId?: string | null;
requesterSenderId?: string | null;
senderIsOwner?: boolean;
};
/**
* Plugin-owned schema fragments for the shared `message` tool.
* `current-channel` means expose the fields only when that provider is the
* active runtime channel. `all-configured` keeps the fields visible even while
* another configured channel is active, which is useful for cross-channel
* sends from cron or isolated agents.
*/
type ChannelMessageToolSchemaContribution = {
properties: Record<string, TSchema>;
/**
* Actions whose validation depends on this schema fragment. Cross-channel
* discovery can hide only these actions when the fragment is current-channel
* scoped. Omit to keep the legacy conservative behavior.
*/
actions?: readonly ChannelMessageActionName[] | null;
visibility?: "current-channel" | "all-configured";
};
type ChannelMessageToolMediaSourceParams = readonly string[] | Partial<Record<ChannelMessageActionName, readonly string[]>>;
type ChannelMessageToolDiscovery = {
actions?: readonly ChannelMessageActionName[] | null;
capabilities?: readonly ChannelMessageCapability[] | null;
schema?: ChannelMessageToolSchemaContribution | ChannelMessageToolSchemaContribution[] | null;
/**
* Plugin-owned message-tool params that carry media sources.
* Core uses this to derive sandbox path normalization and host media-access
* hints without hardcoding plugin-specific param names. Prefer scoping keys
* by action so unrelated actions do not inherit another action's media args.
*/
mediaSourceParams?: ChannelMessageToolMediaSourceParams | null;
};
type ChannelStatusIssue = {
channel: ChannelId;
accountId: string;
kind: "intent" | "permissions" | "config" | "auth" | "runtime";
message: string;
fix?: string;
};
type ChannelAccountState = "linked" | "not linked" | "configured" | "not configured" | "enabled" | "disabled";
type ChannelHeartbeatDeps = {
webAuthExists?: () => Promise<boolean>;
hasActiveWebListener?: (accountId?: string) => boolean;
};
/** User-facing metadata used in docs, pickers, and setup surfaces. */
type ChannelMeta = {
id: ChannelId;
label: string;
selectionLabel: string;
docsPath: string;
docsLabel?: string;
blurb: string;
order?: number;
aliases?: readonly string[];
selectionDocsPrefix?: string;
selectionDocsOmitLabel?: boolean;
selectionExtras?: readonly string[];
detailLabel?: string;
systemImage?: string;
markdownCapable?: boolean;
exposure?: ChannelExposure;
quickstartAllowFrom?: boolean;
forceAccountBinding?: boolean;
preferSessionLookupForAnnounceTarget?: boolean;
preferOver?: readonly string[];
};
/** Snapshot row returned by channel status and lifecycle surfaces. */
type ChannelAccountSnapshot = {
accountId: string;
name?: string;
enabled?: boolean;
configured?: boolean;
statusState?: string;
linked?: boolean;
running?: boolean;
connected?: boolean;
restartPending?: boolean;
reconnectAttempts?: number;
lastConnectedAt?: number | null;
lastDisconnect?: string | {
at: number;
status?: number;
error?: string;
loggedOut?: boolean;
} | null;
lastMessageAt?: number | null;
lastEventAt?: number | null;
lastTransportActivityAt?: number | null;
stateReason?: string;
lastError?: string | null;
/**
* Legacy channel-authored health label; channel plugins should publish `lifecycle` instead.
* Core-derived policy writes remain supported. There is no removal date; removal awaits
* external plugin adoption.
*/
healthState?: string;
/**
* Recorded account lifecycle, independent of inferred transport health.
* Optional so channels that never publish lifecycle remain unaffected.
*/
lifecycle?: "starting" | "ready" | "recovering" | "blocked" | "stopped";
/**
* Inbound admission, which is a different failure domain from `connected`.
* Optional-`true` on purpose: there is no `false` to mistake for "unknown",
* so the 20+ channels that never report ingress at all stay unaffected.
*/
ingressUnavailable?: true;
terminalDisconnect?: boolean;
lastStartAt?: number | null;
lastStopAt?: number | null;
lastInboundAt?: number | null;
lastOutboundAt?: number | null;
busy?: boolean;
activeRuns?: number;
lastRunActivityAt?: number | null;
activeRunStartedAt?: number | null;
mode?: string;
dmPolicy?: string;
allowFrom?: string[];
tokenSource?: string;
botTokenSource?: string;
appTokenSource?: string;
userTokenSource?: string;
signingSecretSource?: string;
tokenStatus?: string;
botTokenStatus?: string;
appTokenStatus?: string;
signingSecretStatus?: string;
userTokenStatus?: string;
apiCredentialStatus?: "available" | "configured_unavailable" | "missing";
identity?: string;
credentialSource?: string;
secretSource?: string;
audienceType?: string;
audience?: string;
webhookPath?: string;
webhookUrl?: string;
baseUrl?: string;
allowUnmentionedGroups?: boolean;
cliPath?: string | null;
dbPath?: string | null;
port?: number | null;
probe?: unknown;
lastProbeAt?: number | null;
audit?: unknown;
application?: unknown;
bot?: unknown;
publicKey?: string | null;
profile?: unknown;
channelAccessToken?: string;
channelSecret?: string;
};
type ChannelLogSink = {
info: (msg: string) => void;
warn: (msg: string) => void;
error: (msg: string) => void;
debug?: (msg: string) => void;
};
type ChannelGroupContext = {
cfg: OpenClawConfig;
groupId?: string | null;
/** Human label for channel-like group conversations (e.g. #general). */
groupChannel?: string | null;
groupSpace?: string | null;
accountId?: string | null;
/** Trusted host instruction to ignore toolsBySender for non-ingress work. */
senderPolicyMode?: "always" | "never";
senderId?: string | null;
senderName?: string | null;
senderUsername?: string | null;
senderE164?: string | null;
};
/** TTS voice delivery behavior advertised by a channel plugin. */
/**
* Container tokens (file-extension shape, no leading dot) that the host
* TTS pipeline knows how to pre-transcode synthesized audio into.
* Channels that benefit from a specific container — currently only
* iMessage, which needs Apple's native voice-memo CAF descriptor — name
* one here. Adding a new entry requires extending the host transcoder
* recipe table in lockstep so a typed declaration cannot silently no-op.
*/
type PreferredAudioFileFormat = "caf";
type ChannelTtsVoiceDeliveryCapabilities = {
synthesisTarget: "audio-file" | "voice-note";
transcodesAudio?: boolean;
audioFileFormats?: readonly string[];
/** Voice notes can carry the final reply text as a visible caption. */
captionedFinalText?: boolean;
/**
* Optional preferred audio container the channel wants for voice-memo
* delivery. When set and the host can transcode (e.g. `afconvert` on
* macOS), the TTS pipeline pre-encodes synthesized audio to this format
* before handing it to the channel. Useful for channels (such as
* iMessage) whose downstream attempts its own container conversion
* that races against the upload write and fails.
*/
preferAudioFileFormat?: PreferredAudioFileFormat;
};
/** Static capability flags advertised by a channel plugin. */
type ChannelCapabilities = {
chatTypes: Array<ChatType | "thread">;
polls?: boolean;
reactions?: boolean;
edit?: boolean;
unsend?: boolean;
reply?: boolean;
effects?: boolean;
groupManagement?: boolean;
threads?: boolean;
media?: boolean;
tts?: {
voice?: ChannelTtsVoiceDeliveryCapabilities;
};
nativeCommands?: boolean;
blockStreaming?: boolean;
};
type ChannelSecurityDmPolicy = {
policy: string;
allowFrom?: Array<string | number> | null;
policyPath?: string;
allowFromPath: string;
approveHint: string;
normalizeEntry?: (raw: string) => string;
classifyEntryAuthentication?: (raw: string) => IdentifierAuthentication | undefined;
};
type ChannelSecurityContext<ResolvedAccount = unknown> = {
cfg: OpenClawConfig;
accountId?: string | null;
account: ResolvedAccount;
};
type ChannelMentionAdapter = {
stripRegexes?: (params: {
ctx: MsgContext;
cfg: OpenClawConfig | undefined;
agentId?: string;
}) => RegExp[];
stripPatterns?: (params: {
ctx: MsgContext;
cfg: OpenClawConfig | undefined;
agentId?: string;
}) => string[];
stripMentions?: (params: {
text: string;
ctx: MsgContext;
cfg: OpenClawConfig | undefined;
agentId?: string;
}) => string;
};
type ChannelStreamingAdapter = {
blockStreamingCoalesceDefaults?: {
minChars: number;
idleMs: number;
};
};
type ChannelCrossContextPresentationFactory = (params: {
originLabel: string;
message: string;
cfg: OpenClawConfig;
accountId?: string | null;
}) => MessagePresentation;
type ChannelReplyTransport = {
replyToId?: string | null;
threadId?: string | number | null;
};
type ChannelFocusedBindingContext = {
conversationId: string;
parentConversationId?: string;
placement: "current" | "child";
labelNoun: string;
};
type ChannelOutboundSessionRoute = {
sessionKey: string;
baseSessionKey: string;
/** Route authority for explicit recipient session selection. */
recipientSessionExact?: boolean | "direct-alias" | "delivery-identity";
peer: {
kind: ChatType;
id: string;
};
chatType: "direct" | "group" | "channel";
from: string;
to: string;
threadId?: string | number;
};
type ChannelThreadingAdapter = {
/**
* Where the transport keeps thread identity.
* "address" (default): the thread is part of the routing address (own channel id, topic id
* in the target tuple), fully known before send.
* "message": thread identity lives on a message (e.g. Slack thread_ts) — replying to a
* message enters its thread, and routes can discover a session-scoping thread only after
* target lookup.
*/
threadAddressing?: "address" | "message";
matchesToolContextTarget?: (params: {
target: string;
toolContext: ChannelThreadingToolContext;
}) => boolean;
resolveReplyToMode?: (params: {
cfg: OpenClawConfig;
accountId?: string | null;
chatType?: string | null;
}) => "off" | "first" | "all" | "batched";
/**
* When replyToMode is "off", allow explicit reply tags/directives to keep replyToId.
*
* Default in shared reply flow: true for known providers; per-channel opt-out supported.
*/
allowExplicitReplyTagsWhenOff?: boolean;
/**
* @deprecated Use allowExplicitReplyTagsWhenOff.
*
* Deprecated alias for allowExplicitReplyTagsWhenOff.
* Kept for compatibility with older plugin surfaces.
*/
allowTagsWhenOff?: boolean;
buildToolContext?: (params: {
cfg: OpenClawConfig;
accountId?: string | null;
context: ChannelThreadingContext;
hasRepliedRef?: {
value: boolean;
};
}) => ChannelThreadingToolContext | undefined;
resolveAutoThreadId?: (params: {
cfg: OpenClawConfig;
accountId?: string | null;
to: string;
toolContext?: ChannelThreadingToolContext;
replyToId?: string | null;
}) => string | undefined;
resolveCurrentChannelId?: (params: {
to: string;
threadId?: string | number | null;
}) => string | undefined;
resolveReplyTransport?: (params: {
cfg: OpenClawConfig;
accountId?: string | null;
threadId?: string | number | null;
replyToId?: string | null;
/** True when replyToId came from an explicit payload target or reply tag. */
replyToIsExplicit?: boolean;
/** Existing payload intent to reply to the current conversation, not an arbitrary target. */
replyToCurrent?: boolean;
replyDelivery?: ReplyDeliveryContext;
}) => ChannelReplyTransport | null;
resolveFocusedBinding?: (params: {
cfg: OpenClawConfig;
accountId?: string | null;
context: ChannelThreadingContext;
}) => ChannelFocusedBindingContext | null;
};
type ChannelThreadingContext = {
Channel?: string;
From?: string;
To?: string;
ChatType?: string;
CurrentMessageId?: string | number;
/** Effective channel reply mode prepared for this turn. */
ReplyToMode?: MsgContext["ReplyToMode"];
ReplyToId?: string;
ReplyToIdFull?: string;
ThreadLabel?: string;
MessageThreadId?: string | number;
TransportThreadId?: string | number;
/** Platform-native channel/conversation id (e.g. Slack DM channel "D…" id). */
NativeChannelId?: string;
};
type ChannelThreadingToolContext = {
currentChannelId?: string;
/** Trusted normalized conversation kind for the active inbound turn. */
currentChatType?: ChatType;
/** Routable messaging target when it differs from the platform-native channel id. */
currentMessagingTarget?: string;
currentGraphChannelId?: string;
currentChannelProvider?: ChannelId;
currentThreadTs?: string;
currentMessageId?: string | number;
replyToMode?: "off" | "first" | "all" | "batched";
hasRepliedRef?: {
value: boolean;
};
/** True when posting at the parent conversation root would leak a thread-originated reply. */
sameChannelThreadRequired?: boolean;
/**
* When true, skip cross-context decoration (e.g., "[from X]" prefix).
* Use this for direct tool invocations where the agent is composing a new message,
* not forwarding/relaying a message from another conversation.
*/
skipCrossContextDecoration?: boolean;
};
/** Channel-owned messaging helpers for target parsing, routing, and payload shaping. */
type ChannelMessagingAdapter = {
/**
* Provider prefixes accepted in explicit targets, including aliases not used
* as channel-selection aliases. Core uses these to reject cross-channel
* targets before plugin-specific normalization.
*/
targetPrefixes?: readonly string[];
/** Re-resolve the current owner when channel behavior exceeds generic bindings. */
resolveConversationRouteOwner?: (params: {
cfg: OpenClawConfig;
accountId: string;
conversation: {
kind: "direct" | "group" | "channel";
peerId: string;
/** Canonical delivery target when it differs from the routing peer. */
target?: string;
threadId?: string;
nativeChannelId?: string;
context?: {
parentPeerId?: string;
guildId?: string;
teamId?: string;
memberRoleIds?: string[];
};
};
}) => {
kind: "agent";
agentId: string;
} | {
kind: "plugin";
pluginId: string;
fallbackAgentId: string;
} | {
kind: "unavailable";
} | null | undefined;
/** DM targets rebuilt from session keys require an explicit `user:` kind prefix. */
directTargetStyle?: "user-prefixed";
/** Equality rule for ids carried by prefixed outbound targets. */
targetIdComparison?: "case-sensitive" | "lowercase";
/** Bare numeric conversation/topic shorthand is valid for this channel. */
numericTopicShorthand?: true;
normalizeTarget?: (raw: string) => string | undefined;
defaultMarkdownTableMode?: MarkdownTableMode;
normalizeExplicitSessionKey?: (params: {
sessionKey: string;
ctx: MsgContext;
}) => string | undefined;
deriveLegacySessionChatType?: (sessionKey: string) => "direct" | "group" | "channel" | undefined;
isLegacyGroupSessionKey?: (key: string) => boolean;
canonicalizeLegacySessionKey?: (params: {
key: string;
agentId: string;
}) => string | null | undefined;
resolveLegacyGroupSessionKey?: (ctx: MsgContext) => {
key: string;
channel: string;
id: string;
chatType: "group" | "channel";
} | null;
resolveInboundAttachmentRoots?: (params: {
cfg: OpenClawConfig;
accountId?: string | null;
}) => string[];
resolveRemoteInboundAttachmentRoots?: (params: {
cfg: OpenClawConfig;
accountId?: string | null;
}) => string[];
/**
* Bundled plugins that need inbound conversation resolution before runtime
* bootstrap can mirror it through a top-level `thread-binding-api.ts` surface.
*/
resolveInboundConversation?: (params: {
from?: string;
to?: string;
conversationId?: string;
threadId?: string | number;
threadParentId?: string | number;
isGroup: boolean;
}) => {
conversationId?: string;
parentConversationId?: string;
} | null;
resolveDeliveryTarget?: (params: {
conversationId: string;
parentConversationId?: string;
}) => {
to?: string;
threadId?: string;
} | null;
/**
* Canonical plugin-owned session conversation grammar.
* Use this when the provider encodes thread or scoped-conversation semantics
* inside `rawId` (for example Telegram topics or Feishu sender scopes).
* Return `baseConversationId` and `parentConversationCandidates` here when
* you can so parsing and inheritance stay in one place.
* `parentConversationCandidates`, when present, should be ordered from the
* narrowest parent to the broadest/base conversation.
* Bundled plugins that need the same grammar before runtime bootstrap can
* mirror this contract through a top-level `session-key-api.ts` surface.
*/
resolveSessionConversation?: (params: {
kind: "group" | "channel";
rawId: string;
}) => {
id: string;
threadId?: string | null;
baseConversationId?: string | null;
parentConversationCandidates?: string[];
} | null;
/**
* @deprecated Return parentConversationCandidates from resolveSessionConversation.
*
* Legacy compatibility hook for parent fallbacks when a plugin does not need
* to customize `id` or `threadId`. Core only uses this when
* `resolveSessionConversation(...)` does not return
* `parentConversationCandidates`.
*/
resolveParentConversationCandidates?: (params: {
kind: "group" | "channel";
rawId: string;
}) => string[] | null;
resolveSessionTarget?: (params: {
kind: "group" | "channel";
id: string;
threadId?: string | null;
}) => string | undefined;
/**
* Lightweight chat-type inference used before directory lookup so plugins can
* steer peer-vs-group resolution without reimplementing host search flow.
*/
inferTargetChatType?: (params: {
to: string;
}) => ChatType | undefined;
/**
* Preserve the session thread/topic id for heartbeat replies when that thread
* is part of the destination identity, not a transient reply thread.
*/
preserveHeartbeatThreadIdForGroupRoute?: boolean;
buildCrossContextPresentation?: ChannelCrossContextPresentationFactory;
transformReplyPayload?: (params: {
payload: ReplyPayload;
cfg: OpenClawConfig;
accountId?: string | null;
}) => ReplyPayload | null;
hasStructuredReplyPayload?: (params: {
payload: ReplyPayload;
}) => boolean;
targetResolver?: {
looksLikeId?: (raw: string, normalized?: string) => boolean;
hint?: string;
/** Bare words that are command/session references for this channel, not literal destinations. */
reservedLiterals?: readonly string[];
/**
* Plugin-owned fallback for explicit/native targets or post-directory-miss
* resolution. This should complement directory lookup, not duplicate it.
*/
resolveTarget?: (params: {
cfg: OpenClawConfig;
accountId?: string | null;
input: string;
normalized: string;
preferredKind?: ChannelDirectoryEntryKind | "channel";
}) => Promise<{
to: string;
kind: ChannelDirectoryEntryKind | "channel";
display?: string;
source?: "normalized" | "directory";
} | null>;
};
formatTargetDisplay?: (params: {
target: string;
display?: string;
kind?: ChannelDirectoryEntryKind;
}) => string;
/**
* Provider-specific session-route builder used after target resolution.
* Keep session-key orchestration in core and channel-native routing rules here.
* Set `recipientSessionExact` to true only when the target maps unambiguously
* to the same canonical session that inbound delivery uses. `direct-alias`
* may be used when only the direct chat kind is authoritative.
* `delivery-identity` requires a stable outbound-only recipient identity and
* a provider-keyed session that stays isolated from the agent main session.
*/
resolveOutboundSessionRoute?: (params: {
cfg: OpenClawConfig;
agentId: string;
accountId?: string | null;
target: string;
currentSessionKey?: string;
resolvedTarget?: {
to: string;
kind: ChannelDirectoryEntryKind | "channel";
display?: string;
source: "normalized" | "directory";
};
replyToId?: string | null;
threadId?: string | number | null;
}) => ChannelOutboundSessionRoute | Promise<ChannelOutboundSessionRoute | null> | null;
};
type ChannelAgentPromptAdapter = {
messageToolHints?: (params: {
cfg: OpenClawConfig;
accountId?: string | null;
}) => string[];
messageToolCapabilities?: (params: {
cfg: OpenClawConfig;
accountId?: string | null;
}) => string[] | undefined;
inboundFormattingHints?: (params: {
cfg: OpenClawConfig;
accountId?: string | null;
}) => {
text_markup: string;
rules: string[];
} | undefined;
reactionGuidance?: (params: {
cfg: OpenClawConfig;
accountId?: string | null;
}) => {
level: "minimal" | "extensive";
channelLabel?: string;
} | undefined;
};
type ChannelDirectoryEntryKind = "user" | "group" | "channel";
type ChannelDirectoryEntry = {
kind: ChannelDirectoryEntryKind;
id: string;
name?: string;
handle?: string;
avatarUrl?: string;
rank?: number;
raw?: unknown;
};
type ChannelMessageActionName = ChannelMessageActionName$1;
/** Execution context passed to channel-owned actions on the shared `message` tool. */
type ChannelMessageActionContext = {
channel: ChannelId;
action: ChannelMessageActionName;
cfg: OpenClawConfig;
params: Record<string, unknown>;
reply?: OutboundReplyFacts;
mediaAccess?: OutboundMediaAccess;
mediaLocalRoots?: readonly string[];
mediaReadFile?: (filePath: string) => Promise<Buffer>;
accountId?: string | null;
/** Trusted originating account id paired with requesterSenderId. */
requesterAccountId?: string | null;
/**
* Trusted sender id from inbound context. This is server-injected and must
* never be sourced from tool/model-controlled params.
*/
requesterSenderId?: string | null;
/** Trusted owner identity bit from command/channel-action auth. */
senderIsOwner?: boolean;
/**
* Server-owned origin for this operation. Missing values are delegated.
* Plugins must use it only for conversation-read visibility policy.
*/
conversationReadOrigin?: ConversationReadInvocationOrigin;
sessionKey?: string | null;
sessionId?: string | null;
inboundEventKind?: InboundEventKind;
agentId?: string | null;
gateway?: {
url?: string;
token?: string;
timeoutMs?: number;
clientName: GatewayClientName;
clientDisplayName?: string;
mode: GatewayClientMode;
};
toolContext?: ChannelThreadingToolContext;
dryRun?: boolean;
gatewayClientScopes?: readonly string[];
/**
* Server-owned fact: this caller receives proven-not-sent failures and resends
* them. Plugins forward it into durable sends so recovery does not replay too.
*/
deliveryRetryOwner?: "caller";
};
type ChannelToolSend = {
to: string;
accountId?: string | null;
threadId?: string | null;
/** True when the native provider send may inherit the active conversation thread. */
threadImplicit?: boolean;
threadSuppressed?: boolean;
};
type ChannelMessagePreparedSendPayloadContext = {
ctx: ChannelMessageActionContext;
to: string;
payload: ReplyPayload;
replyToId?: string | null;
/** Preserve caller intent when plugins translate reply ids into durable payloads. */
replyToIdSource?: "explicit" | "implicit";
threadId?: string | number | null;
};
/** Channel-owned action surface for the shared `message` tool. */
type ChannelMessageActionAdapter = {
/**
* Unified discovery surface for the shared `message` tool.
* This returns the scoped actions,
* capabilities, schema fragments, and any plugin-owned media-source params
* together so they cannot drift.
*/
describeMessageTool: (params: ChannelMessageActionDiscoveryContext) => ChannelMessageToolDiscovery | null | undefined;
/** Delegate conversation-read authorization to this adapter for bundled registrations only. */
providerOwnedReadGates?: true | readonly ChannelMessageActionName[];
supportsAction?: (params: {
action: ChannelMessageActionName;
}) => boolean;
resolveExecutionMode?: (params: {
action: ChannelMessageActionName;
}) => "local" | "gateway";
resolveCliActionRequest?: (params: {
action: ChannelMessageActionName;
args: Record<string, unknown>;
}) => {
action: ChannelMessageActionName;
args: Record<string, unknown>;
};
messageActionTargetAliases?: Partial<Record<ChannelMessageActionName, {
aliases: string[];
/** Alias fields that identify the destination conversation, not an existing message. */
deliveryTargetAliases?: string[];
/** Convert typed owner fields such as chatId into the canonical shared target shape. */
resolveDeliveryTarget?: (params: {
args: Record<string, unknown>;
}) => string | undefined;
/**
* Prove that provider-native aliases name the trusted current conversation.
* Core consults this only for host-owned bundled registrations.
*/
matchesCurrentConversation?: (params: {
args: Record<string, unknown>;
accountId: string;
toolContext: ChannelThreadingToolContext;
}) => boolean;
}>>;
requiresTrustedRequesterSender?: (params: {
action: ChannelMessageActionName;
toolContext?: ChannelThreadingToolContext;
}) => boolean;
/** Return true when a provider-native tool invocation has a visible or destructive side effect. */
isToolDeliveryAction?: (params: {
args: Record<string, unknown>;
}) => boolean;
extractToolSend?: (params: {
args: Record<string, unknown>;
}) => ChannelToolSend | null;
/** Recover the actual resolved send route from a successful action result. */
extractToolSendResult?: (params: {
result: unknown;
send: ChannelToolSend;
}) => ChannelToolSend | null;
/**
* Translate generic `message(action=send)` arguments into the payload core
* should persist, retry, recover, and ack. Return null to keep the legacy
* plugin-owned action path for sends that cannot be represented durably.
*/
prepareSendPayload?: (params: ChannelMessagePreparedSendPayloadContext) => ReplyPayload | null | undefined | Promise<ReplyPayload | null | undefined>;
/**
* Prefer this for channel-specific poll semantics or extra poll parameters.
* Core only parses the shared poll model when falling back to `outbound.sendPoll`.
*/
handleAction?: (ctx: ChannelMessageActionContext) => Promise<AgentToolResult<unknown>>;
};
type ChannelPollResult = Pick<MessageReceiptSourceResult, "messageId" | "toJid" | "channelId" | "conversationId" | "pollId"> & {
messageId: string;
receipt?: MessageReceipt;
};
/** Shared poll input after core has normalized the common poll model. */
type ChannelPollContext = Pick<ChannelMessageSendPollContext, "cfg" | "to" | "poll" | "accountId" | "threadId" | "silent" | "isAnonymous" | "gatewayClientScopes" | "onPlatformSendDispatch" | "assertDirectAdapterHandoff"> & {
content?: string;
/** Trusted originating turn context for channel-owned delivery correlation. */
sessionKey?: string;
inboundEventKind?: InboundEventKind;
};
/** Minimal base for all channel probe results. Channel-specific probes extend this. */
type BaseProbeResult<TError = string | null> = {
ok: boolean;
error?: TError;
};
/** Minimal base for token resolution results. */
type BaseTokenResolution = {
token: string;
source: string;
};
//#endregion
//#region src/config/legacy.shared.d.ts
type LegacyConfigRule = {
path: string[];
message: string;
match?: (value: unknown, root: Record<string, unknown>) => boolean;
requireSourceLiteral?: boolean;
};
//#endregion
//#region src/channels/plugins/approval-native.types.d.ts
/**
* Native channel surface that can receive approval prompts.
*/
type ChannelApprovalNativeSurface = "origin" | "approver-dm";
/**
* Native channel destination for an approval prompt.
*/
type ChannelApprovalNativeTarget = {
to: string;
threadId?: string | number | null;
};
/**
* Preferred native delivery surface for approval prompts.
*/
type ChannelApprovalNativeDeliveryPreference = ChannelApprovalNativeSurface | "both";
/**
* Approval request shapes supported by native channel approval delivery.
*/
type ChannelApprovalNativeRequest = ExecApprovalRequest | PluginApprovalRequest | SystemAgentApprovalRequest;
/**
* Capabilities returned by native channel approval delivery inspection.
*/
type ChannelApprovalNativeDeliveryCapabilities = {
enabled: boolean;
preferredSurface: ChannelApprovalNativeDeliveryPreference;
supportsOriginSurface: boolean;
supportsApproverDmSurface: boolean;
notifyOriginWhenDmOnly?: boolean;
};
/**
* Adapter implemented by channel plugins that support native approval delivery.
*/
type ChannelApprovalNativeAdapter = {
describeDeliveryCapabilities: (params: {
cfg: OpenClawConfig;
accountId?: string | null;
approvalKind: ChannelApprovalKind;
request: ChannelApprovalNativeRequest;
}) => ChannelApprovalNativeDeliveryCapabilities;
resolveOriginTarget?: (params: {
cfg: OpenClawConfig;
accountId?: string | null;
approvalKind: ChannelApprovalKind;
request: ChannelApprovalNativeRequest;
}) => ChannelApprovalNativeTarget | null | Promise<ChannelApprovalNativeTarget | null>;
resolveApproverDmTargets?: (params: {
cfg: OpenClawConfig;
accountId?: string | null;
approvalKind: ChannelApprovalKind;
request: ChannelApprovalNativeRequest;
}) => ChannelApprovalNativeTarget[] | Promise<ChannelApprovalNativeTarget[]>;
};
//#endregion
//#region src/infra/approval-native-delivery.d.ts
/** One native approval delivery target selected by the channel adapter plan. */
type ChannelApprovalNativePlannedTarget = {
surface: ChannelApprovalNativeSurface;
target: ChannelApprovalNativeTarget;
reason: "preferred" | "fallback";
};
//#endregion
//#region src/infra/approval-native-runtime-types.d.ts
/** Prepared delivery target plus the stable key used to avoid duplicate native messages. */
type PreparedChannelNativeApprovalTarget<TPreparedTarget> = {
dedupeKey: string;
target: TPreparedTarget;
};
//#endregion
//#region src/infra/approval-view-model.types.d.ts
type ApprovalPhase = "pending" | "resolved" | "expired";
/** Button or command action shown with a pending approval prompt. */
type ApprovalActionView = {
kind?: "command" | "decision";
decision: ExecApprovalDecision;
label: string;
style: NonNullable<MessagePresentationButton["style"]>;
action?: MessagePresentationAction;
/** Copyable command fallback for non-interactive surfaces. */
command: string;
};
/** Label/value metadata row rendered with an approval prompt. */
type ApprovalMetadataView = {
label: string;
value: string;
};
type ApprovalViewBase = {
approvalId: string;
approvalKind: ChannelApprovalKind;
phase: ApprovalPhase;
title: string;
description?: string | null;
metadata: ApprovalMetadataView[];
};
/** Shared presentation fields for exec approval views across all phases. */
type ExecApprovalViewBase = ApprovalViewBase & {
approvalKind: "exec";
ask?: string | null;
agentId?: string | null;
warningText?: string | null;
commandAnalysis?: CommandExplanationSummary | null;
commandText: string;
commandPreview?: string | null;
cwd?: string | null;
envKeys?: readonly string[];
host?: string | null;
nodeId?: string | null;
scope?: ApprovalScope | null;
sessionKey?: string | null;
};
/** Pending exec approval view, including executable reply actions. */
type ExecApprovalPendingView = ExecApprovalViewBase & {
phase: "pending";
actions: ApprovalActionView[];
expiresAtMs: number;
};
/** Resolved exec approval view with the recorded decision. */
type ExecApprovalResolvedView = ExecApprovalViewBase & {
phase: "resolved";
decision: ExecApprovalDecision;
resolvedBy?: string | null;
};
/** Expired exec approval view without reply actions. */
type ExecApprovalExpiredView = ExecApprovalViewBase & {
phase: "expired";
};
/** Shared presentation fields for plugin approval views across all phases. */
type PluginApprovalViewBase = ApprovalViewBase & {
approvalKind: "plugin";
agentId?: string | null;
pluginId?: string | null;
scope?: ApprovalScope | null;
toolName?: string | null;
severity: "info" | "warning" | "critical";
};
/** Pending plugin approval view, including executable reply actions. */
type PluginApprovalPendingView = PluginApprovalViewBase & {
phase: "pending";
actions: ApprovalActionView[];
expiresAtMs: number;
};
/** Resolved plugin approval view with the recorded decision. */
type PluginApprovalResolvedView = PluginApprovalViewBase & {
phase: "resolved";
decision: ExecApprovalDecision;
resolvedBy?: string | null;
};
/** Expired plugin approval view without reply actions. */
type PluginApprovalExpiredView = PluginApprovalViewBase & {
phase: "expired";
};
/** Shared presentation fields for OpenClaw system change approvals. */
type SystemAgentApprovalViewBase = ApprovalViewBase & {
approvalKind: "system-agent";
agentId?: string | null;
scope?: null;
commandText: string;
commandPreview?: string | null;
ask?: string | null;
cwd?: string | null;
envKeys?: readonly string[];
host?: string | null;
nodeId?: string | null;
sessionKey?: string | null;
operationSummary: string;
};
/** Pending system change approval view, including executable reply actions. */
type SystemAgentApprovalPendingView = SystemAgentApprovalViewBase & {
phase: "pending";
actions: ApprovalActionView[];
expiresAtMs: number;
};
/** Resolved system change approval view with the recorded decision. */
type SystemAgentApprovalResolvedView = SystemAgentApprovalViewBase & {
phase: "resolved";
decision: ExecApprovalDecision;
resolvedBy?: string | null;
applicationStatus?: SystemAgentApprovalApplicationStatus;
terminalStatus?: "expired" | "cancelled";
};
/** Expired system change approval view without reply actions. */
type SystemAgentApprovalExpiredView = SystemAgentApprovalViewBase & {
phase: "expired";
};
/** Any pending approval view that still accepts a user decision. */
type PendingApprovalView = ExecApprovalPendingView | PluginApprovalPendingView | SystemAgentApprovalPendingView;
/** Any approval view after a decision was recorded. */
type ResolvedApprovalView = ExecApprovalResolvedView | PluginApprovalResolvedView | SystemAgentApprovalResolvedView;
/** Any approval view after it can no longer be acted on. */
type ExpiredApprovalView = ExecApprovalExpiredView | PluginApprovalExpiredView | SystemAgentApprovalExpiredView;
//#endregion
//#region src/infra/approval-handler-runtime-types.d.ts
/** Backward-compatible approval request accepted by public plugin callbacks. */
type ApprovalRequest = ApprovalRequestInput;
/** Union of approval resolution events a native approval handler can finalize. */
type ApprovalResolved = ExecApprovalResolved | PluginApprovalResolved | SystemAgentApprovalResolved;
/** Shared context passed to channel-native approval hooks. */
type ChannelApprovalCapabilityHandlerContext = {
cfg: OpenClawConfig;
accountId?: string | null;
gatewayUrl?: string;
context?: unknown;
};
/** Result instruction for updating, deleting, clearing, or leaving a delivered approval entry. */
type ChannelApprovalNativeFinalAction<TPayload> = {
kind: "update";
payload: TPayload;
} | {
kind: "delete";
} | {
kind: "clear-actions";
} | {
kind: "leave";
};
/** Availability gate for deciding whether a channel-native approval runtime can handle work. */
type ChannelApprovalNativeAvailabilityAdapter = {
isConfigured: (params: ChannelApprovalCapabilityHandlerContext) => boolean;
shouldHandle: (params: ChannelApprovalCapabilityHandlerContext & {
request: ApprovalRequest;
/** Payload-derived owner; channel adapters must not infer ownership from the id. */
approvalKind: ChannelApprovalKind;
}) => boolean;
};
/** Builds channel-native payloads for pending, resolved, and expired approval views. */
type ChannelApprovalNativePresentationAdapter<TPendingPayload = unknown, TFinalPayload = unknown> = {
buildPendingPayload: (params: ChannelApprovalCapabilityHandlerContext & {
request: ApprovalRequest;
approvalKind: ChannelApprovalKind;
nowMs: number;
view: PendingApprovalView;
}) => TPendingPayload | Promise<TPendingPayload>;
buildResolvedResult: (params: ChannelApprovalCapabilityHandlerContext & {
request: ApprovalRequest;
resolved: ApprovalResolved;
view: ResolvedApprovalView;
entry: unknown;
}) => ChannelApprovalNativeFinalAction<TFinalPayload> | Promise<ChannelApprovalNativeFinalAction<TFinalPayload>>;
buildExpiredResult: (params: ChannelApprovalCapabilityHandlerContext & {
request: ApprovalRequest;
view: ExpiredApprovalView;
entry: unknown;
}) => ChannelApprovalNativeFinalAction<TFinalPayload> | Promise<ChannelApprovalNativeFinalAction<TFinalPayload>>;
};
type ChannelApprovalNativeTransportAdapterForView<TPreparedTarget = unknown, TPendingEntry = unknown, TPendingPayload = unknown, TFinalPayload = unknown, TPendingView extends PendingApprovalView = PendingApprovalView> = {
prepareTarget: (params: ChannelApprovalCapabilityHandlerContext & {
plannedTarget: ChannelApprovalNativePlannedTarget;
request: ApprovalRequest;
approvalKind: ChannelApprovalKind;
view: TPendingView;
pendingPayload: TPendingPayload;
}) => PreparedChannelNativeApprovalTarget<TPreparedTarget> | null | Promise<PreparedChannelNativeApprovalTarget<TPreparedTarget> | null>;
deliverPending: (params: ChannelApprovalCapabilityHandlerContext & {
plannedTarget: ChannelApprovalNativePlannedTarget;
preparedTarget: TPreparedTarget;
request: ApprovalRequest;
approvalKind: ChannelApprovalKind;
view: TPendingView;
pendingPayload: TPendingPayload;
}) => TPendingEntry | null | Promise<TPendingEntry | null>;
updateEntry?: (params: ChannelApprovalCapabilityHandlerContext & {
entry: TPendingEntry;
request: ApprovalRequest;
approvalKind: ChannelApprovalKind;
payload: TFinalPayload;
phase: "resolved" | "expired";
}) => Promise<void>;
deleteEntry?: (params: ChannelApprovalCapabilityHandlerContext & {
entry: TPendingEntry;
phase: "resolved" | "expired";
}) => Promise<void>;
};
/** Transport hooks for preparing, delivering, updating, and deleting native approval entries. */
type ChannelApprovalNativeTransportAdapter<TPreparedTarget = unknown, TPendingEntry = unknown, TPendingPayload = unknown, TFinalPayload = unknown> = ChannelApprovalNativeTransportAdapterForView<TPreparedTarget, TPendingEntry, TPendingPayload, TFinalPayload>;
type ChannelApprovalNativeInteractionAdapterForView<TPendingEntry = unknown, TBinding = unknown, TPendingPayload = unknown, TPendingView extends PendingApprovalView = PendingApprovalView> = {
bindPending?: (params: ChannelApprovalCapabilityHandlerContext & {
entry: TPendingEntry;
request: ApprovalRequest;
approvalKind: ChannelApprovalKind;
view: TPendingView;
pendingPayload: TPendingPayload;
}) => TBinding | null | Promise<TBinding | null>;
unbindPending?: (params: ChannelApprovalCapabilityHandlerContext & {
entry: TPendingEntry;
binding: TBinding;
request: ApprovalRequest;
approvalKind: ChannelApprovalKind;
}) => Promise<void> | void;
clearPendingActions?: (params: ChannelApprovalCapabilityHandlerContext & {
entry: TPendingEntry;
phase: "resolved" | "expired";
}) => Promise<void>;
cancelDelivered?: (params: ChannelApprovalCapabilityHandlerContext & {
entry: TPendingEntry;
request: ApprovalRequest;
approvalKind: ChannelApprovalKind;
}) => Promise<void> | void;
};
/** Optional hooks for binding and clearing interactive approval controls. */
type ChannelApprovalNativeInteractionAdapter<TPendingEntry = unknown, TBinding = unknown> = ChannelApprovalNativeInteractionAdapterForView<TPendingEntry, TBinding>;
type ChannelApprovalNativeObserveAdapterForView<TPreparedTarget = unknown, TPendingPayload = unknown, TPendingEntry = unknown, TPendingView extends PendingApprovalView = PendingApprovalView> = {
onDeliveryError?: (params: ChannelApprovalCapabilityHandlerContext & {
error: unknown;
plannedTarget: ChannelApprovalNativePlannedTarget;
request: ApprovalRequest;
approvalKind: ChannelApprovalKind;
view: TPendingView;
pendingPayload: TPendingPayload;
}) => void;
onDuplicateSkipped?: (params: ChannelApprovalCapabilityHandlerContext & {
plannedTarget: ChannelApprovalNativePlannedTarget;
preparedTarget: PreparedChannelNativeApprovalTarget<TPreparedTarget>;
request: ApprovalRequest;
approvalKind: ChannelApprovalKind;
view: TPendingView;
pendingPayload: TPendingPayload;
}) => void;
onDelivered?: (params: ChannelApprovalCapabilityHandlerContext & {
plannedTarget: ChannelApprovalNativePlannedTarget;
preparedTarget: PreparedChannelNativeApprovalTarget<TPreparedTarget>;
request: ApprovalRequest;
approvalKind: ChannelApprovalKind;
view: TPendingView;
pendingPayload: TPendingPayload;
entry: TPendingEntry;
}) => void;
/** Runs after every terminal entry for one approval has been finalized. */
onFinalized?: (params: ChannelApprovalCapabilityHandlerContext & {
request: ApprovalRequest;
approvalKind: ChannelApprovalKind;
phase: "resolved" | "expired";
}) => void;
};
/** Optional observer hooks for delivery errors, duplicates, and successful deliveries. */
type ChannelApprovalNativeObserveAdapter<TPreparedTarget = unknown, TPendingPayload = unknown, TPendingEntry = unknown> = ChannelApprovalNativeObserveAdapterForView<TPreparedTarget, TPendingPayload, TPendingEntry>;
/** Runtime adapter consumed by core after a plugin's strongly typed spec has been erased. */
type ChannelApprovalNativeRuntimeAdapter<TPendingPayload = unknown, TPreparedTarget = unknown, TPendingEntry = unknown, TBinding = unknown, TFinalPayload = unknown> = {
eventKinds?: readonly ChannelApprovalKind[];
/**
* Trusted legacy ownership override retained for compatibility.
* @deprecated Omit this so core derives approval ownership from the request payload.
*/
resolveApprovalKind?: (request: ApprovalRequest) => ChannelApprovalKind;
availability: ChannelApprovalNativeAvailabilityAdapter;
presentation: ChannelApprovalNativePresentationAdapter<TPendingPayload, TFinalPayload>;
transport: ChannelApprovalNativeTransportAdapter<TPreparedTarget, TPendingEntry, TPendingPayload, TFinalPayload>;
interactions?: ChannelApprovalNativeInteractionAdapter<TPendingEntry, TBinding>;
observe?: ChannelApprovalNativeObserveAdapter;
};
//#endregion
//#region src/routing/resolve-route.d.ts
type RoutePeer = {
kind: ChatType;
id: string;
};
type ResolveAgentRouteInput = {
cfg: OpenClawConfig;
channel: string;
/** Known owner when no configured binding matches this route. */
defaultAgentId?: string;
accountId?: string | null;
peer?: RoutePeer | null;
dmScope?: DmScope;
groupScope?: GroupScope;
/** Parent peer for threads — used for binding inheritance when peer doesn't match directly. */
parentPeer?: RoutePeer | null;
guildId?: string | null;
teamId?: string | null;
/** Discord member role IDs — used for role-based agent routing. */
memberRoleIds?: string[];
};
type ResolvedAgentRoute = {
agentId: string;
channel: string;
accountId: string;
/** Effective direct-message scope after a matching binding override. */
dmScope?: DmScope;
groupScope?: GroupScope;
/** Internal session key used for persistence + concurrency. */
sessionKey: string;
/** Convenience alias for direct-chat collapse. */
mainSessionKey: string;
/** Which session should receive inbound last-route updates. */
lastRoutePolicy: "main" | "session";
/** Match description for debugging/logging. */
matchedBy: "binding.peer" | "binding.peer.parent" | "binding.peer.wildcard" | "binding.guild+roles" | "binding.guild" | "binding.team" | "binding.account" | "binding.channel" | "default";
};
declare function buildAgentSessionKey(params: {
agentId: string;
mainKey?: string;
channel: string;
accountId?: string | null;
peer?: RoutePeer | null;
/** DM session scope. */
dmScope?: DmScope;
groupScope?: GroupScope;
identityLinks?: Record<string, string[]>;
}): string;
declare function resolveAgentRoute(input: ResolveAgentRouteInput): ResolvedAgentRoute;
//#endregion
//#region src/secrets/resolve-types.d.ts
/** Shared per-runtime cache for resolved SecretRefs and file provider payloads. */
type SecretRefResolveCache = {
/** In-flight or completed resolution promise keyed by `secretRefKey(ref)`. */
resolvedByRefKey?: Map<string, Promise<unknown>>;
/** In-flight or completed parsed file-provider payload keyed by provider alias. */
filePayloadByProvider?: Map<string, Promise<unknown>>;
};
//#endregion
//#region src/secrets/runtime-degraded-state.d.ts
type SecretOwnerKind = "account" | "capability" | "gateway" | "provider" | "route" | "unknown";
type SecretAssignmentDisposition = "fail-closed" | "isolate";
//#endregion
//#region src/secrets/runtime-shared.d.ts
type SecretResolverWarningCode = "SECRETS_REF_OVERRIDES_PLAINTEXT" | "SECRETS_REF_IGNORED_INACTIVE_SURFACE" | "SECRETS_OWNER_UNAVAILABLE" | "WEB_SEARCH_PROVIDER_INVALID_AUTODETECT" | "WEB_SEARCH_AUTODETECT_SELECTED" | "WEB_SEARCH_KEY_UNRESOLVED_FALLBACK_USED" | "WEB_SEARCH_KEY_UNRESOLVED_NO_FALLBACK" | "WEB_FETCH_PROVIDER_INVALID_AUTODETECT" | "WEB_FETCH_AUTODETECT_SELECTED" | "WEB_FETCH_PROVIDER_KEY_UNRESOLVED_FALLBACK_USED" | "WEB_FETCH_PROVIDER_KEY_UNRESOLVED_NO_FALLBACK";
type SecretResolverWarning = {
code: SecretResolverWarningCode;
path: string;
message: string;
};
type SecretAssignment = {
ref: SecretRef;
path: string;
expected: "string" | "string-or-object";
ownerKind: SecretOwnerKind;
ownerId: string;
requiredForGateway: boolean;
disposition: SecretAssignmentDisposition;
/** Digest of the complete owner config captured before secret materialization. */
ownerContractDigest?: string;
apply: (value: unknown) => void;
/** Applies the canonical unavailable state when this owner must start cold. */
applyUnavailable?: () => void;
};
type ResolverContext = {
sourceConfig: OpenClawConfig;
env: NodeJS.ProcessEnv;
cache: SecretRefResolveCache;
manifestRegistry?: Pick<PluginManifestRegistry, "plugins">;
warnings: SecretResolverWarning[];
warningKeys: Set<string>;
assignments: SecretAssignment[];
};
type SecretDefaults = NonNullable<OpenClawConfig["secrets"]>["defaults"];
//#endregion
//#region src/secrets/target-registry-types.d.ts
/** Config document that owns a registered secret-bearing target. */
type SecretTargetConfigFile = "openclaw.json" | "auth-profile-store";
/** Storage shape used by a target: inline SecretInput or a sibling `*Ref` field. */
type SecretTargetShape = "secret_input" | "sibling_ref";
/** Resolved value shape accepted by runtime and apply validation. */
type SecretTargetExpected = "string" | "string-or-object";
/** Auth profile families that have separate secret target coverage. */
type AuthProfileType = "api_key" | "token";
/**
* Registry metadata for one configurable secret-bearing value.
*/
type SecretTargetRegistryEntry = {
/** Stable id used by plans, audits, docs, and targeted discovery filters. */
id: string;
/** Plan/configure target family; aliases keep CLI-facing names additive. */
targetType: string;
targetTypeAliases?: string[];
/** Config document where the value is discovered or rewritten. */
configFile: SecretTargetConfigFile;
/** Dot-path pattern for the secret-bearing value; `*` captures path segments. */
pathPattern: string;
/** Structured pattern segments preserve literal plugin IDs containing dots. */
pathPatternSegments?: string[];
/** Optional sibling SecretRef path materialized from the same captures as `pathPattern`. */
refPathPattern?: string;
/** Whether the registered value stores a SecretInput directly or via a sibling ref field. */
secretShape: SecretTargetShape;
/** Runtime value shape accepted after SecretRef resolution. */
expectedResolvedValue: SecretTargetExpected;
/** Enables `openclaw secrets apply` targeting for this entry. */
includeInPlan: boolean;
/** Enables interactive/non-interactive configure candidate generation. */
includeInConfigure: boolean;
/** Enables plaintext/unresolved-ref audit scanning. */
includeInAudit: boolean;
/** Captured path segment that names the owning provider, when applicable. */
providerIdPathSegmentIndex?: number;
/** Captured path segment that names the owning account/profile, when applicable. */
accountIdPathSegmentIndex?: number;
/** Auth-profile family for auth-profiles.json entries. */
authProfileType?: AuthProfileType;
/** Enables provider-shadowing diagnostics for provider-auth surfaces with fallback order. */
trackProviderShadowing?: boolean;
};
//#endregion
//#region src/security/audit.types.d.ts
/** Severity levels emitted by security audit checks. */
type SecurityAuditSeverity = "info" | "warn" | "critical";
/** One actionable or informational security audit finding. */
type SecurityAuditFinding = {
checkId: string;
severity: SecurityAuditSeverity;
title: string;
detail: string;
remediation?: string;
};
//#endregion
//#region src/channels/plugins/channel-runtime-surface.types.d.ts
/**
* Channel runtime context registry types.
*
* Defines the public plugin SDK surface for channel runtime context registration and watches.
*/
type ChannelRuntimeContextKey = {
channelId: string;
accountId?: string | null;
capability: string;
};
type ChannelRuntimeContextEvent = {
type: "registered" | "unregistered";
key: {
channelId: string;
accountId?: string;
capability: string;
};
context?: unknown;
};
type ChannelRuntimeContextRegistry = {
register: (params: ChannelRuntimeContextKey & {
context: unknown;
abortSignal?: AbortSignal;
}) => {
dispose: () => void;
};
get: <T = unknown>(params: ChannelRuntimeContextKey) => T | undefined;
watch: (params: {
channelId?: string;
accountId?: string | null;
capability?: string;
onEvent: (event: ChannelRuntimeContextEvent) => void;
}) => () => void;
};
/**
* Minimal channel-runtime surface exported through the public plugin SDK.
*
* Gateway startup supplies the full plugin channel runtime, but external callers
* may still type context-only helpers against this compatibility surface.
*/
type ChannelRuntimeSurface = {
runtimeContexts: ChannelRuntimeContextRegistry;
[key: string]: unknown;
};
//#endregion
//#region src/channels/plugins/config-write-policy-shared.d.ts
/**
* Channel/account scope used to evaluate config write policy.
*/
type ConfigWriteScopeLike<TChannelId extends string = string> = {
channelId?: TChannelId | null;
accountId?: string | null;
};
/**
* Target affected by a config write command.
*/
type ConfigWriteTargetLike<TChannelId extends string = string> = {
kind: "global";
} | {
kind: "channel";
scope: {
channelId: TChannelId;
};
} | {
kind: "account";
scope: {
channelId: TChannelId;
accountId: string;
};
} | {
kind: "ambiguous";
scopes: ConfigWriteScopeLike<TChannelId>[];
};
//#endregion
//#region src/channels/plugins/config-writes.d.ts
/**
* Target affected by a channel config write.
*/
type ConfigWriteTarget = ConfigWriteTargetLike;
//#endregion
//#region src/infra/outbound/deliver-types.d.ts
/** Channel send result or explicit non-outcome normalized for delivery accounting. */
type OutboundDeliveryResult = {
outcome?: MessageReceiptSourceResult["outcome"];
channel: ChannelId;
messageId: string;
target?: {
kind: "chat" | "channel" | "room" | "conversation";
id: string;
};
timestamp?: number;
toJid?: string;
pollId?: string;
receipt?: MessageReceipt;
meta?: Record<string, unknown>;
};
/** Reason a payload was intentionally not sent after normalization or hooks. */
type OutboundPayloadDeliverySuppressionReason = "cancelled_by_message_sending_hook" | "cancelled_by_reply_payload_sending_hook" | "empty_after_message_sending_hook" | "empty_after_reply_payload_sending_hook" | "no_visible_payload" | "adapter_returned_no_send" | "adapter_returned_no_identity";
/** Delivery phase where a failure occurred. */
type OutboundDeliveryFailureStage = "platform_send" | "queue" | "unknown";
type OutboundPayloadDeliveryKind = "text" | "media" | "other";
/** Per-payload delivery status emitted to callers and channel send summaries. */
type OutboundPayloadDeliveryOutcome = {
index: number;
status: "sent";
results: OutboundDeliveryResult[];
/** Effective post-hook, post-render payload kind. */
deliveryKind?: OutboundPayloadDeliveryKind;
} | {
index: number;
status: "suppressed";
reason: OutboundPayloadDeliverySuppressionReason;
hookEffect?: {
cancelReason?: string;
metadata?: Record<string, unknown>;
};
} | {
index: number;
status: "failed";
error: unknown;
sentBeforeError: boolean;
stage: OutboundDeliveryFailureStage;
/** Identified platform sends from this payload before its terminal failure. */
results?: OutboundDeliveryResult[];
/** Effective post-hook, post-render payload kind when platform delivery began. */
deliveryKind?: OutboundPayloadDeliveryKind;
};
//#endregion
//#region src/auto-reply/chunk.d.ts
type TextChunkProvider = ChannelId;
/**
* Chunking mode for outbound messages:
* - "length": Split only when exceeding textChunkLimit (default)
* - "newline": Prefer breaking on "soft" boundaries. Historically this split on every
* newline; now it only breaks on paragraph boundaries (blank lines) unless the text
* exceeds the length limit.
*/
type ChunkMode = "length" | "newline";
declare function resolveTextChunkLimit(cfg: OpenClawConfig | undefined, provider?: TextChunkProvider, accountId?: string | null, opts?: {
fallbackLimit?: number;
}): number;
declare function resolveChunkMode(cfg: OpenClawConfig | undefined, provider?: TextChunkProvider, accountId?: string | null): ChunkMode;
/**
* Split text on newlines, trimming line whitespace.
* Blank lines are folded into the next non-empty line as leading "\n" prefixes.
* Leading and trailing blank lines are capped to the available UTF-16 space.
* Long lines can be split by length (default) or kept intact via splitLongLines:false.
*/
declare function chunkByNewline(text: string, maxLineLength: number, opts?: {
splitLongLines?: boolean;
trimLines?: boolean;
isSafeBreak?: (index: number) => boolean;
}): string[];
/**
* Unified chunking function that dispatches based on mode.
*/
declare function chunkTextWithMode(text: string, limit: number, mode: ChunkMode): string[];
declare function chunkMarkdownTextWithMode(text: string, limit: number, mode: ChunkMode): string[];
declare function chunkText(text: string, limit: number): string[];
declare function chunkMarkdownText(text: string, limit: number): string[];
//#endregion
//#region src/infra/outbound/formatting.d.ts
/**
* Formatting and chunking hints carried through outbound delivery planning.
*/
type OutboundDeliveryFormattingOptions = {
textLimit?: number;
maxLinesPerMessage?: number;
tableMode?: MarkdownTableMode;
chunkMode?: ChunkMode;
parseMode?: "HTML";
};
//#endregion
//#region src/infra/outbound/identity-types.d.ts
/** Agent identity metadata that outbound channels can render with a message. */
type OutboundIdentity = {
name?: string;
avatarUrl?: string;
emoji?: string;
theme?: string;
};
//#endregion
//#region src/channels/plugins/outbound.types.d.ts
type ChannelOutboundContext = {
cfg: OpenClawConfig;
to: string;
text: string;
mediaUrl?: string;
audioAsVoice?: boolean;
mediaAccess?: OutboundMediaAccess;
mediaLocalRoots?: readonly string[];
mediaReadFile?: (filePath: string) => Promise<Buffer>;
gifPlayback?: boolean;
/** Send image, GIF, or video as document to avoid channel compression. */
forceDocument?: boolean;
replyToId?: string | null;
replyToIdSource?: "explicit" | "implicit";
replyToMode?: ReplyToMode;
formatting?: OutboundDeliveryFormattingOptions;
threadId?: string | number | null;
accountId?: string | null;
identity?: OutboundIdentity;
deps?: OutboundSendDeps;
silent?: boolean;
gatewayClientScopes?: readonly string[];
/** @internal Opaque durable intent id for exact provider-side send reconciliation. */
deliveryQueueId?: string;
/** @internal Stable platform-send index within one durable payload. */
deliveryPartIndex?: number;
/** @internal Exact platform-send count within one durable payload. */
deliveryPartCount?: number;
/** @internal Channel-valid id reserved before a correlated conversation turn is sent. */
preparedMessageId?: string;
/** @internal Refresh durable timing before recipient-visible or finalizing platform I/O. */
onPlatformSendDispatch?: () => Promise<void>;
/** @internal Synchronously fence custody after refresh and immediately before provider I/O. */
assertDirectAdapterHandoff?: () => void;
/** @internal Report each completed platform sub-send before starting another fallible step. */
onDeliveryResult?: (result: OutboundDeliveryResult) => Promise<void> | void;
};
type ChannelOutboundPayloadContext = ChannelOutboundContext & {
payload: ReplyPayload;
};
type ChannelPresentationCapabilities = {
/** Whether the channel accepts structured presentation payloads at all. */
supported?: boolean;
/** Whether the channel can render button action blocks natively. */
buttons?: boolean;
/** Whether the channel can render select/menu blocks natively. */
selects?: boolean;
/** Whether the channel can render low-emphasis context blocks natively. */
context?: boolean;
/** Whether the channel can render divider blocks natively. */
divider?: boolean;
/** Whether the channel can render chart blocks natively. */
charts?: boolean;
/** Whether the channel can render table blocks natively. */
tables?: boolean;
/** Per-channel limits used to adapt portable presentation blocks before rendering. */
limits?: {
actions?: {
/** Maximum total button/select actions in one message. */
maxActions?: number;
/** Maximum buttons per rendered action row. */
maxActionsPerRow?: number;
/** Maximum action rows in one message. */
maxRows?: number;
/** Maximum user-visible button label length. */
maxLabelLength?: number;
/** Maximum callback/action value size in UTF-8 bytes. */
maxValueBytes?: number;
/** Whether action styles such as primary or danger are preserved. */
supportsStyles?: boolean;
/** Whether disabled button state is preserved. */
supportsDisabled?: boolean;
/** Whether priority/layout hints affect native rendering. */
supportsLayoutHints?: boolean;
};
selects?: {
/** Maximum options in one select/menu block. */
maxOptions?: number;
/** Maximum user-visible option label length. */
maxLabelLength?: number;
/** Maximum option callback value size in UTF-8 bytes. */
maxValueBytes?: number;
};
text?: {
/** Maximum text length for title, text, and context blocks. */
maxLength?: number;
/** Unit used by maxLength. Defaults to Unicode code points. */
encoding?: "characters" | "utf8-bytes" | "utf16-units";
/** Markdown dialect understood by rendered text blocks. */
markdownDialect?: "plain" | "markdown" | "html" | "slack-mrkdwn" | "discord-markdown";
/** Whether the channel can edit presentation text in-place. */
supportsEdit?: boolean;
};
};
};
type ChannelDeliveryCapabilities = {
pin?: boolean;
durableFinal?: {
text?: boolean;
media?: boolean;
poll?: boolean;
payload?: boolean;
silent?: boolean;
replyTo?: boolean;
thread?: boolean;
nativeQuote?: boolean;
messageSendingHooks?: boolean;
batch?: boolean;
reconcileUnknownSend?: boolean;
afterSendSuccess?: boolean;
afterCommit?: boolean;
};
};
type ChannelOutboundPayloadHint = {
kind: "approval-pending";
approvalKind: ChannelApprovalKind;
nativeRouteActive?: boolean;
} | {
kind: "approval-resolved";
approvalKind: ChannelApprovalKind;
};
type ChannelOutboundTargetRef = {
channel: string;
to: string;
accountId?: string | null;
threadId?: string | number | null;
};
type ChannelOutboundFormattedContext = ChannelOutboundContext & {
abortSignal?: AbortSignal;
};
type ChannelOutboundChunkContext = {
formatting?: OutboundDeliveryFormattingOptions;
};
type ChannelOutboundNormalizePayloadParams = {
payload: ReplyPayload;
cfg: OpenClawConfig;
accountId?: string | null;
};
type ChannelOutboundNormalizePayloadBatchParams = {
payloads: readonly {
index: number;
payload: ReplyPayload;
}[];
cfg: OpenClawConfig;
accountId?: string | null;
};
type ChannelOutboundAdapter = {
deliveryMode: "direct" | "gateway" | "hybrid";
chunker?: ((text: string, limit: number, ctx?: ChannelOutboundChunkContext) => string[]) | null;
chunkerMode?: "text" | "markdown";
chunkedTextFormatting?: OutboundDeliveryFormattingOptions;
/** Lift remote Markdown image syntax in text into outbound media attachments. */
extractMarkdownImages?: boolean;
/** Preserve model-authored Markdown details blocks for a native channel renderer. */
preserveMarkdownDetails?: (params: {
cfg: OpenClawConfig;
accountId?: string | null;
}) => boolean;
textChunkLimit?: number;
/**
* Reserve the exact provider id used by the next single-message send.
* Presence opts the channel into conversations_turn reply correlation.
*/
prepareConversationTurnMessageId?: (params: {
cfg: OpenClawConfig;
to: string;
text: string;
accountId?: string | null;
threadId?: string | number | null;
}) => string;
sanitizeText?: (params: {
text: string;
payload: ReplyPayload;
cfg?: OpenClawConfig;
accountId?: string;
}) => string;
pollMaxOptions?: number;
supportsPollDurationSeconds?: boolean;
supportsAnonymousPolls?: boolean;
normalizePayload?: (params: ChannelOutboundNormalizePayloadParams) => ReplyPayload | null;
/** Normalize an ordered batch in place. Return one entry per input; null suppresses that send. */
normalizePayloadBatch?: (params: ChannelOutboundNormalizePayloadBatchParams) => ReadonlyArray<ReplyPayload | null>;
sendTextOnlyErrorPayloads?: boolean;
shouldSkipPlainTextSanitization?: (params: {
payload: ReplyPayload;
}) => boolean;
resolveEffectiveTextChunkLimit?: (params: {
cfg: OpenClawConfig;
accountId?: string | null;
fallbackLimit?: number;
formatting?: OutboundDeliveryFormattingOptions;
}) => number | undefined;
shouldSuppressLocalPayloadPrompt?: (params: {
cfg: OpenClawConfig;
accountId?: string | null;
payload: ReplyPayload;
hint?: ChannelOutboundPayloadHint;
}) => boolean;
beforeDeliverPayload?: (params: {
cfg: OpenClawConfig;
target: ChannelOutboundTargetRef;
payload: ReplyPayload;
hint?: ChannelOutboundPayloadHint;
}) => Promise<void> | void;
afterDeliverPayload?: (params: {
cfg: OpenClawConfig;
target: ChannelOutboundTargetRef;
payload: ReplyPayload;
results: readonly OutboundDeliveryResult[];
}) => Promise<void> | void;
/** Adopt a provider-created thread for later payloads in the same durable batch. */
adoptTargetFromDelivery?: (params: {
cfg: OpenClawConfig;
target: ChannelOutboundTargetRef;
result: OutboundDeliveryResult;
}) => {
threadId: string | number;
} | null | undefined;
/** Channel-advertised presentation features and limits used by core adaptation. */
presentationCapabilities?: ChannelPresentationCapabilities;
/**
* Account- and formatting-aware capability resolution; takes precedence over
* the static declaration. Formatting is the delivery's outbound formatting
* options, so capabilities that only apply to one text funnel (for example
* rich tables on the markdown path) can turn off for HTML-mode sends.
*/
resolvePresentationCapabilities?: (params: {
cfg: OpenClawConfig;
accountId?: string | null;
formatting?: OutboundDeliveryFormattingOptions;
}) => ChannelPresentationCapabilities;
deliveryCapabilities?: ChannelDeliveryCapabilities;
/** Render an adapted portable presentation into channel-native payload data. */
renderPresentation?: (params: {
payload: ReplyPayload;
presentation: MessagePresentation;
/** Normalized original for readable fallbacks; native rendering uses presentation. */
sourcePresentation?: MessagePresentation;
ctx: ChannelOutboundPayloadContext;
}) => Promise<ReplyPayload | null> | ReplyPayload | null;
pinDeliveredMessage?: (params: {
cfg: OpenClawConfig;
target: ChannelOutboundTargetRef;
messageId: string;
pin: ReplyPayloadDeliveryPin;
gatewayClientScopes?: readonly string[];
}) => Promise<void> | void;
/**
* @deprecated Use shouldTreatDeliveredTextAsVisible instead.
*/
shouldTreatRoutedTextAsVisible?: (params: {
kind: "tool" | "block" | "final";
text?: string;
}) => boolean;
shouldTreatDeliveredTextAsVisible?: (params: {
kind: "tool" | "block" | "final";
text?: string;
}) => boolean;
preferFinalAssistantVisibleText?: boolean;
targetsMatchForReplySuppression?: (params: {
originTarget: string;
targetKey: string;
targetThreadId?: string;
}) => boolean;
resolveTarget?: (params: {
cfg?: OpenClawConfig;
to?: string;
allowFrom?: string[];
accountId?: string | null;
mode?: ChannelOutboundTargetMode;
}) => {
ok: true;
to: string;
} | {
ok: false;
error: Error;
};
sendPayload?: (ctx: ChannelOutboundPayloadContext) => Promise<OutboundDeliveryResult>;
sendFormattedText?: (ctx: ChannelOutboundFormattedContext) => Promise<OutboundDeliveryResult[]>;
sendFormattedMedia?: (ctx: ChannelOutboundFormattedContext & {
mediaUrl: string;
}) => Promise<OutboundDeliveryResult>;
sendText?: (ctx: ChannelOutboundContext) => Promise<OutboundDeliveryResult>;
sendMedia?: (ctx: ChannelOutboundContext) => Promise<OutboundDeliveryResult>;
sendPoll?: (ctx: ChannelPollContext) => Promise<ChannelPollResult>;
};
//#endregion
//#region src/channels/plugins/pairing.types.d.ts
/**
* Channel pairing hooks used by setup and allowlist approval flows.
*/
type ChannelPairingAdapter = {
idLabel: string;
normalizeAllowEntry?: (entry: string) => string;
/** Derive the persisted approval entry from the locally issued request. */
resolveApprovalStoreEntry?: (request: {
id: string;
meta?: Record<string, string>;
}) => string | null | undefined;
notifyApproval?: (params: {
cfg: OpenClawConfig;
id: string;
accountId?: string;
meta?: Record<string, string>;
runtime?: RuntimeEnv;
}) => Promise<void>;
};
//#endregion
//#region src/channels/plugins/types.adapters.d.ts
type ConfiguredBindingRule = AgentBinding;
type ChannelActionAvailabilityState = {
kind: "enabled";
} | {
kind: "disabled";
} | {
kind: "unsupported";
};
type ChannelApprovalForwardTarget = {
channel: string;
to: string;
accountId?: string | null;
threadId?: string | number | null;
source?: "session" | "target";
};
type ChannelCapabilitiesDisplayTone = "default" | "muted" | "success" | "warn" | "error";
type ChannelCapabilitiesDisplayLine = {
text: string;
tone?: ChannelCapabilitiesDisplayTone;
};
type ChannelCapabilitiesDiagnostics = {
lines?: ChannelCapabilitiesDisplayLine[];
details?: Record<string, unknown>;
};
type ChannelAdapterCallback<T extends (...args: never[]) => unknown> = T;
type ChannelAccountLinkState = "linked" | "not-linked" | "unknown";
type ChannelConfigAdapter<ResolvedAccount> = {
listAccountIds: (cfg: OpenClawConfig) => string[];
resolveAccount: (cfg: OpenClawConfig, accountId?: string | null) => ResolvedAccount;
inspectAccount?: (cfg: OpenClawConfig, accountId?: string | null) => unknown;
defaultAccountId?: (cfg: OpenClawConfig) => string;
setAccountEnabled?: (params: {
cfg: OpenClawConfig;
accountId: string;
enabled: boolean;
}) => OpenClawConfig;
deleteAccount?: (params: {
cfg: OpenClawConfig;
accountId: string;
}) => OpenClawConfig;
isEnabled?: ChannelAdapterCallback<(account: ResolvedAccount, cfg: OpenClawConfig) => boolean>;
disabledReason?: ChannelAdapterCallback<(account: ResolvedAccount, cfg: OpenClawConfig) => string>;
isConfigured?: ChannelAdapterCallback<(account: ResolvedAccount, cfg: OpenClawConfig) => boolean | Promise<boolean>>;
isLinked?: ChannelAdapterCallback<(account: ResolvedAccount, cfg: OpenClawConfig) => ChannelAccountLinkState | Promise<ChannelAccountLinkState>>;
unconfiguredReason?: ChannelAdapterCallback<(account: ResolvedAccount, cfg: OpenClawConfig) => string>;
unlinkedReason?: ChannelAdapterCallback<(account: ResolvedAccount, cfg: OpenClawConfig) => string>;
describeAccount?: ChannelAdapterCallback<(account: ResolvedAccount, cfg: OpenClawConfig) => ChannelAccountSnapshot>;
resolveAllowFrom?: (params: {
cfg: OpenClawConfig;
accountId?: string | null;
}) => Array<string | number> | undefined;
formatAllowFrom?: (params: {
cfg: OpenClawConfig;
accountId?: string | null;
allowFrom: Array<string | number>;
}) => string[];
hasConfiguredState?: (params: {
cfg: OpenClawConfig;
env?: NodeJS.ProcessEnv;
}) => boolean;
hasPersistedAuthState?: (params: {
cfg: OpenClawConfig;
env?: NodeJS.ProcessEnv;
}) => boolean;
resolveDefaultTo?: (params: {
cfg: OpenClawConfig;
accountId?: string | null;
}) => string | undefined;
};
type ChannelSecretsAdapter = {
secretTargetRegistryEntries?: readonly SecretTargetRegistryEntry[];
unsupportedSecretRefSurfacePatterns?: readonly string[];
collectUnsupportedSecretRefConfigCandidates?: (raw: unknown) => Array<{
path: string;
value: unknown;
}>;
collectRuntimeConfigAssignments?: (params: {
config: OpenClawConfig;
defaults: SecretDefaults | undefined;
context: ResolverContext;
}) => void;
};
type ChannelGroupAdapter = {
resolveRequireMention?: (params: ChannelGroupContext) => boolean | undefined;
resolveToolPolicy?: (params: ChannelGroupContext) => GroupToolPolicyConfig | undefined;
};
type ChannelStatusAdapter<ResolvedAccount, Probe = unknown, Audit = unknown> = {
defaultRuntime?: ChannelAccountSnapshot;
buildChannelSummary?: ChannelAdapterCallback<(params: {
account: ResolvedAccount;
cfg: OpenClawConfig;
defaultAccountId: string;
snapshot: ChannelAccountSnapshot;
}) => Record<string, unknown> | Promise<Record<string, unknown>>>;
probeAccount?: ChannelAdapterCallback<(params: {
account: ResolvedAccount;
timeoutMs: number;
cfg: OpenClawConfig;
}) => Promise<Probe>>;
formatCapabilitiesProbe?: ChannelAdapterCallback<(params: {
probe: Probe;
}) => ChannelCapabilitiesDisplayLine[]>;
auditAccount?: ChannelAdapterCallback<(params: {
account: ResolvedAccount;
timeoutMs: number;
cfg: OpenClawConfig;
probe?: Probe;
}) => Promise<Audit>>;
buildCapabilitiesDiagnostics?: ChannelAdapterCallback<(params: {
account: ResolvedAccount;
timeoutMs: number;
cfg: OpenClawConfig;
probe?: Probe;
audit?: Audit;
target?: string;
}) => Promise<ChannelCapabilitiesDiagnostics | undefined>>;
buildAccountSnapshot?: ChannelAdapterCallback<(params: {
account: ResolvedAccount;
cfg: OpenClawConfig;
runtime?: ChannelAccountSnapshot;
probe?: Probe;
audit?: Audit;
}) => ChannelAccountSnapshot | Promise<ChannelAccountSnapshot>>;
logSelfId?: ChannelAdapterCallback<(params: {
account: ResolvedAccount;
cfg: OpenClawConfig;
runtime: RuntimeEnv;
includeChannelPrefix?: boolean;
}) => void>;
resolveAccountState?: ChannelAdapterCallback<(params: {
account: ResolvedAccount;
cfg: OpenClawConfig;
configured: boolean;
enabled: boolean;
}) => ChannelAccountState>;
collectStatusIssues?: (accounts: ChannelAccountSnapshot[]) => ChannelStatusIssue[];
};
type ChannelGatewayContext<ResolvedAccount = unknown> = {
cfg: OpenClawConfig;
accountId: string;
account: ResolvedAccount;
runtime: RuntimeEnv;
abortSignal: AbortSignal;
log?: ChannelLogSink;
getStatus: () => ChannelAccountSnapshot;
setStatus: (next: ChannelAccountSnapshot) => void;
/** Clear cached outbound directory lookups after the channel accepts newer directory data. */
invalidateDirectoryCache?: () => void;
/**
* Optional channel runtime helpers for external channel plugins.
*
* This field provides the canonical channel runtime helpers for channel
* dispatch, routing, session, reply, and startup context work.
*
* ## Available Features
*
* - **reply**: AI response dispatching, formatting, and delivery
* - **routing**: Agent route resolution and matching
* - **text**: Text chunking, markdown processing, and control command detection
* - **session**: Session management and metadata tracking
* - **media**: Remote media fetching and buffer saving
* - **commands**: Command authorization and control command handling
* - **groups**: Group policy resolution and mention requirements
* - **pairing**: Channel pairing and allow-from management
*
* ## Use Cases
*
* Channel plugins that need:
* - AI-powered response generation and delivery
* - Advanced text processing and formatting
* - Session tracking and management
* - Agent routing and policy resolution
*
* ## Example
*
* ```typescript
* const emailGatewayAdapter: ChannelGatewayAdapter<EmailAccount> = {
* startAccount: async (ctx) => {
* // Check availability (for backward compatibility)
* if (!ctx.channelRuntime) {
* ctx.log?.warn?.("channelRuntime not available - skipping AI features");
* return;
* }
*
* // Use AI dispatch
* await ctx.channelRuntime.reply.dispatchReplyWithBufferedBlockDispatcher({
* ctx: { ... },
* cfg: ctx.cfg,
* dispatcherOptions: {
* deliver: async (payload) => {
* // Send reply via email
* },
* },
* });
* },
* };
* ```
*
* ## Backward Compatibility
*
* - This field is **optional** - channels that don't need it can ignore it
* - Gateway startup passes a full `createPluginRuntime().channel` surface
* when a runtime resolver is configured
* - External plugins should check for undefined before using
*
* @since Plugin SDK 2026.2.19
* @see {@link https://docs.openclaw.ai/plugins/building-plugins | Plugin SDK documentation}
*/
channelRuntime?: ChannelRuntimeSurface;
};
type ChannelLogoutResult = {
cleared: boolean;
loggedOut?: boolean;
[key: string]: unknown;
};
type ChannelLoginWithQrStartResult = {
qrDataUrl?: string;
message: string;
connected?: boolean;
sessionKey?: string;
};
type ChannelLoginWithQrWaitResult = {
connected: boolean;
message: string;
qrDataUrl?: string;
};
type ChannelLogoutContext<ResolvedAccount = unknown> = {
cfg: OpenClawConfig;
accountId: string;
account: ResolvedAccount;
runtime: RuntimeEnv;
log?: ChannelLogSink;
};
type ChannelGatewayAdapter<ResolvedAccount = unknown> = {
startAccount?: (ctx: ChannelGatewayContext<ResolvedAccount>) => Promise<unknown>;
stopAccount?: (ctx: ChannelGatewayContext<ResolvedAccount>) => Promise<void>;
/** Keep gateway auth bypass resolution mirrored through a lightweight top-level `gateway-auth-api.ts` artifact. */
resolveGatewayAuthBypassPaths?: (params: {
cfg: OpenClawConfig;
}) => string[];
loginWithQrStart?: (params: {
accountId?: string;
force?: boolean;
timeoutMs?: number;
verbose?: boolean;
}) => Promise<ChannelLoginWithQrStartResult>;
loginWithQrWait?: (params: {
accountId?: string;
sessionKey?: string;
timeoutMs?: number;
currentQrDataUrl?: string;
}) => Promise<ChannelLoginWithQrWaitResult>;
logoutAccount?: (ctx: ChannelLogoutContext<ResolvedAccount>) => Promise<ChannelLogoutResult>;
};
type ChannelAuthAdapter = {
login?: (params: {
cfg: OpenClawConfig;
accountId?: string | null;
runtime: RuntimeEnv;
verbose?: boolean;
channelInput?: string | null;
}) => Promise<void>;
};
type ChannelHeartbeatAdapter = {
checkReady?: (params: {
cfg: OpenClawConfig;
accountId?: string | null;
deps?: ChannelHeartbeatDeps;
}) => Promise<{
ok: boolean;
reason: string;
}>;
sendTyping?: (params: {
cfg: OpenClawConfig;
to: string;
accountId?: string | null;
threadId?: string | number | null;
deps?: ChannelHeartbeatDeps;
}) => Promise<void> | void;
clearTyping?: (params: {
cfg: OpenClawConfig;
to: string;
accountId?: string | null;
threadId?: string | number | null;
deps?: ChannelHeartbeatDeps;
}) => Promise<void> | void;
};
type ChannelDirectorySelfParams = {
cfg: OpenClawConfig;
accountId?: string | null;
runtime: RuntimeEnv;
};
type ChannelDirectoryListParams = {
cfg: OpenClawConfig;
accountId?: string | null;
query?: string | null;
limit?: number | null;
runtime: RuntimeEnv;
};
type ChannelDirectoryListGroupMembersParams = {
cfg: OpenClawConfig;
accountId?: string | null;
groupId: string;
limit?: number | null;
runtime: RuntimeEnv;
};
type ChannelDirectoryAdapter = {
self?: (params: ChannelDirectorySelfParams) => Promise<ChannelDirectoryEntry | null>;
listPeers?: (params: ChannelDirectoryListParams) => Promise<ChannelDirectoryEntry[]>;
listPeersLive?: (params: ChannelDirectoryListParams) => Promise<ChannelDirectoryEntry[]>;
listGroups?: (params: ChannelDirectoryListParams) => Promise<ChannelDirectoryEntry[]>;
listGroupsLive?: (params: ChannelDirectoryListParams) => Promise<ChannelDirectoryEntry[]>;
listGroupMembers?: (params: ChannelDirectoryListGroupMembersParams) => Promise<ChannelDirectoryEntry[]>;
};
type ChannelResolveKind = "user" | "group";
type ChannelResolveResult = {
input: string;
resolved: boolean;
id?: string;
name?: string;
note?: string;
};
type ChannelResolverAdapter = {
resolveTargets: (params: {
cfg: OpenClawConfig;
accountId?: string | null;
inputs: string[];
kind: ChannelResolveKind;
runtime: RuntimeEnv;
}) => Promise<ChannelResolveResult[]>;
};
type ChannelElevatedAdapter = {
allowFromFallback?: (params: {
cfg: OpenClawConfig;
accountId?: string | null;
}) => Array<string | number> | undefined;
};
type ChannelCommandAdapter = {
enforceOwnerForCommands?: boolean;
skipWhenConfigEmpty?: boolean;
nativeCommandsAutoEnabled?: boolean;
nativeSkillsAutoEnabled?: boolean;
preferSenderE164ForCommands?: boolean;
resolveNativeCommandName?: (params: {
commandKey: string;
defaultName: string;
}) => string | undefined;
buildCommandsListChannelData?: (params: {
currentPage: number;
totalPages: number;
agentId?: string;
}) => ReplyPayload["channelData"] | null;
buildModelsMenuChannelData?: (params: {
providers: Array<{
id: string;
count: number;
}>;
}) => ReplyPayload["channelData"] | null;
buildModelsProviderChannelData?: (params: {
providers: Array<{
id: string;
count: number;
}>;
}) => ReplyPayload["channelData"] | null;
buildModelsAddProviderChannelData?: (params: {
providers: Array<{
id: string;
}>;
}) => ReplyPayload["channelData"] | null;
buildModelsListChannelData?: (params: {
provider: string;
models: readonly string[];
currentModel?: string;
currentPage: number;
totalPages: number;
pageSize?: number;
modelNames?: ReadonlyMap<string, string>;
}) => ReplyPayload["channelData"] | null;
buildModelBrowseChannelData?: () => ReplyPayload["channelData"] | null;
};
type ChannelDoctorConfigMutation = {
config: OpenClawConfig;
changes: string[];
warnings?: string[];
};
type ChannelDoctorSequenceResult = {
changeNotes: string[];
warningNotes: string[];
};
type ChannelDoctorEmptyAllowlistAccountContext = {
account: Record<string, unknown>;
channelName: string;
dmPolicy?: string;
effectiveAllowFrom?: Array<string | number>;
parent?: Record<string, unknown>;
prefix: string;
};
type ChannelDoctorAdapter = {
dmAllowFromMode?: "topOnly" | "topOrNested" | "nestedOnly";
groupModel?: "sender" | "route" | "hybrid";
groupAllowFromFallbackToAllowFrom?: boolean;
warnOnEmptyGroupSenderAllowlist?: boolean;
legacyConfigRules?: LegacyConfigRule[];
normalizeCompatibilityConfig?: (params: {
cfg: OpenClawConfig;
}) => ChannelDoctorConfigMutation;
collectPreviewWarnings?: (params: {
cfg: OpenClawConfig;
doctorFixCommand: string;
env?: NodeJS.ProcessEnv;
}) => string[] | Promise<string[]>;
collectMutableAllowlistWarnings?: (params: {
cfg: OpenClawConfig;
}) => string[] | Promise<string[]>;
repairConfig?: (params: {
cfg: OpenClawConfig;
doctorFixCommand: string;
env?: NodeJS.ProcessEnv;
}) => ChannelDoctorConfigMutation | Promise<ChannelDoctorConfigMutation>;
runConfigSequence?: (params: {
cfg: OpenClawConfig;
env: NodeJS.ProcessEnv;
shouldRepair: boolean;
}) => ChannelDoctorSequenceResult | Promise<ChannelDoctorSequenceResult>;
cleanStaleConfig?: (params: {
cfg: OpenClawConfig;
}) => ChannelDoctorConfigMutation | Promise<ChannelDoctorConfigMutation>;
collectEmptyAllowlistExtraWarnings?: (params: ChannelDoctorEmptyAllowlistAccountContext) => string[];
shouldSkipDefaultEmptyGroupAllowlistWarning?: (params: ChannelDoctorEmptyAllowlistAccountContext) => boolean;
};
type ChannelLifecycleAdapter = {
onAccountConfigChanged?: (params: {
prevCfg: OpenClawConfig;
nextCfg: OpenClawConfig;
accountId: string;
runtime: RuntimeEnv;
}) => Promise<void> | void;
onAccountRemoved?: (params: {
prevCfg: OpenClawConfig;
accountId: string;
runtime: RuntimeEnv;
}) => Promise<void> | void;
runStartupMaintenance?: (params: {
cfg: OpenClawConfig;
env?: NodeJS.ProcessEnv;
log: {
info?: (message: string) => void;
warn?: (message: string) => void;
};
trigger?: string;
logPrefix?: string;
}) => Promise<void> | void;
/**
* @deprecated Export stateMigrations from the plugin doctor contract instead.
* Removal plan: remove the lifecycle adapter after the 2027.1 external-plugin migration window.
*/
detectLegacyStateMigrations?: (params: {
cfg: OpenClawConfig;
env: NodeJS.ProcessEnv;
stateDir: string;
oauthDir: string;
}) => ChannelLegacyStateMigrationPlan[] | Promise<ChannelLegacyStateMigrationPlan[]>;
};
type ChannelApprovalDeliveryAdapter = {
hasConfiguredDmRoute?: (params: {
cfg: OpenClawConfig;
}) => boolean;
shouldSuppressForwardingFallback?: (params: {
cfg: OpenClawConfig;
approvalKind: ChannelApprovalKind;
target: ChannelApprovalForwardTarget;
request: ExecApprovalRequest | PluginApprovalRequest | SystemAgentApprovalRequest;
}) => boolean;
};
type ChannelApproveCommandBehavior = {
kind: "allow";
} | {
kind: "ignore";
} | {
kind: "reply";
text: string;
};
type ChannelApprovalRenderAdapter = {
exec?: {
buildPendingPayload?: (params: {
cfg: OpenClawConfig;
request: ExecApprovalRequest;
target: ChannelApprovalForwardTarget;
nowMs: number;
}) => ReplyPayload | null;
buildResolvedPayload?: (params: {
cfg: OpenClawConfig;
resolved: ExecApprovalResolved;
target: ChannelApprovalForwardTarget;
}) => ReplyPayload | null;
};
plugin?: {
buildPendingPayload?: (params: {
cfg: OpenClawConfig;
request: PluginApprovalRequest;
target: ChannelApprovalForwardTarget;
nowMs: number;
}) => ReplyPayload | null;
buildResolvedPayload?: (params: {
cfg: OpenClawConfig;
resolved: PluginApprovalResolved;
target: ChannelApprovalForwardTarget;
}) => ReplyPayload | null;
};
};
type ChannelApprovalAdapter = {
delivery?: ChannelApprovalDeliveryAdapter;
nativeRuntime?: ChannelApprovalNativeRuntimeAdapter;
render?: ChannelApprovalRenderAdapter;
native?: ChannelApprovalNativeAdapter;
describeExecApprovalSetup?: (params: {
channel: string;
channelLabel: string;
accountId?: string;
}) => string | null | undefined;
describePluginApprovalSetup?: (params: {
channel: string;
channelLabel: string;
accountId?: string;
}) => string | null | undefined;
};
type ChannelApprovalCapability = ChannelApprovalAdapter & {
authorizeActorAction?: (params: {
cfg: OpenClawConfig;
accountId?: string | null;
senderId?: string | null;
action: "approve";
approvalKind: ChannelApprovalKind;
}) => {
authorized: boolean;
reason?: string;
};
getActionAvailabilityState?: (params: {
cfg: OpenClawConfig;
accountId?: string | null;
action: "approve";
approvalKind?: ChannelApprovalKind;
}) => ChannelActionAvailabilityState;
/** Exec-native client availability for the initiating surface; distinct from same-chat auth. */
getExecInitiatingSurfaceState?: (params: {
cfg: OpenClawConfig;
accountId?: string | null;
action: "approve";
}) => ChannelActionAvailabilityState;
resolveApproveCommandBehavior?: (params: {
cfg: OpenClawConfig;
accountId?: string | null;
senderId?: string | null;
approvalKind: ChannelApprovalKind;
}) => ChannelApproveCommandBehavior | undefined;
};
type ChannelAllowlistAdapter = {
applyConfigEdit?: (params: {
cfg: OpenClawConfig;
parsedConfig: Record<string, unknown>;
accountId?: string | null;
scope: "dm" | "group";
action: "add" | "remove";
entry: string;
}) => {
kind: "ok";
changed: boolean;
pathLabel: string;
writeTarget: ConfigWriteTarget;
} | {
kind: "invalid-entry";
} | Promise<{
kind: "ok";
changed: boolean;
pathLabel: string;
writeTarget: ConfigWriteTarget;
} | {
kind: "invalid-entry";
}> | null;
readConfig?: (params: {
cfg: OpenClawConfig;
accountId?: string | null;
}) => {
dmAllowFrom?: Array<string | number>;
groupAllowFrom?: Array<string | number>;
dmPolicy?: string;
groupPolicy?: string;
groupOverrides?: Array<{
label: string;
entries: Array<string | number>;
}>;
} | Promise<{
dmAllowFrom?: Array<string | number>;
groupAllowFrom?: Array<string | number>;
dmPolicy?: string;
groupPolicy?: string;
groupOverrides?: Array<{
label: string;
entries: Array<string | number>;
}>;
}>;
resolveNames?: (params: {
cfg: OpenClawConfig;
accountId?: string | null;
scope: "dm" | "group";
entries: string[];
}) => Array<{
input: string;
resolved: boolean;
name?: string | null;
}> | Promise<Array<{
input: string;
resolved: boolean;
name?: string | null;
}>>;
supportsScope?: (params: {
scope: "dm" | "group" | "all";
}) => boolean;
};
type ChannelConfiguredBindingConversationRef = {
conversationId: string;
parentConversationId?: string;
};
type ChannelConfiguredBindingMatch = ChannelConfiguredBindingConversationRef & {
matchPriority?: number;
};
type ChannelCommandConversationContext = {
accountId: string;
threadId?: string;
threadParentId?: string;
senderId?: string;
sessionKey?: string;
parentSessionKey?: string;
from?: string;
chatType?: string;
originatingTo?: string;
commandTo?: string;
fallbackTo?: string;
};
type ChannelConfiguredBindingProvider = {
selfParentConversationByDefault?: boolean;
compileConfiguredBinding: (params: {
binding: ConfiguredBindingRule;
conversationId: string;
}) => ChannelConfiguredBindingConversationRef | null;
matchInboundConversation: (params: {
binding: ConfiguredBindingRule;
compiledBinding: ChannelConfiguredBindingConversationRef;
conversationId: string;
parentConversationId?: string;
}) => ChannelConfiguredBindingMatch | null;
resolveCommandConversation?: (params: ChannelCommandConversationContext) => ChannelConfiguredBindingConversationRef | null;
};
type ChannelConversationBindingSupport = {
supportsCurrentConversationBinding?: boolean;
isCurrentConversationBindingSupported?: (params: {
accountId: string;
}) => boolean;
/** Declares that live bindings come from a channel-registered adapter, never generic storage. */
bindingStore?: "adapter";
/**
* Preferred placement when a command is started from a top-level conversation
* without an existing native thread id.
*
* - `current`: bind/spawn in the current conversation
* - `child`: create a child thread/conversation first
*/
defaultTopLevelPlacement?: "current" | "child";
resolveConversationRef?: (params: {
accountId?: string | null;
conversationId: string;
parentConversationId?: string;
threadId?: string | number | null;
}) => {
conversationId: string;
parentConversationId?: string;
} | null;
buildBoundReplyPayload?: (params: {
operation: "acp-spawn";
placement: "current" | "child";
conversation: {
channel: string;
accountId?: string | null;
conversationId: string;
parentConversationId?: string;
};
}) => Pick<ReplyPayload, "channelData" | "delivery" | "presentation"> | null | Promise<Pick<ReplyPayload, "channelData" | "delivery" | "presentation"> | null>;
buildModelOverrideParentCandidates?: (params: {
parentConversationId?: string | null;
}) => string[] | null | undefined;
shouldStripThreadFromAnnounceOrigin?: (params: {
requester: {
channel?: string;
to?: string;
threadId?: string | number;
};
entry: {
channel?: string;
to?: string;
threadId?: string | number;
};
}) => boolean;
setIdleTimeoutBySessionKey?: (params: {
targetSessionKey: string;
accountId?: string | null;
idleTimeoutMs: number;
}) => Array<{
boundAt: number;
lastActivityAt: number;
idleTimeoutMs?: number;
maxAgeMs?: number;
}>;
setMaxAgeBySessionKey?: (params: {
targetSessionKey: string;
accountId?: string | null;
maxAgeMs: number;
}) => Array<{
boundAt: number;
lastActivityAt: number;
idleTimeoutMs?: number;
maxAgeMs?: number;
}>;
createManager?: (params: {
cfg: OpenClawConfig;
accountId?: string | null;
}) => {
stop: () => void | Promise<void>;
} | Promise<{
stop: () => void | Promise<void>;
}>;
};
type ChannelSecurityDmRouteContext<ResolvedAccount> = ChannelSecurityContext<ResolvedAccount> & {
accountId: string;
principalId?: string;
};
type ChannelSecurityAdapter<ResolvedAccount = unknown> = {
applyConfigFixes?: (params: {
cfg: OpenClawConfig;
env: NodeJS.ProcessEnv;
}) => ChannelDoctorConfigMutation | Promise<ChannelDoctorConfigMutation>;
resolveDmPolicy?: ChannelAdapterCallback<(ctx: ChannelSecurityContext<ResolvedAccount>) => ChannelSecurityDmPolicy | null>;
dmRouting?: {
resolveDmScope?: (ctx: ChannelSecurityDmRouteContext<ResolvedAccount>) => DmScope | undefined;
resolveDmRoute?: (ctx: ChannelSecurityDmRouteContext<ResolvedAccount> & {
route: ResolvedAgentRoute;
}) => {
kind: "core" | "isolated";
} | {
sessionKey: string;
} | undefined;
};
collectWarnings?: ChannelAdapterCallback<(ctx: ChannelSecurityContext<ResolvedAccount>) => Promise<Array<string | SecurityAuditFinding>> | Array<string | SecurityAuditFinding>>;
collectAuditFindings?: ChannelAdapterCallback<(ctx: ChannelSecurityContext<ResolvedAccount> & {
sourceConfig: OpenClawConfig;
orderedAccountIds: string[];
hasExplicitAccountPath: boolean;
}) => Promise<SecurityAuditFinding[]> | SecurityAuditFinding[]>;
};
//#endregion
//#region src/wizard/prompts.d.ts
type WizardSelectOption<T = string> = {
value: T;
label: string;
hint?: string;
};
type WizardPromptNavigation = {
canGoBack?: boolean;
canGoForward?: boolean;
};
type WizardSelectParams<T = string> = {
message: string;
options: Array<WizardSelectOption<T>>;
initialValue?: T;
searchable?: boolean;
navigation?: WizardPromptNavigation;
};
type WizardMultiSelectParams<T = string> = {
message: string;
options: Array<WizardSelectOption<T>>;
initialValues?: T[];
searchable?: boolean;
navigation?: WizardPromptNavigation;
};
type WizardTextParams = {
message: string;
initialValue?: string;
placeholder?: string;
validate?: (value: string) => string | undefined;
signal?: AbortSignal;
sensitive?: boolean;
navigation?: WizardPromptNavigation;
};
type WizardConfirmParams = {
message: string;
initialValue?: boolean;
layout?: "inline" | "vertical";
navigation?: WizardPromptNavigation;
};
type WizardProgress = {
update: (message: string) => void;
stop: (message?: string) => void;
};
type WizardDeviceCodeParams = {
title: string;
code: string;
expiresInMinutes?: number;
message?: string;
};
type WizardPrompter = {
/** End a hosted flow after a required choice is declined. */
cancel?: (message: string) => never;
intro: (title: string) => Promise<void>;
outro: (message: string) => Promise<void>;
note: (message: string, title?: string) => Promise<void>;
/** Present a browser device code as structured UI when the client supports it. */
deviceCode?: (params: WizardDeviceCodeParams) => Promise<void>;
plain?: (message: string) => Promise<void>;
select: <T>(params: WizardSelectParams<T>) => Promise<T>;
multiselect: <T>(params: WizardMultiSelectParams<T>) => Promise<T[]>;
text: (params: WizardTextParams) => Promise<string>;
confirm: (params: WizardConfirmParams) => Promise<boolean>;
progress: (label: string) => WizardProgress;
/** Queue an explicit browser destination for the next interactive client step. */
openUrl?: (url: string) => Promise<void>;
disableBackNavigation?: () => void;
};
//#endregion
//#region src/channels/plugins/setup-group-access.d.ts
/**
* Group access policy selected during channel setup.
*/
type ChannelAccessPolicy = "allowlist" | "open" | "disabled";
//#endregion
//#region src/channels/plugins/setup-wizard-types.d.ts
type ChannelSetupPlugin = {
id: ChannelId;
meta: ChannelMeta;
capabilities: ChannelCapabilities;
config: ChannelConfigAdapter<unknown>;
setupContract?: ChannelOwnedSetupContract;
setup?: ChannelSetupAdapter;
setupWizard?: ChannelSetupWizard | ChannelSetupWizardAdapter;
};
/** Status block shown before users select channels during setup. */
type ChannelSetupWizardStatus = {
configuredLabel: string;
unconfiguredLabel: string;
configuredHint?: string;
unconfiguredHint?: string;
configuredScore?: number;
unconfiguredScore?: number;
resolveConfigured: (params: {
cfg: OpenClawConfig;
accountId?: string;
}) => boolean | Promise<boolean>;
resolveStatusLines?: (params: {
cfg: OpenClawConfig;
accountId?: string;
configured: boolean;
}) => string[] | Promise<string[]>;
resolveSelectionHint?: (params: {
cfg: OpenClawConfig;
accountId?: string;
configured: boolean;
}) => string | undefined | Promise<string | undefined>;
resolveQuickstartScore?: (params: {
cfg: OpenClawConfig;
accountId?: string;
configured: boolean;
}) => number | undefined | Promise<number | undefined>;
};
/** Snapshot of one credential before prompting or reusing existing config. */
type ChannelSetupWizardCredentialState = {
accountConfigured: boolean;
hasConfiguredValue: boolean;
resolvedValue?: string;
envValue?: string;
};
type ChannelSetupWizardCredentialValues = Partial<Record<string, string>>;
/** Optional explanatory note shown when its owning step is reached. */
type ChannelSetupWizardNote = {
title: string;
lines: string[];
shouldShow?: (params: {
cfg: OpenClawConfig;
accountId: string;
credentialValues: ChannelSetupWizardCredentialValues;
}) => boolean | Promise<boolean>;
};
/** Lets a wizard configure an account entirely from existing environment. */
type ChannelSetupWizardEnvShortcut = {
prompt: string;
preferredEnvVar?: string;
isAvailable: (params: {
cfg: OpenClawConfig;
accountId: string;
}) => boolean;
apply: (params: {
cfg: OpenClawConfig;
accountId: string;
}) => OpenClawConfig | Promise<OpenClawConfig>;
};
/** Declarative secret/input step for a channel account credential. */
type ChannelSetupWizardCredential = {
/** Plugin-owned key written into the runtime setup input. */
inputKey: string;
providerHint: string;
credentialLabel: string;
preferredEnvVar?: string;
helpTitle?: string;
helpLines?: string[];
envPrompt: string;
keepPrompt: string;
inputPrompt: string;
allowEnv?: (params: {
cfg: OpenClawConfig;
accountId: string;
}) => boolean;
inspect: (params: {
cfg: OpenClawConfig;
accountId: string;
}) => ChannelSetupWizardCredentialState;
shouldPrompt?: (params: {
cfg: OpenClawConfig;
accountId: string;
credentialValues: ChannelSetupWizardCredentialValues;
currentValue?: string;
state: ChannelSetupWizardCredentialState;
}) => boolean | Promise<boolean>;
applyUseEnv?: (params: {
cfg: OpenClawConfig;
accountId: string;
}) => OpenClawConfig | Promise<OpenClawConfig>;
applySet?: (params: {
cfg: OpenClawConfig;
accountId: string;
credentialValues: ChannelSetupWizardCredentialValues;
value: unknown;
resolvedValue: string;
}) => OpenClawConfig | Promise<OpenClawConfig>;
};
/** Declarative text step that can depend on resolved credentials. */
type ChannelSetupWizardTextInput = {
/** Plugin-owned key written into the runtime setup input. */
inputKey: string;
message: string;
placeholder?: string;
/** Mask input and keep any configured value server-side. */
sensitive?: boolean;
required?: boolean;
applyEmptyValue?: boolean;
helpTitle?: string;
helpLines?: string[];
confirmCurrentValue?: boolean;
keepPrompt?: string | ((value: string) => string);
currentValue?: (params: {
cfg: OpenClawConfig;
accountId: string;
credentialValues: ChannelSetupWizardCredentialValues;
}) => string | undefined | Promise<string | undefined>;
initialValue?: (params: {
cfg: OpenClawConfig;
accountId: string;
credentialValues: ChannelSetupWizardCredentialValues;
}) => string | undefined | Promise<string | undefined>;
shouldPrompt?: (params: {
cfg: OpenClawConfig;
accountId: string;
credentialValues: ChannelSetupWizardCredentialValues;
currentValue?: string;
}) => boolean | Promise<boolean>;
applyCurrentValue?: boolean;
validate?: (params: {
value: string;
cfg: OpenClawConfig;
accountId: string;
credentialValues: ChannelSetupWizardCredentialValues;
}) => string | undefined;
normalizeValue?: (params: {
value: string;
cfg: OpenClawConfig;
accountId: string;
credentialValues: ChannelSetupWizardCredentialValues;
}) => string;
applySet?: (params: {
cfg: OpenClawConfig;
accountId: string;
value: string;
}) => OpenClawConfig | Promise<OpenClawConfig>;
};
type ChannelSetupWizardAllowFromEntry = {
input: string;
resolved: boolean;
id: string | null;
};
/** Channel-specific resolver for user-entered allowlist targets. */
type ChannelSetupWizardAllowFrom = {
helpTitle?: string;
helpLines?: string[];
credentialInputKey?: string;
message: string;
placeholder: string;
invalidWithoutCredentialNote: string;
parseInputs?: (raw: string) => string[];
parseId: (raw: string) => string | null;
resolveEntries: (params: {
cfg: OpenClawConfig;
accountId: string;
credentialValues: ChannelSetupWizardCredentialValues;
entries: string[];
}) => Promise<ChannelSetupWizardAllowFromEntry[]>;
apply: (params: {
cfg: OpenClawConfig;
accountId: string;
allowFrom: string[];
}) => OpenClawConfig | Promise<OpenClawConfig>;
};
/** Declarative group/DM access policy step used by interactive setup. */
type ChannelSetupWizardGroupAccess = {
label: string;
placeholder: string;
helpTitle?: string;
helpLines?: string[];
skipAllowlistEntries?: boolean;
currentPolicy: (params: {
cfg: OpenClawConfig;
accountId: string;
}) => ChannelAccessPolicy;
currentEntries: (params: {
cfg: OpenClawConfig;
accountId: string;
}) => string[];
updatePrompt: (params: {
cfg: OpenClawConfig;
accountId: string;
}) => boolean;
setPolicy: (params: {
cfg: OpenClawConfig;
accountId: string;
policy: ChannelAccessPolicy;
}) => OpenClawConfig;
resolveAllowlist?: (params: {
cfg: OpenClawConfig;
accountId: string;
credentialValues: ChannelSetupWizardCredentialValues;
entries: string[];
prompter: Pick<WizardPrompter, "note">;
}) => Promise<unknown>;
applyAllowlist?: (params: {
cfg: OpenClawConfig;
accountId: string;
resolved: unknown;
}) => OpenClawConfig;
};
/** Optional pre-step hook for deriving helper config or credential values. */
type ChannelSetupWizardPrepare = (params: {
cfg: OpenClawConfig;
accountId: string;
credentialValues: ChannelSetupWizardCredentialValues;
runtime: ChannelSetupConfigureContext["runtime"];
prompter: WizardPrompter;
options?: ChannelSetupConfigureContext["options"];
}) => {
cfg?: OpenClawConfig;
credentialValues?: ChannelSetupWizardCredentialValues;
} | void | Promise<{
cfg?: OpenClawConfig;
credentialValues?: ChannelSetupWizardCredentialValues;
} | void>;
/** Optional post-step hook for final validation, writes, or post prompts. */
type ChannelSetupWizardFinalize = (params: {
cfg: OpenClawConfig;
accountId: string;
credentialValues: ChannelSetupWizardCredentialValues;
runtime: ChannelSetupConfigureContext["runtime"];
prompter: WizardPrompter;
options?: ChannelSetupConfigureContext["options"];
forceAllowFrom: boolean;
}) => {
cfg?: OpenClawConfig;
credentialValues?: ChannelSetupWizardCredentialValues;
} | void | Promise<{
cfg?: OpenClawConfig;
credentialValues?: ChannelSetupWizardCredentialValues;
} | void>;
/** Full declarative setup wizard consumed by the generic setup adapter. */
type ChannelSetupWizard = {
channel: string;
status: ChannelSetupWizardStatus;
introNote?: ChannelSetupWizardNote;
envShortcut?: ChannelSetupWizardEnvShortcut;
resolveAccountIdForConfigure?: (params: {
cfg: OpenClawConfig;
prompter: WizardPrompter;
options?: ChannelSetupConfigureContext["options"];
accountOverride?: string;
shouldPromptAccountIds: boolean;
listAccountIds: ChannelSetupPlugin["config"]["listAccountIds"];
defaultAccountId: string;
}) => string | Promise<string>;
resolveShouldPromptAccountIds?: (params: {
cfg: OpenClawConfig;
options?: ChannelSetupConfigureContext["options"];
shouldPromptAccountIds: boolean;
}) => boolean;
prepare?: ChannelSetupWizardPrepare;
stepOrder?: "credentials-first" | "text-first";
credentials: ChannelSetupWizardCredential[];
textInputs?: ChannelSetupWizardTextInput[];
finalize?: ChannelSetupWizardFinalize;
completionNote?: ChannelSetupWizardNote;
dmPolicy?: ChannelSetupDmPolicy;
allowFrom?: ChannelSetupWizardAllowFrom;
groupAccess?: ChannelSetupWizardGroupAccess;
disable?: (cfg: OpenClawConfig) => OpenClawConfig;
onAccountRecorded?: ChannelSetupWizardAdapter["onAccountRecorded"];
};
/** Runtime options for selecting and configuring one or more channels. */
type SetupChannelsOptions = {
/** Workspace already selected by the caller, used for trusted plugin discovery. */
workspaceDir?: string;
allowDisable?: boolean;
allowIMessageInstall?: boolean;
allowSignalInstall?: boolean;
/** Revalidate host authority immediately before an installer or other durable effect. */
beforePersistentEffect?: () => Promise<void>;
onSelection?: (selection: ChannelId[]) => void;
onPostWriteHook?: (hook: ChannelOnboardingPostWriteHook) => void;
accountIds?: Partial<Record<ChannelId, string>>;
onAccountId?: (channel: ChannelId, accountId: string) => void;
onResolvedPlugin?: (channel: ChannelId, plugin: ChannelSetupPlugin) => void;
promptAccountIds?: boolean;
forceAllowFromChannels?: ChannelId[];
deferStatusUntilSelection?: boolean;
/**
* The controlling client finishes device linking itself after config is
* written (e.g. Control UI renders the WhatsApp QR via web.login.*), so
* setup surfaces must skip terminal-interactive login/link prompts.
*/
deferDeviceLinkToClient?: boolean;
skipStatusNote?: boolean;
skipDmPolicyPrompt?: boolean;
skipConfirm?: boolean;
quickstartDefaults?: boolean;
initialSelection?: ChannelId[];
/** Finish after the explicitly targeted channel is configured or paused. */
finishAfterInitialSelection?: boolean;
secretInputMode?: "plaintext" | "ref";
};
type ChannelSetupStatus = {
channel: ChannelId;
configured: boolean;
statusLines: string[];
selectionHint?: string;
quickstartScore?: number;
};
/** Shared context for status checks before channel selection. */
type ChannelSetupStatusContext = {
cfg: OpenClawConfig;
options?: SetupChannelsOptions;
accountOverrides: Partial<Record<ChannelId, string>>;
};
/** Shared context for applying setup changes for a selected channel. */
type ChannelSetupConfigureContext = {
cfg: OpenClawConfig;
runtime: RuntimeEnv;
prompter: WizardPrompter;
options?: SetupChannelsOptions;
accountOverrides: Partial<Record<ChannelId, string>>;
shouldPromptAccountIds: boolean;
forceAllowFrom: boolean;
};
/** Context passed after setup has written config to disk. */
type ChannelOnboardingPostWriteContext = {
previousCfg: OpenClawConfig;
cfg: OpenClawConfig;
accountId: string;
runtime: RuntimeEnv;
};
/** Deferred hook for channel work that must run after config persistence. */
type ChannelOnboardingPostWriteHook = {
channel: ChannelId;
accountId: string;
run: (ctx: {
cfg: OpenClawConfig;
runtime: RuntimeEnv;
}) => Promise<void> | void;
};
type ChannelSetupResult = {
cfg: OpenClawConfig;
accountId?: string;
completion?: "configured";
} | {
cfg: OpenClawConfig;
/** Paused setup is persisted without configured-account hooks or routing. */
completion: "paused";
accountId?: never;
};
type ChannelSetupConfiguredResult = ChannelSetupResult | "skip";
type ChannelSetupInteractiveContext = ChannelSetupConfigureContext & {
configured: boolean;
label: string;
};
/** Optional direct-message policy contract exposed by setup adapters. */
type ChannelSetupDmPolicy = {
label: string;
channel: ChannelId;
policyKey: string;
allowFromKey: string;
resolveConfigKeys?: (cfg: OpenClawConfig, accountId?: string) => {
policyKey: string;
allowFromKey: string;
};
getCurrent: (cfg: OpenClawConfig, accountId?: string) => DmPolicy;
setPolicy: (cfg: OpenClawConfig, policy: DmPolicy, accountId?: string) => OpenClawConfig;
promptAllowFrom?: (params: {
cfg: OpenClawConfig;
prompter: WizardPrompter;
accountId?: string;
}) => Promise<OpenClawConfig>;
};
/** Imperative adapter consumed by onboarding and setup flows. */
type ChannelSetupWizardAdapter = {
channel: ChannelId;
getStatus: (ctx: ChannelSetupStatusContext) => Promise<ChannelSetupStatus>;
configure: (ctx: ChannelSetupConfigureContext) => Promise<ChannelSetupResult>;
configureInteractive?: (ctx: ChannelSetupInteractiveContext) => Promise<ChannelSetupConfiguredResult>;
configureWhenConfigured?: (ctx: ChannelSetupInteractiveContext) => Promise<ChannelSetupConfiguredResult>;
afterConfigWritten?: (ctx: ChannelOnboardingPostWriteContext) => Promise<void> | void;
dmPolicy?: ChannelSetupDmPolicy;
onAccountRecorded?: (accountId: string, options?: SetupChannelsOptions) => void;
disable?: (cfg: OpenClawConfig) => OpenClawConfig;
};
//#endregion
//#region src/channels/plugins/types.plugin.d.ts
/** Full capability contract for a native channel plugin. */
type ChannelPluginSetupWizard = ChannelSetupWizard | ChannelSetupWizardAdapter;
type ChannelGatewayMethodDescriptor = {
name: string;
scope?: OperatorScope;
description?: string;
};
type ChannelPlugin<ResolvedAccount = any, Probe = unknown, Audit = unknown> = {
id: ChannelId;
meta: ChannelMeta;
capabilities: ChannelCapabilities;
defaults?: {
queue?: {
debounceMs?: number;
};
};
reload?: {
configPrefixes: string[];
noopPrefixes?: string[];
/**
* Opt into restarting only the changed non-default named account.
* Set only when sibling account resolution and lifecycle state are isolated and
* account stop fully settles owned work. Shared, default, removed, or unresolved
* account changes still restart the whole channel.
*/
accountScopedRestart?: boolean;
};
setupWizard?: ChannelPluginSetupWizard;
config: ChannelConfigAdapter<ResolvedAccount>;
configSchema?: ChannelConfigSchema;
/** Channel-owned typed setup contract. Preferred over the legacy shared input adapter. */
setupContract?: ChannelOwnedSetupContract;
/** @deprecated Use setupContract for new plugins. */
setup?: ChannelSetupAdapter;
pairing?: ChannelPairingAdapter;
security?: ChannelSecurityAdapter<ResolvedAccount>;
groups?: ChannelGroupAdapter;
mentions?: ChannelMentionAdapter;
outbound?: ChannelOutboundAdapter;
status?: ChannelStatusAdapter<ResolvedAccount, Probe, Audit>;
gatewayMethods?: string[];
gatewayMethodDescriptors?: ChannelGatewayMethodDescriptor[];
gateway?: ChannelGatewayAdapter<ResolvedAccount>;
auth?: ChannelAuthAdapter;
approvalCapability?: ChannelApprovalCapability;
elevated?: ChannelElevatedAdapter;
commands?: ChannelCommandAdapter;
lifecycle?: ChannelLifecycleAdapter;
secrets?: ChannelSecretsAdapter;
allowlist?: ChannelAllowlistAdapter;
doctor?: ChannelDoctorAdapter;
bindings?: ChannelConfiguredBindingProvider;
conversationBindings?: ChannelConversationBindingSupport;
streaming?: ChannelStreamingAdapter;
threading?: ChannelThreadingAdapter;
message?: ChannelMessageAdapterShape;
messaging?: ChannelMessagingAdapter;
agentPrompt?: ChannelAgentPromptAdapter;
directory?: ChannelDirectoryAdapter;
resolver?: ChannelResolverAdapter;
actions?: ChannelMessageActionAdapter;
heartbeat?: ChannelHeartbeatAdapter;
agentTools?: ChannelAgentToolFactory | ChannelAgentTool[];
};
//#endregion
//#region src/skills/types.d.ts
type SkillTelemetrySource = "bundled" | "unknown" | "workspace";
type SkillUsagePath = {
/** Path visible to the tool runtime when it reads SKILL.md. */
readPath: string;
/** Canonical source SKILL.md path used as the lifecycle identity. */
skillFile: string;
skillName: string;
skillSource: SkillTelemetrySource;
};
type ExplicitSkillSelection = {
name: string;
path: string;
};
type SkillEligibilityContext = {
nodeSkills?: {
canExec: boolean;
node?: string;
};
remote?: {
platforms: string[];
hasBin: (bin: string) => boolean;
hasAnyBin: (bins: string[]) => boolean;
note?: string;
};
};
type SkillSnapshot = {
librarySelections?: SkillLibrarySelection[];
prompt: string;
/** Complete eligible sync identities, including skills hidden from the model prompt. */
skills: Array<{
name: string;
/** Config key can differ from the prompt-facing skill name. */
skillKey?: string;
primaryEnv?: string;
requiredEnv?: string[];
}>;
/** Normalized agent-level filter used to build this snapshot; undefined means unrestricted. */
skillFilter?: string[];
/** Sparse per-session overlay applied after the agent-level filter. */
skillOverrides?: Record<string, boolean>;
/** Effective node-exec eligibility used to select connected node-hosted skills. */
nodeSkillsEligibility?: SkillEligibilityContext["nodeSkills"];
resolvedSkills?: Skill[];
/** Present only when a session merges skills from distinct agent and execution roots. */
skillRoots?: {
agentWorkspaceDir: string;
executionSkillsDir: string;
};
version?: number;
promptFormatVersion?: number;
};
//#endregion
//#region src/agents/failover/signal.d.ts
/** Persisted and wire-visible failover reason codes. Spellings are frozen. */
declare const FAILOVER_REASONS: readonly ["auth", "auth_permanent", "format", "rate_limit", "overloaded", "billing", "server_error", "timeout", "tls_certificate", "context_overflow", "model_not_found", "session_expired", "empty_response", "no_error_details", "unclassified", "unknown"];
type FailoverReason = (typeof FAILOVER_REASONS)[number];
//#endregion
//#region src/agents/agent-scope.d.ts
type ModelFallbackAvailability = {
kind: "active";
models: string[];
source: "explicit" | "inherited";
} | {
kind: "none_configured";
source: "explicit" | "inherited";
} | {
kind: "disabled_by_model_override";
} | {
kind: "disabled_by_model_selection_lock";
};
//#endregion
//#region src/auto-reply/reply/normalize-reply-skip-reason.d.ts
type NormalizeReplySkipReason = "empty" | "silent" | "heartbeat" | "channel_transform";
//#endregion
//#region src/cron/runtime-authority.d.ts
type CronRuntimeAuthority = Readonly<{
version: 1;
/** Concrete harness runtime that alone may consume this opaque authority. */
runtimeId: string;
/** Runtime-owned payload discriminator; core never interprets its value. */
namespace: string;
payload: Readonly<Record<string, unknown>>;
}>;
//#endregion
//#region src/cron/types-shared.d.ts
/** Optional dynamic-cadence bounds for one cron job. */
type CronPacing = {
min?: string;
max?: string;
};
/** Shared persisted cron job envelope used by runtime and external config shapes. */
type CronJobBase<TSchedule, TSessionTarget, TWakeMode, TPayload, TDelivery, TFailureAlert> = {
id: string;
agentId?: string;
sessionKey?: string;
name: string;
description?: string;
enabled: boolean;
deleteAfterRun?: boolean;
createdAtMs: number;
updatedAtMs: number;
schedule: TSchedule;
pacing?: CronPacing;
sessionTarget: TSessionTarget;
wakeMode: TWakeMode;
payload: TPayload;
delivery?: TDelivery;
failureAlert?: TFailureAlert;
};
//#endregion
//#region src/cron/types.d.ts
/** Supported schedule forms persisted in cron job specs. */
type CronSchedule = {
kind: "at";
at: string;
} | {
kind: "every";
everyMs: number;
anchorMs?: number;
} | {
kind: "cron";
expr: string;
tz?: string;
/** Optional deterministic stagger window in milliseconds (0 keeps exact schedule). */
staggerMs?: number;
} | {
/**
* Event-driven (non-time) trigger: the job fires once when a gateway-owned
* watcher process running `command` exits. The watcher lives under the
* gateway ProcessSupervisor, NOT inside any agent turn's process tree, so
* it survives the per-turn spawn-and-kill teardown that CLI backends apply
* (#71662). On exit the job runs through the normal cron run pipeline, so
* delivery to the bound session works exactly like a scheduled main job.
* `computeNextRunAtMs` returns undefined for this kind (never time-due).
*/
kind: "on-exit";
command: string;
cwd?: string;
} | {
/** Event-driven source whose supervised argv emits payload-triggering lines. */
kind: "stream";
command: string[];
cwd?: string;
mode?: "line" | "match";
/** JavaScript regular-expression source, required when mode is "match". */
match?: string;
batchMs?: number;
maxBatchBytes?: number;
};
/** Runtime target that decides whether a job joins main, isolated, or a named session. */
type CronSessionTarget = "main" | "isolated" | "current" | `session:${string}`;
/** Wake policy for main-session jobs waiting on heartbeat/user activity. */
type CronWakeMode = "next-heartbeat" | "now";
/** Messaging channel id accepted by cron delivery settings. */
type CronMessageChannel = ChannelId;
/** Delivery mode for job completion output. */
type CronDeliveryMode = "none" | "announce" | "webhook";
/** Completion delivery configuration for cron job output. */
type CronDelivery = {
mode: CronDeliveryMode;
channel?: CronMessageChannel;
to?: string;
/** Explicit thread/topic id for channels that support threaded delivery. */
threadId?: string | number;
/** Explicit channel account id for multi-account setups (e.g. multiple Telegram bots). */
accountId?: string;
bestEffort?: boolean;
/** Additional webhook destination used when a job must keep chat delivery. */
completionDestination?: CronCompletionDestination;
/** Separate destination for failure notifications. */
failureDestination?: CronFailureDestination;
};
/** Webhook completion destination used alongside chat delivery. */
type CronCompletionDestination = {
mode: "webhook";
to?: string;
};
/** Destination override for failed-run notifications. */
type CronFailureDestination = {
channel?: CronMessageChannel;
to?: string;
accountId?: string;
mode?: "announce" | "webhook";
};
/** Partial failure-destination update shape; null clears individual override fields. */
type CronFailureDestinationPatch = {
channel?: CronMessageChannel | null;
to?: string | null;
accountId?: string | null;
mode?: "announce" | "webhook" | null;
};
/** Partial delivery update shape; null clears optional delivery destinations or fields. */
type CronDeliveryPatch = Partial<Pick<CronDelivery, "mode" | "bestEffort">> & {
channel?: CronMessageChannel | null;
to?: string | null;
threadId?: string | number | null;
accountId?: string | null;
completionDestination?: CronCompletionDestination | null;
failureDestination?: CronFailureDestinationPatch | null;
};
/** Execution outcome, separate from delivery outcome. */
type CronRunStatus = "ok" | "error" | "skipped";
/** Delivery outcome for completion or failure-notification sends. */
type CronDeliveryStatus = "delivered" | "not-delivered" | "unknown" | "not-requested";
/** Bounded diagnostic bundle stored on the run outcome. */
type CronRunDiagnostics = NonNullable<CronRunLogEntry["diagnostics"]>;
/** Failure alert policy persisted on a cron job. */
type CronFailureAlert = {
after?: number;
channel?: CronMessageChannel;
to?: string;
cooldownMs?: number;
/** When true, consecutive skipped runs count toward the alert threshold. */
includeSkipped?: boolean;
/** Delivery mode: announce (via messaging channels) or webhook (HTTP POST). */
mode?: "announce" | "webhook";
/** Account ID for multi-account channel configurations. */
accountId?: string;
};
/** Partial failure-alert update; null clears an inherited field override. */
type CronFailureAlertPatch = { [K in keyof CronFailureAlert]?: CronFailureAlert[K] | null; };
/** Payload variants cron can execute in main-session or detached modes. */
type CronPayload = ({
kind: "systemEvent";
text: string;
} & CronPayloadToolAllow) | (CronAgentTurnPayload & CronPayloadToolAllow) | (CronCommandPayload & CronPayloadToolAllow) | (CronScriptPayload & CronPayloadToolAllow) | ({
kind: "heartbeat";
} & CronPayloadToolAllow) | ({
kind: "skillCollectionReview";
} & CronPayloadToolAllow);
/** Partial payload update shape used by cron patch/edit flows. */
type CronPayloadPatch = ({
kind: "systemEvent";
text?: string;
} & CronPayloadToolAllowPatch) | (CronAgentTurnPayloadPatch & CronPayloadToolAllowPatch) | (CronCommandPayloadPatch & CronPayloadToolAllowPatch) | (CronScriptPayloadPatch & CronPayloadToolAllowPatch) | ({
kind: "heartbeat";
} & CronPayloadToolAllowPatch) | ({
kind: "skillCollectionReview";
} & CronPayloadToolAllowPatch);
type CronPayloadToolAllow = {
/** Restricts agentTurn execution, or the trigger runtime for other payload kinds. */
toolsAllow?: string[];
/** Server-managed marker for auto-stamped defaults; explicit restrictions omit it. */
toolsAllowIsDefault?: boolean;
};
type CronPayloadToolAllowPatch = {
toolsAllow?: string[] | null;
toolsAllowIsDefault?: boolean;
};
type CronAgentTurnPayloadFields = {
message: string;
/** Optional model override (provider/model or alias). */
model?: string;
/** Optional per-job fallback models; overrides agent/global fallbacks when defined. */
fallbacks?: string[];
thinking?: string;
timeoutSeconds?: number;
allowUnsafeExternalContent?: boolean;
/** Immutable external hook provenance for async dispatch. */
externalContentSource?: HookExternalContentSource;
/** If true, run with lightweight bootstrap context. */
lightContext?: boolean;
};
type CronAgentTurnPayload = {
kind: "agentTurn";
} & CronAgentTurnPayloadFields;
type CronAgentTurnPayloadPatch = {
kind: "agentTurn";
} & Partial<Omit<CronAgentTurnPayloadFields, "model" | "fallbacks" | "toolsAllow" | "thinking">> & {
model?: string | null;
fallbacks?: string[] | null;
toolsAllow?: string[] | null;
thinking?: string | null;
};
type CronCommandPayloadFields = {
/** Explicit argv vector to execute. Use a shell wrapper argv for shell syntax. */
argv: string[];
cwd?: string;
env?: Record<string, string>;
input?: string;
timeoutSeconds?: number;
noOutputTimeoutSeconds?: number;
outputMaxBytes?: number;
};
type CronCommandPayload = {
kind: "command";
} & CronCommandPayloadFields;
type CronCommandPayloadPatch = {
kind: "command";
} & Partial<CronCommandPayloadFields>;
type CronScriptPayloadFields = {
script: string;
timeoutSeconds?: number;
toolBudget?: number;
};
type CronScriptPayload = {
kind: "script";
} & CronScriptPayloadFields;
type CronScriptPayloadPatch = {
kind: "script";
} & Partial<CronScriptPayloadFields>;
/** Mutable runtime state persisted beside the immutable cron job spec. */
type CronJobState = {
nextRunAtMs?: number;
/**
* When the current scheduling inputs took effect. Restart catch-up replays a
* missed slot only when the slot is newer than this, because slots computed
* from a freshly edited schedule never existed under the old one. Absent on
* jobs whose schedule has not changed, where every computed slot is real.
*/
scheduleActivatedAtMs?: number;
/** Exact startup catch-up slot protected from future-slot repair across restarts. */
startupCatchupAtMs?: number;
/** Exact paced completion slot protected from future-slot repair until consumed. */
pacedNextRunAtMs?: number;
/** Exact recurring slot retained across an out-of-band manual force run. */
forcePreservedNextRunAtMs?: number;
/** Durable pre-admission reservation. Cleared on restart without recording a run. */
queuedAtMs?: number;
runningAtMs?: number;
lastRunAtMs?: number;
/** Preferred execution outcome field. */
lastRunStatus?: CronRunStatus;
/** @deprecated Use lastRunStatus. */
lastStatus?: "ok" | "error" | "skipped";
lastError?: string;
lastDiagnostics?: CronRunDiagnostics;
lastDiagnosticSummary?: string;
/** Classified reason for the last error (when available). */
lastErrorReason?: FailoverReason;
lastDurationMs?: number;
/** Number of consecutive execution errors (reset on success). Used for backoff. */
consecutiveErrors?: number;
/** Durable explanation for a scheduler-owned automatic disable transition. */
autoDisabled?: {
reason: "consecutive-failures" | "schedule-errors";
atMs: number;
consecutiveErrors: number;
};
/** Number of consecutive skipped executions (reset on success or error). */
consecutiveSkipped?: number;
/** Last failure alert timestamp (ms since epoch) for cooldown gating. */
lastFailureAlertAtMs?: number;
/** Number of consecutive schedule computation errors. Auto-disables job after threshold. */
scheduleErrorCount?: number;
/** Timestamp of the last trigger script evaluation. */
lastTriggerEvalAtMs?: number;
/** Number of completed trigger script evaluations. */
triggerEvalCount?: number;
/** Timestamp of the last trigger evaluation that fired. */
lastTriggerFireAtMs?: number;
/** JSON state returned by the last trigger script evaluation. */
triggerState?: unknown;
/** Current gateway-owned stream source lifecycle state. */
streamStatus?: "starting" | "running" | "restarting" | "stopped" | "disabled" | "error";
streamError?: string;
streamConsecutiveFailures?: number;
streamRestartExhausted?: boolean;
streamSourceIdentity?: string;
streamDroppedBatches?: number;
streamCoalescedBatches?: number;
streamLastStartedAtMs?: number;
streamLastExitAtMs?: number;
/** Explicit delivery outcome, separate from execution outcome. */
lastDeliveryStatus?: CronDeliveryStatus;
/** Delivery-specific error text when available. */
lastDeliveryError?: string;
/** Intentional non-delivery reason for the last run, when recorded by the dispatcher. */
deliverySuppressionReason?: NormalizeReplySkipReason;
/** Whether the last run's output was delivered to the target channel. */
lastDelivered?: boolean;
/** Whether the last failed run's failure notification was delivered to the target channel. */
lastFailureNotificationDelivered?: boolean;
/** Delivery outcome for the last failed run's failure notification. */
lastFailureNotificationDeliveryStatus?: CronDeliveryStatus;
/** Delivery-specific error for the last failed run's failure notification. */
lastFailureNotificationDeliveryError?: string;
};
type CronTrigger = {
script: string;
once?: boolean;
};
/** Public cron job contract with spec fields and mutable run state. */
type CronJob = CronJobBase<CronSchedule, CronSessionTarget, CronWakeMode, CronPayload, CronDelivery, CronFailureAlert | false> & {
declarationKey?: string;
displayName?: string;
owner?: {
agentId?: string;
sessionKey?: string;
/** Authenticated account that created this scheduled authority envelope. */
accountId?: string;
};
/** Server-authored provenance for requester-scoped scheduled tool authority. */
scheduledToolPolicy?: CronScheduledToolPolicy;
trigger?: CronTrigger;
state: CronJobState;
};
/** Store-only proof omitted from public Gateway results and the CronJob wire/type contract. */
type CronToolsAllowProvenance = {
version: 1;
source: "final-executable-surface";
/** Store-private creator origin; missing legacy facts normalize to unknown. */
callerOrigin?: CronScheduledToolCallerOrigin;
};
/** Persisted row shape; public Gateway and wire contracts use CronJob. */
type CronStoredJob = CronJob & {
/** Immutable revisions inherited from the authorized creator session, never human mutation authority. */
skillLibrarySelections?: SessionEntry["skillLibrarySelections"];
/** Immutable creator provenance stamped by the trusted cron creation seam. */
createdActor?: SessionCreatedActor;
toolsAllowProvenance?: CronToolsAllowProvenance;
toolsAllowExecTarget?: CronToolsAllowExecTarget;
/** Exact expected pin for jobs created from a verified host-owned exec projection. */
toolsAllowExecTargetRequirement?: CronToolsAllowExecTargetRequirement;
/** Runtime-private authority omitted from public Gateway and wire contracts. */
runtimeAuthority?: CronRuntimeAuthority;
/** Authority was explicitly cleared and must be reauthorized before app reuse. */
runtimeAuthorityRecoveryRequired?: true;
};
type CronJobStateInput = Partial<Omit<CronJobState, "autoDisabled" | "scheduleActivatedAtMs" | "streamSourceIdentity">>;
/** Create input accepted by cron APIs before id/timestamps/state are assigned. */
type CronJobCreate = Omit<CronJob, "id" | "createdAtMs" | "updatedAtMs" | "state" | "scheduledToolPolicy"> & {
/** Internal callers can reserve a durable id before creation; public cron.add omits this. */
id?: string;
state?: CronJobStateInput;
};
/** Patch input accepted by cron APIs without allowing immutable identity fields. */
type CronJobPatch = Partial<Omit<CronJob, "id" | "createdAtMs" | "state" | "payload" | "delivery" | "failureAlert" | "declarationKey" | "displayName" | "owner" | "scheduledToolPolicy" | "pacing" | "trigger">> & {
displayName?: string | null;
pacing?: CronPacing | null;
trigger?: CronTrigger | null;
payload?: CronPayloadPatch;
delivery?: CronDeliveryPatch;
failureAlert?: CronFailureAlertPatch | false | null;
state?: CronJobStateInput;
};
//#endregion
export { resolvePollMaxSelections as $, PortalSummary as $n, SessionGitHubPublishParams as $r, ReplyPayload as $t, resolveTextChunkLimit as A, PluginManifestDashboardActionVerb as Ai, CliSessionBinding as An, UsersGitHubAuthorizeStartResult as Ar, LegacyMediaContextKey as At, ChannelAccountSnapshot as B, UnifiedModelCatalogKind as Bi, SourceReplyDeliveryMode as Bn, SessionCatalogShareRoute as Br, ExecutionIdentityAdmissionToken as Bt, OutboundDeliveryFormattingOptions as C, PluginBundleFormat as Ci, MediaUnderstandingOutput as Cn, SystemAgentWizardCancel as Cr, TurnAdoptionLifecycle as Ct, chunkText as D, PluginManifestContracts as Di, AuthProfileCredential as Dn, UsersAuthConnectStartResult as Dr, UserTurnTranscriptRecorder as Dt, chunkMarkdownTextWithMode as E, PluginFormat as Ei, ApiKeyCredential as En, UsersAuthConnectCatalogResult as Er, UserTurnTranscriptAnnotation as Et, SecurityAuditFinding as F, ChannelConfigUiHint as Fi, SessionToolOverrides as Fn, UsersUnlinkAuthProfileResult as Fr, TranscriptEntryAnchor as Ft, ChannelOutboundTargetMode as G, CronToolsAllowExecTarget as Gn, SessionPermissionMode as Gr, AgentToolResult as Gt, ChannelGroupContext as H, ChannelRouteRef as Hn, SessionsCatalogContinueParams as Hr, CompactionResult as Ht, buildAgentSessionKey as I, JsonSchemaObject as Ii, SessionSystemPromptReport as In, ToolsGitHubAuthorizePollResult as Ir, TranscriptTurnAdmission as It, ConversationReadInvocationOrigin as J, WorkerTranscriptMessage as Jn, ApprovalPresentation as Jr, CustomMessage as Jt, ChannelStatusIssue as K, WorkerConnectParams as Kn, WorkerInferenceModelRef as Kr, AgentToolUpdateCallback as Kt, resolveAgentRoute as L, ModelCatalogContextWindowOption as Li, SourceInfo as Ln, ToolsGitHubAuthorizeStartResult as Lr, TranscriptTurnBoundary as Lt, OutboundPayloadDeliveryOutcome as M, PluginManifestMcpServer as Mi, SessionContextBudgetStatus as Mn, UsersListAuthLinksResult as Mr, PromptImageOrderEntry as Mt, OutboundPayloadDeliverySuppressionReason as N, PluginKind as Ni, SessionEntry as Nn, UsersListModelAccountsResult as Nr, MediaKind as Nt, chunkTextWithMode as O, PluginManifestControlUi as Oi, AuthProfileStore as On, UsersAuthConnectStatusResult as Or, InputProvenance as Ot, ChannelRuntimeSurface as P, ChannelConfigSchema as Pi, SessionPluginJsonValue as Pn, UsersSelectModelAccountResult as Pr, mediaKindFromMime as Pt, PollInput as Q, PortalOpenResult as Qn, SessionGitHubPublicationResult as Qr, ReplyMediaAttachment as Qt, BaseProbeResult as R, ModelCatalogStatus as Ri, SessionCreatedActor as Rn, AgentWaitParams as Rr, AgentPlanStep as Rt, OutboundIdentity as S, PluginOrigin as Si, StructuredExtractionInput as Sn, SystemAgentChatQuestion as Sr, TaskSuggestionDeliveryMode as St, chunkMarkdownText as T, PluginDiagnostic as Ti, resolveAgentWorkspaceDir as Tn, PersonalGitHubStatus as Tr, UserTurnTranscriptAdmissionReceipt as Tt, ChannelMessageActionAdapter as U, CronScheduledToolCallerOrigin as Un, SessionsCatalogReadParams as Ur, AgentMessage as Ut, ChannelDirectoryEntry as V, RuntimeEnv as Vi, DeliveryContext as Vn, SessionsCatalogArchiveParams as Vr, AgentRunTimeoutPhase as Vt, ChannelMeta as W, CronScheduledToolPolicy as Wn, SessionsCatalogReadResult as Wr, AgentTool as Wt, OutboundReplyFacts as X, WizardNextResult as Xn, GitHubPublicationPublisher as Xr, ToolExecutionMode as Xt, MessageReceipt as Y, WizardAnswer as Yn, SessionApprovalReplay as Yr, StreamFn as Yt, RenderedMessageBatchPlanItem as Z, WizardStep as Zn, SessionGitHubConfirmParams as Zr, ToolLoopWarning as Zt, ChannelPlugin as _, PluginMetadataSnapshotOwnerMaps as _i, ApprovalScope as _n, UsersMentionableParams as _r, PluginHookChannelContext as _t, CronRunStatus as a, SkillsLibraryActivateResult as ai, ChannelApprovalKind as an, SessionPlacementDiskSpace as ar, FinalizedRuntimeMsgContext as at, ChannelDeliveryCapabilities as b, PluginCompatCode as bi, MediaUnderstandingDecision as bn, WorkerEnvironmentState as br, GetReplyOptions as bt, CronRuntimeAuthority as c, SkillsLibraryReceipt as ci, PluginApprovalRequest as cn, QuestionAnswers as cr, MsgContext as ct, FailoverReason as d, Result as di, ExecApprovalRequest as dn, QuestionResolvedEvent as dr, SupplementalContextFacts as dt, ConnectParams as ei, SessionWriterDeliveryAuthority as en, Snapshot as er, OutboundSendDeps as et, ExplicitSkillSelection as f, resolveStateDir as fi, ExecApprovalRequestPayload as fn, QuestionWaitAnswerResult as fr, TemplateContext as ft, SkillUsagePath as g, PluginMetadataSnapshot as gi, ExecTarget as gn, MentionsListResult as gr, CommandTurnKind as gt, SkillTelemetrySource as h, PluginMetadataRegistryView as hi, ExecSecurity as hn, NodeSkillDescriptor as hr, CommandTurnContext as ht, CronPayload as i, SkillLibrarySelection as ii, ReplyPayloadDelivery as in, SessionMoveTarget as ir, FinalizedMsgContext as it, OutboundDeliveryResult as j, PluginManifestDashboardDataBinding as ji, GroupKeyResolution as jn, UsersLinkAuthProfileResult as jr, MediaFact as jt, resolveChunkMode as k, PluginManifestDashboard as ki, OAuthCredential as kn, UsersGitHubAuthorizePollResult as kr, TranscriptSenderIdentity as kt, NormalizeReplySkipReason as l, ChannelId as li, PluginApprovalRequestPayload as ln, QuestionRecord as lr, OriginatingChannelType as lt, SkillSnapshot as m, ConfigWriteAfterWrite as mi, ExecMode as mn, NodePluginToolDescriptor as mr, HistoryMediaEntry as mt, CronJobCreate as n, RequestFrame as ni, MessagePresentation as nn, SessionsCompanionAskResult as nr, OutboundMediaAccess as nt, CronStoredJob as o, SkillsLibraryListResult as oi, SystemAgentApprovalRequest as on, SessionPlacementRunner as or, InboundSourceModality as ot, SkillEligibilityContext as p, ConfigReplaceResult as pi, ExecAsk as pn, NodeHostStatsPayload as pr, HistoryEntry as pt, ChannelThreadingToolContext as q, WorkerTranscriptCommitParams as qn, WorkerInferenceOptions as qr, BashExecutionMessage as qt, CronJobPatch as r, SkillLibraryFile as ri, MessagePresentationAction as rn, SessionsCompanionStateResult as rr, OutboundMediaReadFile as rt, CronToolsAllowProvenance as s, SkillsLibraryReadResult as si, SystemAgentApprovalRequestPayload as sn, Question as sr, MentionSource as st, CronJob as t, ErrorShape as ti, LegacyInteractiveReply as tn, SessionObserverDigest as tr, IdentifierAuthentication as tt, ModelFallbackAvailability as u, ChatChannelId as ui, ExecApprovalDecision as un, QuestionResolveResult as ur, SessionTranscriptContext as ut, WizardPrompter as v, PluginManifestRecord as vi, NormalizedLocation as vn, UsersMentionableResult as vr, InboundEventKind as vt, chunkByNewline as w, PluginConfigUiHint as wi, resolveAgentDir as wn, ChatAccountSelection as wr, UserTurnInput as wt, ChannelOutboundAdapter as x, PluginDependencyStatus as xi, MediaUnderstandingProvider as xn, WorkerTunnelStatus as xr, PartialReplyPayload as xt, ChannelPairingAdapter as y, PluginTrust as yi, OutboundLocation as yn, ScopeUpgradeResult as yr, BlockReplyContext as yt, BaseTokenResolution as z, UnifiedModelCatalogEntry as zi, SessionCreatedVia as zn, SessionCatalogHost as zr, ExecutionIdentityAdmissionFacts as zt };