@purista/harness 1.0.0

package/dist/harness/defineHarness.js

@@ -0,0 +1,176 @@
+import { z } from 'zod';
+import { JsonLogger } from '../logger/index.js';
+import { InMemoryStateStore } from '../state/in-memory.js';
+import { HarnessConfigError } from '../errors/catalog.js';
+import { autoDetectSandbox } from '../sandbox/index.js';
+import { createSessionHarness } from '../sessions/index.js';
+import { hasAdapterCapabilities, missingCapabilities, uniqueCapabilities } from '../ports/capabilities.js';
+/** Stable harness version string for diagnostics and generated documentation. */
+export const HARNESS_VERSION = '0.0.0';
+class Builder {
+    options;
+    configured;
+    constructor(options, configured = {}) {
+        this.options = options;
+        this.configured = configured;
+    }
+    telemetry(opts) {
+        return this.clone({ telemetry: opts });
+    }
+    logger(logger) {
+        return this.clone({ logger });
+    }
+    state(store) {
+        return this.clone({ state: store });
+    }
+    sandbox(sandbox = autoDetectSandbox()) {
+        return this.clone({ sandbox });
+    }
+    runtime(runtime) {
+        return this.clone({ runtime });
+    }
+    requires(capabilities) {
+        return this.clone({ requiredCapabilities: uniqueCapabilities(capabilities) });
+    }
+    defaults(defaults) {
+        if (defaults.historyWindow !== undefined && defaults.historyWindow < 0) {
+            throw new HarnessConfigError('historyWindow must be >= 0', { reason: 'invalid_defaults', path: 'defaults.historyWindow' });
+        }
+        return this.clone({ defaults });
+    }
+    models(models) {
+        if (Object.keys(models).length === 0) {
+            throw new HarnessConfigError('At least one model alias is required.', { reason: 'missing_models', path: 'models' });
+        }
+        return this.clone({ models });
+    }
+    tools(tools) {
+        return this.clone({ tools });
+    }
+    skills(skills) {
+        return this.clone({ skills });
+    }
+    agents(agents) {
+        const resolved = typeof agents === 'function'
+            ? agents({ agent: (definition) => definition })
+            : agents;
+        return this.clone({ agents: resolved });
+    }
+    workflows(workflows) {
+        const resolved = typeof workflows === 'function'
+            ? workflows({ workflow: (definition) => definition })
+            : workflows;
+        return this.clone({ workflows: resolved });
+    }
+    build() {
+        const models = this.configured.models;
+        if (!models || Object.keys(models).length === 0) {
+            throw new HarnessConfigError('At least one model alias is required.', { reason: 'missing_models', path: 'models' });
+        }
+        const sandbox = this.configured.sandbox ?? autoDetectSandbox();
+        const inspection = this.resolveInspection(this.options.name ?? 'agent-harness', sandbox, models);
+        const missing = missingCapabilities(inspection.requiredCapabilities, inspection.capabilities);
+        if (missing.length > 0) {
+            throw new HarnessConfigError('Required adapter capabilities are not available.', {
+                reason: 'missing_required_capability',
+                path: 'requires',
+                id: missing.join(',')
+            });
+        }
+        const harness = createSessionHarness({
+            name: this.options.name ?? 'agent-harness',
+            logger: this.configured.logger ?? new JsonLogger(),
+            ...(this.configured.telemetry ? { telemetry: this.configured.telemetry } : {}),
+            state: this.configured.state ?? new InMemoryStateStore(),
+            sandbox,
+            defaults: {
+                agentMaxIterations: this.configured.defaults?.agentMaxIterations ?? 16,
+                runTimeoutMs: this.configured.defaults?.runTimeoutMs ?? 600_000,
+                toolTimeoutMs: this.configured.defaults?.toolTimeoutMs ?? 120_000,
+                skillTimeoutMs: this.configured.defaults?.skillTimeoutMs ?? 60_000,
+                modelTimeoutMs: this.configured.defaults?.modelTimeoutMs ?? 300_000,
+                ...(this.configured.defaults?.historyWindow !== undefined ? { historyWindow: this.configured.defaults.historyWindow } : {})
+            },
+            models,
+            tools: (this.configured.tools ?? {}),
+            skills: (this.configured.skills ?? {}),
+            agents: (this.configured.agents ?? {}),
+            workflows: (this.configured.workflows ?? {}),
+            inspection
+        });
+        return harness;
+    }
+    clone(patch) {
+        return new Builder(this.options, { ...this.configured, ...patch });
+    }
+    resolveInspection(name, sandbox, models) {
+        const adapters = [];
+        const sandboxCapabilities = hasAdapterCapabilities(sandbox) ? uniqueCapabilities(sandbox.capabilities) : [];
+        adapters.push({
+            kind: 'sandbox',
+            id: getAdapterId(sandbox, 'sandbox'),
+            capabilities: sandboxCapabilities
+        });
+        if (this.configured.runtime) {
+            adapters.push({
+                kind: 'runtime',
+                id: this.configured.runtime.id ?? 'runtime',
+                capabilities: uniqueCapabilities(this.configured.runtime.capabilities)
+            });
+        }
+        for (const [alias, model] of Object.entries(models)) {
+            adapters.push({
+                kind: 'model',
+                id: alias,
+                capabilities: [],
+                metadata: {
+                    providerId: model.provider.id,
+                    genAiSystem: model.provider.genAiSystem,
+                    model: model.model,
+                    modelCapabilities: model.capabilities,
+                    ...(model.provider.info ? { providerInfo: model.provider.info } : {})
+                }
+            });
+        }
+        const capabilities = uniqueCapabilities(adapters.flatMap((adapter) => adapter.capabilities));
+        return {
+            name,
+            capabilities,
+            requiredCapabilities: uniqueCapabilities(this.configured.requiredCapabilities ?? []),
+            adapters
+        };
+    }
+}
+function getAdapterId(adapter, fallback) {
+    if (adapter && typeof adapter === 'object' && typeof adapter.id === 'string') {
+        return adapter.id;
+    }
+    return fallback;
+}
+/**
+ * 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 function defineHarness(opts = {}) {
+    return new Builder(opts);
+}

package/dist/harness/errors.d.ts

@@ -0,0 +1,62 @@
+import type { JsonValue } from './types.js';
+export declare class HarnessError extends Error {
+    code: string;
+    category: string;
+    retriable: boolean;
+    meta?: Record<string, JsonValue>;
+    constructor(message: string, opts: {
+        code: string;
+        category: string;
+        retriable: boolean;
+        meta?: Record<string, JsonValue>;
+    });
+}
+export declare class HarnessConfigError extends HarnessError {
+    constructor(message: string, meta?: Record<string, JsonValue>);
+}
+export declare class ValidationError extends HarnessError {
+    constructor(message: string, meta?: Record<string, JsonValue>);
+}
+export declare class PermissionDeniedError extends HarnessError {
+    constructor(message: string, meta?: Record<string, JsonValue>);
+}
+export declare class SandboxError extends HarnessError {
+    constructor(message: string, meta?: Record<string, JsonValue>);
+}
+export declare class SandboxNoExecutorError extends HarnessError {
+    constructor();
+}
+export declare class ModelError extends HarnessError {
+    constructor(message: string, meta?: Record<string, JsonValue>);
+}
+export declare class ToolError extends HarnessError {
+    constructor(message: string, meta?: Record<string, JsonValue>);
+}
+export declare class ToolNotFoundError extends HarnessError {
+    constructor(tool: string);
+}
+export declare class SkillManifestError extends HarnessError {
+    constructor(message: string, meta?: Record<string, JsonValue>);
+}
+export declare class AgentLoopBudgetError extends HarnessError {
+    constructor();
+}
+export declare class SessionBusyError extends HarnessError {
+    constructor(reason?: string);
+}
+export declare class OperationTimeoutError extends HarnessError {
+    constructor(scope: string);
+}
+export declare class OperationCancelledError extends HarnessError {
+    constructor(scope: string);
+}
+export declare class InternalError extends HarnessError {
+    constructor(message: string, meta?: Record<string, JsonValue>);
+}
+export declare function serializeError(error: unknown): {
+    code: string;
+    category: string;
+    retriable: boolean;
+    message: string;
+    meta?: Record<string, JsonValue>;
+};

package/dist/harness/errors.js

@@ -0,0 +1,67 @@
+export class HarnessError extends Error {
+    code;
+    category;
+    retriable;
+    meta;
+    constructor(message, opts) {
+        super(message);
+        this.name = new.target.name;
+        this.code = opts.code;
+        this.category = opts.category;
+        this.retriable = opts.retriable;
+        if (opts.meta !== undefined)
+            this.meta = opts.meta;
+    }
+}
+function errorOptions(opts, meta) {
+    return meta === undefined ? opts : { ...opts, meta };
+}
+export class HarnessConfigError extends HarnessError {
+    constructor(message, meta) { super(message, errorOptions({ code: 'HARNESS_CONFIG_ERROR', category: 'config', retriable: false }, meta)); }
+}
+export class ValidationError extends HarnessError {
+    constructor(message, meta) { super(message, errorOptions({ code: 'VALIDATION_ERROR', category: 'validation', retriable: false }, meta)); }
+}
+export class PermissionDeniedError extends HarnessError {
+    constructor(message, meta) { super(message, errorOptions({ code: 'PERMISSION_DENIED', category: 'permission', retriable: false }, meta)); }
+}
+export class SandboxError extends HarnessError {
+    constructor(message, meta) { super(message, errorOptions({ code: 'SANDBOX_ERROR', category: 'sandbox', retriable: false }, meta)); }
+}
+export class SandboxNoExecutorError extends HarnessError {
+    constructor() { super('Sandbox executor unavailable', { code: 'SANDBOX_NO_EXECUTOR', category: 'sandbox', retriable: false }); }
+}
+export class ModelError extends HarnessError {
+    constructor(message, meta) { super(message, errorOptions({ code: 'MODEL_ERROR', category: 'model', retriable: true }, meta)); }
+}
+export class ToolError extends HarnessError {
+    constructor(message, meta) { super(message, errorOptions({ code: 'TOOL_ERROR', category: 'tool', retriable: true }, meta)); }
+}
+export class ToolNotFoundError extends HarnessError {
+    constructor(tool) { super(`Tool not found: ${tool}`, { code: 'TOOL_NOT_FOUND', category: 'tool', retriable: false, meta: { tool } }); }
+}
+export class SkillManifestError extends HarnessError {
+    constructor(message, meta) { super(message, errorOptions({ code: 'SKILL_MANIFEST_ERROR', category: 'config', retriable: false }, meta)); }
+}
+export class AgentLoopBudgetError extends HarnessError {
+    constructor() { super('Agent maxSteps exceeded', { code: 'AGENT_LOOP_BUDGET', category: 'agent', retriable: false, meta: { reason: 'iterations_exceeded' } }); }
+}
+export class SessionBusyError extends HarnessError {
+    constructor(reason = 'run_in_flight') { super('Session is busy', { code: 'SESSION_BUSY', category: 'session', retriable: true, meta: { reason } }); }
+}
+export class OperationTimeoutError extends HarnessError {
+    constructor(scope) { super('Operation timed out', { code: 'OPERATION_TIMEOUT', category: 'harness', retriable: true, meta: { scope } }); }
+}
+export class OperationCancelledError extends HarnessError {
+    constructor(scope) { super('Operation cancelled', { code: 'OPERATION_CANCELLED', category: 'harness', retriable: false, meta: { scope } }); }
+}
+export class InternalError extends HarnessError {
+    constructor(message, meta) { super(message, errorOptions({ code: 'INTERNAL_ERROR', category: 'internal', retriable: false }, meta)); }
+}
+export function serializeError(error) {
+    if (error instanceof HarnessError) {
+        const serialized = { code: error.code, category: error.category, retriable: error.retriable, message: error.message };
+        return error.meta === undefined ? serialized : { ...serialized, meta: error.meta };
+    }
+    return { code: 'INTERNAL_ERROR', category: 'internal', retriable: false, message: error instanceof Error ? error.message : String(error) };
+}

package/dist/harness/types.d.ts

@@ -0,0 +1,27 @@
+export type JsonValue = null | boolean | number | string | JsonValue[] | {
+    [key: string]: JsonValue;
+};
+export interface ExecOptions {
+    cwd?: string;
+    env?: Record<string, string>;
+    stdin?: string;
+    timeoutMs?: number;
+    signal?: AbortSignal;
+}
+export interface ExecResult {
+    stdout: string;
+    stderr: string;
+    exitCode: number;
+    durationSeconds: number;
+}
+export interface DirEntry {
+    name: string;
+    path: string;
+    kind: 'file' | 'directory';
+    size?: number;
+}
+export interface FileStat {
+    kind: 'file' | 'directory';
+    size: number;
+    modifiedAt: string;
+}

package/dist/harness/types.js

@@ -0,0 +1 @@
+export {};

package/dist/index.d.ts

@@ -0,0 +1,14 @@
+export * from './errors/index.js';
+export * from './logger/index.js';
+export * from './telemetry/index.js';
+export * from './ulid/index.js';
+export * from './ports/index.js';
+export { createDurableWorkflowContext, DurableStepError, DurableRunLeaseError, DurableTerminalRunError, inMemoryDurableRuntime, isTerminalRunStatus } from './runtime/index.js';
+export type { DurableActiveRunStatus, DurableWorkflowContext, DurableRunLease, DurableRunStart, DurableRunStatus, DurableRuntime, DurableTerminalRunStatus, FinishRunPatch, InMemoryDurableRuntimeOptions, RunCheckpoint } from './runtime/index.js';
+export * from './state/in-memory.js';
+export * from './models/json.js';
+export type { SessionRecord, Message, RunRecord, PersistedRunEvent, RunStatus } from './models/state.js';
+export * from './models/registry.js';
+export * from './sandbox/index.js';
+export * from './tools/mcp/index.js';
+export * from './harness/defineHarness.js';

package/dist/index.js

@@ -0,0 +1,12 @@
+export * from './errors/index.js';
+export * from './logger/index.js';
+export * from './telemetry/index.js';
+export * from './ulid/index.js';
+export * from './ports/index.js';
+export { createDurableWorkflowContext, DurableStepError, DurableRunLeaseError, DurableTerminalRunError, inMemoryDurableRuntime, isTerminalRunStatus } from './runtime/index.js';
+export * from './state/in-memory.js';
+export * from './models/json.js';
+export * from './models/registry.js';
+export * from './sandbox/index.js';
+export * from './tools/mcp/index.js';
+export * from './harness/defineHarness.js';

package/dist/logger/index.d.ts

@@ -0,0 +1,2 @@
+export * from './logger.js';
+export * from './json-logger.js';

package/dist/logger/index.js

@@ -0,0 +1,2 @@
+export * from './logger.js';
+export * from './json-logger.js';

package/dist/logger/json-logger.d.ts

@@ -0,0 +1,31 @@
+import type { Logger, LogLevel } from './logger.js';
+/**
+ * Options for {@link JsonLogger}.
+ */
+export interface JsonLoggerOptions {
+    /** Minimum emitted level. Defaults to env `PURISTA_HARNESS_LOG_LEVEL` or `info`. */
+    level?: LogLevel;
+    /** Writable destination for newline-delimited JSON records. Defaults to `process.stdout`. */
+    out?: {
+        write(chunk: string): unknown;
+    };
+    /** Static bindings added to every emitted log record. */
+    bindings?: Record<string, unknown>;
+}
+/**
+ * Default structured logger emitting one JSON object per line.
+ */
+export declare class JsonLogger implements Logger {
+    private readonly minLevel;
+    private readonly out;
+    private readonly bindings;
+    constructor(opts?: JsonLoggerOptions);
+    trace(msg: string, fields?: Record<string, unknown>): void;
+    debug(msg: string, fields?: Record<string, unknown>): void;
+    info(msg: string, fields?: Record<string, unknown>): void;
+    warn(msg: string, fields?: Record<string, unknown>): void;
+    error(msg: string, fields?: Record<string, unknown>): void;
+    fatal(msg: string, fields?: Record<string, unknown>): void;
+    child(bindings: Record<string, unknown>): Logger;
+    private write;
+}

