> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agentium.in/llms.txt
> Use this file to discover all available pages before exploring further.

# Runtime and run handles

> Runtime construction, grants, budgets, execution services, results, and controls.

Runtime construction, grants, budgets, execution services, results, and controls. Read the [runtime and run handles guide](/harness/runtime) for examples, defaults, and behavior.

These declarations cover every public export in this category. Import from `@agentium/harness`. Types such as `ChatMessage`, `RunContext`, and `ExecutionServices` come from [`@agentium/core`](/api-reference/core). A `?` marks an optional field.

## ExecutionDriver

```typescript theme={null}
export interface ExecutionDriver {
    id: string;
    version: number;
    capabilities: {
        controls: readonly HarnessSendMode[];
        durable: boolean;
        policyCoverage: "local" | "remote" | "none";
        /** True only when each model/tool operation uses provided execution services. */
        controlledExecution: boolean;
    };
    start: (request: HarnessRunRequest, services: HarnessExecutionServices) => Promise<HarnessDriverOutput>;
}
```

## HarnessBudgets

```typescript theme={null}
export interface HarnessBudgets {
    maxModelCalls?: number;
    maxToolCalls?: number;
    maxTokens?: number;
    maxRevisions?: number;
}
```

## HarnessDriverOutput

```typescript theme={null}
export interface HarnessDriverOutput {
    status?: HarnessStatus;
    text: string;
    structured?: unknown;
    reason?: HarnessReason;
    usage?: TokenUsage;
    history?: readonly ChatMessage[];
    artifacts?: readonly {
        id: string;
        mimeType?: string;
    }[];
}
```

## HarnessExecutionServices

```typescript theme={null}
export interface HarnessExecutionServices extends ExecutionServices {
    readonly definitionId?: string;
    /** Agent-specific declarative options interpreted only by the configured Agent driver. */
    readonly agentConfiguration?: {
        defaults: HarnessDefaults;
        limits: NonNullable<HarnessManifest["limits"]>;
        projectRoot: string;
    };
    /** Independent, tool-free policy call using an explicitly granted host role and shared budgets.
     * Skips task controllers, context projection and middleware to avoid policy recursion.
     */
    controlModel(role: string, messages: readonly ChatMessage[], options?: Pick<ModelConfig, "maxTokens" | "temperature">): Promise<ModelResponse>;
    append(messages: readonly ChatMessage[]): void;
    emit(payload: Exclude<HarnessEventPayload, {
        type: "run.terminal" | "run.started";
    }>): void;
    takeInput(): {
        input: MessageContent;
        mode: HarnessSendMode;
    } | undefined;
    resource<T>(id: string, scope: "host" | "session" | "run", initialize: () => Promise<ScopedResource<T>>): Promise<T>;
    putArtifact(value: unknown): string;
    getArtifact(id: string): unknown;
}
```

## HarnessGrants

```typescript theme={null}
export interface HarnessGrants {
    toolIds: readonly string[];
    requiredToolIds?: readonly string[];
    modelRoles: readonly string[];
}
```

## HarnessRunRequest

```typescript theme={null}
export interface HarnessRunRequest {
    input: MessageContent;
    identity: HarnessIdentity;
    sessionId: string;
    runId: string;
    attemptId: string;
    parentRunId?: string;
    rootRunId: string;
    signal: AbortSignal;
    deadline?: number;
    grants: HarnessGrants;
    runMode: RunMode;
}
```

## HarnessRuntimeConfig

