> ## 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.

# Definitions and abilities

> Compose definitions, implement abilities, and validate portable manifests.

Compose definitions, implement abilities, and validate portable manifests. Read the [definitions and abilities guide](/harness/definitions) 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.

## Ability

```typescript theme={null}
export interface Ability<Options> {
    (options: Options, config?: {
        instanceId?: string;
    }): LocalAbilityUse;
    readonly type: string;
    readonly version: number;
    readonly factory?: AbilityFactory;
}
```

## AbilityDefinition

```typescript theme={null}
export interface AbilityDefinition<Options> {
    type: string;
    version?: number;
    /** Pure validation/snapshotting. Preserve caller-owned service references; never freeze clients. */
    validate: (options: Options) => Options;
    describe: (options: Options) => AbilityDescription;
    bind: (options: Options, ctx: RunContext) => AbilityBinding | Promise<AbilityBinding>;
    /** Explicit trusted mapping. Omit for local callbacks/services that cannot be serialized. */
    portable?: {
        validateOptions: (options: JsonObject) => JsonObject;
        toOptions: (options: JsonObject) => Options;
        toJSON: (options: Options) => JsonObject;
    };
}
```

## AbilityDescription

```typescript theme={null}
export interface AbilityDescription {
    toolNames: readonly string[];
    requirements: readonly string[];
    runtimeDependent?: boolean;
}
```

## defineAbility

```typescript theme={null}
/** Capture typed local options; erase only the wrapper so heterogeneous abilities compose without casts. */
export declare function defineAbility<Options>(definition: AbilityDefinition<Options>): Ability<Options>;
```

## defineHarness

```typescript theme={null}
export declare function defineHarness(input: HarnessDefinitionInput): HarnessDefinition;
```

## describeHarness

```typescript theme={null}
export declare function describeHarness(input: HarnessDefinition): HarnessDescription;
```

## exportManifest

```typescript theme={null}
export declare function exportManifest(input: HarnessDefinition): HarnessManifest;
```

## extendHarness

```typescript theme={null}
export declare function extendHarness(base: HarnessDefinition, extension: HarnessExtension): HarnessDefinition;
```

## hashManifest

```typescript theme={null}
export declare function hashManifest(input: HarnessManifest): string;
```

## loadManifest

```typescript theme={null}
export declare function loadManifest(input: unknown, factories: readonly AbilityFactory[], runtimeRegistry?: HarnessRuntimeRegistry): HarnessDefinition;
```

## AbilityBinding

```typescript theme={null}
export interface AbilityBinding {
    tools: readonly ToolDef[];
    promptFragments?: readonly PromptFragment[];
    contextSources?: readonly HarnessContextSource[];
    middleware?: readonly HarnessMiddleware[];
    dispose?: () => Promise<void>;
}
```

## AbilityFactory

```typescript theme={null}
export interface AbilityFactory {
    type: string;
    version: number;
    validateOptions: (input: JsonObject) => JsonObject;
    describe: (options: JsonObject) => AbilityDescription;
    bind: (options: JsonObject, ctx: RunContext) => Promise<AbilityBinding>;
}
```

## AbilitySelection

```typescript theme={null}
export interface AbilitySelection {
    instanceId: string;
    type: string;
    version: number;
    options: JsonObject;
}
```

## BoundHarness

```typescript theme={null}
export interface BoundHarness {
    readonly tools: ToolDef[];
    readonly promptFragments: PromptFragment[];
    readonly contextSources: HarnessContextSource[];
    readonly middleware: HarnessMiddleware[];
    dispose: () => Promise<readonly HarnessDiagnostic[]>;
}
```

## HarnessContextBudget

```typescript theme={null}
export interface HarnessContextBudget {
    maxEntries: number;
    maxBytes: number;
    maxTokens?: number;
    deadlineMs: number;
}
```

## HarnessContextEntry

```typescript theme={null}
export interface HarnessContextEntry {
    id: string;
    text: string;
    trust: "host" | "source";
    source?: {
        uri: string;
        version?: string;
        locator?: string;
    };
    expiresAt?: number;
    estimatedTokens?: number;
    byteLength: number;
}
```

## HarnessContextSource

```typescript theme={null}
export interface HarnessContextSource {
    id: string;
    fetch: (query: string, ctx: RunContext, budget: HarnessContextBudget) => Promise<readonly HarnessContextEntry[]>;
}
```

## HarnessDefaults

```typescript theme={null}
export interface HarnessDefaults {
    workspace?: false | {
        path: string;
        mode: "read" | "write";
    };
    skillDirs?: readonly string[] | false;
    contextFiles?: boolean;
    filesystem?: boolean;
    subagents?: boolean;
    fileMemory?: boolean;
    searchPastSessions?: boolean;
}
```

