@sema-ai/core 1.275.1

package/dist/engine/harness/types.d.ts

@@ -0,0 +1,713 @@
+import type { DocumentContent, ImageContent, Model, SimpleStreamOptions, TextContent, Transport } from "../llm/index.js";
+import type { AgentEvent, AgentMessage, AgentTool, QueueMode, ThinkingLevel } from "../loop/types.js";
+import type { AgentCoreRuntimeDeps } from "../loop/runtime-deps.js";
+/** Result of a fallible operation. Expected failures are returned as `ok: false` instead of thrown. */
+export type Result<TValue, TError> = {
+    ok: true;
+    value: TValue;
+} | {
+    ok: false;
+    error: TError;
+};
+/** Create a successful {@link Result}. */
+export declare function ok<TValue, TError>(value: TValue): Result<TValue, TError>;
+/** Create a failed {@link Result}. */
+export declare function err<TValue, TError>(error: TError): Result<TValue, TError>;
+/** Return the success value or throw the failure error. Intended for tests and explicit adapter boundaries. */
+export declare function getOrThrow<TValue, TError>(result: Result<TValue, TError>): TValue;
+/** Return the success value or `undefined`. Only object values are allowed to avoid truthiness bugs with primitives. */
+export declare function getOrUndefined<TValue extends object, TError>(result: Result<TValue, TError>): TValue | undefined;
+/** Normalize unknown thrown values into Error instances before using them as typed error causes. */
+export declare function toError(error: unknown): Error;
+/**
+ * Skill loaded from a `SKILL.md` file or provided by an application.
+ *
+ * `name`, `description`, and `filePath` are inserted into the system prompt in an XML-formatted block as suggested by agentskills.io.
+ */
+export interface Skill {
+    /** Stable skill name used for lookup and model-visible listings. */
+    name: string;
+    /** Short model-visible description of when to use the skill. */
+    description: string;
+    /** Full skill instructions. */
+    content: string;
+    /** Absolute path to the skill file. Used for model-visible location and resolving relative references. */
+    filePath: string;
+    /** Exclude this skill from model-visible skill lists while still allowing explicit application invocation. */
+    disableModelInvocation?: boolean;
+}
+/** Prompt template that can be formatted into a prompt for explicit invocation. */
+export interface PromptTemplate {
+    /** Stable template name used for lookup or application command routing. */
+    name: string;
+    /** Optional description for command lists or autocomplete. */
+    description?: string;
+    /** Template content. Argument placeholders are formatted by `formatPromptTemplateInvocation`. */
+    content: string;
+}
+/** Resources made available to explicit invocation methods and system-prompt callbacks. */
+export interface AgentHarnessResources<TSkill extends Skill = Skill, TPromptTemplate extends PromptTemplate = PromptTemplate> {
+    /** Prompt templates available for explicit invocation. */
+    promptTemplates?: TPromptTemplate[];
+    /** Skills available to the model and explicit skill invocation. */
+    skills?: TSkill[];
+}
+/** Curated provider request options owned by the harness and snapshotted per turn. */
+export interface AgentHarnessStreamOptions {
+    /** Preferred transport forwarded to the stream function. */
+    transport?: Transport;
+    /** Provider request timeout in milliseconds. */
+    timeoutMs?: number;
+    /** Maximum provider retry attempts. */
+    maxRetries?: number;
+    /** Optional cap for provider-requested retry delays. */
+    maxRetryDelayMs?: number;
+    /** Additional request headers merged with auth and lifecycle headers. */
+    headers?: Record<string, string>;
+    /** Provider metadata forwarded with requests. */
+    metadata?: SimpleStreamOptions["metadata"];
+    /** Provider cache retention hint. */
+    cacheRetention?: SimpleStreamOptions["cacheRetention"];
+}
+/** Per-request stream option patch returned by provider hooks. */
+export interface AgentHarnessStreamOptionsPatch extends Omit<Partial<AgentHarnessStreamOptions>, "headers" | "metadata"> {
+    /** Header patch. `undefined` values delete keys; explicit `headers: undefined` clears all headers. */
+    headers?: Record<string, string | undefined>;
+    /** Metadata patch. `undefined` values delete keys; explicit `metadata: undefined` clears all metadata. */
+    metadata?: Record<string, unknown>;
+}
+/** Kind of filesystem object as addressed by a {@link FileSystem}. Symlinks are not followed automatically. */
+export type FileKind = "file" | "directory" | "symlink";
+/** Stable, backend-independent file error codes returned by {@link FileSystem} file operations. */
+export type FileErrorCode = "aborted" | "not_found" | "permission_denied" | "not_directory" | "is_directory" | "invalid" | "not_supported"
+/** A remote fs RPC exceeded its liveness/idle bound (a hung provider call) — retryable by the caller per
+ *  the op's idempotency. Mirrors `RemoteExecutionError` code `"timeout"` so a remote `FileSystem` op can
+ *  surface a hang as a typed, retryable error instead of `"unknown"` (core src/core/remote-env.ts contract;
+ *  VENDOR.md mod #6 / service[45]/[49] class-fix). */
+ | "timeout"
+/** The transport carrying a remote fs op dropped mid-session (SSH channel death, ADB device offline) —
+ *  retryable after reconnect. Mirrors `RemoteExecutionErrorCode` `"transport_lost"`, same precedent as
+ *  `"timeout"` above (VENDOR.md mod #9 / service[63] SSH/ADB adapters), so a retry whitelist can see it
+ *  instead of an opaque `"unknown"`. */
+ | "transport_lost" | "unknown";
+/** Error returned by {@link FileSystem} file operations. */
+export declare class FileError extends Error {
+    /** Backend-independent error code. */
+    code: FileErrorCode;
+    /** Absolute addressed path associated with the failure, when available. */
+    path?: string;
+    constructor(code: FileErrorCode, message: string, path?: string, cause?: Error);
+}
+/** Stable, backend-independent execution error codes returned by {@link ExecutionEnv.exec}. */
+export type ExecutionErrorCode = "aborted" | "timeout" | "shell_unavailable" | "spawn_error" | "callback_error"
+/** The transport carrying a remote exec dropped mid-session (SSH channel death without exit-status, ADB
+ *  device offline) — the command's outcome is UNKNOWN (it may have kept running); retry only per the op's
+ *  idempotency, after reconnect. Mirrors `RemoteExecutionErrorCode` `"transport_lost"` (VENDOR.md mod #9 /
+ *  service[63] SSH/ADB adapters). */
+ | "transport_lost" | "unknown";
+/** Error returned by {@link ExecutionEnv.exec}. */
+export declare class ExecutionError extends Error {
+    /** Backend-independent error code. */
+    code: ExecutionErrorCode;
+    constructor(code: ExecutionErrorCode, message: string, cause?: Error);
+}
+/** Stable compaction error codes returned by compaction helpers. */
+export type CompactionErrorCode = "aborted" | "summarization_failed" | "invalid_session" | "unknown";
+/** Error returned by compaction helpers. */
+export declare class CompactionError extends Error {
+    /** Backend-independent error code. */
+    code: CompactionErrorCode;
+    constructor(code: CompactionErrorCode, message: string, cause?: Error);
+}
+export type SessionErrorCode = "not_found" | "invalid_session" | "invalid_entry" | "invalid_fork_target" | "storage" | "conflict" | "unknown";
+/** Error thrown by session storage, repositories, and session tree operations. */
+export declare class SessionError extends Error {
+    /** Session subsystem error code. */
+    code: SessionErrorCode;
+    constructor(code: SessionErrorCode, message: string, cause?: Error);
+}
+export type AgentHarnessErrorCode = "busy" | "invalid_state" | "invalid_argument" | "session" | "hook" | "auth" | "compaction" | "unknown";
+/** Public AgentHarness failure with a stable top-level classification. */
+export declare class AgentHarnessError extends Error {
+    code: AgentHarnessErrorCode;
+    constructor(code: AgentHarnessErrorCode, message: string, cause?: Error);
+}
+/** Metadata for one filesystem object in a {@link FileSystem}. */
+export interface FileInfo {
+    /** Basename of {@link path}. */
+    name: string;
+    /** Absolute, syntactically normalized addressed path in the execution environment. Symlinks are not followed. */
+    path: string;
+    /** Object kind. Symlink targets are not followed; use {@link FileSystem.canonicalPath} explicitly. */
+    kind: FileKind;
+    /** Size in bytes for the addressed filesystem object. */
+    size: number;
+    /** Modification time as milliseconds since Unix epoch. */
+    mtimeMs: number;
+}
+/** Options for {@link Shell.exec}. */
+export interface ExecutionEnvExecOptions {
+    /** Working directory for the command. Relative paths are resolved against {@link ExecutionEnv.cwd}. Defaults to {@link ExecutionEnv.cwd}. */
+    cwd?: string;
+    /** Additional environment variables for the command. Values override the environment defaults. Defaults to no overrides. */
+    env?: Record<string, string>;
+    /** Timeout in seconds. Implementations should return a timeout error when the command exceeds this duration. Defaults to no timeout. */
+    timeout?: number;
+    /** Abort signal used to terminate the command. Defaults to no abort signal. */
+    abortSignal?: AbortSignal;
+    /** Called with stdout chunks as they are produced. */
+    onStdout?: (chunk: string) => void;
+    /** Called with stderr chunks as they are produced. */
+    onStderr?: (chunk: string) => void;
+    /**
+     * VENDORED EDIT (design/116 detach, 飞轮 [C]): when fired mid-run, an env that supports detach ADOPTS the
+     * running child as a background process (its handle never leaves the env) and settles the exec with a
+     * `detached` marker instead of killing it. Envs without detach support ignore this (the exec runs on).
+     */
+    detachSignal?: AbortSignal;
+}
+/**
+ * Filesystem capability used by the harness.
+ *
+ * Paths passed to methods may be absolute or relative to {@link cwd}. Paths returned by file operations are addressed paths
+ * in the filesystem namespace, but are not canonicalized through symlinks unless returned by {@link canonicalPath}.
+ *
+ * Operation methods must never throw or reject. All filesystem failures, including unexpected backend failures, must be
+ * encoded in the returned {@link Result}. Implementations must preserve this invariant.
+ */
+export interface FileSystem {
+    /** Current working directory for relative paths. */
+    cwd: string;
+    /** Return an absolute addressed path without requiring it to exist and without resolving symlinks. */
+    absolutePath(path: string, abortSignal?: AbortSignal): Promise<Result<string, FileError>>;
+    /** Join path segments in the filesystem namespace without requiring the result to exist. */
+    joinPath(parts: string[], abortSignal?: AbortSignal): Promise<Result<string, FileError>>;
+    /** Read a UTF-8 text file. */
+    readTextFile(path: string, abortSignal?: AbortSignal): Promise<Result<string, FileError>>;
+    /** Read UTF-8 text lines. Implementations should stop once `maxLines` lines have been read. */
+    readTextLines(path: string, options?: {
+        maxLines?: number;
+        abortSignal?: AbortSignal;
+    }): Promise<Result<string[], FileError>>;
+    /** Read a binary file. */
+    readBinaryFile(path: string, abortSignal?: AbortSignal): Promise<Result<Uint8Array, FileError>>;
+    /** Create or overwrite a file, creating parent directories when supported. */
+    writeFile(path: string, content: string | Uint8Array, abortSignal?: AbortSignal): Promise<Result<void, FileError>>;
+    /** Create or append to a file, creating parent directories when supported. */
+    appendFile(path: string, content: string | Uint8Array, abortSignal?: AbortSignal): Promise<Result<void, FileError>>;
+    /** Return metadata for the addressed path without following symlinks. */
+    fileInfo(path: string, abortSignal?: AbortSignal): Promise<Result<FileInfo, FileError>>;
+    /** List direct children of a directory without following symlinks. */
+    listDir(path: string, abortSignal?: AbortSignal): Promise<Result<FileInfo[], FileError>>;
+    /** Return the canonical path for an existing path, resolving symlinks where supported. */
+    canonicalPath(path: string, abortSignal?: AbortSignal): Promise<Result<string, FileError>>;
+    /**
+     * VENDORED EDIT (design/72 §2.1, additive/backward-compatible): read a symlink's raw target (one
+     * hop, NOT followed). Optional — an env that omits it falls back to best-effort canonicalization
+     * for a DANGLING leaf symlink (a symlink whose target doesn't exist yet, which `canonicalPath`'s
+     * `realpath` can't resolve). Needed so a sensitive-path guard / containment check sees the real
+     * target of `write_file innocent.txt` where `innocent.txt -> .git/hooks/payload`.
+     */
+    readLink?(path: string, abortSignal?: AbortSignal): Promise<Result<string, FileError>>;
+    /** Return false for missing paths. Other errors, such as permission failures, return a {@link FileError}. */
+    exists(path: string, abortSignal?: AbortSignal): Promise<Result<boolean, FileError>>;
+    /** Create a directory. Defaults: `recursive: true`, no abort signal. */
+    createDir(path: string, options?: {
+        recursive?: boolean;
+        abortSignal?: AbortSignal;
+    }): Promise<Result<void, FileError>>;
+    /** Remove a file or directory. Defaults: `recursive: false`, `force: false`, no abort signal. */
+    remove(path: string, options?: {
+        recursive?: boolean;
+        force?: boolean;
+        abortSignal?: AbortSignal;
+    }): Promise<Result<void, FileError>>;
+    /** Create a temporary directory and return its absolute path. Defaults: `prefix: "tmp-"`, no abort signal. */
+    createTempDir(prefix?: string, abortSignal?: AbortSignal): Promise<Result<string, FileError>>;
+    /** Create a temporary file and return its absolute path. Defaults: `prefix: ""`, `suffix: ""`, no abort signal. */
+    createTempFile(options?: {
+        prefix?: string;
+        suffix?: string;
+        abortSignal?: AbortSignal;
+    }): Promise<Result<string, FileError>>;
+    /** Release filesystem resources. Must be best-effort and must not throw or reject. */
+    cleanup(): Promise<void>;
+}
+/** Shell execution capability used by the harness. */
+export interface Shell {
+    /** Execute a shell command in {@link FileSystem.cwd} unless `options.cwd` is provided. */
+    exec(command: string, options?: ExecutionEnvExecOptions): Promise<Result<{
+        stdout: string;
+        stderr: string;
+        exitCode: number;
+        detached?: {
+            shellId: string;
+        };
+    }, ExecutionError>>;
+    /** Release shell resources. Must be best-effort and must not throw or reject. */
+    cleanup(): Promise<void>;
+}
+/** Filesystem and process execution environment used by the harness. */
+export interface ExecutionEnv extends FileSystem, Shell {
+}
+/** Base fields shared by append-only session tree entries. */
+export interface SessionTreeEntryBase {
+    /** Entry discriminator used for JSONL persistence and typed narrowing. */
+    type: string;
+    /** Stable entry id unique within a session file. */
+    id: string;
+    /** Parent entry id, or null for a root entry. */
+    parentId: string | null;
+    /** ISO timestamp string used for persistence and sorting. */
+    timestamp: string;
+}
+/** Persisted transcript message entry. */
+export interface MessageEntry extends SessionTreeEntryBase {
+    type: "message";
+    message: AgentMessage;
+}
+/** Persisted thinking-level selection marker. */
+export interface ThinkingLevelChangeEntry extends SessionTreeEntryBase {
+    type: "thinking_level_change";
+    thinkingLevel: string;
+}
+/** Persisted model selection marker. */
+export interface ModelChangeEntry extends SessionTreeEntryBase {
+    type: "model_change";
+    provider: string;
+    modelId: string;
+}
+/** Persisted summary that replaces older transcript history in context. */
+export interface CompactionEntry<T = unknown> extends SessionTreeEntryBase {
+    type: "compaction";
+    summary: string;
+    firstKeptEntryId: string;
+    tokensBefore: number;
+    details?: T;
+    fromHook?: boolean;
+}
+/** Persisted harness/application marker that is not replayed into model context. */
+export interface CustomEntry<T = unknown> extends SessionTreeEntryBase {
+    type: "custom";
+    customType: string;
+    data?: T;
+}
+/** Persisted harness/application message that can be replayed into model context. */
+export interface CustomMessageEntry<T = unknown> extends SessionTreeEntryBase {
+    type: "custom_message";
+    customType: string;
+    content: string | (TextContent | ImageContent)[];
+    details?: T;
+    display: boolean;
+}
+/** Append-only label update for another session entry. */
+export interface LabelEntry extends SessionTreeEntryBase {
+    type: "label";
+    targetId: string;
+    label: string | undefined;
+}
+/** Persisted session metadata marker. */
+export interface SessionInfoEntry extends SessionTreeEntryBase {
+    type: "session_info";
+    name?: string;
+}
+/** Append-only marker that changes the active visible leaf. */
+export interface LeafEntry extends SessionTreeEntryBase {
+    type: "leaf";
+    targetId: string | null;
+}
+/** All persisted session tree entry variants. */
+export type SessionTreeEntry = MessageEntry | ThinkingLevelChangeEntry | ModelChangeEntry | CompactionEntry | CustomEntry | CustomMessageEntry | LabelEntry | SessionInfoEntry | LeafEntry;
+export interface SessionContext {
+    messages: AgentMessage[];
+    thinkingLevel: string;
+    model: {
+        provider: string;
+        modelId: string;
+    } | null;
+}
+export interface SessionMetadata {
+    id: string;
+    createdAt: string;
+    /** F7 fork-GC seam (1.175 known-limitation closed 2026-07-11): the PARENT session this one was forked
+     *  from, stamped by every `SessionRepo.fork` implementation. Durable fork sessions have no core GC
+     *  path by design — a deployment's retention/reap (service, design/109 family) reads this to identify
+     *  fork lineage (e.g. reap forks whose parent is gone/expired). Absent on a non-forked session and on
+     *  forked sessions persisted before this field shipped. */
+    forkedFrom?: string;
+}
+export interface JsonlSessionMetadata extends SessionMetadata {
+    cwd: string;
+    path: string;
+    parentSessionPath?: string;
+}
+/**
+ * Optimistic-lock options for session writes (F2). A durable backend uses `expectedLeafId` to make
+ * the write conditional — preventing cross-instance split-brain, where two stateless runners that
+ * both woke the same session append to the same parent and one branch is silently abandoned.
+ */
+export interface SessionWriteOptions {
+    /**
+     * Apply only if the current branch leaf still equals this value; on mismatch the storage throws
+     * `SessionError("conflict")`. Omit (the default) to write unconditionally. `null` means "expect an
+     * empty session". A durable backend turns this into a compare-and-set (e.g. a `(session_id, seq)`
+     * unique-key insert); the in-process base storage checks it against its in-memory leaf.
+     */
+    expectedLeafId?: string | null;
+}
+export interface SessionStorage<TMetadata extends SessionMetadata = SessionMetadata> {
+    getMetadata(): Promise<TMetadata>;
+    getLeafId(): Promise<string | null>;
+    /** Persist a leaf entry that records the active session-tree leaf. */
+    setLeafId(leafId: string | null, opts?: SessionWriteOptions): Promise<void>;
+    createEntryId(): Promise<string>;
+    appendEntry(entry: SessionTreeEntry, opts?: SessionWriteOptions): Promise<void>;
+    getEntry(id: string): Promise<SessionTreeEntry | undefined>;
+    findEntries<TType extends SessionTreeEntry["type"]>(type: TType): Promise<Array<Extract<SessionTreeEntry, {
+        type: TType;
+    }>>>;
+    getLabel(id: string): Promise<string | undefined>;
+    getPathToRoot(leafId: string | null): Promise<SessionTreeEntry[]>;
+    getEntries(): Promise<SessionTreeEntry[]>;
+}
+/**
+ * The session CONTRACT the harness consumes (`SessionApi`) — dependency inversion: the substrate defines the
+ * interface it needs; the application provides the implementation. Replaces a vendored→first-party
+ * `import type { Session }` coupling — the vendored harness no longer reaches into `engine/session/session.ts`
+ * for a concrete type, so the substrate is self-contained for the planned de-vendoring. The first-party
+ * `class Session` `implements SessionApi`. (Named `SessionApi`, not `Session`, so it coexists with the public,
+ * constructable `class Session` without a breaking public-API change.)
+ */
+export interface SessionApi<TMetadata extends SessionMetadata = SessionMetadata> {
+    getMetadata(): Promise<TMetadata>;
+    getStorage(): SessionStorage<TMetadata>;
+    getLeafId(): Promise<string | null>;
+    getEntry(id: string): Promise<SessionTreeEntry | undefined>;
+    getEntries(): Promise<SessionTreeEntry[]>;
+    getBranch(fromId?: string): Promise<SessionTreeEntry[]>;
+    buildContext(): Promise<SessionContext>;
+    getLabel(id: string): Promise<string | undefined>;
+    getSessionName(): Promise<string | undefined>;
+    appendMessage(message: AgentMessage): Promise<string>;
+    appendThinkingLevelChange(thinkingLevel: string): Promise<string>;
+    appendModelChange(provider: string, modelId: string): Promise<string>;
+    appendCompaction(summary: string, firstKeptEntryId: string, tokensBefore: number, details?: unknown, fromHook?: boolean): Promise<string>;
+    appendCustomEntry(customType: string, data?: unknown): Promise<string>;
+    appendCustomMessageEntry(customType: string, content: string | (TextContent | ImageContent)[], display: boolean, details?: unknown): Promise<string>;
+    appendLabel(targetId: string, label: string | undefined): Promise<string>;
+    appendSessionName(name: string): Promise<string>;
+}
+export interface SessionCreateOptions {
+    id?: string;
+}
+export interface SessionForkOptions {
+    entryId?: string;
+    position?: "before" | "at";
+    id?: string;
+}
+export interface SessionRepo<TMetadata extends SessionMetadata = SessionMetadata, TCreateOptions extends SessionCreateOptions = SessionCreateOptions, TListOptions = void> {
+    create(options: TCreateOptions): Promise<SessionApi<TMetadata>>;
+    open(metadata: TMetadata): Promise<SessionApi<TMetadata>>;
+    list(options?: TListOptions): Promise<TMetadata[]>;
+    delete(metadata: TMetadata): Promise<void>;
+    fork(source: TMetadata, options: SessionForkOptions & TCreateOptions): Promise<SessionApi<TMetadata>>;
+    /**
+     * 2c session-sync (service [266]②): the FULL durable entry log for `sessionId`, oldest-first, with
+     * `id`/`parentId` VERBATIM and BYPASSING any compaction floor — NOT `getEntries()`, which on a durable
+     * backend that woke with a bounded F3 window returns only the tail (silently truncating pre-floor history).
+     * Optional — a backend that supports cross-backend session export/migration implements it.
+     */
+    exportEntries?(sessionId: string): Promise<SessionTreeEntry[]>;
+    /**
+     * 2c session-sync: write a verbatim entry log (produced by {@link exportEntries} on another backend) into
+     * `sessionId`, re-stamping ownership to `owner` (from the caller's authenticated principal — never trusted
+     * from the bundle). The log MUST be passed through `validateEntriesForImport` first (the single fail-closed
+     * invariant gate); a durable backend persists THAT function's output, it does not re-implement the checks.
+     * Optional.
+     */
+    importEntries?(sessionId: string, owner: string | undefined, entries: SessionTreeEntry[]): Promise<void>;
+}
+export interface JsonlSessionCreateOptions extends SessionCreateOptions {
+    cwd: string;
+    parentSessionPath?: string;
+}
+export interface JsonlSessionListOptions {
+    cwd?: string;
+}
+export interface JsonlSessionRepoApi extends SessionRepo<JsonlSessionMetadata, JsonlSessionCreateOptions, JsonlSessionListOptions> {
+}
+export type AgentHarnessPhase = "idle" | "turn" | "compaction" | "retry";
+export type PendingSessionWrite = SessionTreeEntry extends infer TEntry ? TEntry extends SessionTreeEntry ? Omit<TEntry, "id" | "parentId" | "timestamp"> : never : never;
+export interface QueueUpdateEvent {
+    type: "queue_update";
+    steer: AgentMessage[];
+    followUp: AgentMessage[];
+    nextTurn: AgentMessage[];
+}
+export interface SavePointEvent {
+    type: "save_point";
+    hadPendingMutations: boolean;
+}
+export interface AbortEvent {
+    type: "abort";
+    clearedSteer: AgentMessage[];
+    clearedFollowUp: AgentMessage[];
+}
+export interface SettledEvent {
+    type: "settled";
+    nextTurnCount: number;
+}
+export interface BeforeAgentStartEvent<TSkill extends Skill = Skill, TPromptTemplate extends PromptTemplate = PromptTemplate> {
+    type: "before_agent_start";
+    prompt: string;
+    images?: ImageContent[];
+    systemPrompt: string;
+    resources: AgentHarnessResources<TSkill, TPromptTemplate>;
+}
+export interface ContextEvent {
+    type: "context";
+    messages: AgentMessage[];
+}
+export interface TurnBoundaryEvent {
+    /** Fires between model-request boundaries, after session flush, before the context rebuild. */
+    type: "turn_boundary";
+    /** The model that will run the next turn (authoritative under a mid-task model switch). */
+    model: Model;
+}
+export interface BeforeProviderRequestEvent {
+    type: "before_provider_request";
+    model: Model;
+    sessionId: string;
+    streamOptions: AgentHarnessStreamOptions;
+}
+export interface BeforeProviderPayloadEvent {
+    type: "before_provider_payload";
+    model: Model;
+    payload: unknown;
+}
+export interface AfterProviderResponseEvent {
+    type: "after_provider_response";
+    status: number;
+    headers: Record<string, string>;
+}
+export interface ToolCallEvent {
+    type: "tool_call";
+    toolCallId: string;
+    toolName: string;
+    input: Record<string, unknown>;
+}
+export interface ToolResultEvent {
+    type: "tool_result";
+    toolCallId: string;
+    toolName: string;
+    input: Record<string, unknown>;
+    content: Array<TextContent | ImageContent | DocumentContent>;
+    details: unknown;
+    isError: boolean;
+}
+export interface SessionBeforeCompactEvent {
+    type: "session_before_compact";
+    preparation: CompactionPreparation;
+    branchEntries: SessionTreeEntry[];
+    customInstructions?: string;
+    signal: AbortSignal;
+}
+export interface SessionCompactEvent {
+    type: "session_compact";
+    compactionEntry: CompactionEntry;
+    fromHook: boolean;
+}
+export interface ModelSelectEvent {
+    type: "model_select";
+    model: Model;
+    previousModel: Model | undefined;
+    source: "set" | "restore";
+}
+export interface ThinkingLevelSelectEvent {
+    type: "thinking_level_select";
+    level: ThinkingLevel;
+    previousLevel: ThinkingLevel;
+}
+export interface ResourcesUpdateEvent<TSkill extends Skill = Skill, TPromptTemplate extends PromptTemplate = PromptTemplate> {
+    type: "resources_update";
+    resources: AgentHarnessResources<TSkill, TPromptTemplate>;
+    previousResources: AgentHarnessResources<TSkill, TPromptTemplate>;
+}
+export type AgentHarnessOwnEvent<TSkill extends Skill = Skill, TPromptTemplate extends PromptTemplate = PromptTemplate> = QueueUpdateEvent | SavePointEvent | AbortEvent | SettledEvent | BeforeAgentStartEvent<TSkill, TPromptTemplate> | ContextEvent | TurnBoundaryEvent | BeforeProviderRequestEvent | BeforeProviderPayloadEvent | AfterProviderResponseEvent | ToolCallEvent | ToolResultEvent | SessionBeforeCompactEvent | SessionCompactEvent | ModelSelectEvent | ThinkingLevelSelectEvent | ResourcesUpdateEvent<TSkill, TPromptTemplate>;
+export type AgentHarnessEvent<TSkill extends Skill = Skill, TPromptTemplate extends PromptTemplate = PromptTemplate> = AgentEvent | AgentHarnessOwnEvent<TSkill, TPromptTemplate>;
+/** Hook result for mutating the initial prompt run before the agent starts. */
+export interface BeforeAgentStartResult {
+    /** Replacement messages for the prompt run. */
+    messages?: AgentMessage[];
+    /** Replacement system prompt for the prompt run. */
+    systemPrompt?: string;
+}
+/** Hook result for replacing the full context message list before provider conversion. */
+export interface ContextResult {
+    messages: AgentMessage[];
+}
+/** Hook result for patching provider request options before payload construction. */
+export interface BeforeProviderRequestResult {
+    streamOptions?: AgentHarnessStreamOptionsPatch;
+}
+/** Hook result for replacing the provider payload after construction. */
+export interface BeforeProviderPayloadResult {
+    payload: unknown;
+}
+/**
+ * Hook result for blocking a tool call before execution, or rewriting its arguments.
+ *
+ * `block: true` blocks the call (`reason` becomes the error text). `updatedInput` (without `block`)
+ * rewrites the args the tool executes with — re-validated against the tool schema by the loop before
+ * execution (design/37). `block` wins over `updatedInput`.
+ *
+ * Keep in sync with `BeforeToolCallResult` (../types.ts): the harness's `beforeToolCall` callback
+ * returns this object verbatim, so its shape must remain a structural match.
+ */
+export interface ToolCallResult {
+    block?: boolean;
+    reason?: string;
+    updatedInput?: unknown;
+}
+/** Hook patch for a completed tool result before it is persisted/emitted. */
+export interface ToolResultPatch {
+    content?: Array<TextContent | ImageContent | DocumentContent>;
+    details?: unknown;
+    isError?: boolean;
+    terminate?: boolean;
+}
+/** Hook result for cancelling or replacing a planned compaction. */
+export interface SessionBeforeCompactResult {
+    cancel?: boolean;
+    compaction?: CompactResult;
+}
+/** Typed return values expected from AgentHarness hook handlers by event type. */
+export type AgentHarnessEventResultMap = {
+    before_agent_start: BeforeAgentStartResult | undefined;
+    context: ContextResult | undefined;
+    turn_boundary: undefined;
+    before_provider_request: BeforeProviderRequestResult | undefined;
+    before_provider_payload: BeforeProviderPayloadResult | undefined;
+    after_provider_response: undefined;
+    tool_call: ToolCallResult | undefined;
+    tool_result: ToolResultPatch | undefined;
+    session_before_compact: SessionBeforeCompactResult | undefined;
+    session_compact: undefined;
+    model_select: undefined;
+    thinking_level_select: undefined;
+    resources_update: undefined;
+    queue_update: undefined;
+    save_point: undefined;
+    abort: undefined;
+    settled: undefined;
+};
+/** Options for a prompt submitted through AgentHarness. */
+export interface AgentHarnessPromptOptions {
+    images?: ImageContent[];
+}
+/** Queued messages removed by an abort operation. */
+export interface AbortResult {
+    clearedSteer: AgentMessage[];
+    clearedFollowUp: AgentMessage[];
+}
+/** Compaction data supplied by hooks or returned from compaction preparation. */
+export interface CompactResult {
+    summary: string;
+    firstKeptEntryId: string;
+    tokensBefore: number;
+    details?: unknown;
+}
+/** Settings that control automatic context compaction. */
+export interface CompactionSettings {
+    enabled: boolean;
+    reserveTokens: number;
+    keepRecentTokens: number;
+}
+/** Prepared compaction inputs exposed to hooks before a summary is generated. */
+export interface CompactionPreparation {
+    firstKeptEntryId: string;
+    messagesToSummarize: AgentMessage[];
+    turnPrefixMessages: AgentMessage[];
+    isSplitTurn: boolean;
+    tokensBefore: number;
+    previousSummary?: string;
+    fileOps: FileOperations;
+    settings: CompactionSettings;
+}
+/** File operations accumulated from summarized transcript ranges. */
+export interface FileOperations {
+    read: Set<string>;
+    written: Set<string>;
+    edited: Set<string>;
+}
+/** Construction options for AgentHarness. */
+export interface AgentHarnessOptions<TSkill extends Skill = Skill, TPromptTemplate extends PromptTemplate = PromptTemplate, TTool extends AgentTool = AgentTool> {
+    env: ExecutionEnv;
+    session: SessionApi;
+    tools?: TTool[];
+    /**
+     * Concrete resources available to explicit invocation methods and system-prompt callbacks.
+     * Applications own loading/reloading resources and should call `setResources()` with new values.
+     */
+    resources?: AgentHarnessResources<TSkill, TPromptTemplate>;
+    systemPrompt?: string | ((context: {
+        env: ExecutionEnv;
+        session: SessionApi;
+        model: Model;
+        thinkingLevel: ThinkingLevel;
+        activeTools: TTool[];
+        resources: AgentHarnessResources<TSkill, TPromptTemplate>;
+    }) => string | Promise<string>);
+    getApiKeyAndHeaders?: (model: Model) => Promise<{
+        apiKey: string;
+        headers?: Record<string, string>;
+    } | undefined>;
+    runtime?: AgentCoreRuntimeDeps;
+    /** Curated stream/provider request options. Snapshotted at turn start. */
+    streamOptions?: AgentHarnessStreamOptions;
+    model: Model;
+    thinkingLevel?: ThinkingLevel;
+    activeToolNames?: string[];
+    steeringMode?: QueueMode;
+    followUpMode?: QueueMode;
+    /** design/119 #2: per-request output-token cap forwarded to the provider (`options.maxTokens`). */
+    maxOutputTokens?: number;
+    /**
+     * design/130 P1: per-CALL dynamic output cap, evaluated by the loop immediately before EACH
+     * provider call. A number return overrides `maxOutputTokens` for that call only; undefined
+     * leaves the static chain untouched. Must be cheap (hot path).
+     */
+    maxOutputTokensPerCall?: () => number | undefined;
+    /**
+     * design/130 P2b: per-CALL soft wall-clock deadline (absolute ms epoch), evaluated by the loop
+     * immediately before EACH provider call and forwarded as `StreamOptions.callDeadlineMs` — a
+     * brain that observes the wall clock crossing it cuts the stream (salvaging the prefix) instead
+     * of riding into the hard abort. undefined = unbounded. Must be cheap (hot path).
+     */
+    callDeadlineMsPerCall?: () => number | undefined;
+    /**
+     * service [398] C2: the loop's recovery/terminal trace sink, forwarded to `runAgentLoop`'s trace
+     * parameter (previously test-only — never passed in production, so the loop's six self-heal
+     * recoveries were invisible outside display:false nudge messages). Must not throw; hot path.
+     */
+    loopTrace?: (step: import("../loop/agent-loop.js").LoopStep) => void;
+    /**
+     * design/131 (service [404] 拍): per-task resilience intent flags, forwarded to every provider
+     * call (`StreamOptions.resilience`) so the deployment's decorator stack (degrading / failover /
+     * breaker) can stand aside for this task. Absent ⇒ today's behavior.
+     */
+    resilience?: import("../llm/types.js").ResilienceOptions;
+    /** design/120 P1: parallel-batch tool concurrency cap forwarded to the loop (default 10). */
+    maxToolConcurrency?: number;
+    /**
+     * design/120 P2: opt in to in-stream tool execution (safe tool calls start while the model is
+     * still streaming). Default OFF. The harness forwards this to the loop ONLY when no `tool_call`
+     * hook handler is registered at run start (snapshot per prompt()) — a policy/approval gate on
+     * that hook could durably suspend, which has no stable leaf mid-stream. Hosts that register a
+     * suspending `tool_call` handler mid-run after opting in get undefined behavior (documented
+     * contract, see AgentLoopConfig.streamingToolExecution).
+     */
+    streamingToolExecution?: boolean;
+}
+export type { AgentHarness } from "./agent-harness.js";
+//# sourceMappingURL=types.d.ts.map