tnega 0.1.0 → 0.3.0

package/dist/types/packages/session/src/index.d.ts

@@ -0,0 +1,500 @@
+import type { Context } from "../../core/src/index.js";
+import { type SessionInvariantFailure } from './invariant.js';
+/**
+ * v7 derives model-visible messages from the *folded surface* instead of from
+ * raw file order, so compaction can stay strictly append-only.
+ *
+ * v6 rewrote the log on every real compaction: the kept tail was physically
+ * reordered after the checkpoint (and every seq renumbered) purely so that a
+ * file-order projection would equal the surface. v7 removes that coupling:
+ * `deriveMessages()` walks the surface nodes in surface position order (a
+ * replacement node may carry a *higher* seq than the nodes that follow it),
+ * so compaction appends `compaction/start` → `checkpoint` (prefix +
+ * `surfaceOp.replace` range) → `compaction/end` and never rewrites history.
+ * To keep every surface node self-describing, `assistant/message` now carries
+ * its own `toolCalls` (the assistant turn is not reassembled from separate
+ * `tool/call` events at projection time).
+ *
+ * v6 logs are rejected (no migration in the pre-release window).
+ */
+export declare const SESSION_FORMAT_VERSION = 7;
+/** Serialized tool schema, structurally compatible with @tnega/tools ToolSchema. */
+export interface ToolSchemaSnapshot {
+    name: string;
+    description: string;
+    parameters?: Record<string, unknown>;
+}
+/** Call configuration recorded beside a request so it can be reconstructed. */
+export interface LlmCallConfig {
+    provider?: string;
+    model?: string;
+    maxTokens?: number;
+    temperature?: number;
+    reasoningEffort?: string;
+}
+export declare class SessionFormatError extends Error {
+    name: string;
+}
+export type ModelRole = 'system' | 'user' | 'assistant' | 'tool';
+export interface ModelToolCall {
+    id: string;
+    name: string;
+    arguments: unknown;
+}
+export interface ModelMessage {
+    role: ModelRole;
+    content: string;
+    name?: string;
+    tool_call_id?: string;
+    tool_calls?: ModelToolCall[];
+    toolOk?: boolean;
+    toolError?: ToolResultErrorPayload;
+}
+export interface UserMessagePayload {
+    content: string;
+    name?: string;
+    parentId?: string;
+}
+export interface AssistantMessagePayload {
+    content: string;
+    name?: string;
+    parentId?: string;
+    interrupted?: boolean;
+    /**
+     * The tool requests this assistant turn made, when it made any. The model
+     * transcript is derived node-by-node from the surface, so an assistant turn
+     * must carry its calls itself rather than being reassembled from the
+     * separate (log-only) `tool/call` events that follow it.
+     */
+    toolCalls?: ModelToolCall[];
+}
+export interface AssistantChunkPayload {
+    id: string;
+    content: string;
+    index?: number;
+}
+export interface SystemMessagePayload {
+    content: string;
+    name?: string;
+    parentId?: string;
+}
+export type MessageEventPayload = UserMessagePayload | AssistantMessagePayload | SystemMessagePayload;
+export type MessageEventType = 'user/message' | 'assistant/message' | 'system/message';
+export interface CompactionStartPayload {
+    boundary?: number;
+    keep?: number;
+    tokensBefore?: number;
+}
+export interface CompactionEndPayload {
+    checkpointId?: string;
+    keep?: number;
+}
+export interface ToolCallPayload {
+    id: string;
+    name: string;
+    arguments: unknown;
+    /** Exact raw arguments JSON as produced by the model; preserves serialization. */
+    argRaw?: string;
+    turn?: number;
+    step?: number;
+}
+export interface ToolResultErrorPayload {
+    name?: string;
+    message: string;
+    stack?: string;
+}
+export interface ToolResultPayload {
+    id: string;
+    toolCallId: string;
+    name: string;
+    ok: boolean;
+    durationMs?: number;
+    output?: unknown;
+    error?: ToolResultErrorPayload;
+    argRaw?: string;
+    turn?: number;
+    step?: number;
+}
+export type CancelCause = {
+    type: 'user';
+} | {
+    type: 'parent';
+} | {
+    type: 'disposed';
+} | {
+    type: 'abort';
+    message?: string;
+} | {
+    type: 'timeout';
+    timeoutMs: number;
+};
+/**
+ * Why a turn ended — the durable machine outcome, distinct from the
+ * per-step model `finishReason`. Written on `turn/end`.
+ */
+export type TurnEndReason = {
+    kind: 'completed';
+} | {
+    kind: 'aborted';
+    cause: CancelCause;
+} | {
+    kind: 'blocked';
+} | {
+    kind: 'error';
+    error: ToolResultErrorPayload;
+} | {
+    kind: 'max-tokens';
+} | {
+    kind: 'max-steps';
+} | {
+    kind: 'max-turns';
+} | {
+    kind: 'interrupted';
+};
+export interface TurnStartPayload {
+    turn: number;
+    input?: unknown;
+    reason?: string;
+}
+export interface TurnEndPayload {
+    turn: number;
+    finishReason?: string;
+    /** The typed durable reason this turn ended. Supersedes `finishReason`. */
+    reason?: TurnEndReason;
+    output?: string;
+    steps?: number;
+    interrupted?: boolean;
+    cancelCause?: CancelCause;
+    error?: ToolResultErrorPayload;
+}
+export interface StepStartPayload {
+    turn: number;
+    step: number;
+}
+export interface StepEndPayload {
+    turn: number;
+    step: number;
+    finishReason?: string;
+    toolCalls?: number;
+    interrupted?: boolean;
+    cancelCause?: CancelCause;
+    error?: ToolResultErrorPayload;
+}
+export interface LLMRetryPayload {
+    retryId: string;
+    retry: number;
+    delayMs?: number;
+    failure?: ToolResultErrorPayload;
+}
+export interface LLMRetryStartedPayload {
+    retryId: string;
+    retry: number;
+}
+/** How a `request/header` snapshot enters the log. */
+export type RequestHeaderReason = 'initial' | 'resume' | 'change' | 'series' | 'change-series';
+export interface RequestHeaderPayload {
+    reason: RequestHeaderReason;
+    config?: LlmCallConfig;
+    /** Rendered system prompt; absent for a system-less request. */
+    system?: string;
+    /** Assembled tool schemas; absent for a tool-less request. */
+    tools?: ToolSchemaSnapshot[];
+    /** True when this snapshot also begins a new model-message series. */
+    startsSeries?: boolean;
+}
+export interface RequestContextPayload {
+    provider?: string;
+    model?: string;
+    contextWindow?: number;
+}
+export interface CheckpointPayload {
+    /** The compacted prefix: messages the model keeps seeing after compaction. */
+    messages: ModelMessage[];
+    summary?: string;
+    tokensBefore?: number;
+    /**
+     * The surface span this checkpoint shadows, when written by a v7
+     * compaction: `start`/`end` are the seqs of the first and last *surface
+     * nodes* being replaced (surface positions, so `start` may be numerically
+     * greater than `end` after an earlier compaction). The fold removes every
+     * live node between those two positions and inserts this checkpoint there;
+     * the kept tail stays in place and the log is never rewritten.
+     * `'replace'` (bare string) is the legacy v5 form and shadows nothing
+     * structurally; projection treats it as a full-surface seed.
+     */
+    surfaceOp?: {
+        op: 'replace';
+        start: number;
+        end: number;
+    } | 'replace';
+    /** @deprecated v0.2 keeps raw events in place; use messages instead. */
+    snapshot?: SessionEvent[];
+}
+export type PlanItemStatus = 'pending' | 'done' | 'failed';
+export interface PlanItemPayload {
+    id: string;
+    title: string;
+    status: PlanItemStatus;
+    detail?: string;
+}
+export interface PlanPayload {
+    items: PlanItemPayload[];
+    status?: 'pending' | 'running' | 'done' | 'failed';
+    summary?: string;
+}
+export interface InboxSplicePayload {
+    target: 'next-turn' | 'next-step';
+    index?: number;
+    deleteCount?: number;
+    inserted?: Array<{
+        id: string;
+        content: string;
+        /** Structured message payload preserved across restart when present. */
+        payload?: unknown;
+        mode?: 'followup' | 'steer';
+    }>;
+}
+/** A durable change to session display metadata (title, mode, agentType). */
+export interface MetaPatchPayload {
+    /** Keys changed by this event; only present keys are touched. */
+    fields: Array<'title' | 'agentType' | 'mode'>;
+    title?: string;
+    agentType?: AgentType;
+    mode?: SessionMode;
+}
+export type AgentType = 'general' | 'coding';
+export type SessionMode = 'auto' | 'plan' | 'execute';
+export type SessionEventType = MessageEventType | 'assistant/chunk' | 'tool/call' | 'tool/result' | 'request/header' | 'request/context' | 'agent/inbox/spliced' | 'plan' | 'checkpoint' | 'compaction/start' | 'compaction/end' | 'meta' | 'meta/patch' | 'llm/retry' | 'llm/retry-started' | 'turn/start' | 'turn/end' | 'step/start' | 'step/end';
+export interface SessionEventBase<T extends SessionEventType, P> {
+    id: string;
+    seq: number;
+    ts: number;
+    type: T;
+    payload: P;
+    /** Surface placement; required on message-producing events. */
+    surfaceOp?: SurfaceOp;
+    /** Seqs of earlier raw events this event derives from. */
+    sourceEventSeqs?: number[];
+}
+/**
+ * The message-producing subset of event types. Every variant is a surface
+ * node that carries `surfaceOp` and participates in the ordered fold.
+ * `system/message` is included because tnega keeps the system prompt on the
+ * transcript (OpenAI-style), so it must be replaceable and derivable like any
+ * other message rather than living only in `request/header`.
+ */
+export type SurfaceEventType = 'user/message' | 'system/message' | 'assistant/message' | 'tool/result';
+export type SurfaceOp = 'append' | {
+    op: 'replace';
+    start: number;
+    end: number;
+};
+export type SessionEvent = SessionEventBase<'user/message', UserMessagePayload> | SessionEventBase<'assistant/message', AssistantMessagePayload> | SessionEventBase<'assistant/chunk', AssistantChunkPayload> | SessionEventBase<'system/message', SystemMessagePayload> | SessionEventBase<'tool/call', ToolCallPayload> | SessionEventBase<'tool/result', ToolResultPayload> | SessionEventBase<'request/header', RequestHeaderPayload> | SessionEventBase<'request/context', RequestContextPayload> | SessionEventBase<'agent/inbox/spliced', InboxSplicePayload> | SessionEventBase<'plan', PlanPayload> | SessionEventBase<'checkpoint', CheckpointPayload> | SessionEventBase<'compaction/start', CompactionStartPayload> | SessionEventBase<'compaction/end', CompactionEndPayload> | SessionEventBase<'meta', Record<string, unknown>> | SessionEventBase<'meta/patch', MetaPatchPayload> | SessionEventBase<'llm/retry', LLMRetryPayload> | SessionEventBase<'llm/retry-started', LLMRetryStartedPayload> | SessionEventBase<'turn/start', TurnStartPayload> | SessionEventBase<'turn/end', TurnEndPayload> | SessionEventBase<'step/start', StepStartPayload> | SessionEventBase<'step/end', StepEndPayload>;
+export interface SessionConfig {
+    file: string;
+    broadcast?: SessionBroadcast;
+}
+export interface CompactOptions {
+    keep?: number;
+    keepTokens?: number;
+    summary?: string;
+    tokensBefore?: number;
+    messages?: ModelMessage[];
+}
+export type ReplayReducer<T> = (state: T, event: SessionEvent) => T | Promise<T>;
+export type SessionBroadcast = (type: 'event' | 'flush', payload: unknown) => void;
+export interface ContextUsage {
+    tokens: number;
+    limit: number;
+    ratio: number;
+}
+export declare const DEFAULT_CONTEXT_LIMIT = 128000;
+/**
+ * Project an event list to model messages, in the list's own order. Each
+ * surface event is mapped through {@link deriveEventMessage}; a `checkpoint`
+ * splices its compacted prefix in at its position. This is the building block
+ * both {@link deriveSurfaceMessages} (surface order) and callers holding a
+ * compact slice (e.g. the events a summarizer will read) share.
+ */
+export declare function projectEvents(events: readonly SessionEvent[]): ModelMessage[];
+export declare function isAppendSurfaceEvent(event: SessionEvent): boolean;
+export declare function isSurfaceEventType(type: SessionEventType): type is SurfaceEventType;
+/** A v7 checkpoint shadows a surface span; legacy ('replace') shadows nothing structurally. */
+export declare function checkpointShadowRange(event: SessionEvent): {
+    start: number;
+    end: number;
+} | undefined;
+/** Detached current surface nodes plus every replacement's shadowed ranges. */
+export interface SurfaceFoldReplacement {
+    seq: number;
+    start: number;
+    end: number;
+    shadowedSeqs: number[];
+}
+export interface SurfaceFoldResult {
+    nodes: number[];
+    replacements: SurfaceFoldReplacement[];
+}
+/**
+ * Fold a log's surface operations into the current surface node order.
+ *
+ * The surface is *positional*: a replacement removes the live nodes between
+ * the positions of `start`/`end` and inserts the replacing event's seq there,
+ * so surface order is independent of raw seq order — after compaction the
+ * checkpoint node may carry a higher seq than the kept tail that follows it.
+ */
+export declare function foldSurface(events: readonly SessionEvent[]): SurfaceFoldResult;
+/**
+ * Derive one surface node's model-visible message. A content-less assistant
+ * turn (e.g. a max-token cutoff with no output and no tool calls) is skipped
+ * so it never enters a provider transcript; `tool/result` yields the `tool`
+ * role message that pairs with the assistant's `toolCalls`.
+ */
+export declare function deriveEventMessage(event: SessionEvent): ModelMessage | null;
+/**
+ * Derive the model transcript strictly from the folded surface: walk the
+ * surface nodes in surface position order (so a checkpoint's prefix is placed
+ * where it replaced history, whatever its raw seq), mapping each node through
+ * {@link deriveEventMessage}. This is the single source of the model's view;
+ * raw log order never influences it.
+ */
+export declare function deriveSurfaceMessages(events: readonly SessionEvent[]): ModelMessage[];
+/**
+ * Project the log into a human-facing transcript (the web view). Unlike the
+ * model surface, a compaction does **not** hide the history it summarized:
+ * shadowed messages are kept in place, and each live checkpoint is retained
+ * as a marker exactly where it replaced them (with nested checkpoints
+ * expanded recursively). Readers see the full conversation; the model keeps
+ * deriving from the folded surface via {@link deriveSurfaceMessages}.
+ */
+export declare function transcriptEvents(events: readonly SessionEvent[]): SessionEvent[];
+export declare function foldRequestHeader(events: readonly SessionEvent[]): RequestHeaderPayload | undefined;
+export declare function foldRequestContext(events: readonly SessionEvent[]): RequestContextPayload | undefined;
+/**
+ * Session display metadata, rebuilt from the immutable events: the head
+ * `meta` base followed by every `meta/patch` in seq order. No mutable
+ * side file or in-place rewrite is involved, so title/mode/agentType stay
+ * replayable and fork-clean like every other durable fact.
+ */
+export declare function foldSessionMeta(events: readonly SessionEvent[]): {
+    title?: string;
+    agentType?: AgentType;
+    mode?: SessionMode;
+};
+/** Convenience wrapper: fold session metadata from a `SessionLog`'s events. */
+export declare function foldMetaFromLog(log: {
+    read(): Promise<SessionEvent[]>;
+}): Promise<{
+    title?: string;
+    agentType?: AgentType;
+    mode?: SessionMode;
+}>;
+export declare function estimateMessageTokens(messages: readonly ModelMessage[]): number;
+export declare function estimateEventTokens(event: SessionEvent): number;
+export declare function suffixStartIndexForTokens(events: readonly SessionEvent[], targetTokens: number): number;
+export declare function safeCompactSplit(events: readonly SessionEvent[], splitIndex: number): number;
+export declare function repairUnclosed(events: readonly SessionEvent[]): SessionEvent[];
+export declare function resolveCompactKeep(events: readonly SessionEvent[], options: CompactOptions): number;
+export declare function estimateContextUsage(messages: readonly ModelMessage[], limit?: number): ContextUsage;
+export declare class SessionLog {
+    readonly file: string;
+    private _broadcast?;
+    private _events;
+    private _surface;
+    private _surfaceNodes;
+    private _requestHeader;
+    private _requestContext;
+    private _loaded;
+    private _nextSeq;
+    private _queue;
+    private _writeTail;
+    private _pending;
+    private _drainScheduled;
+    private _writeError;
+    constructor(file: string, _broadcast?: SessionBroadcast | undefined);
+    init(): Promise<void>;
+    append(type: 'user/message', payload: UserMessagePayload): Promise<SessionEvent>;
+    append(type: 'assistant/message', payload: AssistantMessagePayload): Promise<SessionEvent>;
+    append(type: 'assistant/chunk', payload: AssistantChunkPayload): Promise<SessionEvent>;
+    append(type: 'system/message', payload: SystemMessagePayload): Promise<SessionEvent>;
+    append(type: 'tool/call', payload: ToolCallPayload): Promise<SessionEvent>;
+    append(type: 'tool/result', payload: ToolResultPayload): Promise<SessionEvent>;
+    append(type: 'request/header', payload: RequestHeaderPayload): Promise<SessionEvent>;
+    append(type: 'request/context', payload: RequestContextPayload): Promise<SessionEvent>;
+    append(type: 'agent/inbox/spliced', payload: InboxSplicePayload): Promise<SessionEvent>;
+    append(type: 'plan', payload: PlanPayload): Promise<SessionEvent>;
+    append(type: 'checkpoint', payload: CheckpointPayload): Promise<SessionEvent>;
+    append(type: 'compaction/start', payload: CompactionStartPayload): Promise<SessionEvent>;
+    append(type: 'compaction/end', payload: CompactionEndPayload): Promise<SessionEvent>;
+    append(type: 'meta', payload: Record<string, unknown>): Promise<SessionEvent>;
+    append(type: 'meta/patch', payload: MetaPatchPayload): Promise<SessionEvent>;
+    append(type: 'llm/retry', payload: LLMRetryPayload): Promise<SessionEvent>;
+    append(type: 'llm/retry-started', payload: LLMRetryStartedPayload): Promise<SessionEvent>;
+    append(type: 'turn/start', payload: TurnStartPayload): Promise<SessionEvent>;
+    append(type: 'turn/end', payload: TurnEndPayload): Promise<SessionEvent>;
+    append(type: 'step/start', payload: StepStartPayload): Promise<SessionEvent>;
+    append(type: 'step/end', payload: StepEndPayload): Promise<SessionEvent>;
+    private _buildEvent;
+    private _commitEvent;
+    /**
+     * Rebuild both surface views from the committed log. The nodes come from the
+     * positional {@link foldSurface} fold; the messages come from
+     * {@link deriveSurfaceMessages}, which walks those nodes in surface order —
+     * the model view is a pure function of the surface, never of raw file order.
+     */
+    private _refreshSurface;
+    private _enqueue;
+    private _drainWrite;
+    flush(): Promise<number>;
+    lineage(messageId: string): Promise<SessionEvent[]>;
+    /** The next turn number: one more than the highest recorded `turn/start`. */
+    nextTurn(): Promise<number>;
+    forkAt(messageId: string): Promise<SessionEvent[]>;
+    read(): Promise<SessionEvent[]>;
+    deriveMessages(): Promise<ModelMessage[]>;
+    /** The ordered surface events, after compaction replacements are applied. */
+    surfaceEvents(): Promise<SessionEvent[]>;
+    /** The latest `request/header` snapshot, or undefined before the first one. */
+    requestHeader(): RequestHeaderPayload | undefined;
+    /** The latest resolved route metadata, or undefined before the first one. */
+    requestContext(): RequestContextPayload | undefined;
+    /** Display metadata folded from the durable `meta` + `meta/patch` events. */
+    meta(): Promise<{
+        title?: string;
+        agentType?: AgentType;
+        mode?: SessionMode;
+    }>;
+    estimateContext(limit?: number): Promise<ContextUsage>;
+    replay(): Promise<SessionEvent[]>;
+    replay<T>(reduce: ReplayReducer<T>, initial: T): Promise<T>;
+    /** Structural violations in the loaded event stream (empty = balanced). */
+    runInvariants(): Promise<SessionInvariantFailure[]>;
+    /**
+     * Compact the session without ever rewriting history.
+     *
+     * The surface (not the raw log) is the unit of compaction. A kept suffix —
+     * measured in tokens via `keepTokens`, or in nodes via `keep`, and always
+     * snapped to start on a fresh `user/message` turn so a tool result never
+     * outlives the assistant call it answers — stays visible; every earlier
+     * surface node is shadowed by the checkpoint's `surfaceOp.replace` range.
+     * The three compaction events are appended like any other event, so seqs
+     * stay immutable, live observers see the transition, and a crash can only
+     * leave an orphaned `compaction/start` rather than a torn rewrite.
+     *
+     * Returns the new event count, or the unchanged count when there is no
+     * useful surface span to shadow.
+     */
+    compact(options?: CompactOptions): Promise<number>;
+    close(): Promise<void>;
+    private _run;
+    private _ensureLoaded;
+    private _read;
+    private _assertFormat;
+    private _resolveLineage;
+}
+export declare const session: {
+    name: string;
+    apply: (ctx: Context, config: SessionConfig) => Promise<() => Promise<void>>;
+};
+export * from './invariant.js';
+export declare const name = "index.js";

