@prismshadow/penguin-core 0.0.1

package/dist/index.d.ts

@@ -0,0 +1,1462 @@
+import { O as OmniMessage, S as StopReason, C as CompactionMode, b as TokenCounts, T as ToolDefinition, c as CompleteModelMessage, d as SessionMetaMessage, e as SessionMetaPayload } from './types-D6FERSdT.js';
+export { f as AbortPayload, A as ApprovalDecision, g as ApprovalDecisionPayload, h as CompactionBeginPayload, i as CompactionEndPayload, j as CompactionReason, k as CompleteModelPayload, E as EventMessage, l as EventPayload, I as ImageUrlPayload, m as InlineDataPayload, n as InlineThinkingPayload, M as MessageOrigin, o as ModelMessage, p as ModelPayload, q as OmniMessageType, r as OmniPayload, P as PartialModelMessage, s as PartialModelPayload, t as PartialTextPayload, u as PartialThinkingPayload, v as PartialToolCallOutputPayload, w as PartialToolCallPayload, R as RequestBeginPayload, x as RequestEndPayload, y as Role, z as StreamEventType, B as SubagentPayload, D as TextPayload, F as ThinkingPayload, G as TokenUsagePayload, H as ToolCallOutputPayload, a as ToolCallPayload, J as isCompleteModelMessage, K as isEventMessage, L as isModelMessage, N as isPartialPayload, Q as isSessionMeta } from './types-D6FERSdT.js';
+export { FidelityFields, PartialAggregator, abortEvent, addTokenCounts, aggregateAll, approvalDecision, assistantText, compactionBegin, compactionEnd, emptyTokenCounts, imageUrlMessage, inlineData, inlineThinking, partialText, partialThinking, partialToolCall, partialToolCallOutput, requestBegin, requestEnd, sessionMeta, subagentEvent, textMessage, thinkingMessage, tokenUsage, toolCall, toolCallOutput, userText, withOrigin } from './omnimessage/index.js';
+import { T as ToolDefinitionConfig, A as ApproveFn, a as ThinkingLevelName, M as MCPServerConfig, b as ToolConfig, c as ToolCallIdAllocator, L as LLMInterface, G as GenerativeModelConfig, d as GenerativeModelParameters, e as LLMOutcome, E as EnvironmentInterface, f as EnvironmentConfig, g as ToolPermission, h as ToolExecutionRequest, i as EnvironmentServices } from './interfaces-CMSN7-pO.js';
+export { C as CommandSessionManager, j as ManagedSession, k as ManagedSubagentSession, P as ProcessExit, S as SpawnOptions, l as SubagentHandle, m as SubagentRunner, n as SubagentSessionManager, V as VisionDescriberService, s as stripToolCallIdSuffix } from './interfaces-CMSN7-pO.js';
+import { LibrarySkill, SkillMetadata } from '@prismshadow/penguin-skills';
+export { SkillMetadata, parseSkillFrontmatter } from '@prismshadow/penguin-skills';
+import { P as ProjectConfig } from './model-catalog-DTu0IPjs.js';
+export { M as MODEL_CATALOG, a as MODEL_PROVIDERS, b as ModelCatalogEntry, c as ModelEntry, d as ModelEnvInfo, e as ModelPricing, f as ModelProviderInfo, g as ModelRef, h as addModel, i as catalogEntryFor, j as defaultProjectConfig, k as formatModelRef, l as getModel, m as inferProviderForUpstream, n as loadProjectConfig, p as presetModelEntries, o as providerInfo, r as renderProjectConfigToml, q as resolveModelEnv, s as resolveModelRef, t as saveProjectConfig, u as setDefaultModel, v as setVisionModel } from './model-catalog-DTu0IPjs.js';
+import { UniEvent, UniMessage, UniConfig, ThinkingLevel, ToolSchema, UsageMetadata } from '@prismshadow/agenthub';
+
+/**
+ * BuiltinTool abstraction — lets Environment avoid special-casing any specific tool name.
+ *
+ * Each builtin tool carries its own: `name`, the `definition` handed to the LLM, and a streaming
+ * `execute`. Environment dispatches purely by looking up `name`; an unknown tool collapses to an
+ * explanatory `tool_call_output`, never throwing. Adding a new tool later (e.g. file read/write,
+ * retrieval) only requires implementing this interface and registering it with the registry, with
+ * no changes needed to Environment.
+ */
+
+/**
+ * Tool execution context: runtime information needed to execute one tool call.
+ * Docs: /docs/tools § "Execution contract".
+ */
+interface ToolExecutionContext {
+    /** Workspace absolute path; relative-path arguments should be resolved against it. */
+    workspaceDir: string;
+    /** The tool_call_id passed through unchanged, used to build streaming deltas and nested origin tags. */
+    toolCallId: string;
+    /** Abort signal; the tool should close out and return as soon as possible once it fires. */
+    signal?: AbortSignal;
+    /** The parent Agent's approval callback; run_subagent passes it through to the child Session so it inherits the parent's approval mode (unused by most tools). */
+    approve?: ApproveFn;
+}
+/**
+ * Tool execution result (the generator's return value); treated as `completed` if omitted.
+ * Docs: /docs/tools § "Execution contract".
+ */
+interface ToolResult {
+    stopReason?: StopReason;
+    /**
+     * Terminal marker (e.g. `[exit code: 1]`): appended by Environment during its unified
+     * close-out, **outside** the maxOutputLength truncation, and streamed to the frontend as an
+     * extra chunk — so the failure marker isn't lost when long output gets truncated (it would be
+     * cut off if produced as a content delta instead).
+     */
+    note?: string;
+    /**
+     * Images carried by the tool output (e.g. an image read by read_image): each entry is a
+     * `data:<mime>;base64,...` data URL. Attached by Environment during close-out: a single
+     * streaming delta carries it all at once before stop, plus the final complete
+     * `tool_call_output` (only carried on normal completion; images are not chunked and don't
+     * count toward text truncation).
+     */
+    images?: string[];
+}
+/**
+ * Builtin tool interface. `execute` receives the already-parsed tool argument object and the
+ * execution context, streaming out OmniMessage as an async generator. Contract (a relaxed
+ * version — framing and close-out are handled uniformly by Environment):
+ *
+ * - **Own output**: yielding the **delta** of `partial_tool_call_output` is enough; `start`/`stop`
+ *   are optional (Environment ignores the tool's start/stop and frames it itself), and there's
+ *   **no need** to produce a complete `tool_call_output` either (the complete message,
+ *   maxOutputLength forward truncation, and close-out are all derived by Environment from the
+ *   deltas). If a tool does produce a complete `tool_call_output` anyway, Environment uses it as
+ *   the basis for content and stop reason (tolerated for compatibility, not recommended).
+ * - **Nested forwarding**: yielding any message **tagged with origin** is passed through by
+ *   Environment unchanged (e.g. run_subagent forwarding all of a child session's messages).
+ * - **Stop reason**: reported via the generator's return value (defaults to completed); a throw
+ *   is collapsed by Environment into aborted/failed based on interruption/error, never
+ *   propagating up as an exception.
+ * Docs: /docs/interfaces § "The inner tool contract: BuiltinTool"; /docs/tools § "Execution contract".
+ */
+interface BuiltinTool {
+    /** Tool name (corresponds to the tool_call.name returned by the LLM). */
+    name: string;
+    /** Tool definition handed to the LLM (including description / parameters / permission / maxOutputLength). */
+    definition: ToolDefinitionConfig;
+    /** Executes one tool call: args is the already-parsed argument object, ctx is the runtime context. */
+    execute(args: Record<string, unknown>, ctx: ToolExecutionContext): AsyncGenerator<OmniMessage, ToolResult | void>;
+}
+
+/** Default Project id used when none is specified. */
+declare const DEFAULT_PROJECT_ID = "default_project";
+/** Default Agent id used when none is specified. */
+declare const DEFAULT_AGENT_ID = "default_agent";
+/**
+ * Resolves the local data root directory.
+ * Prefers the `PENGUIN_HOME` environment variable, otherwise falls back to `~/.penguin/data`
+ * (under the hidden `~/.penguin` home so it never collides with unrelated folders, and in a
+ * `data/` subdir kept separate from the installer's binaries under `~/.penguin`).
+ */
+declare function resolveRoot(): string;
+/** `<root>/<projectId>`. */
+declare function projectDir(root: string, projectId: string): string;
+/** `<projectDir>/agents`, the container directory holding every Agent in the Project. */
+declare function agentsDir(root: string, projectId: string): string;
+/** `<projectDir>/agents/<agentId>`. */
+declare function agentDir(root: string, projectId: string, agentId: string): string;
+/** `<agentDir>/agent_state`. */
+declare function agentStateDir(root: string, projectId: string, agentId: string): string;
+/** `<agentDir>/traces`. */
+declare function tracesDir(root: string, projectId: string, agentId: string): string;
+/** `<agentDir>/scratchpad`, the Agent's temporary/draft file directory (the model creates a subdirectory per Session id). */
+declare function scratchpadDir(root: string, projectId: string, agentId: string): string;
+/** `<agentDir>/workspaces`. */
+declare function workspacesDir(root: string, projectId: string, agentId: string): string;
+/**
+ * `<projectDir>/.project_config.toml`, the Project's single config file (a hidden file, not
+ * shown by default `ls`, written with mode 0600; model entries are inlined with their credential,
+ * see state/project-config.ts).
+ */
+declare function projectConfigPath(root: string, projectId: string): string;
+/** `<agentStateDir>/system_config.yaml`. */
+declare function systemConfigPath(root: string, projectId: string, agentId: string): string;
+/** `<agentStateDir>/AGENTS.md`. */
+declare function agentsMdPath(root: string, projectId: string, agentId: string): string;
+/** `<agentStateDir>/.vault.toml`, the Agent-level environment-variable vault (see state/agent-vault.ts). */
+declare function agentVaultPath(root: string, projectId: string, agentId: string): string;
+/** `<agentStateDir>/tools`, reserved for user-defined Tool config. */
+declare function toolsDir(root: string, projectId: string, agentId: string): string;
+/** `<agentStateDir>/memory`. */
+declare function memoryDir(root: string, projectId: string, agentId: string): string;
+/** `<agentStateDir>/skills`. */
+declare function skillsDir(root: string, projectId: string, agentId: string): string;
+/** `<agentStateDir>/schedule`, the scheduled-task directory (doesn't exist when unconfigured). */
+declare function scheduleDir(root: string, projectId: string, agentId: string): string;
+/** `<agentDir>/benchmarks`, the capability-evaluation question bank and scores (doesn't exist when unconfigured). */
+declare function benchmarksDir(root: string, projectId: string, agentId: string): string;
+/** `<agentDir>/snapshots`, Agent State version snapshots (doesn't exist when unconfigured). */
+declare function snapshotsDir(root: string, projectId: string, agentId: string): string;
+
+/**
+ * Default system configuration for Agent State (written to `system_config.yaml`) and the
+ * default `AGENTS.md` (empty).
+ *
+ * Runtime Prompt and tool configuration should come from editable files;
+ * code only supplies the initial defaults. `system_config.yaml` holds the relatively stable
+ * system-level Prompt, built-in tools, and MCP Server configuration; `AGENTS.md` is injected
+ * via a system Prompt placeholder.
+ *
+ * The system Prompt is sectioned and trimmed as needed (Role/Personality/Success
+ * criteria/Constraints/Stop rules/File system/Suggested workflows); it does not describe
+ * specific tools (that comes from the tool schema). AGENTS.md, Vault/Skills, and Environment
+ * injection go at the end.
+ *
+ * Placeholders (`{{...}}`) appear only in the trailing injection zones (AGENTS.md / Vault /
+ * Skills / Environment); elsewhere the body uses angle-bracket notation such as
+ * \`<project_dir>\`, \`<agent_id>\`, \`<session_id>\` — these are **not substituted**; the model
+ * fills in the actual values from the Environment section itself.
+ */
+
+/** Docs: /docs/configuration § "System prompt placeholders". */
+declare const AGENTS_MD_PLACEHOLDER = "{{AGENTS_MD}}";
+declare const VAULT_KEYS_PLACEHOLDER = "{{VAULT_KEYS}}";
+declare const SKILL_METADATA_PLACEHOLDER = "{{SKILL_METADATA}}";
+declare const SESSION_ID_PLACEHOLDER = "{{SESSION_ID}}";
+declare const CWD_PLACEHOLDER = "{{CWD}}";
+declare const AGENT_ID_PLACEHOLDER = "{{AGENT_ID}}";
+declare const PROJECT_DIR_PLACEHOLDER = "{{PROJECT_DIR}}";
+declare const PLATFORM_PLACEHOLDER = "{{PLATFORM}}";
+declare const OS_VERSION_PLACEHOLDER = "{{OS_VERSION}}";
+declare const DATE_PLACEHOLDER = "{{DATE}}";
+/**
+ * Context compaction config (the `compaction` section of `system_config.yaml`).
+ * Docs: /docs/configuration § "Agent config".
+ */
+interface CompactionConfig {
+    /** Context Token threshold (taken from the most recent token_usage's request.total); defaults to 128000, <=0 disables. */
+    max_context_length?: number;
+    /** Session cumulative turn threshold (counted in LLM Requests, across Tasks); defaults to -1, <=0 means no limit. */
+    max_session_turns?: number;
+    /** Compaction mode; defaults to summarize. */
+    mode?: CompactionMode;
+    /** Prompt template for summarize compaction; defaults to the built-in value (editable config, not hardcoded). */
+    prompt?: string;
+}
+/**
+ * System-level config for Agent State, serialized as `system_config.yaml`.
+ * Docs: /docs/configuration § "Agent config".
+ */
+interface SystemConfig {
+    /** Agent display name (display name is separate from id; falls back to id when unset). */
+    name?: string;
+    /** Agent description. */
+    description?: string;
+    /** Agent State version number: a natural number, 1 on creation, incremented on successful optimization; a missing field is treated as 1. */
+    version?: number;
+    /** System-level Prompt (relatively stable; should not be modified frequently). */
+    system_prompt: string;
+    /** Max LLM turns per Task (a runtime parameter that belongs to Agent config, not specified when creating a Session). */
+    max_turns?: number;
+    model?: {
+        max_tokens?: number;
+        thinking_level?: ThinkingLevelName;
+        timeoutMs?: number;
+    };
+    /** Context compaction (enabled by default, max_context_length 128k, mode summarize). */
+    compaction?: CompactionConfig;
+    tools?: {
+        /** Built-in system tool configuration. */
+        builtin?: ToolDefinitionConfig[];
+        /** MCP Server configuration. */
+        mcpServers?: MCPServerConfig[];
+    };
+}
+/**
+ * Built-in default compaction Prompt (summarize mode): tells the model that after
+ * compaction the raw transcript is no longer visible and the
+ * summary is the only record, so it must include everything needed to continue the task,
+ * and no tools may be called while writing the summary.
+ */
+declare const DEFAULT_COMPACTION_PROMPT: string;
+/** Agent State version number: an invalid or missing field is always treated as 1. */
+declare function agentStateVersion(config: Pick<SystemConfig, "version">): number;
+/** Returns the default system configuration for Agent State. */
+declare function defaultSystemConfig(): SystemConfig;
+/**
+ * Returns the default editable `AGENTS.md` content: an empty string — no guidance is
+ * preprovisioned by default; Subagent delegation conventions and general task practices
+ * live in the default template's Suggested workflows section as a soft convention.
+ * Kept so initialization can still write an empty AGENTS.md file.
+ */
+declare function defaultAgentsMd(): string;
+
+/**
+ * Preset content for builtin Agents; Skill documentation lives in @prismshadow/penguin-skills
+ * (the library files are read live when building the preset).
+ *
+ * - Every Project comes with a single builtin Agent: `default_agent` (the General Agent, the
+ *   default conversational Agent), which has every Skill in the library installed at
+ *   initialization. Dedicated capabilities (creating an Agent, optimizing an Agent, etc.)
+ *   are carried by Skills rather than dedicated builtin Agents.
+ * - The preset carries no AGENTS.md: the default AGENTS.md is empty, with delegation and task
+ *   conventions living in the default template's Suggested Workflows section.
+ * - Skill metadata is auto-injected into the system Prompt via the `{{SKILL_METADATA}}`
+ *   placeholder; it's not registered in AGENTS.md.
+ */
+
+/** The set of Project builtin Agent ids (supplied along with the Project, cannot be deleted from Web). */
+declare const BUILTIN_AGENT_IDS: readonly string[];
+/** Agent initialization preset (only takes effect at initialization; ignored when loading an existing Agent). */
+interface AgentPreset {
+    /** Display name written to system_config.yaml. */
+    name?: string;
+    /** Description written to system_config.yaml. */
+    description?: string;
+    /** Overrides the default AGENTS.md content. */
+    agentsMd?: string;
+    /** Skills installed at initialization (installs none by default). */
+    skills?: LibrarySkill[];
+}
+/**
+ * The preset list for a Project's builtin Agents (each initialized in turn when the Project is
+ * created; an existing Agent is never overwritten). The only builtin Agent is default_agent:
+ * installs every Skill in the library, with no preset AGENTS.md.
+ */
+declare function builtinProjectAgentPresets(): Array<{
+    agentId: string;
+    preset: AgentPreset;
+}>;
+
+type IdKind = "project_id" | "agent_id" | "skill_name";
+declare function isValidId(id: string): boolean;
+declare function assertValidId(kind: IdKind, id: string): void;
+/** A loaded Agent State handle. */
+interface AgentState {
+    root: string;
+    projectId: string;
+    agentId: string;
+    stateDir: string;
+    systemConfig: SystemConfig;
+    agentsMd: string;
+}
+interface SessionEnvironmentValues {
+    sessionId: string;
+    cwd: string;
+    /** The Agent id this Session belongs to (system Prompt placeholder {{AGENT_ID}}). */
+    agentId: string;
+    /** Absolute path to this Project's directory (system Prompt placeholder {{PROJECT_DIR}}; Agent State/scratchpad paths are derived from it). */
+    projectDir: string;
+    platform: string;
+    osVersion: string;
+    date: string;
+}
+/**
+ * Loads or initializes Agent State.
+ *
+ * When root/project/agent are omitted, `resolveRoot()` and the default constants are used. If
+ * `system_config.yaml` doesn't exist, the directory is treated as empty and initialized;
+ * otherwise the existing content is loaded. `preset` only takes effect on the initialization
+ * path (name/description/AGENTS.md overrides and extra Skills) and is ignored when loading an
+ * existing Agent — existing config is never overwritten.
+ */
+declare function loadOrInitAgentState(opts?: {
+    agentId?: string;
+    projectId?: string;
+    root?: string;
+    preset?: AgentPreset;
+}): Promise<AgentState>;
+/**
+ * Initializes a Project's built-in Agent (the only built-in Agent: default_agent).
+ *
+ * Calls loadOrInitAgentState for each one: an Agent whose directory already exists (including a
+ * default_agent created earlier by the CLI) is only loaded, never overwritten (preset only
+ * takes effect on initialization). Returns the list of built-in Agent ids.
+ */
+declare function provisionProjectAgents(opts?: {
+    root?: string;
+    projectId?: string;
+}): Promise<string[]>;
+/**
+ * Installs a Skill into the target Agent: writes `skills/<name>/SKILL.md` verbatim (the full
+ * SKILL.md content including frontmatter, ensuring a trailing newline); if the directory
+ * already exists, it's overwritten (reinstalling = updating to the latest content). An optional
+ * icon.svg is written alongside SKILL.md; if this install doesn't
+ * include an icon, any old icon.svg is removed, preserving "overwrite update" semantics (the
+ * directory content matches the Skill being installed).
+ * Docs: /docs/skills § "Installation and storage".
+ */
+declare function installSkill(root: string, projectId: string, agentId: string, skill: {
+    name: string;
+    content: string;
+    icon?: string;
+}): Promise<void>;
+/** Uninstalls a Skill: deletes the entire `skills/<name>/` directory; idempotent, no error if it doesn't exist. */
+declare function removeSkill(root: string, projectId: string, agentId: string, name: string): Promise<void>;
+/** An installed Skill entry: frontmatter metadata (including an optional short description) + the optional icon.svg content in the directory. */
+interface InstalledSkill extends SkillMetadata {
+    /** The raw content of `skills/<name>/icon.svg` (a custom icon copied alongside SKILL.md at install time); the field is omitted when missing (the frontend falls back to a default book icon). */
+    icon?: string;
+}
+/**
+ * Lists the metadata of Skills installed on the target Agent: scans `skills/<name>/SKILL.md` and
+ * parses its frontmatter (optional fields like short_description(_zh) pass through as parsed),
+ * also reading the optional icon.svg content in the directory. Tolerant: a directory whose
+ * frontmatter fails to parse or is missing `name` falls back to
+ * `{ name: <directory name>, description: "", version: 1, updated: "" }`; a directory with no
+ * SKILL.md doesn't count as a Skill; returns [] if skills/ doesn't exist. Results are sorted by
+ * name (a stable order for both Prompt injection and API responses).
+ * Docs: /docs/skills § "Installation and storage".
+ */
+declare function listInstalledSkills(root: string, projectId: string, agentId: string): Promise<InstalledSkill[]>;
+/**
+ * Skill metadata section: the replacement value for `{{SKILL_METADATA}}`, one line per Skill in
+ * the form `- \`name\` — description` (just the name when description is empty); an empty array
+ * returns an empty string. The full body is read by the model on demand via shell.
+ */
+declare function skillMetadataSection(skills: SkillMetadata[]): string;
+/**
+ * Renders the complete runtime system Prompt: substitutes `AGENTS.md`, vault key names, Skill
+ * metadata, and the concrete Session runtime environment placeholders into the system Prompt
+ * template. The assembly layer only does placeholder substitution and adds no extra text —
+ * wrapper text such as `<developer_instructions>` and the # Vault / # Skills statements are
+ * written directly into the system Prompt template itself (the Prompt is fully
+ * transparent and editable via `system_config.yaml`). Other files in Agent State / Workspace are
+ * never auto-injected.
+ *
+ * `{{VAULT_KEYS}}` is replaced with the vault key-name list (an empty string if empty/not
+ * provided): this lets the model know which APIs requiring a key it can call; values are never
+ * injected. `{{SKILL_METADATA}}` is replaced with the installed Skills' metadata lines (an empty
+ * string if empty/not provided). A custom template that removes a placeholder gets no
+ * corresponding content injected.
+ * Docs: /docs/configuration § "System prompt placeholders".
+ */
+declare function assembleSystemPrompt(state: AgentState, sessionEnvironment?: SessionEnvironmentValues, vaultKeys?: string[], skillMetadata?: SkillMetadata[]): string;
+/**
+ * Builds the `ToolConfig` needed by Environment from Agent State.
+ *
+ * Both builtin tools and MCP Server config are taken from `system_config.yaml`; falls back to the
+ * default config when builtin tools are missing.
+ */
+/**
+ * Filters builtin tool entries by the session model's type: entries with `forModel: "vision"` are
+ * only used for models that support images (vision models), `forModel: "text-only"` is only for
+ * text-only models (e.g. choosing between read_image / describe_image); unlabeled entries are
+ * available to all models.
+ * Docs: /docs/tools § "Image tools".
+ */
+declare function selectBuiltinToolsForModel(tools: ToolDefinitionConfig[], modelVision: boolean): ToolDefinitionConfig[];
+declare function buildToolConfig(state: AgentState): ToolConfig;
+
+/**
+ * Vault value length cap: since values are injected into the child-process environment, Linux
+ * caps a single env entry at roughly 128KB, and an oversized value would make every
+ * exec_command spawn for that Agent fail (E2BIG) — so it's rejected on the write side (core and
+ * the API layer share this same cap).
+ */
+declare const VAULT_VALUE_MAX_LENGTH = 8192;
+/** Whether a vault key name is valid (shell environment variable name rules). */
+declare function isValidVaultKey(key: string): boolean;
+/** Validates a vault key name, throwing if invalid (core and the API layer share this same rule). */
+declare function assertValidVaultKey(key: string): void;
+/** Validates a vault value's length (see `VAULT_VALUE_MAX_LENGTH`), throwing if it exceeds the cap. */
+declare function assertValidVaultValue(key: string, value: string): void;
+/**
+ * Reads the Agent vault: returns an empty table if the file doesn't exist.
+ * A hand-edited file is filtered by the same rule as the write side: only string values are
+ * accepted (numbers/dates etc. are ignored), and key names must follow shell variable name rules
+ * (invalid keys are always ignored — otherwise they'd get injected into the Prompt/child-process
+ * environment, and an invalid key surfaced by a GET view would make a full-table PUT 400, leaving
+ * the vault page unable to add or remove any further entries).
+ */
+declare function loadAgentVault(root: string, projectId: string, agentId: string): Promise<Record<string, string>>;
+/**
+ * Writes the full table to the Agent vault: validates all key names first; an empty table
+ * deletes the file (idempotent if it doesn't exist).
+ * The directory is created automatically if it doesn't exist (the vault can be configured even
+ * before the Agent is initialized).
+ */
+declare function saveAgentVault(root: string, projectId: string, agentId: string, vault: Record<string, string>): Promise<void>;
+/**
+ * Writes or updates one vault entry (added if it doesn't exist, overwritten if it does).
+ * The key name must follow shell environment variable name rules (see `isValidVaultKey`), and the
+ * value length is constrained by `VAULT_VALUE_MAX_LENGTH`; throws if invalid. Returns the updated
+ * vault.
+ */
+declare function setVaultEntry(root: string, projectId: string, agentId: string, key: string, value: string): Promise<Record<string, string>>;
+/**
+ * Removes one vault entry; idempotent if the key doesn't exist (no write happens). Once emptied,
+ * the whole .vault.toml is removed. Returns the updated vault.
+ */
+declare function removeVaultEntry(root: string, projectId: string, agentId: string, key: string): Promise<Record<string, string>>;
+
+/** Directory name of the example Benchmark (the directory name is also its identifier). */
+declare const EXAMPLE_BENCHMARK_ID = "example-benchmark";
+/** Raw result of a single run (a runs element in scoreboard v2). */
+interface ExampleRun {
+    score: number;
+    cost: number;
+    duration_ms: number;
+    session_id: string;
+}
+/**
+ * Builds the scoreboard object from raw runs data: each case's three metrics are the
+ * average of its runs, and each evaluation's metrics are the sum of its cases' averages
+ * (following the scoreboard v2 convention). Exported so tests can verify the numbers
+ * are self-consistent.
+ */
+declare function buildExampleScoreboard(): {
+    evaluations: Array<{
+        time: string;
+        version: number;
+        provider: string;
+        model_id: string;
+        summary_title: string;
+        summary: string;
+        score: number;
+        cost: number;
+        duration_ms: number;
+        cases: Array<{
+            case: string;
+            score: number;
+            cost: number;
+            duration_ms: number;
+            runs: ExampleRun[];
+        }>;
+    }>;
+};
+/**
+ * Provisions the example Benchmark: if `benchmarks/` already exists (the user already has a
+ * case library), does nothing; otherwise creates `benchmarks/example-benchmark/` (config, the
+ * two sample cases, and the scoreboard). Callers are restricted to the default_agent
+ * initialization path (see agent-state.ts).
+ */
+declare function provisionExampleBenchmark(root: string, projectId: string, agentId: string): Promise<void>;
+
+/**
+ * GenerativeModel —— the SDK's LLM interface implementation.
+ *
+ * Responsibilities (protocol translation + streaming aggregation):
+ *   1. Merge a group of OmniMessages that **share the same role** into a single AgentHub `UniMessage`;
+ *   2. Issue the request via `AutoLLMClient.streamingResponseStateful` (stateful — AgentHub
+ *      maintains history internally), translating streamed `UniEvent`s back into OmniMessages:
+ *        - text/thinking/tool-call deltas → `partial_*` (before the first delta of each segment
+ *          `yield` a `start`; after the segment ends `yield` a `stop`);
+ *        - after a segment ends, append the full `model_msg` (thinking / text / tool_call);
+ *        - a `token_usage` event_msg is produced **only on normal completion**
+ *          (observability/Token).
+ *   3. Interruption/error handling: `finishInterrupted` first closes any open
+ *      streaming segments and backfills the complete message, then the output ends — never
+ *      leaking a malformed structure. This interface **never retries internally** — retryable
+ *      errors (network/timeout/429/5xx, see `isRetryableError`) end with `timeout`; AgentHub
+ *      JSON parse errors end with `malformed`; both are handed to `context_engine` to reconnect
+ *      within the same run. User interruption ends with `aborted`; non-retryable errors
+ *      (auth/parameters) end with `failed`.
+ *
+ * `context_engine` only consumes OmniMessage; all Uni* protocol details are encapsulated here.
+ * Docs: /docs/interfaces § "The built-in implementation: GenerativeModel".
+ */
+
+/**
+ * Groups a replayed, complete OmniMessage history into a sequence of UniMessages by
+ * **adjacent same-role** runs (used for the setHistory injection during Session recovery).
+ * One committed turn = a group of user-side input + a group of
+ * assistant output, matching exactly the adjacent user / assistant UniMessages in AgentHub history.
+ */
+declare function groupHistoryToUniMessages(history: OmniMessage[]): UniMessage[];
+/**
+ * Merges a group of OmniMessages into **a single** UniMessage.
+ *
+ * Constraint: all messages in the array must share the same
+ * role; the role of the first payload is used as the UniMessage's role (a tool_call_output
+ * group has role "user"). Throws if roles are mixed.
+ */
+declare function mergeOmniToUniMessage(messages: OmniMessage[]): UniMessage;
+/**
+ * Converts AgentHub `UsageMetadata` into PenguinHarness `TokenCounts`.
+ *
+ * Conversion rules (AgentHub UsageMetadata → OmniMessage TokenCounts, null treated as 0):
+ *   - `cache_read  = cached_tokens` (input tokens served from cache hits);
+ *   - `cache_write = prompt_tokens` (input tokens on a cache miss);
+ *   - `output     = thoughts_tokens + response_tokens`;
+ *   - `total      = cache_read + cache_write + output`.
+ * That is, `input = cache_read + cache_write = cached_tokens + prompt_tokens`,
+ * and `total = input + output` (consistent with SKILL.md's input/output accounting).
+ */
+declare function usageToTokenCounts(usage: UsageMetadata): TokenCounts;
+/**
+ * Streaming translator. Feed `UniEvent`s one at a time into `pushEvent`, which yields
+ * incremental OmniMessages (`partial_*`); after the stream ends, call `finish` to produce
+ * `stop`, the complete `model_msg`, and `token_usage`.
+ *
+ * Split into its own class to make unit testing easier (feed a constructed array of UniEvents,
+ * assert on emission order / aggregation / token counts).
+ * Docs: /docs/omni-message § "The streaming discipline".
+ */
+declare class EventTranslator {
+    private readonly toolCallIds;
+    /**
+     * tool_call_id uniqueness registry. By default each translator creates its own (unit tests /
+     * one-off translation); in production `GenerativeModel` injects a Session-level shared instance so
+     * the uniqueness scope spans Requests and survives compaction rebuilds.
+     */
+    constructor(toolCallIds?: ToolCallIdAllocator);
+    private textStarted;
+    private thinkingStarted;
+    private toolStarted;
+    private activeToolCallId;
+    private textBuffer;
+    private thinkingBuffer;
+    private thinkingSignature;
+    private textPhase;
+    private textSignature;
+    /** Provider id keys saved in order of appearance, so complete tool_calls are emitted in a stable order. */
+    private toolOrder;
+    /** provider's original tool_call_id → the accumulator for the **latest** call under that id. */
+    private tools;
+    private finishReason;
+    /** Token usage for this request (a snapshot from the most recent usage report). */
+    private requestTokens;
+    /** Consumes one UniEvent, yielding 0..n streaming OmniMessages. */
+    pushEvent(event: UniEvent): Generator<OmniMessage>;
+    /**
+     * Stream-end finalization: first `yield` the `stop` and complete message for the text/thinking
+     * segments, then backfill partial(stop) + complete tool_call for tool_calls that **haven't
+     * been emitted eagerly yet** (i.e. the fallback case — no complete tool_call content item was
+     * received, only deltas). Tools already emitted eagerly in `pushEvent` are not repeated here.
+     */
+    finish(): Generator<OmniMessage>;
+    /**
+     * Interruption finalization: even when interrupted or on error, close the structure
+     * as `start → delta → stop → complete message`. Closes any unclosed thinking/text segments and
+     * backfills their complete messages, then backfills partial(stop) + complete tool_call for
+     * tool_calls that only have deltas and were never emitted eagerly. All backfilled messages are
+     * uniformly tagged with the interruption `stopReason` (`aborted` / `timeout` / `failed`), to
+     * distinguish them from normal completion (`completed`).
+     *
+     * Differs from `finish`: doesn't read `finish_reason`, and doesn't produce `token_usage` (an
+     * interrupted Request has no usage to report); backfilled incomplete tool_calls carry the
+     * interruption stop_reason, so `context_engine` won't dispatch them for execution.
+     */
+    finishInterrupted(stopReason: StopReason): Generator<OmniMessage>;
+    /**
+     * Eagerly emits the finalization of a tool_call: partial(stop) (without name) + complete
+     * tool_call. Marks `emitted` to prevent duplicate emission in finish. `stopReason` defaults to
+     * `completed` (a normal request); when called during interruption finalization
+     * (`finishInterrupted`), the interruption reason is passed in, letting `context_engine`
+     * distinguish "a real tool request" from "an incomplete tool_call backfilled to close the
+     * structure on interruption" by stop_reason, and dispatch only the former.
+     */
+    private emitCompleteTool;
+    /**
+     * Closes out the currently buffered thinking segment and appends the complete thinking
+     * message, then clears the buffer and resets the start flag. May be called before eagerly
+     * emitting the first complete tool_call (`pushEvent`) or at stream end (`finish`), which
+     * guarantees the complete-message order is thinking → text → tool_call.
+     *
+     * "Flush then reset" rather than a one-shot guard: once the buffer is cleared, a repeated call
+     * is a no-op (each segment is emitted exactly once); if the model outputs new thinking after a
+     * tool_call (interleaved/multi-segment models), that new segment accumulates again and gets
+     * correctly flushed at the next tool_call or `finish`, without being lost.
+     *
+     * The complete thinking message passes through the given stop_reason just like partial(stop)
+     * (aligned with flushText — streamed concatenation == complete message): at type boundaries the
+     * caller passes completed (the stop reason belongs to the following tool_call/text);
+     * finish/finishInterrupted follow the actual end reason.
+     */
+    private flushThinking;
+    /**
+     * Closes out the currently buffered text segment and appends the complete text message, then
+     * clears the buffer and resets the start flag. Uses the same "flush then reset" approach as
+     * `flushThinking` to support new text segments after a tool_call. When emitted before the
+     * first complete tool_call, finish_reason is unknown and the caller passes completed; when
+     * emitted in `finish`, the final `omniStopReason()` is passed (consistent with prior behavior).
+     */
+    private flushText;
+    /** Whether finish_reason (the terminal event) has been received: signals a fully delivered response (see the defensive branch in streamGenerate). */
+    sawFinishReason(): boolean;
+    /** Token usage for this request (read after finish). */
+    getRequestTokens(): TokenCounts;
+    private ensureTool;
+    /**
+     * Create an accumulator for a new call: the emitted id is made unique via the Session-level registry
+     * (kept as-is when the provider id is free, with a `#n` suffix on collision). Creating again under the
+     * same provider id (another call with a duplicate id) replaces the old Map entry — the old call has
+     * finished emitting, so later inbound events are attributed to the latest call.
+     */
+    private createTool;
+    private usageOnce;
+    /**
+     * Converts an AgentHub finish_reason into an OmniMessage stop_reason (the five-value protocol).
+     * "stop", "tool_call", and null are treated as completed; length or unknown reasons map to failed.
+     */
+    private omniStopReason;
+}
+/**
+ * One-shot translation: folds a batch of UniEvents into an OmniMessage sequence (including
+ * complete messages and token_usage). A pure function for easy unit testing; the live streaming
+ * path is wired up by `GenerativeModel.streamGenerate`.
+ *
+ * @param events The event sequence
+ * @param sessionTokensBefore The session's cumulative tokens before this translation (used to produce token_usage.session)
+ * @returns `{ messages, requestTokens, sessionTokens }`
+ */
+declare function translateEvents(events: UniEvent[], sessionTokensBefore?: TokenCounts): {
+    messages: OmniMessage[];
+    requestTokens: TokenCounts;
+    sessionTokens: TokenCounts;
+};
+/**
+ * Determines whether an error is an AgentHub / Provider response JSON parse error.
+ *
+ * AgentHub uses `JSON.parse` internally to parse response bodies, and a parse failure throws a
+ * `SyntaxError`; hence we judge directly by exception type (the `name` check also covers
+ * cross-realm or deserialization-reconstructed errors, and we probe down the `cause` chain for
+ * wrapped errors). This is not an auth/parameter failure but an incomplete LLM Request, and
+ * should end with `malformed` and be handed to the engine to retry.
+ */
+declare function isMalformedJsonParseError(error: unknown): boolean;
+/**
+ * Determines whether an error is AgentHub's "incomplete stream" validation error: when a
+ * server/proxy terminates the stream early **cleanly** at an event boundary (no network error
+ * thrown), AgentHub's `_validateLastEvent` reports the missing or incomplete final event as a
+ * plain `Error` ("Streaming response yielded no events" / "Last event must carry
+ * usage_metadata|finish_reason"). This is not an auth/parameter failure but an incomplete LLM
+ * Request, and should end with `malformed` and be handed to the engine to reconnect and retry.
+ * AgentHub doesn't provide an error type for this, so we match by message prefix
+ * (@prismshadow/agenthub 0.3.x), probing down the `cause` chain.
+ */
+declare function isIncompleteStreamError(error: unknown): boolean;
+/**
+ * Determines whether an error is retryable.
+ *
+ * Retryable: network errors, timeouts, connection reset, HTTP 429 / 5xx.
+ * Not retryable: HTTP 4xx auth/parameter errors (401/403/400/404, etc.).
+ * JSON parse errors are classified separately as `malformed` by `isMalformedJsonParseError`.
+ *
+ * Since AgentHub doesn't guarantee the shape of error objects, this uses a lenient check: first
+ * the status code, then error codes / message keywords. When undeterminable, treat it as
+ * **non-retryable** to avoid pointless retries.
+ */
+declare function isRetryableError(error: unknown): boolean;
+/**
+ * A stateful LLM object attached to a Session. AgentHub's `streamingResponseStateful` maintains
+ * conversation history internally; this class is only responsible for protocol translation,
+ * streaming aggregation, and token accumulation. **It never retries internally** — retries are
+ * handled by `context_engine`.
+ */
+declare class GenerativeModel implements LLMInterface {
+    private readonly client;
+    private readonly uniConfig;
+    /** Streaming idle timeout (milliseconds); <= 0 disables it. A timeout is treated as needing reconnection. */
+    private readonly requestTimeoutMs;
+    /**
+     * tool_call_id uniqueness registry (see tool-call-ids.ts): when a name-as-id provider (e.g. Gemini)
+     * calls the same tool repeatedly, it assigns a `#n` suffix to later calls so engine pairing and the
+     * frontend tool cards don't collide on id. Injected via config so it can be shared across the new
+     * instance rebuilt on compaction; defaults to a fresh one.
+     */
+    private readonly toolCallIds;
+    /** Cumulative session tokens. */
+    sessionTokens: TokenCounts;
+    constructor(config: GenerativeModelConfig);
+    /**
+     * Streaming generation (a single attempt, no internal retry). Merges
+     * `params.newMessages` into one UniMessage to issue a stateful request, translating streamed
+     * UniEvents into OmniMessages.
+     *
+     * **Never throws to `context_engine`**: whether it ends normally or is interrupted/errors out,
+     * every `partial_*` segment is closed as `start → delta → stop → complete message`,
+     * and the terminal state is then returned as `LLMOutcome`:
+     *   - **Normal completion**: `finish()` closes out and produces `token_usage` (usage is only
+     *     produced in this case) → `completed`;
+     *   - **Idle timeout / network drop** (retryable errors like network/429/5xx):
+     *     `finishInterrupted("timeout")` closes out, produces no usage → `timeout`, reconnected by
+     *     `context_engine` within the same run;
+     *   - **AgentHub JSON parse error**: `finishInterrupted("malformed")` closes out, produces no
+     *     usage → `malformed`, likewise reconnected by `context_engine` within the same run;
+     *   - **User interruption**: `finishInterrupted("aborted")` closes out, produces no usage →
+     *     `aborted`;
+     *   - **Other non-retryable errors** (auth/parameters etc.): `finishInterrupted("failed")`
+     *     closes out, produces no usage → `failed` (carrying `message`), handed to
+     *     `context_engine` to stop and return control to the user.
+     *
+     * Timeout detection: the idle timer resets on every event received; once idle exceeds
+     * `requestTimeoutMs`, the underlying stream is aborted and handled as needing reconnection
+     * (merged with user interruption into a single internal AbortController).
+     */
+    streamGenerate(params: GenerativeModelParameters): AsyncGenerator<OmniMessage, LLMOutcome>;
+    /**
+     * Injects the replayed history in one shot when resuming a Session: converts the complete
+     * OmniMessage history, grouped by adjacent same role, into
+     * AgentHub UniMessages and calls AgentHub's setHistory, so subsequent Requests continue from a
+     * history exactly matching the original conversation. **Called only once, on a fresh context
+     * object, during resumption**; not used during normal operation, where the incremental context
+     * is maintained by AgentHub itself.
+     * Docs: /docs/sessions-and-traces § "Session recovery".
+     */
+    setHistory(history: OmniMessage[]): void;
+    /**
+     * Opens the underlying AgentHub stream (a testing seam): defaults to
+     * `streamingResponseStateful`; unit tests can subclass and override this method, feeding in a
+     * controlled UniEvent stream to verify the outcome classification for timeout/network
+     * drop/interruption/error (without a real API).
+     */
+    protected openStream(uniMessage: UniMessage, signal: AbortSignal): AsyncIterable<UniEvent>;
+}
+/** Maps a ThinkingLevelName to the AgentHub ThinkingLevel enum; returns undefined if not found. */
+declare function mapThinkingLevel(name: ThinkingLevelName | undefined): ThinkingLevel | undefined;
+/** Maps ToolDefinition[] to AgentHub ToolSchema[]. */
+declare function toolDefinitionsToSchemas(tools: ToolDefinition[]): ToolSchema[];
+/** Pre-builds UniConfig from GenerativeModelConfig (called once at construction time). */
+declare function buildUniConfig(config: GenerativeModelConfig): UniConfig;
+
+declare class Environment implements EnvironmentInterface {
+    private readonly workspaceDir;
+    private readonly toolConfig;
+    /** Assembled built-in tools: tool name -> BuiltinTool. Only tools supported by the registry and present in config. */
+    private readonly tools;
+    /** Long-running command session registry: constructed within this Environment and shared between exec_command / input_command. */
+    private readonly commandSessions;
+    /** Background subagent session registry: constructed within this Environment and shared between run_subagent / input_subagent. */
+    private readonly subagentSessions;
+    constructor(config: EnvironmentConfig);
+    /** Releases runtime resources held by Environment: finalizes all managed background sessions (command and subagent). Idempotent. */
+    dispose(): void;
+    /**
+     * Lists tools available to the current Session, for context_engine to initialize GenerativeModel.
+     * Only lists tools that have been assembled (i.e. supported by the registry) — tool names
+     * unrecognized in config are not exposed to the LLM (consistent with the constructor);
+     * the definition (description/parameters) treats **the config entry as the single source of
+     * truth** — factories must not rewrite the definition at runtime; where a differentiated
+     * implementation is needed, use a separate explicit tool-name entry with a `forModel`
+     * annotation (e.g. read_image / describe_image).
+     * Only exposes `{name, description, parameters}`, dropping permission/maxOutputLength.
+     * MCP Server config flows into Environment via toolConfig; enumerating concrete MCP tools
+     * is left to a later adapter layer.
+     */
+    listTools(): Promise<ToolDefinition[]>;
+    /** Looks up a tool's permission level (for the frontend's permission-mode decisions); returns undefined for an unknown tool. */
+    toolPermission(name: string): ToolPermission | undefined;
+    /**
+     * Executes an approved tool call, streaming `partial_tool_call_output` and a final
+     * `tool_call_output`; nested messages carrying origin pass through unchanged. Dispatches by
+     * looking up the tool name; any exception collapses into an explanatory output — never throws.
+     *
+     * The priority for deciding stop_reason is: user interruption > timeout > tool throw > tool
+     * self-report. Interruption is determined by the `signal` held by Environment, and is
+     * compatible with both a tool self-reporting aborted and an AbortError raised by the
+     * interruption. An internal abort raised by a timeout does not count as a user interruption —
+     * it's finalized as failed, with the timeout reason written into the output.
+     * Docs: /docs/tools § "Execution contract".
+     */
+    executeTool(request: ToolExecutionRequest): AsyncGenerator<OmniMessage>;
+}
+
+/**
+ * Built-in tool registry —— maps tool names to BuiltinTool factories.
+ *
+ * Environment uses this table to assemble entries from ToolConfig into BuiltinTool instances:
+ * a tool is only assembled if its name is in the table (i.e. a supported built-in tool); the
+ * description/parameters/permission/maxOutputLength from config are injected into the tool's
+ * `definition` by each factory.
+ * When adding a new built-in tool, just register one factory entry here — no changes to
+ * Environment needed.
+ *
+ * Docs: packages/docs/content/tools.{zh,en}.md (site path /docs/tools) documents every
+ * built-in tool and the approval flow — keep the page in sync when this table changes.
+ */
+
+/**
+ * A factory that constructs a BuiltinTool instance from a tool config entry; optionally
+ * receives runtime services injected by Environment.
+ * Most tools ignore `services`; only a few (e.g. `run_subagent`) use it.
+ */
+type BuiltinToolFactory = (definition: ToolDefinitionConfig, services?: EnvironmentServices) => BuiltinTool;
+/** Tool name -> factory. */
+declare const BUILTIN_TOOL_FACTORIES: Record<string, BuiltinToolFactory>;
+
+/** Tool name constant (used only inside this tool module, not exposed to Environment). */
+declare const EXEC_COMMAND_NAME = "exec_command";
+/**
+ * exec_command built-in tool: parses arguments, resolves workdir, and delegates to
+ * `CommandSessionManager` to spawn the process and collect output.
+ * `definition` is overridden by Environment at construction time with the matching entry
+ * from ToolConfig (description/parameters/permission/limits).
+ * `services.commandSessions` is injected by Environment (shares the same registry with
+ * input_command).
+ */
+declare function createExecCommandTool(definition: ToolDefinitionConfig, services?: EnvironmentServices): BuiltinTool;
+
+/** Tool name constant. */
+declare const INPUT_COMMAND_NAME = "input_command";
+declare function createInputCommandTool(definition: ToolDefinitionConfig, services?: EnvironmentServices): BuiltinTool;
+
+/** Tool name constant (used only within this tool module, never exposed to Environment). */
+declare const SUBAGENT_NAME = "run_subagent";
+/** Builds run_subagent's BuiltinTool from tool config + injected services. */
+declare function createSubagentTool(definition: ToolDefinitionConfig, services?: EnvironmentServices): BuiltinTool;
+
+/** Tool name constant. */
+declare const INPUT_SUBAGENT_NAME = "input_subagent";
+declare function createInputSubagentTool(definition: ToolDefinitionConfig, services?: EnvironmentServices): BuiltinTool;
+
+interface WriterOptions {
+    /** Trace root directory, typically `<agent>/traces`. */
+    tracesDir: string;
+    /** Current Session id, written into the file name. */
+    sessionId: string;
+    /** The time used to derive the date subdirectory; defaults to `new Date()`. */
+    date?: Date;
+    /**
+     * Directly specifies the date subdirectory name (used when Session resumption continues
+     * writing to the original file: the Trace file follows the context, not the date); takes
+     * priority over `date`.
+     */
+    dateDir?: string;
+    /** Starting Trace index (used when Session resumption continues the original index); defaults to 1. */
+    startIndex?: number;
+}
+/**
+ * append-only JSONL Trace writer.
+ *
+ * Single-writer scenario (MVP): concurrency safety isn't required, but every write uses
+ * `appendFile` (O_APPEND) rather than caching a file handle and seeking to write, avoiding
+ * overwriting existing content; this also removes the need for an explicit close.
+ */
+declare class Writer {
+    private readonly tracesDir;
+    private readonly sessionId;
+    private readonly dateDir;
+    /** Current Trace index, starting at 1; incremented by `rotate()`. */
+    private index;
+    /** Set true once the date directory has been created for the current file, to avoid a redundant mkdir. */
+    private ensuredDirForIndex;
+    constructor(opts: WriterOptions);
+    /** Absolute path of the current Trace file. */
+    currentPath(): string;
+    /**
+     * Appends one message. Only written if it's a recordable message; streaming `partial_*` is
+     * skipped. `mkdir -p`s the date directory on the first write to the current file.
+     */
+    write(msg: OmniMessage): Promise<void>;
+    /** Writes multiple messages in sequence. */
+    writeAll(msgs: OmniMessage[]): Promise<void>;
+    /**
+     * Aggregates a message stream mixed with streaming `partial_*` into complete messages first,
+     * then writes them per the `write` convention. A convenience helper: `write` skips partial_*
+     * by default (the producer will already append the complete message), so this method is only
+     * needed when reconstructing a complete context from raw streaming fragments.
+     */
+    aggregateAndWrite(msgs: OmniMessage[]): Promise<void>;
+    /**
+     * Starts a new Trace file: increments the index, so the next `write` goes to the new file.
+     * Used to split into a separate file when the context is compacted and a new context segment is produced.
+     * Docs: /docs/sessions-and-traces § "Trace design".
+     */
+    rotate(): Promise<void>;
+}
+/** Parses a Trace file line by line (ignoring blank lines), for testing and later reads. */
+declare function readTrace(path: string): Promise<OmniMessage[]>;
+
+/** Replay result: all the state needed to resume a Session. */
+interface ResumeResult {
+    /** Committed history (complete model_msg, in order), injected in one shot via setHistory; empty on compaction closure. */
+    history: CompleteModelMessage[];
+    /**
+     * Pending input (carry-over): resent alongside new input with the first `run` after resume.
+     * Already includes pairing-backfill placeholders — placeholders exist only in memory
+     * (synthesized carry-over is never written to Trace) and are resynthesized on each resume.
+     */
+    carryOver: OmniMessage[];
+    /** Compaction closure (file-level): this file's context is fully closed; resume starts a new, empty context. */
+    contextClosed: boolean;
+    /** Compaction closure in summarize mode: the reconstructed `<context_summary>` summary, prepended to the next run's input. */
+    pendingSummary?: OmniMessage;
+    /** Session-level cumulative Token carry-over (the session value from the last token_usage). */
+    sessionTokens: TokenCounts;
+    /** The request.total from the last token_usage (context usage figure). */
+    lastRequestTotal: number;
+    /** Session cumulative turn count carry-over (count of completed requests). */
+    sessionTurns: number;
+    /** Rendering view: this context's complete model_msg plus key event_msg entries (including interrupted turns and their markers); empty on compaction closure. */
+    renderMessages: OmniMessage[];
+    /** The file's first session_meta; null if missing (unresumable — the caller reports the error). */
+    meta: SessionMetaMessage | null;
+}
+/**
+ * Parse Trace JSONL content. Tolerates a **truncated last line** left behind by an abnormal
+ * process exit (that line is ignored); corruption in the middle is outside the crash window
+ * (append-only, single writer), so it throws loudly.
+ */
+declare function parseTraceLines(content: string): OmniMessage[];
+/** Read and parse a Trace file (tolerates a truncated last line). */
+declare function readTraceTolerant(path: string): Promise<OmniMessage[]>;
+/** A located Trace file: its path, containing date-directory name, and index. */
+interface LocatedTraceFile {
+    path: string;
+    dateDir: string;
+    index: number;
+}
+/**
+ * Locate the **highest-index** Trace file for a Session (one Trace file corresponds to one
+ * complete model context). Scans `<tracesDir>/<yyyy-mm-dd>/<sessionId>_<index3>.jsonl`; returns
+ * null if no match is found.
+ */
+declare function findLatestTraceFile(tracesDir: string, sessionId: string): Promise<LocatedTraceFile | null>;
+/**
+ * The id of the most recent Session under this Agent, determined by the timestamp embedded in
+ * session_id (ids are zero-padded, so lexical order equals chronological order). Returns null if
+ * there are no Sessions.
+ */
+declare function latestSessionId(tracesDir: string): Promise<string | null>;
+/**
+ * Replay a Trace file (the current context), reconstructing history and carry-over input.
+ * Input is the message sequence parsed by `readTraceTolerant`.
+ */
+declare function resumeTrace(messages: OmniMessage[]): ResumeResult;
+
+/** Trace sink: `write` a complete/event/meta message; `rotate` starts a new file (compaction splits files). */
+interface TraceSink {
+    write(msg: OmniMessage): Promise<void>;
+    /** Optional: start a new Trace file (index+1), used to record the new model context after compaction. */
+    rotate?(): Promise<void>;
+}
+/**
+ * Resolved context compaction settings (defaults filled in by the composition layer).
+ * Docs: /docs/agent-loop § "Compaction".
+ */
+interface CompactionSettings {
+    /** Context token threshold (uses the most recent token_usage's request.total); <=0 disables it. */
+    maxContextLength: number;
+    /** Session cumulative turn threshold (counted per LLM Request, across Tasks); <=0 means no limit. */
+    maxSessionTurns: number;
+    mode: CompactionMode;
+    /** Prompt used for summarize compaction. */
+    prompt: string;
+}
+/**
+ * Options for `run`.
+ * Docs: /docs/agent-loop § "Inputs and outputs".
+ */
+interface RunOptions {
+    /** Abort signal (e.g. Ctrl-C). */
+    signal?: AbortSignal;
+    /** Per-tool approval callback; defaults to denying everything (conservative, to avoid accidental approval when unattended). */
+    approve?: ApproveFn;
+}
+/**
+ * Engine initial state (used for Session resumption): derived by replaying Trace, so the
+ * resumed engine behaves the same as before the process
+ * exited. Not passed when creating a normal new Session.
+ */
+interface EngineInitialState {
+    /** Pending input (carry-over): resent alongside new input on the first `run` after resumption (synthetic placeholders exist only in memory, never written to Trace). */
+    carryOver?: OmniMessage[];
+    /** Summary recovered from a completed summarize compaction: used as the prefix of the next `run` input (merged with the user Prompt). */
+    pendingSummary?: OmniMessage;
+    /** Carried-over Session cumulative turn count. */
+    sessionTurns?: number;
+    /** Carried-over Session cumulative token counts (handed to the new object when compaction swaps it in). */
+    sessionTokens?: TokenCounts;
+    /** Most recent token_usage's request.total (the context usage figure, keeps compaction threshold checks continuous). */
+    lastRequestTotal?: number;
+    /** Recovered from a completed compaction: the context is already closed, so rotate the Trace file (index+1, writing session_meta) before the first write. */
+    pendingTraceRotation?: boolean;
+}
+interface ContextEngineDeps {
+    llm: LLMInterface;
+    environment: EnvironmentInterface;
+    /** Optional Trace writer; the writer is responsible for filtering out streaming partial_* messages. */
+    trace?: TraceSink;
+    /** Engine initial state (derived by replaying Trace on Session resumption). */
+    initialState?: EngineInitialState;
+    /** Maximum LLM turns for a single Task. Defaults to 100. */
+    maxTurns?: number;
+    /** Maximum automatic retries for LLM timeout/reconnect within a single run. Defaults to 2. */
+    maxReconnects?: number;
+    /** Linear backoff base (ms) before each reconnect retry; actual backoff = base × retry number. Defaults to 250. */
+    reconnectBackoffMs?: number;
+    /**
+     * Creates a new LLM object after compaction (a fresh model context); the argument is the
+     * current Session cumulative token counts, for the new object to carry forward
+     * (token_usage.session stays continuous across compaction). Context compaction is
+     * unavailable if this is not provided.
+     */
+    createLLM?: (sessionTokens: TokenCounts) => LLMInterface;
+    /** Context compaction settings; only takes effect if provided together with `createLLM`. */
+    compaction?: CompactionSettings;
+    /** This Session's session_meta message; written at the start of the new Trace file after compaction splits it. */
+    sessionMeta?: OmniMessage;
+}
+/** Whether compaction is possible; when not `ok`, `compact()` is a no-op and yields no messages (see ContextEngine.compactability). */
+type CompactAvailability = "ok" | "unsupported" | "empty" | "just_compacted";
+declare class ContextEngine {
+    private readonly deps;
+    private readonly maxTurns;
+    private readonly maxReconnects;
+    private readonly reconnectBackoffMs;
+    /** Interruption cleanup: content to resend generated when the previous run was aborted, held on the engine across runs. */
+    private pendingCarryOver;
+    /** Current LLM object; swapped for a new one created by `createLLM` after a successful compaction (a fresh model context). */
+    private llm;
+    /** Session cumulative turn count: counted per LLM Request that produces token_usage, across Tasks; reset to zero after compaction completes. */
+    private sessionTurns;
+    /** Whether the current context was produced by a compaction (`startNewContext`); this flag becomes meaningless once a new completed turn occurs. */
+    private fromCompaction;
+    /** Most recent token_usage's request.total, i.e. the current context usage figure. */
+    private lastRequestTotal;
+    /** Most recent token_usage's session cumulative counts, handed to the new LLM object when compaction swaps it in. */
+    private lastSessionTokens;
+    /** Summary produced by a Task-boundary compaction: used as the prefix of the next `run` input (merged with the next user Prompt). */
+    private pendingSummary;
+    /**
+     * Set to true once compaction completes: Trace rotation is deferred until the next
+     * message that needs writing (see `write`) — so that if no further messages follow the
+     * compaction, we don't create an empty file containing only session_meta.
+     */
+    private pendingTraceRotation;
+    constructor(deps: ContextEngineDeps);
+    /**
+     * Runs a Task to completion, streaming out OmniMessage. `newMessages` is this call's
+     * Prompt (only the newly added input, not the full history — history is maintained by the
+     * stateful GenerativeModel); `opts.signal` is the abort signal, `opts.approve` is the
+     * per-tool approval callback.
+     * Docs: /docs/agent-loop § "The loop at a glance".
+     */
+    run(newMessages: OmniMessage[], opts?: RunOptions): AsyncGenerator<OmniMessage>;
+    /**
+     * User-initiated compaction request (e.g. a CLI command): reuses the automatic compaction
+     * flow without checking thresholds (reason=manual). Only callable at a Task boundary (between
+     * runs); streams out paired compaction events. No-op when compaction is not configured.
+     *
+     * Carry-over left over from an interruption is cleaned up here too: summarize folds it into
+     * the compaction request (structured tool outputs keep their pairing with the already
+     * committed tool_call, otherwise the compaction request itself would be rejected by the
+     * provider as an unanswered tool_use, see issue #33; flatten text is absorbed into the
+     * summary); discard drops the structured outputs paired with the old context, keeping only the
+     * self-contained flatten text.
+     */
+    /**
+     * Whether compaction is possible, and the **reason** when it isn't.
+     *
+     * `compact()` is a no-op and **yields no messages** in these cases; if the UI treats invoking
+     * it as a successful start, it ends up waiting forever for a compaction banner that never
+     * arrives — that's exactly how "/compact does nothing after an interruption" happens. Callers
+     * (Web / CLI) should give feedback upfront based on this.
+     *
+     *   - `unsupported`: compaction capability is not configured;
+     *   - `empty`: the current context hasn't completed a single turn (`sessionTurns` only
+     *     increments when `token_usage` arrives — a turn only counts once the request finishes
+     *     normally, so it's still 0 right after the first request is interrupted);
+     *   - `just_compacted`: no new conversation since the last compaction. Both cases have
+     *     `sessionTurns` === 0, but they mean two completely different things to the user and must
+     *     not be conflated.
+     */
+    compactability(): CompactAvailability;
+    compact(opts?: {
+        signal?: AbortSignal;
+    }): AsyncGenerator<OmniMessage>;
+    /**
+     * Linear backoff before a reconnect retry (base × retry number, numbering starts at 1);
+     * returns false if the user interrupts during the backoff, so the caller can proceed to
+     * interruption cleanup.
+     */
+    private backoff;
+    /**
+     * Runs one LLM turn: consumes the LLM stream, approving each complete tool_call immediately;
+     * "allow" runs it concurrently (without blocking further stream consumption/approval), "deny"
+     * feeds back an aborted output. partial/complete tool_call_output is yielded in completion
+     * order. Returns all of this turn's tool outputs (for the next turn) and whether it was
+     * interrupted midway.
+     * Docs: /docs/agent-loop § "Lifecycle of a turn".
+     */
+    private runTurn;
+    /**
+     * Executes a single approved tool: streams its partial/complete tool_call_output (through the
+     * queue), and collects the complete tool_call_output into toolOutputs.
+     *
+     * Environment is contracted to handle all errors internally: it guarantees exactly one
+     * complete `tool_call_output` to close out and never throws. But since
+     * EnvironmentInterface can be injected by consumers via a public API, if a contract-violating
+     * exception escapes, this fire-and-forget promise would take down the process with an
+     * unhandled rejection, and the missing output would leave the already-committed tool_use
+     * unanswered (the next request gets rejected by the provider) — so a boundary safety net is
+     * kept here, collapsing a contract-violating exception into a failed output. This guarantees
+     * exactly one complete output per tool enters toolOutputs, keeping tool_use and tool_result
+     * paired.
+     */
+    private executeOne;
+    /** Max turns reached: emits a failed notice (streaming fragments + complete text) for CLI/frontend rendering. */
+    private emitMaxTurns;
+    /**
+     * Checks the compaction threshold: triggers once context usage (the most recent
+     * token_usage's request.total) or the Session cumulative turn count **reaches** the threshold
+     * (>=) — e.g. maxSessionTurns=1 compacts as soon as turn 1 completes, without waiting for the
+     * next Task; when both are configured, either reaching its threshold triggers compaction.
+     * Never triggers when compaction is not configured.
+     * Docs: /docs/agent-loop § "Compaction".
+     */
+    private compactionTrigger;
+    /** Records context usage and Session cumulative counts from a token_usage event; returns whether the message is a token_usage. */
+    private observeTokenUsage;
+    /**
+     * `discard` compaction: sends no compaction request, simply discards the old context —
+     * swaps in a new LLM object and splits a new Trace file, with the next turn's input used
+     * unchanged as the new object's first input. Only runs at a Task boundary (deferred by the
+     * caller while mid-Task).
+     */
+    private discardContext;
+    /**
+     * `summarize` compaction: appends the compaction Prompt to the **old** LLM object (first
+     * folding in all of this turn's tool results when mid-Task, to keep tool_use/tool_result
+     * pairing), then extracts the `<summary>` and wraps it as `<context_summary>` user text. The
+     * compaction request's streamed output is not pushed to the Human output stream (it emits
+     * paired compaction events, plus the compaction request's `token_usage` — positioned between
+     * the two events, so the frontend can count compaction cost into its stats), but it is written
+     * to the old Trace. timeout/malformed reconnect via the existing retry mechanism, collapsing
+     * to failed once retries are exhausted; on failure/abort, the original context and Trace index
+     * are kept — it does not fall back to discard.
+     * Docs: /docs/agent-loop § "Compaction".
+     */
+    private summarizeContext;
+    /**
+     * Issues one compaction request (an ordinary LLM Request): consumes the old LLM object's
+     * streamed output but **does not push it to the Human output stream** (except `token_usage`
+     * — captured and handed back via the return value for summarizeContext to yield); complete
+     * messages and events are written to the old Trace; complete text segments are collected as
+     * the compaction output. Token usage is counted into the Session cumulative totals (recorded
+     * via observeTokenUsage, for the new object to carry forward).
+     */
+    private runCompactionRequest;
+    /**
+     * Opens a new model context after successful compaction: swaps in a new LLM object (carrying
+     * forward the Session cumulative token counts), resets the Session turn count and context
+     * usage counter. Trace **does not** split files immediately — that's deferred until the next
+     * message that needs writing, when it rotates and opens with a session_meta (see `write`),
+     * avoiding an empty file if no further messages follow the compaction.
+     */
+    private startNewContext;
+    /** Yields and records a compaction start event (carrying reason/mode/current context usage/Session cumulative turns). */
+    private emitCompactionBegin;
+    /** Yields and records a compaction stop event (carrying the result status; non-completed means compaction was abandoned). */
+    private emitCompactionEnd;
+    /** Interruption: emits an abort event. Cleanup/resending is managed centrally by `run` via carry-over; the LLM history is never touched again. */
+    private emitAbort;
+    /**
+     * Builds the interruption resend content (carry-over, interruption cleanup)
+     * based on the LLM's terminal state. Used only for the **exit** cleanup of
+     * aborted / failed (reconnect retry doesn't go through here — retry input is assembled by
+     * withRetriedTurns, appending `<turn_retried>` with the failed attempt's output, distinct
+     * from the user-interruption `<turn_aborted>`):
+     * - Model output completed (case A, outcome=completed): AgentHub already committed an
+     *   assistant turn containing `tool_call`, so it can only be resent as a structured
+     *   `tool_call_output` to pair with it (cannot flatten, or the already-committed tool_call
+     *   would be left unanswered and rejected).
+     * - Model output incomplete (case B): the `tool_call_output` in this turn's input (paired
+     *   with the previous completed turn) is kept as-is; the text input and this turn's
+     *   thinking/text/tool call/result are flattened into a single `<turn_aborted>` plain-text
+     *   user message.
+     * Docs: /docs/agent-loop § "Interruption and carry-over".
+     */
+    private buildCarryOver;
+    /**
+     * Case B: flattens this attempt's input and its produced content into carry-over. Structured
+     * `tool_call_output` in the input (paired with the previous completed turn) is kept as-is;
+     * everything else (text input, model thinking/text, this attempt's tool calls/results) is
+     * transcribed into a single `<turn_aborted>` plain-text user message (includes all
+     * completed and incomplete messages, including partial thinking/text). If the input text is
+     * itself already a `<turn_aborted>` block (from a previous attempt or a previous run's
+     * carry-over), its content is unwrapped and merged in, keeping a single-level structure.
+     *
+     * TODO(multimodal): only text input is currently kept — `image_url` / `inline_data` input is
+     * lost during flatten (the `<turn_aborted>` structure has no corresponding transcription yet);
+     * multimodal carry-over support to be added later.
+     */
+    private flattenCarryOver;
+    /** Transcribes the interrupted turn's input, model thinking/text, and tool calls/results into a single `<turn_aborted>` plain-text block. */
+    private buildTurnAbortedText;
+    /**
+     * Assembles the reconnect retry input: the original input is kept as-is (structure and
+     * multimodal content preserved), with a `<turn_retried>` text appended at the end carrying
+     * each failed attempt's thinking/text and tool calls/results produced so far; if nothing has
+     * been produced yet, it's just the original input. The synthetic message is sent to the model
+     * only and not written to Trace (same rule as flatten carry-over).
+     * Docs: /docs/agent-loop § "Automatic reconnect".
+     */
+    private withRetriedTurns;
+    /**
+     * Trace writes are **best-effort**: observability should never interrupt the ReAct
+     * loop, so write failures only warn rather than throw. The first write after compaction first
+     * performs the deferred Trace rotation: splitting the file and opening it with session_meta.
+     */
+    private write;
+}
+
+interface SessionTitleResult {
+    /** The sanitized title; null when material is insufficient, the request fails, or the output is empty. */
+    title: string | null;
+    /** Token consumption for this request (accumulated token_usage.request); null if no request occurred or there's no usage. */
+    usage: TokenCounts | null;
+}
+/**
+ * Assembles the title-generation Prompt (exported for host/test assertion use). Uses English
+ * instructions to avoid polluting the title's language, and requires the **title to be in the
+ * same language as the conversation** (English conversation gets an English title, Chinese
+ * conversation gets a Chinese title); when assistant material is empty, it relies on the user
+ * request alone.
+ */
+declare function buildTitlePrompt(userExcerpt: string, assistantExcerpt: string): string;
+/** Sanitizes model output into a title: strips leading/trailing quotes/brackets and trailing punctuation (until stable), collapses whitespace, and truncates if too long; returns null for an empty result. */
+declare function sanitizeTitle(raw: string): string | null;
+/**
+ * Drives a single title-generation request: collects model text and token_usage, and resolves
+ * based on the outcome. Generation only requires user material (assistant material may be
+ * empty — a pure tool-only turn can still get a title); no request is sent if user material is
+ * empty; `title` is null if the request doesn't complete (any usage already produced is still
+ * returned).
+ */
+declare function generateTitleWithLLM(llm: LLMInterface, args: {
+    userText: string;
+    assistantText: string;
+    signal?: AbortSignal;
+}): Promise<SessionTitleResult>;
+
+interface SessionConfig {
+    /** Session metadata (session_id / provider / model_id / model_context_window / system_prompt / tools / thinking_level / agent_state / workspace). */
+    meta: SessionMetaPayload;
+    llm: LLMInterface;
+    environment: EnvironmentInterface;
+    trace?: TraceSink;
+    maxTurns?: number;
+    /** Creates a new LLM object after compaction (carries over the Session's accumulated Token count); context compaction is unavailable if not provided. */
+    createLLM?: (sessionTokens: TokenCounts) => LLMInterface;
+    /**
+     * Factory for the bare LLM used by out-of-band, one-off requests (same Model/credential as
+     * the session; no tools, no system prompt, thinking off): used for meta-requests such as
+     * `generateTitle`; if not provided, `generateTitle` returns null.
+     */
+    createBareLLM?: () => LLMInterface;
+    /** Context compaction settings (defaults are filled in by the composition layer); only takes effect when provided together with `createLLM`. */
+    compaction?: CompactionSettings;
+    /** Session resume: `session_meta` is already in the original Trace file, so it isn't written again on the first run (avoids duplication). */
+    metaAlreadyWritten?: boolean;
+    /** Session resume: the engine's initial state derived from Trace replay (carry-over / accumulated stats, etc.). */
+    initialEngineState?: EngineInitialState;
+    /** Session resume: the full historical messages of the current context (for rendering, including interrupted turns and their markers), for frontend display. */
+    resumedHistory?: OmniMessage[];
+    /**
+     * Set when the session's model doesn't support images (the composition layer decides this via
+     * ModelEntry.vision): images in `run` input are saved to this directory (the session's
+     * scratchpad), and the path is appended to the user text instead — the model views the image
+     * via describe_image, and images never enter the session history directly (some providers
+     * return a 400 outright on image input).
+     */
+    inputImagesDir?: string;
+}
+declare class Session {
+    readonly sessionId: string;
+    /** The session model's provider group (paired with `modelId` to form the model reference). */
+    readonly provider: string;
+    /** The session model's upstream model_id (the request id sent to AgentHub). */
+    readonly modelId: string;
+    readonly workspaceDir: string;
+    /** Session resume: the full historical messages of the current context (for rendering); undefined for a non-resumed Session. */
+    readonly resumedHistory?: OmniMessage[];
+    private readonly engine;
+    private readonly environment;
+    private readonly trace?;
+    private readonly meta;
+    private readonly createBareLLM?;
+    private readonly inputImagesDir?;
+    private metaWritten;
+    /** Title material (used by `generateTitle` as the default): the user input and model body text of the first Task that contains user text. */
+    private titleUserText;
+    private titleAssistantText;
+    /** Material-frozen flag: becomes true once the first Task containing user text finishes; subsequent runs stop accumulating. */
+    private titleMaterialFrozen;
+    constructor(config: SessionConfig);
+    /**
+     * Runs a Task to completion and streams out OmniMessage. `newMessages` is this call's Prompt
+     * (only the newly added input); `opts` carries the abort signal `signal` and the per-call
+     * approval callback `approve` (the engine calls it once per tool_call within a turn).
+     * On the first run, `session_meta` is written to the Trace first.
+     *
+     * A single `run` automatically drives the whole ReAct loop: consuming the LLM stream,
+     * approving and executing tools one at a time, feeding results back for the next turn,
+     * until a turn no longer produces a tool_call (Task ends) or it's aborted.
+     * Docs: /docs/agent-loop § "The loop at a glance".
+     */
+    run(newMessages: OmniMessage[], opts?: RunOptions): AsyncGenerator<OmniMessage>;
+    /**
+     * User-initiated request to compact context (e.g. a CLI command): reuses the automatic
+     * compaction flow but skips the threshold check (reason=manual). Only callable at Task
+     * boundaries (between runs); streams out paired `compaction` events. The summarize digest
+     * becomes the prefix of the next `run`'s input (merged with the next user Prompt). A no-op
+     * if compaction isn't configured.
+     * Docs: /docs/agent-loop § "Compaction".
+     */
+    compact(opts?: {
+        signal?: AbortSignal;
+    }): AsyncGenerator<OmniMessage>;
+    /**
+     * Whether compaction is possible, and why not if not (see ContextEngine.compactability).
+     * When the result isn't `ok`, `compact()` is a no-op and yields no messages — callers should
+     * give feedback based on this rather than triggering a silent, fruitless compaction.
+     */
+    compactability(): CompactAvailability;
+    /** Writes `session_meta` to the Trace before the first run/compaction; best-effort — failure doesn't interrupt the run. */
+    private ensureMetaWritten;
+    /**
+     * Out-of-band, one-off request that generates a short title from the first-turn conversation
+     * text: sends one request using the bare LLM for the session's Model (no
+     * tools, no system prompt, thinking off), **without writing history or Trace**. Material
+     * defaults to the first Task text self-captured by the Session (user input and model body
+     * text collected during run; thinking and tool calls don't count), so callers don't need to
+     * supply it; `material` can override this (e.g. when a host generates a title for a
+     * sub-session — the material is that sub-session's own conversation). `title` is null if the
+     * material is empty, the request fails, or the composition layer didn't supply a bare LLM
+     * factory. Token consumption is returned via `usage` for the host to account for.
+     * Docs: /docs/agent-loop § "Side channels".
+     */
+    generateTitle(args?: {
+        /** Material override; defaults to the Session's self-captured material. */
+        material?: {
+            userText: string;
+            assistantText: string;
+        };
+        signal?: AbortSignal;
+    }): Promise<SessionTitleResult>;
+    /** Queries a tool's permission level (for the frontend to determine permission mode); returns undefined for unknown tools. */
+    toolPermission(name: string): ToolPermission | undefined;
+    /** This Session's session_meta message (used e.g. by host tools to forward nested-session metadata to a parent session). */
+    get metaMessage(): OmniMessage;
+    /**
+     * Releases runtime resources held by the Session: kills long-running command sessions
+     * managed by the Environment. The host calls this when the Session ends (CLI exit, Web
+     * session close) to avoid leaking background processes into the host process's lifetime.
+     * Optional, idempotent.
+     */
+    dispose(): void;
+}
+
+interface CreateAgentOptions {
+    agentId?: string;
+    projectId?: string;
+    /** Local data root directory; defaults to `resolveRoot()` (PENGUIN_HOME or ~/.penguin/data). */
+    root?: string;
+}
+interface CreateSessionOptions {
+    /** Workspace for this run; if unspecified, a temporary Workspace is created under the Agent directory. */
+    workspaceDir?: string;
+    /** Model used for this Session (upstream model_id); if unspecified, uses the Project's default Model. */
+    modelId?: string;
+    /**
+     * Provider grouping for `modelId` (a paired reference); if omitted, resolved via
+     * `resolveModelRef` semantics — `model_id` only resolves if it is a globally unique
+     * exact match in the config; zero or multiple matches produce a clear error.
+     */
+    provider?: string;
+    /** Explicit credentials; if unspecified, falls back to credentials in the Project config, then to AgentHub reading environment variables. */
+    apiKey?: string;
+    baseUrl?: string;
+    /** Internal use: this Session's depth in the subagent spawn chain (0 at the top level), used to cap spawn depth. */
+    subagentDepth?: number;
+}
+interface ResumeSessionOptions {
+    /** Id of the Session to resume. */
+    sessionId: string;
+    /** Explicit credentials; if unspecified, falls back to credentials in the Project config, then to AgentHub reading environment variables. */
+    apiKey?: string;
+    baseUrl?: string;
+}
+/** Create or load an Agent. */
+declare function createAgent(opts?: CreateAgentOptions): Promise<Agent>;
+declare class Agent {
+    readonly state: AgentState;
+    readonly projectConfig: ProjectConfig;
+    constructor(state: AgentState, projectConfig: ProjectConfig);
+    /**
+     * Create a Session in the specified (or a temporary) Workspace.
+     * Docs: /docs/sessions-and-traces § "Run model".
+     */
+    createSession(opts?: CreateSessionOptions): Promise<Session>;
+    /**
+     * Resume an existing Session and continue the conversation.
+     *
+     * The resume source is the Session's **latest-index** Trace file: runtime config is
+     * read from its `session_meta` (Model, the original system prompt text, and the
+     * Workspace all carry over from the original Session and cannot be changed), while
+     * tools and Environment are reassembled from the current Agent State. The replayed,
+     * already-committed history is injected once via AgentHub's setHistory (used only on
+     * resume); any leftover input is rebuilt as carry-over (paired fallback placeholders
+     * are synthesized in memory only, never written to the Trace). Messages after resume
+     * continue in the original Trace file (the file follows the context, not the date),
+     * and Token / turn-count stats carry over from their original values.
+     * Docs: /docs/sessions-and-traces § "Session recovery".
+     */
+    resumeSession(opts: ResumeSessionOptions): Promise<Session>;
+    /** Id of the most recent Session under the current Agent (determined by the timestamp in session_id); returns null if there is no Session. */
+    latestSessionId(): Promise<string | null>;
+    /**
+     * Assemble a Session's runtime components (shared by createSession and
+     * resumeSession): the child-Agent runner, Environment and tools, the LLM object
+     * and its post-compaction rebuild factory, and the compaction config.
+     */
+    private buildRuntime;
+}
+
+/**
+ * @prismshadow/penguin-core — public entry point for the PenguinHarness core SDK.
+ *
+ * Exports the OmniMessage protocol, the three interface contracts (Human/LLM/Environment),
+ * and the runtime entry points for Agent / Session / context_engine along with their
+ * submodules (state / llm / environment / trace).
+ *
+ * Typical usage:
+ *
+ * ```ts
+ * const agent = await createAgent({ agentId: "default_agent" });
+ * const session = await agent.createSession({ workspaceDir, modelId });
+ * for await (const output of session.run([userText("...")])) { ... }
+ * ```
+ */
+
+/** SDK version number. */
+declare const VERSION = "0.0.1";
+
+export { AGENTS_MD_PLACEHOLDER, AGENT_ID_PLACEHOLDER, Agent, type AgentPreset, type AgentState, ApproveFn, BUILTIN_AGENT_IDS, BUILTIN_TOOL_FACTORIES, type BuiltinTool, type BuiltinToolFactory, CWD_PLACEHOLDER, type CompactAvailability, type CompactionConfig, CompactionMode, type CompactionSettings, CompleteModelMessage, ContextEngine, type ContextEngineDeps, type CreateAgentOptions, type CreateSessionOptions, DATE_PLACEHOLDER, DEFAULT_AGENT_ID, DEFAULT_COMPACTION_PROMPT, DEFAULT_PROJECT_ID, EXAMPLE_BENCHMARK_ID, EXEC_COMMAND_NAME, type EngineInitialState, Environment, EnvironmentConfig, EnvironmentInterface, EnvironmentServices, EventTranslator, GenerativeModel, GenerativeModelConfig, GenerativeModelParameters, INPUT_COMMAND_NAME, INPUT_SUBAGENT_NAME, type IdKind, type InstalledSkill, LLMInterface, LLMOutcome, type LocatedTraceFile, MCPServerConfig, OS_VERSION_PLACEHOLDER, OmniMessage, PLATFORM_PLACEHOLDER, PROJECT_DIR_PLACEHOLDER, ProjectConfig, type ResumeResult, type ResumeSessionOptions, type RunOptions, SESSION_ID_PLACEHOLDER, SKILL_METADATA_PLACEHOLDER, SUBAGENT_NAME, Session, type SessionConfig, type SessionEnvironmentValues, SessionMetaMessage, SessionMetaPayload, type SessionTitleResult, StopReason, type SystemConfig, ThinkingLevelName, TokenCounts, ToolCallIdAllocator, ToolConfig, ToolDefinition, ToolDefinitionConfig, type ToolExecutionContext, ToolExecutionRequest, ToolPermission, type TraceSink, VAULT_KEYS_PLACEHOLDER, VAULT_VALUE_MAX_LENGTH, VERSION, Writer, type WriterOptions, agentDir, agentStateDir, agentStateVersion, agentVaultPath, agentsDir, agentsMdPath, assembleSystemPrompt, assertValidId, assertValidVaultKey, assertValidVaultValue, benchmarksDir, buildExampleScoreboard, buildTitlePrompt, buildToolConfig, buildUniConfig, builtinProjectAgentPresets, createAgent, createExecCommandTool, createInputCommandTool, createInputSubagentTool, createSubagentTool, defaultAgentsMd, defaultSystemConfig, findLatestTraceFile, generateTitleWithLLM, groupHistoryToUniMessages, installSkill, isIncompleteStreamError, isMalformedJsonParseError, isRetryableError, isValidId, isValidVaultKey, latestSessionId, listInstalledSkills, loadAgentVault, loadOrInitAgentState, mapThinkingLevel, memoryDir, mergeOmniToUniMessage, parseTraceLines, projectConfigPath, projectDir, provisionExampleBenchmark, provisionProjectAgents, readTrace, readTraceTolerant, removeSkill, removeVaultEntry, resolveRoot, resumeTrace, sanitizeTitle, saveAgentVault, scheduleDir, scratchpadDir, selectBuiltinToolsForModel, setVaultEntry, skillMetadataSection, skillsDir, snapshotsDir, systemConfigPath, toolDefinitionsToSchemas, toolsDir, tracesDir, translateEvents, usageToTokenCounts, workspacesDir };