@purista/harness 1.0.0

package/dist/harness/defineHarness.d.ts

@@ -0,0 +1,640 @@
+import { z } from 'zod';
+import { type Logger } from '../logger/index.js';
+import type { ModelAlias, ModelCapability, TokenUsage } from '../ports/model-provider.js';
+import type { StateStore } from '../ports/state.js';
+import type { TelemetryShim } from '../telemetry/index.js';
+import type { HarnessAdapterContext } from '../ports/harness-context.js';
+import type { JsonValue } from '../models/json.js';
+import type { Message } from '../models/state.js';
+import type { HarnessError } from '../errors/harness-error.js';
+import { type Sandbox } from '../sandbox/index.js';
+import type { ModelHandle } from '../models/registry.js';
+import { type AdapterCapability, type DurableRuntimeAdapter, type HarnessInspection } from '../ports/capabilities.js';
+/** Stable harness version string for diagnostics and generated documentation. */
+export declare const HARNESS_VERSION = "0.0.0";
+/** OpenTelemetry capture controls used by the harness. */
+export interface TelemetryOptions {
+    /**
+     * When `true`, emitted telemetry may include full prompt/message content.
+     * The default is `false` to avoid accidental sensitive-content capture.
+     */
+    captureContent?: boolean;
+}
+/** Default harness budgets and execution behavior. */
+export interface HarnessDefaults {
+    /** Default maximum iterations for the built-in agent loop. Default: `16`. */
+    agentMaxIterations?: number;
+    /** Per-run timeout in milliseconds. `0` disables. Default: `600_000`. */
+    runTimeoutMs?: number;
+    /** Per-tool timeout in milliseconds. Default: `120_000`. */
+    toolTimeoutMs?: number;
+    /** Per-skill timeout in milliseconds. Default: `60_000`. */
+    skillTimeoutMs?: number;
+    /** Per-model timeout in milliseconds. Default: `300_000`. */
+    modelTimeoutMs?: number;
+    /**
+     * Max non-system messages forwarded into model calls.
+     * `undefined` keeps all history, `0` keeps only system messages.
+     */
+    historyWindow?: number;
+}
+/** Top-level harness options passed to {@link defineHarness}. */
+export interface HarnessOptions {
+    /** Optional harness name for logs, telemetry, and diagnostics. Default: `agent-harness`. */
+    name?: string;
+}
+/** Shared invoke options for workflow and agent execution. */
+export interface InvokeOptions {
+    /** Abort signal used to cooperatively cancel the call. */
+    signal?: AbortSignal;
+    /** Optional timeout override in milliseconds. `0` disables. */
+    timeoutMs?: number;
+    /** Optional history-window override for this call only. */
+    historyWindow?: number;
+}
+/** Canonical built-in tool names provided by the harness. */
+export type BuiltinToolName = 'bash' | 'read' | 'write' | 'edit' | 'glob' | 'grep' | 'list';
+/** Permission modes for sandbox-mutating tools. */
+export type PermissionMode = 'allow' | 'ask' | 'deny';
+/** Structured permission policy for a single tool family. */
+export interface PermissionPolicy {
+    /** Base decision mode for the tool family. */
+    mode: PermissionMode;
+    /** Optional allowlist evaluated by harness-specific policy hooks. */
+    allow?: readonly string[];
+    /** Optional denylist evaluated by harness-specific policy hooks. */
+    deny?: readonly string[];
+}
+/** Per-agent permission configuration for built-in mutating tools. */
+export interface AgentPermissions {
+    /** Permission mode or policy for the `bash` built-in tool. */
+    bash?: PermissionMode | PermissionPolicy;
+    /** Permission mode or policy for the `write` built-in tool. */
+    write?: PermissionMode | PermissionPolicy;
+    /** Permission mode or policy for the `edit` built-in tool. */
+    edit?: PermissionMode | PermissionPolicy;
+}
+/** Context passed to custom permission hooks. */
+export interface PermissionContext {
+    /** Tool name under evaluation. */
+    toolName: string;
+    /** Raw input proposed for the tool call. */
+    input: unknown;
+    /** Current agent id. */
+    agentId: string;
+    /** Current run id. */
+    runId: string;
+    /** Current session id. */
+    sessionId: string;
+}
+/** Final decision returned from a permission hook. */
+export type PermissionDecision = 'allow' | 'deny';
+/** Async permission hook used for interactive approvals or custom policy engines. */
+export type OnPermission = (ctx: PermissionContext) => Promise<PermissionDecision>;
+/** Mounted skill metadata after frontmatter parsing. */
+export interface ResolvedSkill {
+    /** Public skill id. */
+    name: string;
+    /** Short user-facing description from frontmatter. */
+    description: string;
+    /** Optional skill version. */
+    version?: string;
+    /** Absolute directory mounted into `/skills/<name>`. */
+    directory: string;
+}
+/** Sandbox-backed per-session memory facade. */
+export interface SessionMemory {
+    /** Reads `/memory/<key>.json` and returns the parsed JSON value if present. */
+    read<T = JsonValue>(key: string): Promise<T | undefined>;
+    /** Writes JSON-serializable data to `/memory/<key>.json`. */
+    write(key: string, value: JsonValue): Promise<void>;
+    /** Deletes `/memory/<key>.json` if it exists. */
+    delete(key: string): Promise<void>;
+    /** Lists known memory keys without the `.json` suffix. */
+    list(): Promise<string[]>;
+}
+/** Conversation history accessor for a single session thread. */
+export interface ConversationHistory {
+    /** Returns persisted conversation messages for the session. */
+    list(opts?: {
+        limit?: number;
+        before?: string;
+    }): Promise<Message[]>;
+}
+/** Context provided to custom TypeScript tools. */
+export interface ToolHandlerContext {
+    signal: AbortSignal;
+    sandbox: import('../sandbox/index.js').SandboxSession;
+    logger: Logger;
+    telemetry: TelemetryShim;
+    runId: string;
+    sessionId: string;
+    agentId: string;
+    toolId: string;
+}
+/** TypeScript-native tool definition. */
+export interface TsToolDefinition<I extends z.ZodTypeAny = z.ZodTypeAny, O extends z.ZodTypeAny = z.ZodTypeAny> {
+    /** Tool kind discriminator. Defaults to `ts`. */
+    kind?: 'ts';
+    /** Short model-facing description. */
+    description: string;
+    /** Input schema validated before handler invocation. */
+    input: I;
+    /** Output schema validated after handler invocation. */
+    output: O;
+    /** Async tool implementation running inside the current session sandbox. */
+    handler: (ctx: ToolHandlerContext, input: z.infer<I>) => Promise<z.infer<O>>;
+    /** Optional adapter hook for inheriting harness logger, telemetry, and defaults. */
+    configureHarnessContext?: (context: HarnessAdapterContext) => void;
+}
+/** MCP-over-stdio tool definition. */
+export interface McpStdioToolDefinition {
+    kind: 'mcp_stdio';
+    description: string;
+    command: string;
+    args?: readonly string[];
+    env?: Record<string, string>;
+    /** Optional bootstrap command executed inside the sandbox before the MCP server is called. */
+    install?: {
+        command: string;
+        cwd?: string;
+        env?: Record<string, string>;
+        timeoutMs?: number;
+    };
+    tool: string;
+    inputAdapter?: (input: unknown) => unknown;
+    outputAdapter?: (output: unknown) => unknown;
+    configureHarnessContext?: (context: HarnessAdapterContext) => void;
+}
+/** Supported MCP auth kinds. */
+export type McpAuth = 
+/** No authentication. */
+{
+    kind: 'none';
+}
+/** Bearer token authentication. */
+ | {
+    kind: 'bearer';
+    token: string;
+}
+/** OAuth2 access token authentication. */
+ | {
+    kind: 'oauth2';
+    accessToken: string;
+}
+/** API key authentication. */
+ | {
+    kind: 'api_key';
+    header: string;
+    value: string;
+}
+/** Basic authentication. */
+ | {
+    kind: 'basic';
+    username: string;
+    password: string;
+};
+/** MCP-over-HTTP tool definition. */
+export interface McpHttpToolDefinition {
+    kind: 'mcp_http';
+    description: string;
+    url: string;
+    tool: string;
+    auth?: McpAuth;
+    headers?: Record<string, string>;
+    inputAdapter?: (input: unknown) => unknown;
+    outputAdapter?: (output: unknown) => unknown;
+    configureHarnessContext?: (context: HarnessAdapterContext) => void;
+}
+/** Any tool definition accepted by `.tools(...)`. */
+export type ToolDefinition = TsToolDefinition | McpStdioToolDefinition | McpHttpToolDefinition;
+/** Full tool registry shape. */
+export type ToolsConfig = Record<string, ToolDefinition>;
+/** Skill definition registered on the harness builder. */
+export interface SkillDefinition {
+    /** Absolute path to the directory containing `SKILL.md`. */
+    directory: string;
+}
+/** Full skill registry shape. */
+export type SkillsConfig = Record<string, SkillDefinition>;
+/** Alias map passed to `.models(...)`. */
+export type ModelsConfig = Record<string, ModelAlias>;
+/** Builder-state accumulator used for type propagation across the fluent harness builder. */
+export interface BuilderState {
+    models?: ModelsConfig;
+    tools?: ToolsConfig;
+    skills?: SkillsConfig;
+    agents?: Record<string, AgentDefinition<any, any, any>>;
+    workflows?: Record<string, WorkflowDefinition<any, any, any>>;
+}
+type InferSchemaOrString<T> = T extends z.ZodTypeAny ? z.infer<T> : string;
+type DefinitionInput<D> = D extends {
+    input: infer I;
+} ? InferSchemaOrString<I> : D extends {
+    input?: infer I;
+} ? InferSchemaOrString<I> : string;
+type DefinitionOutput<D> = D extends {
+    output: infer O;
+} ? InferSchemaOrString<O> : D extends {
+    output?: infer O;
+} ? InferSchemaOrString<O> : string;
+/** Helper to infer workflow input type from a workflow definition. */
+export type WorkflowInput<S extends BuilderState, K extends keyof NonNullable<S['workflows']>> = DefinitionInput<NonNullable<S['workflows']>[K]>;
+/** Helper to infer workflow output type from a workflow definition. */
+export type WorkflowOutput<S extends BuilderState, K extends keyof NonNullable<S['workflows']>> = DefinitionOutput<NonNullable<S['workflows']>[K]>;
+/** Helper to infer agent input type from an agent definition. */
+export type AgentInput<S extends BuilderState, K extends keyof NonNullable<S['agents']>> = DefinitionInput<NonNullable<S['agents']>[K]>;
+/** Helper to infer agent output type from an agent definition. */
+export type AgentOutput<S extends BuilderState, K extends keyof NonNullable<S['agents']>> = DefinitionOutput<NonNullable<S['agents']>[K]>;
+/** Capability-filtered model handles keyed by configured model alias. */
+export type ModelHandles<S extends BuilderState> = {
+    readonly [K in keyof NonNullable<S['models']>]: NonNullable<S['models']>[K] extends {
+        capabilities: readonly ModelCapability[];
+    } ? ModelHandle<NonNullable<S['models']>[K]> : never;
+};
+/** Minimal context available when deriving dynamic agent instructions. */
+export interface AgentContextMinimal<S extends BuilderState, I> {
+    input: I;
+    sessionId: string;
+    runId: string;
+    history: ConversationHistory;
+    memory: SessionMemory;
+}
+/** Full context passed to workflow handlers. */
+export interface WorkflowContext<S extends BuilderState, I, O> {
+    input: I;
+    agents: {
+        [K in keyof NonNullable<S['agents']>]: (input: AgentInput<S, K>, opts?: InvokeOptions) => Promise<AgentOutput<S, K>>;
+    };
+    models: ModelHandles<S>;
+    signal: AbortSignal;
+    runId: string;
+    sessionId: string;
+    output?: O;
+}
+/** Full context passed to custom agent handlers. */
+export interface AgentContext<S extends BuilderState, I, O> extends AgentContextMinimal<S, I> {
+    models: ModelHandles<S>;
+    signal: AbortSignal;
+    output?: O;
+}
+/** Agent definition registered inline within `.agents(...)`. */
+export interface AgentDefinition<S extends BuilderState, I extends z.ZodTypeAny = z.ZodTypeAny, O extends z.ZodTypeAny = z.ZodTypeAny> {
+    input?: I;
+    output?: O;
+    model: keyof NonNullable<S['models']> & string;
+    instructions: string | ((ctx: AgentContextMinimal<S, z.infer<I>>) => string);
+    tools?: readonly (keyof NonNullable<S['tools']> & string)[];
+    builtinTools?: readonly BuiltinToolName[] | false;
+    skills?: readonly (keyof NonNullable<S['skills']> & string)[];
+    permissions?: AgentPermissions;
+    onPermission?: OnPermission;
+    maxSteps?: number;
+    handler?: (ctx: AgentContext<S, z.infer<I>, z.infer<O>>) => Promise<z.infer<O>>;
+}
+/** Workflow definition registered inline within `.workflows(...)`. */
+export interface WorkflowDefinition<S extends BuilderState, I extends z.ZodTypeAny = z.ZodTypeAny, O extends z.ZodTypeAny = z.ZodTypeAny> {
+    input?: I;
+    output?: O;
+    handler: (ctx: WorkflowContext<S, z.infer<I>, z.infer<O>>) => Promise<z.infer<O>>;
+}
+type AgentSchemaFields = {
+    input?: z.ZodTypeAny;
+    output?: z.ZodTypeAny;
+};
+type AgentDefinitionResolved<S extends BuilderState, I extends z.ZodTypeAny, O extends z.ZodTypeAny> = {
+    input?: I;
+    output?: O;
+    model: keyof NonNullable<S['models']> & string;
+    instructions: string | ((ctx: AgentContextMinimal<S, z.infer<I>>) => string);
+    tools?: readonly (keyof NonNullable<S['tools']> & string)[];
+    builtinTools?: readonly BuiltinToolName[] | false;
+    skills?: readonly (keyof NonNullable<S['skills']> & string)[];
+    permissions?: AgentPermissions;
+    onPermission?: OnPermission;
+    maxSteps?: number;
+    handler?: (ctx: AgentContext<S, z.infer<I>, z.infer<O>>) => Promise<z.infer<O>>;
+};
+type AgentDefinitionFor<S extends BuilderState, D> = D extends {
+    input: infer I extends z.ZodTypeAny;
+    output: infer O extends z.ZodTypeAny;
+} ? AgentDefinitionResolved<S, I, O> : D extends {
+    input: infer I extends z.ZodTypeAny;
+} ? AgentDefinitionResolved<S, I, z.ZodString> : D extends {
+    output: infer O extends z.ZodTypeAny;
+} ? AgentDefinitionResolved<S, z.ZodString, O> : AgentDefinitionResolved<S, z.ZodString, z.ZodString>;
+type AgentsConfigFromSchemaMaps<S extends BuilderState, A extends {
+    [K in keyof A]: {
+        input: z.ZodTypeAny;
+        output: z.ZodTypeAny;
+    };
+}> = {
+    [K in keyof A]: A[K] & AgentDefinitionResolved<S, A[K]['input'], A[K]['output']>;
+};
+type WorkflowSchemaFields = {
+    input?: z.ZodTypeAny;
+    output?: z.ZodTypeAny;
+};
+type WorkflowDefinitionResolved<S extends BuilderState, I extends z.ZodTypeAny, O extends z.ZodTypeAny> = {
+    input?: I;
+    output?: O;
+    handler: (ctx: WorkflowContext<S, z.infer<I>, z.infer<O>>) => Promise<z.infer<O>>;
+};
+type WorkflowDefinitionFor<S extends BuilderState, D> = D extends {
+    input: infer I extends z.ZodTypeAny;
+    output: infer O extends z.ZodTypeAny;
+} ? WorkflowDefinitionResolved<S, I, O> : D extends {
+    input: infer I extends z.ZodTypeAny;
+} ? WorkflowDefinitionResolved<S, I, z.ZodString> : D extends {
+    output: infer O extends z.ZodTypeAny;
+} ? WorkflowDefinitionResolved<S, z.ZodString, O> : WorkflowDefinitionResolved<S, z.ZodString, z.ZodString>;
+type WorkflowsConfigFromSchemaMaps<S extends BuilderState, W extends {
+    [K in keyof W]: {
+        input: z.ZodTypeAny;
+        output: z.ZodTypeAny;
+    };
+}> = {
+    [K in keyof W]: W[K] & WorkflowDefinitionResolved<S, W[K]['input'], W[K]['output']>;
+};
+export interface AgentDefinitionHelpers<S extends BuilderState> {
+    agent<const I extends z.ZodTypeAny, const O extends z.ZodTypeAny>(definition: AgentDefinitionResolved<S, I, O> & {
+        input: I;
+        output: O;
+    }): AgentDefinitionResolved<S, I, O> & {
+        input: I;
+        output: O;
+    };
+}
+export interface WorkflowDefinitionHelpers<S extends BuilderState> {
+    workflow<const I extends z.ZodTypeAny, const O extends z.ZodTypeAny>(definition: WorkflowDefinitionResolved<S, I, O> & {
+        input: I;
+        output: O;
+    }): WorkflowDefinitionResolved<S, I, O> & {
+        input: I;
+        output: O;
+    };
+}
+/** Agent registry shape constrained by the previously declared models/tools/skills. */
+export type AgentsConfig<S extends BuilderState, A extends {
+    [K in keyof A]: AgentSchemaFields;
+} = Record<string, AgentSchemaFields>> = {
+    [K in keyof A]: A[K] & AgentDefinitionFor<S, A[K]>;
+};
+/** Workflow registry shape constrained by the previously declared agents. */
+export type WorkflowsConfig<S extends BuilderState, W extends {
+    [K in keyof W]: WorkflowSchemaFields;
+} = Record<string, WorkflowSchemaFields>> = {
+    [K in keyof W]: W[K] & WorkflowDefinitionFor<S, W[K]>;
+};
+/** Typed workflow invoker available under `session.workflows.<id>`. */
+export interface WorkflowInvoker<S extends BuilderState, K extends keyof NonNullable<S['workflows']>> {
+    /** Runs the workflow to completion and resolves its validated output. */
+    prompt(input: WorkflowInput<S, K>, opts?: InvokeOptions): Promise<WorkflowOutput<S, K>>;
+    /** Streams run events while the workflow executes. */
+    stream(input: WorkflowInput<S, K>, opts?: InvokeOptions): AsyncIterable<RunEvent>;
+}
+/** Typed agent invoker available under `session.agents.<id>`. */
+export interface AgentInvoker<S extends BuilderState, K extends keyof NonNullable<S['agents']>> {
+    /** Runs the agent to completion and resolves its validated output. */
+    prompt(input: AgentInput<S, K>, opts?: InvokeOptions): Promise<AgentOutput<S, K>>;
+    /** Streams run events while the agent executes. */
+    stream(input: AgentInput<S, K>, opts?: InvokeOptions): AsyncIterable<RunEvent>;
+}
+/** Compile-time-only namespace exposed as `harness.$infer`. */
+export type InferTypes<S extends BuilderState> = {
+    models: keyof NonNullable<S['models']>;
+    tools: keyof NonNullable<S['tools']>;
+    skills: keyof NonNullable<S['skills']>;
+    agents: {
+        [K in keyof NonNullable<S['agents']>]: {
+            input: AgentInput<S, K>;
+            output: AgentOutput<S, K>;
+        };
+    };
+    workflows: {
+        [K in keyof NonNullable<S['workflows']>]: {
+            input: WorkflowInput<S, K>;
+            output: WorkflowOutput<S, K>;
+        };
+    };
+};
+/** Harness handle returned from `build()`. */
+export interface Harness<S extends BuilderState> {
+    /** Opens or creates a fresh session facade bound to `id`. */
+    getSession(id: string): Promise<Session<S>>;
+    /** Returns a synchronous, data-only snapshot of resolved adapter setup. */
+    inspect(): HarnessInspection;
+    /** Closes harness-owned adapters and returns any shutdown errors. */
+    shutdown(): Promise<{
+        errors: HarnessError[];
+    }>;
+    /** Phantom inference handle. Harness value is always the literal `{}`. */
+    readonly $infer: InferTypes<S>;
+}
+/** Session-scoped operational API. */
+export interface Session<S extends BuilderState> {
+    readonly id: string;
+    readonly agents: {
+        readonly [K in keyof NonNullable<S['agents']>]: AgentInvoker<S, K>;
+    };
+    readonly workflows: {
+        readonly [K in keyof NonNullable<S['workflows']>]: WorkflowInvoker<S, K>;
+    };
+    memory: SessionMemory;
+    history: ConversationHistory;
+    clearHistory(): Promise<void>;
+    replaceHistory(messages: ReadonlyArray<Omit<Message, 'id' | 'timestamp'>>): Promise<void>;
+    close(): Promise<void>;
+}
+/** Structured run-event error payload. */
+export interface SerializedError {
+    code: string;
+    category: string;
+    retriable: boolean;
+    message: string;
+    meta?: Record<string, unknown>;
+}
+/** Harness streaming events emitted from `session.workflows.<id>.stream(...)`. */
+export type RunEvent = {
+    type: 'run.started';
+    runId: string;
+    at: string;
+} | {
+    type: 'run.finished';
+    runId: string;
+    at: string;
+    output?: JsonValue;
+    error?: SerializedError;
+} | {
+    type: 'agent.started';
+    runId: string;
+    agentId: string;
+    at: string;
+} | {
+    type: 'agent.finished';
+    runId: string;
+    agentId: string;
+    at: string;
+    output?: JsonValue;
+    error?: SerializedError;
+} | {
+    type: 'model.delta';
+    runId: string;
+    agentId: string;
+    delta: string;
+} | {
+    type: 'tool.started';
+    runId: string;
+    agentId: string;
+    toolId: string;
+    callId: string;
+    input: JsonValue;
+} | {
+    type: 'tool.finished';
+    runId: string;
+    agentId: string;
+    toolId: string;
+    callId: string;
+    output?: JsonValue;
+    error?: SerializedError;
+} | {
+    type: 'model.message';
+    runId: string;
+    agentId: string;
+    message: Message;
+} | {
+    type: 'model.object.partial';
+    runId: string;
+    agentId?: string;
+    partial: JsonValue;
+} | {
+    type: 'model.object';
+    runId: string;
+    agentId?: string;
+    object: JsonValue;
+} | {
+    type: 'model.embedding.completed';
+    runId: string;
+    agentId?: string;
+    count: number;
+    dimensions?: number;
+    usage?: TokenUsage;
+} | {
+    type: 'model.rerank.completed';
+    runId: string;
+    agentId?: string;
+    count: number;
+    topN?: number;
+    usage?: TokenUsage;
+} | {
+    type: 'stream.overflow';
+    runId: string;
+    at: string;
+    dropped: number;
+};
+/** Fluent builder contract for composing a harness. */
+export interface HarnessBuilder<S extends BuilderState = {}> {
+    telemetry(opts: TelemetryOptions): HarnessBuilder<S>;
+    logger(logger: Logger): HarnessBuilder<S>;
+    state(store: StateStore): HarnessBuilder<S>;
+    sandbox(sandbox?: Sandbox<any>): HarnessBuilder<S>;
+    runtime(runtime: DurableRuntimeAdapter): HarnessBuilder<S>;
+    requires(capabilities: readonly AdapterCapability[]): HarnessBuilder<S>;
+    defaults(defaults: HarnessDefaults): HarnessBuilder<S>;
+    models<const M extends ModelsConfig>(models: M): HarnessBuilder<S & {
+        models: M;
+    }>;
+    tools<const T extends ToolsConfig>(tools: T): HarnessBuilder<S & {
+        tools: T;
+    }>;
+    skills<const K extends SkillsConfig>(skills: K): HarnessBuilder<S & {
+        skills: K;
+    }>;
+    agents<const A extends {
+        [K in keyof A]: AgentDefinition<any, any, any>;
+    }>(agents: (helpers: AgentDefinitionHelpers<S & {
+        models: NonNullable<S['models']>;
+        tools: NonNullable<S['tools']>;
+        skills: NonNullable<S['skills']>;
+    }>) => A): HarnessBuilder<S & {
+        agents: A;
+    }>;
+    agents<const A extends {
+        [K in keyof A]: {
+            input: z.ZodTypeAny;
+            output: z.ZodTypeAny;
+        };
+    }>(agents: AgentsConfigFromSchemaMaps<S & {
+        models: NonNullable<S['models']>;
+        tools: NonNullable<S['tools']>;
+        skills: NonNullable<S['skills']>;
+    }, A>): HarnessBuilder<S & {
+        agents: AgentsConfigFromSchemaMaps<S & {
+            models: NonNullable<S['models']>;
+            tools: NonNullable<S['tools']>;
+            skills: NonNullable<S['skills']>;
+        }, A>;
+    }>;
+    agents<const A extends {
+        [K in keyof A]: AgentDefinitionFor<S & {
+            models: NonNullable<S['models']>;
+            tools: NonNullable<S['tools']>;
+            skills: NonNullable<S['skills']>;
+        }, A[K]>;
+    }>(agents: A): HarnessBuilder<S & {
+        agents: A;
+    }>;
+    workflows<const W extends {
+        [K in keyof W]: WorkflowDefinition<any, any, any>;
+    }>(workflows: (helpers: WorkflowDefinitionHelpers<S & {
+        agents: NonNullable<S['agents']>;
+    }>) => W): HarnessBuilder<S & {
+        workflows: W;
+    }>;
+    workflows<const W extends {
+        [K in keyof W]: {
+            input: z.ZodTypeAny;
+            output: z.ZodTypeAny;
+        };
+    }>(workflows: WorkflowsConfigFromSchemaMaps<S & {
+        agents: NonNullable<S['agents']>;
+    }, W>): HarnessBuilder<S & {
+        workflows: WorkflowsConfigFromSchemaMaps<S & {
+            agents: NonNullable<S['agents']>;
+        }, W>;
+    }>;
+    workflows<const W extends {
+        [K in keyof W]: WorkflowDefinitionFor<S & {
+            agents: NonNullable<S['agents']>;
+        }, W[K]>;
+    }>(workflows: W): HarnessBuilder<S & {
+        workflows: W;
+    }>;
+    build(): Harness<S>;
+}
+/**
+ * Creates the chainable harness builder used to define a harness system.
+ *
+ * Application code should compose models, tools, skills, agents, and workflows here,
+ * build the harness, and then execute work exclusively through `harness.getSession(...)`.
+ *
+ * @example
+ * ```ts
+ * const harness = defineHarness()
+ *   .models({ fast: { provider, model: 'gpt-4.1-mini', capabilities: ['object'] } })
+ *   .agents({ summarize: { model: 'fast', instructions: 'Summarize the input.' } })
+ *   .workflows({
+ *     summarize_ticket: {
+ *       input: z.object({ ticket: z.string() }),
+ *       output: z.string(),
+ *       handler: (ctx) => ctx.agents.summarize(ctx.input.ticket)
+ *     }
+ *   })
+ *   .build()
+ *
+ * const session = await harness.getSession('ticket-123')
+ * const summary = await session.workflows.summarize_ticket.prompt({ ticket: 'Cannot log in' })
+ * ```
+ */
+export declare function defineHarness(opts?: HarnessOptions): HarnessBuilder<{}>;
+export {};