```typescript theme={null}
export interface HarnessRuntimeConfig {
    /** Optional observer bus for the runtime and its direct model/controller calls.
     * Keep Agent instrumentation on its own bus to avoid counting the same call twice. */
    telemetry?: EventBus;
    driver?: ExecutionDriver;
    definition?: HarnessDefinition;
    projectRoot?: string;
    requirements?: readonly string[];
    tools?: readonly ToolDef[];
    models?: Readonly<Record<string, ModelRoleBinding>>;
    grants: HarnessGrants;
    budgets?: HarnessBudgets;
    executionPolicy?: ExecutionPolicy;
    approvalManager?: ApprovalManager;
    controller?: StepController;
    contextPolicy?: ContextPolicy;
    completionPolicy?: CompletionPolicy;
    /** Explicit opt-in to new tool effects in completion revisions. */
    allowRevisionEffects?: boolean;
    sessionStore?: HarnessSessionStore;
    resources?: HarnessResourcePool;
    eventCapacity?: number;
}
```

## HarnessSendMode

```typescript theme={null}
export type HarnessSendMode = "follow_up" | "steer" | "replace";
```

## HarnessStartOptions

```typescript theme={null}
export interface HarnessStartOptions {
    identity: HarnessIdentity;
    sessionId: string;
    parentRunId?: string;
    rootRunId?: string;
    signal?: AbortSignal;
    deadline?: number;
    grants?: HarnessGrants;
    runMode?: RunMode;
}
```

## RunHandle

```typescript theme={null}
export interface RunHandle {
    readonly runId: string;
    events(options?: {
        after?: number;
    }): AsyncGenerator<HarnessEvent>;
    result(): Promise<HarnessResult>;
    cancel(reason?: string): void;
    send(input: MessageContent, options: {
        mode: HarnessSendMode;
    }): Promise<void>;
}
```

## HarnessBudgetError

```typescript theme={null}
export declare class HarnessBudgetError extends Error {
    readonly code = "budget_exhausted";
    constructor(message: string);
}
```

## HarnessRuntime

```typescript theme={null}
/** Local lifecycle owner. Custom driver code is trusted; services enforce all intercepted effects. */
export declare class HarnessRuntime {
    readonly sessions: HarnessSessionStore;
    readonly resources: HarnessResourcePool;
    getArtifact(identity: HarnessIdentity, sessionId: string, id: string): unknown;
    constructor(config: HarnessRuntimeConfig);
    run(input: MessageContent, options: HarnessStartOptions): Promise<HarnessResult>;
    stream(input: MessageContent, options: HarnessStartOptions): AsyncGenerator<HarnessEvent>;
    start(input: MessageContent, options: HarnessStartOptions): RunHandle;
}
```

## HarnessUnsupportedError

```typescript theme={null}
export declare class HarnessUnsupportedError extends Error {
    readonly operation: string;
    readonly code = "unsupported";
    constructor(operation: string);
}
```

## Supporting types

These shapes appear in the signatures above but are not named exports of the package entrypoint.

### ExecutionServices

```typescript theme={null}
/** Host-supplied execution boundary. Core consumes these operations; it does not
 * construct or own the host's orchestration, configuration, or resource lifecycle.
 */
export interface ExecutionServices {
    readonly ctx: RunContext;
    readonly signal: AbortSignal;
    readonly tools: readonly ToolDef[];
    readonly history: readonly ChatMessage[];
    readonly executionPolicy: ExecutionPolicy;
    readonly approvalManager?: ApprovalManager;
    readonly state: Record<string, unknown>;
    readonly sessionKey: string;
    model(provider: ModelProvider, messages: ChatMessage[], options?: ModelConfig & {
        tools?: ToolDefinition[];
    }, context?: RunContext): Promise<ModelResponse>;
    streamModel(provider: ModelProvider, messages: ChatMessage[], options?: ModelConfig & {
        tools?: ToolDefinition[];
    }, context?: RunContext): AsyncGenerator<StreamChunk>;
    runOwned<T>(operation: () => Promise<T>): Promise<T>;
    observeTool(result: ToolCallResult, context?: RunContext): Promise<void>;
    dispatchEffect<T>(name: string, args: Record<string, unknown>, execute: (args: Record<string, unknown>, ctx: RunContext) => Promise<T>): Promise<T>;
    dispatch(call: ToolCall): Promise<ToolCallResult>;
    recordConversation(executionId: string, messages: readonly ChatMessage[]): void;
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.