package/dist/logger/json-logger.js

@@ -0,0 +1,65 @@
+import { context, trace } from '@opentelemetry/api';
+import { sanitizeForLog } from '../errors/redaction.js';
+const ORDERED_LEVELS = ['trace', 'debug', 'info', 'warn', 'error', 'fatal'];
+const LEVEL_INDEX = new Map(ORDERED_LEVELS.map((level, index) => [level, index]));
+const ENV_NAME = 'PURISTA_HARNESS_LOG_LEVEL';
+function isLogLevel(value) {
+    return LEVEL_INDEX.has(value);
+}
+/**
+ * Default structured logger emitting one JSON object per line.
+ */
+export class JsonLogger {
+    minLevel;
+    out;
+    bindings;
+    constructor(opts = {}) {
+        this.out = opts.out ?? process.stdout;
+        this.bindings = { ...(opts.bindings ?? {}) };
+        if (opts.level) {
+            this.minLevel = opts.level;
+            return;
+        }
+        const envLevel = process.env[ENV_NAME];
+        if (envLevel && !isLogLevel(envLevel)) {
+            this.minLevel = 'info';
+            this.write('warn', `Invalid ${ENV_NAME} value. Falling back to info.`, { invalid_level: envLevel });
+            return;
+        }
+        this.minLevel = envLevel && isLogLevel(envLevel) ? envLevel : 'info';
+    }
+    trace(msg, fields) { this.write('trace', msg, fields); }
+    debug(msg, fields) { this.write('debug', msg, fields); }
+    info(msg, fields) { this.write('info', msg, fields); }
+    warn(msg, fields) { this.write('warn', msg, fields); }
+    error(msg, fields) { this.write('error', msg, fields); }
+    fatal(msg, fields) { this.write('fatal', msg, fields); }
+    child(bindings) {
+        return new JsonLogger({ level: this.minLevel, out: this.out, bindings: { ...this.bindings, ...bindings } });
+    }
+    write(level, msg, fields = {}) {
+        if ((LEVEL_INDEX.get(level) ?? 0) < (LEVEL_INDEX.get(this.minLevel) ?? 0)) {
+            return;
+        }
+        const activeContext = context.active();
+        const spanContext = trace.getSpan(activeContext)?.spanContext() ?? trace.getSpanContext(activeContext);
+        const sanitized = sanitizeForLog({ ...this.bindings, ...fields });
+        const safeFields = sanitized && typeof sanitized === 'object' && !Array.isArray(sanitized)
+            ? sanitized
+            : {};
+        const line = {
+            level,
+            time: new Date().toISOString(),
+            msg,
+            ...(spanContext?.traceId ? { trace_id: spanContext.traceId } : {}),
+            ...(spanContext?.spanId ? { span_id: spanContext.spanId } : {}),
+            ...safeFields
+        };
+        try {
+            this.out.write(`${JSON.stringify(line)}\n`);
+        }
+        catch {
+            // Logging must not affect harness execution.
+        }
+    }
+}