## HarnessDefinition

```typescript theme={null}
export type HarnessDefinition = {
    readonly kind: "portable";
    readonly manifest: HarnessManifest;
    readonly factories: readonly AbilityFactory[];
    readonly runtimeRegistry?: HarnessRuntimeRegistry;
} | {
    readonly kind: "local";
    readonly id?: string;
    readonly abilities: readonly LocalAbilityUse[];
    readonly defaults?: HarnessDefaults;
    readonly limits?: HarnessManifest["limits"];
    readonly runtime?: HarnessRuntimeBindings;
    readonly runtimeReferences?: HarnessRuntimeReferences;
    readonly runtimeRegistry?: HarnessRuntimeRegistry;
};
```

## HarnessDescription

```typescript theme={null}
export interface HarnessDescription {
    id: string;
    kind: "portable" | "local";
    contractVersion: 1;
    abilities: readonly (AbilityDescription & {
        instanceId: string;
        type?: string;
        version?: number;
    })[];
    toolNames: readonly string[];
    requirements: readonly string[];
    runtimeDependent: boolean;
    defaults: HarnessDefaults;
    limits: NonNullable<HarnessManifest["limits"]>;
    diagnostics: readonly HarnessDiagnostic[];
}
```

## HarnessDiagnostic

```typescript theme={null}
export interface HarnessDiagnostic {
    code: string;
    path: string;
    message: string;
    severity: "info" | "warning" | "error";
}
```

## HarnessExtension

```typescript theme={null}
export interface HarnessExtension {
    runtime?: HarnessRuntimeBindings;
    runtimeReferences?: HarnessRuntimeReferences;
    runtimeRegistry?: HarnessRuntimeRegistry;
    id?: string;
    abilities?: readonly LocalAbilityUse[];
    disable?: readonly string[];
    replaceAbilities?: readonly LocalAbilityUse[];
    defaults?: HarnessDefaults;
    limits?: HarnessManifest["limits"];
}
```

## HarnessManifest

```typescript theme={null}
export interface HarnessManifest {
    contractVersion: 1;
    runtime?: HarnessRuntimeReferences;
    id: string;
    abilities: readonly AbilitySelection[];
    defaults?: HarnessDefaults;
    limits?: {
        toolRoundtrips?: number;
        maxChildDepth?: number;
    };
}
```

## HarnessMiddleware

```typescript theme={null}
export interface HarnessMiddleware {
    id: string;
    before?: readonly string[];
    after?: readonly string[];
    beforeModel?: (messages: readonly ChatMessage[], ctx: RunContext) => Promise<ChatMessage[]>;
    afterModel?: (response: ModelResponse, ctx: RunContext) => Promise<void>;
    afterTool?: (result: ToolCallResult, ctx: RunContext) => Promise<void>;
}
```

## JsonObject

```typescript theme={null}
export type JsonObject = {
    [key: string]: JsonValue;
};
```

## JsonValue

```typescript theme={null}
export type JsonValue = null | boolean | number | string | JsonValue[] | {
    [key: string]: JsonValue;
};
```

## LocalAbilityUse

```typescript theme={null}
export interface LocalAbilityUse {
    instanceId: string;
    validate: () => void;
    describe: () => AbilityDescription;
    bind: (ctx: RunContext) => Promise<AbilityBinding>;
    portable?: AbilitySelection;
    /** Trusted factory approved by the creator/host, never recovered from JSON. */
    factory?: AbilityFactory;
}
```

## PromptFragment

```typescript theme={null}
export interface PromptFragment {
    id: string;
    text: string;
}
```

## ResolvedHarness

```typescript theme={null}
export interface ResolvedHarness {
    readonly definition: HarnessDefinition;
    readonly defaults: HarnessDefaults;
    readonly limits: NonNullable<HarnessManifest["limits"]>;
    readonly description: HarnessDescription;
    readonly provenance: readonly HarnessProvenance[];
}
```

## Supporting types

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

### HarnessDefinitionInput

```typescript theme={null}
export type HarnessDefinitionInput = HarnessDefinition | {
    id?: string;
    abilities?: readonly LocalAbilityUse[];
    defaults?: HarnessDefaults;
    limits?: HarnessManifest["limits"];
    runtime?: HarnessRuntimeBindings;
    runtimeReferences?: HarnessRuntimeReferences;
    runtimeRegistry?: HarnessRuntimeRegistry;
};
```

### HarnessProvenance

```typescript theme={null}
export interface HarnessProvenance {
    path: string;
    origin: string;
}
```


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