import type { BlockStreamingChunkConfig, BlockStreamingCoalesceConfig, HumanDelayConfig, TypingMode, } from "./types.base.js"; import type { SandboxBrowserSettings, SandboxDockerSettings, SandboxPruneSettings, } from "./types.sandbox.js"; import type { MemorySearchConfig } from "./types.tools.js"; export type AgentModelEntryConfig = { alias?: string; /** Provider-specific API parameters (e.g., GLM-4.7 thinking mode). */ params?: Record; }; export type AgentModelListConfig = { primary?: string; fallbacks?: string[]; }; export type AgentContextPruningConfig = { mode?: "off" | "cache-ttl"; /** TTL to consider cache expired (duration string, default unit: minutes). */ ttl?: string; keepLastAssistants?: number; softTrimRatio?: number; hardClearRatio?: number; minPrunableToolChars?: number; tools?: { allow?: string[]; deny?: string[]; }; softTrim?: { maxChars?: number; headChars?: number; tailChars?: number; }; hardClear?: { enabled?: boolean; placeholder?: string; }; }; export type CliBackendConfig = { /** CLI command to execute (absolute path or on PATH). */ command: string; /** Base args applied to every invocation. */ args?: string[]; /** Output parsing mode (default: json). */ output?: "json" | "text" | "jsonl"; /** Output parsing mode when resuming a CLI session. */ resumeOutput?: "json" | "text" | "jsonl"; /** Prompt input mode (default: arg). */ input?: "arg" | "stdin"; /** Max prompt length for arg mode (if exceeded, stdin is used). */ maxPromptArgChars?: number; /** Extra env vars injected for this CLI. */ env?: Record; /** Env vars to remove before launching this CLI. */ clearEnv?: string[]; /** Flag used to pass model id (e.g. --model). */ modelArg?: string; /** Model aliases mapping (config model id → CLI model id). */ modelAliases?: Record; /** Flag used to pass session id (e.g. --session-id). */ sessionArg?: string; /** Extra args used when resuming a session (use {sessionId} placeholder). */ sessionArgs?: string[]; /** Alternate args to use when resuming a session (use {sessionId} placeholder). */ resumeArgs?: string[]; /** When to pass session ids. */ sessionMode?: "always" | "existing" | "none"; /** JSON fields to read session id from (in order). */ sessionIdFields?: string[]; /** Flag used to pass system prompt. */ systemPromptArg?: string; /** System prompt behavior (append vs replace). */ systemPromptMode?: "append" | "replace"; /** When to send system prompt. */ systemPromptWhen?: "first" | "always" | "never"; /** Flag used to pass image paths. */ imageArg?: string; /** How to pass multiple images. */ imageMode?: "repeat" | "list"; /** Serialize runs for this CLI. */ serialize?: boolean; }; export type AgentDefaultsConfig = { /** Primary model and fallbacks (provider/model). */ model?: AgentModelListConfig; /** Optional image-capable model and fallbacks (provider/model). */ imageModel?: AgentModelListConfig; /** Model catalog with optional aliases (full provider/model keys). */ models?: Record; /** Agent working directory (preferred). Used as the default cwd for agent runs. */ workspace?: string; /** Skip bootstrap (BOOTSTRAP.md creation, etc.) for pre-configured deployments. */ skipBootstrap?: boolean; /** Max chars for injected bootstrap files before truncation (default: 20000). */ bootstrapMaxChars?: number; /** Optional IANA timezone for the user (used in system prompt; defaults to host timezone). */ userTimezone?: string; /** Time format in system prompt: auto (OS preference), 12-hour, or 24-hour. */ timeFormat?: "auto" | "12" | "24"; /** * Envelope timestamp timezone: "utc" (default), "local", "user", or an IANA timezone string. */ envelopeTimezone?: string; /** * Include absolute timestamps in message envelopes ("on" | "off", default: "on"). */ envelopeTimestamp?: "on" | "off"; /** * Include elapsed time in message envelopes ("on" | "off", default: "on"). */ envelopeElapsed?: "on" | "off"; /** Optional display-only context window override (used for % in status UIs). */ contextTokens?: number; /** Optional CLI backends for text-only fallback (claude-cli, etc.). */ cliBackends?: Record; /** Opt-in: prune old tool results from the LLM context to reduce token usage. */ contextPruning?: AgentContextPruningConfig; /** Compaction tuning and pre-compaction memory flush behavior. */ compaction?: AgentCompactionConfig; /** Vector memory search configuration (per-agent overrides supported). */ memorySearch?: MemorySearchConfig; /** Default thinking level when no /think directive is present. */ thinkingDefault?: "off" | "minimal" | "low" | "medium" | "high" | "xhigh"; /** Default verbose level when no /verbose directive is present. */ verboseDefault?: "off" | "on" | "full"; /** Default elevated level when no /elevated directive is present. */ elevatedDefault?: "off" | "on"; /** Default block streaming level when no override is present. */ blockStreamingDefault?: "off" | "on"; /** * Block streaming boundary: * - "text_end": end of each assistant text content block (before tool calls) * - "message_end": end of the whole assistant message (may include tool blocks) */ blockStreamingBreak?: "text_end" | "message_end"; /** Soft block chunking for streamed replies (min/max chars, prefer paragraph/newline). */ blockStreamingChunk?: BlockStreamingChunkConfig; /** * Block reply coalescing (merge streamed chunks before send). * idleMs: wait time before flushing when idle. */ blockStreamingCoalesce?: BlockStreamingCoalesceConfig; /** Human-like delay between block replies. */ humanDelay?: HumanDelayConfig; timeoutSeconds?: number; /** Max inbound media size in MB for agent-visible attachments (text note or future image attach). */ mediaMaxMb?: number; typingIntervalSeconds?: number; /** Typing indicator start mode (never|instant|thinking|message). */ typingMode?: TypingMode; /** Periodic background heartbeat runs. */ heartbeat?: { /** Heartbeat interval (duration string, default unit: minutes; default: 30m). */ every?: string; /** Heartbeat model override (provider/model). */ model?: string; /** Delivery target (last|whatsapp|telegram|discord|slack|msteams|signal|imessage|none). */ target?: | "last" | "whatsapp" | "telegram" | "discord" | "slack" | "msteams" | "signal" | "imessage" | "none"; /** Optional delivery override (E.164 for WhatsApp, chat id for Telegram). */ to?: string; /** Override the heartbeat prompt body (default: "Read HEARTBEAT.md if it exists (workspace context). Follow it strictly. Do not infer or repeat old tasks from prior chats. If nothing needs attention, reply HEARTBEAT_OK."). */ prompt?: string; /** Max chars allowed after HEARTBEAT_OK before delivery (default: 30). */ ackMaxChars?: number; /** * When enabled, deliver the model's reasoning payload for heartbeat runs (when available) * as a separate message prefixed with `Reasoning:` (same as `/reasoning on`). * * Default: false (only the final heartbeat payload is delivered). */ includeReasoning?: boolean; }; /** Max concurrent agent runs across all conversations. Default: 1 (sequential). */ maxConcurrent?: number; /** Sub-agent defaults (spawned via sessions_spawn). */ subagents?: { /** Max concurrent sub-agent runs (global lane: "subagent"). Default: 1. */ maxConcurrent?: number; /** Auto-archive sub-agent sessions after N minutes (default: 60). */ archiveAfterMinutes?: number; /** Default model selection for spawned sub-agents (string or {primary,fallbacks}). */ model?: string | { primary?: string; fallbacks?: string[] }; }; /** Optional sandbox settings for non-main sessions. */ sandbox?: { /** Enable sandboxing for sessions. */ mode?: "off" | "non-main" | "all"; /** * Agent workspace access inside the sandbox. * - "none": do not mount the agent workspace into the container; use a sandbox workspace under workspaceRoot * - "ro": mount the agent workspace read-only; disables write/edit tools * - "rw": mount the agent workspace read/write; enables write/edit tools */ workspaceAccess?: "none" | "ro" | "rw"; /** * Session tools visibility for sandboxed sessions. * - "spawned": only allow session tools to target sessions spawned from this session (default) * - "all": allow session tools to target any session */ sessionToolsVisibility?: "spawned" | "all"; /** Container/workspace scope for sandbox isolation. */ scope?: "session" | "agent" | "shared"; /** Legacy alias for scope ("session" when true, "shared" when false). */ perSession?: boolean; /** Root directory for sandbox workspaces. */ workspaceRoot?: string; /** Docker-specific sandbox settings. */ docker?: SandboxDockerSettings; /** Optional sandboxed browser settings. */ browser?: SandboxBrowserSettings; /** Auto-prune sandbox containers. */ prune?: SandboxPruneSettings; }; }; export type AgentCompactionMode = "default" | "safeguard"; export type AgentCompactionConfig = { /** Compaction summarization mode. */ mode?: AgentCompactionMode; /** Minimum reserve tokens enforced for Pi compaction (0 disables the floor). */ reserveTokensFloor?: number; /** Pre-compaction memory flush (agentic turn). Default: enabled. */ memoryFlush?: AgentCompactionMemoryFlushConfig; }; export type AgentCompactionMemoryFlushConfig = { /** Enable the pre-compaction memory flush (default: true). */ enabled?: boolean; /** Run the memory flush when context is within this many tokens of the compaction threshold. */ softThresholdTokens?: number; /** User prompt used for the memory flush turn (NO_REPLY is enforced if missing). */ prompt?: string; /** System prompt appended for the memory flush turn. */ systemPrompt?: string; };