Runtime and run handles

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>;
}

export interface HarnessBudgets {
    maxModelCalls?: number;
    maxToolCalls?: number;
    maxTokens?: number;
    maxRevisions?: number;
}

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

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;
}

export interface HarnessGrants {
    toolIds: readonly string[];
    requiredToolIds?: readonly string[];
    modelRoles: readonly string[];
}

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;
}

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;
}

export type HarnessSendMode = "follow_up" | "steer" | "replace";

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

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>;
}

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

/** 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;
}

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

/** 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;
}