package/dist/logger/logger.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Supported structured log levels, ordered from most to least verbose.
+ */
+export type LogLevel = 
+/** Fine-grained diagnostic tracing. */
+'trace'
+/** Developer-oriented debugging details. */
+ | 'debug'
+/** Standard operational information. */
+ | 'info'
+/** Recoverable warnings requiring visibility. */
+ | 'warn'
+/** Errors that impacted a request/run. */
+ | 'error'
+/** Fatal errors that may terminate process health. */
+ | 'fatal';
+/**
+ * Logger contract used by the harness.
+ *
+ * All methods must be synchronous and non-throwing from the perspective of
+ * harness callers.
+ */
+export interface Logger {
+    trace(msg: string, fields?: Record<string, unknown>): void;
+    debug(msg: string, fields?: Record<string, unknown>): void;
+    info(msg: string, fields?: Record<string, unknown>): void;
+    warn(msg: string, fields?: Record<string, unknown>): void;
+    error(msg: string, fields?: Record<string, unknown>): void;
+    fatal(msg: string, fields?: Record<string, unknown>): void;
+    child(bindings: Record<string, unknown>): Logger;
+}

package/dist/logger/logger.js

@@ -0,0 +1 @@
+export {};

package/dist/models/json.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Canonical JSON value type used across harness ports and persistence models.
+ */
+export type JsonValue = null | boolean | number | string | JsonValue[] | {
+    [key: string]: JsonValue;
+};