package/dist/types/packages/session/src/invariant.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Session invariant companion.
+ *
+ * Pure structural checks over a session event stream, mirroring the DSH
+ * "each package ships a ./invariant" discipline. They assert the relationships
+ * the event-sourcing layer promises:
+ *
+ * - durable lifecycle structures (turn / step / tool call) stay balanced —
+ *   every `turn/start` has a `turn/end`, every `tool/call` a `tool/result`;
+ * - seq stays strictly monotonic;
+ * - message events that reach the model surface stay append-only unless they
+ *   belong to a compaction replacement.
+ *
+ * The checks are pure over `SessionEvent[]`, so they run equally on a full
+ * log, on a single newly-committed event, or in tests. Recovery (repairing an
+ * interrupted log into a closed one) is `repairUnclosed`; these checks assert
+ * that the result is actually legal.
+ */
+import type { SessionEvent } from './index.js';
+export interface SessionInvariantFailure {
+    name: string;
+    detail: string;
+}
+/** Balanced `turn/start` ↔ `turn/end` per turn number. */
+export declare function checkBalancedTurns(events: readonly SessionEvent[]): SessionInvariantFailure[];
+/** Balanced `step/start` ↔ `step/end` per (turn, step). */
+export declare function checkBalancedSteps(events: readonly SessionEvent[]): SessionInvariantFailure[];
+/** Balanced `tool/call` ↔ `tool/result` per call id. */
+export declare function checkBalancedToolCalls(events: readonly SessionEvent[]): SessionInvariantFailure[];
+/** seq is strictly monotonic (an append-only log never rewinds). */
+export declare function checkMonotonicSeq(events: readonly SessionEvent[]): SessionInvariantFailure[];
+/** Aggregate all structural session checks over an event stream. */
+export declare function checkSessionInvariants(events: readonly SessionEvent[]): SessionInvariantFailure[];