package/dist/models/json.js

@@ -0,0 +1 @@
+export {};

package/dist/models/registry.d.ts

@@ -0,0 +1,112 @@
+import type { EmbeddingRequest, EmbeddingResponse, ContentPart, ModelAlias, ModelCapability, ModelToolSpec, ObjectRequest, ObjectResponse, ObjectStreamChunk, RerankRequest, RerankResponse, TextRequest, TextResponse, TextStreamChunk, ToolCallSpec } from '../ports/model-provider.js';
+import type { TelemetryShim } from '../telemetry/index.js';
+import type { JsonValue } from './json.js';
+export interface ModelInvokeContext {
+    harnessName: string;
+    sessionId: string;
+    runId: string;
+    workflowId?: string;
+    agentId?: string;
+}
+type TextPart = Extract<ContentPart, {
+    kind: 'text';
+}>;
+type VisionPart = Extract<ContentPart, {
+    kind: 'image' | 'image_url';
+}>;
+type AudioPart = Extract<ContentPart, {
+    kind: 'audio';
+}>;
+type FilePart = Extract<ContentPart, {
+    kind: 'file' | 'file_url';
+}>;
+type EmbeddingRequestInput = Omit<EmbeddingRequest, 'model' | 'signal'>;
+type RerankRequestInput = Omit<RerankRequest, 'model' | 'signal'>;
+type AliasCapabilities<A> = A extends {
+    capabilities: readonly (infer C)[];
+} ? C : never;
+type HasCapability<A, C extends ModelCapability> = C extends AliasCapabilities<A> ? true : false;
+type ContentPartFor<A> = TextPart | (HasCapability<A, 'vision_input'> extends true ? VisionPart : never) | (HasCapability<A, 'audio_input'> extends true ? AudioPart : never) | (HasCapability<A, 'file_input'> extends true ? FilePart : never);
+type ToolCallsFor<A> = HasCapability<A, 'tool_use'> extends true ? {
+    toolCalls?: ToolCallSpec[];
+} : {
+    toolCalls?: never;
+};
+type ToolInputFor<A> = HasCapability<A, 'tool_use'> extends true ? {
+    tools?: ModelToolSpec[] | undefined;
+} : {
+    tools?: never;
+};
+type ModelMessageFor<A> = {
+    role: 'system';
+    content: string;
+} | {
+    role: 'user';
+    content: string | ContentPartFor<A>[];
+} | ({
+    role: 'assistant';
+    content: string | ContentPartFor<A>[];
+} & ToolCallsFor<A>) | (HasCapability<A, 'tool_use'> extends true ? {
+    role: 'tool';
+    toolCallId: string;
+    content: string;
+} : never);
+type TextRequestInputFor<A> = Omit<TextRequest, 'model' | 'signal' | 'defaults' | 'messages' | 'tools'> & {
+    messages: ModelMessageFor<A>[];
+} & ToolInputFor<A>;
+type ObjectRequestInputFor<A, T extends JsonValue = JsonValue> = Omit<ObjectRequest<T>, 'model' | 'signal' | 'defaults' | 'messages' | 'tools'> & {
+    messages: ModelMessageFor<A>[];
+} & ToolInputFor<A>;
+type TextModelMethods<A> = {
+    /** Executes a single text generation request. */
+    text(req: TextRequestInputFor<A>, signal: AbortSignal, ctx?: ModelInvokeContext): Promise<TextResponse>;
+};
+type TextStreamModelMethods<A> = {
+    /** Executes a streaming text generation request. */
+    textStream(req: TextRequestInputFor<A>, signal: AbortSignal, ctx?: ModelInvokeContext): AsyncIterable<TextStreamChunk>;
+};
+type ObjectModelMethods<A> = {
+    /** Executes a single structured object generation request. */
+    object<T extends JsonValue = JsonValue>(req: ObjectRequestInputFor<A, T>, signal: AbortSignal, ctx?: ModelInvokeContext): Promise<ObjectResponse<T>>;
+};
+type ObjectStreamModelMethods<A> = {
+    /** Executes a streaming structured object generation request. */
+    objectStream<T extends JsonValue = JsonValue>(req: ObjectRequestInputFor<A, T>, signal: AbortSignal, ctx?: ModelInvokeContext): AsyncIterable<ObjectStreamChunk<T>>;
+};
+type EmbeddingModelMethods = {
+    /** Generates embeddings for one or more input strings. */
+    embed(req: EmbeddingRequestInput, signal: AbortSignal, ctx?: ModelInvokeContext): Promise<EmbeddingResponse>;
+};
+type RerankModelMethods = {
+    /** Reranks documents for a query. */
+    rerank(req: RerankRequestInput, signal: AbortSignal, ctx?: ModelInvokeContext): Promise<RerankResponse>;
+};
+/**
+ * Bound model handle produced by {@link createModelRegistry}.
+ *
+ * The visible methods are a type-level projection of the alias capability
+ * policy. For example, aliases without `'embeddings'` do not expose `embed`.
+ */
+export type ModelHandle<A extends {
+    capabilities: readonly ModelCapability[];
+} = {
+    capabilities: readonly ModelCapability[];
+}> = (HasCapability<A, 'text'> extends true ? TextModelMethods<A> : {}) & (HasCapability<A, 'text_stream'> extends true ? TextStreamModelMethods<A> : {}) & (HasCapability<A, 'object'> extends true ? ObjectModelMethods<A> : {}) & (HasCapability<A, 'object_stream'> extends true ? ObjectStreamModelMethods<A> : {}) & (HasCapability<A, 'embeddings'> extends true ? EmbeddingModelMethods : {}) & (HasCapability<A, 'rerank'> extends true ? RerankModelMethods : {});
+/**
+ * Creates per-alias model handles that enforce capability gates before provider invocation.
+ *
+ * @example
+ * ```ts
+ * const registry = createModelRegistry({
+ *   assistant: { provider, model: 'gpt-4.1-mini', capabilities: ['text'] }
+ * })
+ * const out = await registry.assistant.text({ messages: [{ role: 'user', content: 'hi' }] }, new AbortController().signal)
+ * ```
+ */
+export declare function createModelRegistry<const M extends Record<string, ModelAlias>>(aliases: M, options?: {
+    telemetry?: TelemetryShim;
+    harnessName?: string;
+}): {
+    readonly [K in keyof M]: ModelHandle<M[K]>;
+};
+export {};