package/dist/types/packages/tools/src/builtins.d.ts

@@ -0,0 +1,25 @@
+import type { Context } from "../../core/src/index.js";
+import type { ToolDefinition } from './index.js';
+import { type ExecutionProvider } from './execution.js';
+export interface BuiltinToolsConfig {
+    cwd?: string;
+    allowNetwork?: boolean;
+    allowShell?: boolean;
+    disabled?: readonly string[];
+    maxReadBytes?: number;
+    maxWriteBytes?: number;
+    maxSearchBytes?: number;
+    maxResults?: number;
+    timeoutMs?: number;
+    execution?: ExecutionProvider;
+}
+export declare class ToolInputError extends Error {
+    name: string;
+}
+export declare function createBuiltinToolDefinitions(config?: BuiltinToolsConfig): ToolDefinition[];
+export declare const builtinTools: {
+    name: string;
+    inject: string[];
+    apply(ctx: Context, config?: BuiltinToolsConfig): void;
+};
+export declare const DEFAULT_BUILTIN_TOOL_NAMES: readonly string[];

package/dist/types/packages/tools/src/calc.d.ts

@@ -0,0 +1,4 @@
+export declare class CalculatorError extends Error {
+    name: string;
+}
+export declare function evaluateExpression(source: string): number;

package/dist/types/packages/tools/src/execution.d.ts

@@ -0,0 +1,31 @@
+export interface ShellRequest {
+    command: string;
+    cwd: string;
+    timeoutMs?: number;
+    maxBuffer?: number;
+    signal?: AbortSignal;
+}
+export interface ShellResult {
+    exitCode: number;
+    stdout: string;
+    stderr: string;
+}
+export interface HttpRequest {
+    url: string;
+    headers?: Record<string, string>;
+    signal?: AbortSignal;
+    maxBytes?: number;
+}
+export interface HttpResponse {
+    status: number;
+    ok: boolean;
+    headers: Record<string, string>;
+    body: string;
+    truncated: boolean;
+}
+/** Replaceable execution boundary used by builtin network/shell tools. */
+export interface ExecutionProvider {
+    runShell(request: ShellRequest): Promise<ShellResult>;
+    fetchHttp(request: HttpRequest): Promise<HttpResponse>;
+}
+export declare const localExecutionProvider: ExecutionProvider;