@qvac/harness 1.0.0-rc.0 → 1.0.0-rc.2

package/dist-lib/index.d.ts

@@ -1,49 +1,54 @@
 import type { AbortSignal as BareAbortSignal } from 'bare-abort-controller';
 import ReadyResource from 'ready-resource';
-import type { EngineBoot, EngineStep, RecoveryResolution } from './lib/machine/index.ts';
-import { type Agent, type ApproveFn, type AskUserFn, type AttachFn, type CompletionEvent, type FetchAttachmentFn, type Message, type ProgressFn, type RagSearchFn, type ResponseFormat, type ToolDefinition, type ToolExecuteContext } from './lib/capabilities/completion.ts';
+import type { EngineBoot, EngineStep, RecoveryResolution } from './lib/run-log/index.ts';
+import type { AgentConfig, ApproveFn, AskUserFn, AttachFn, CompletionEvent, FetchAttachmentFn, Message, ProgressFn, ResponseFormat, RunGoal, RunInput, ToolDefinition, ToolExecuteContext } from './lib/contract/index.ts';
 import { type DetectLanguageContext, type DetectedLanguage } from './lib/capabilities/detect-language.ts';
 import { type Capability } from './lib/capabilities/invoke.ts';
 import { type ModelSourcePreview, type PreviewModelSourceContext } from './lib/capabilities/preview-model-source.ts';
 import { type EnhanceMode } from './lib/capabilities/enhance.ts';
 import { type DownloadArgs, type DownloadEventStream } from './lib/capabilities/download.ts';
-import { type EmbedContext } from './lib/capabilities/embed.ts';
+import type { EmbedContext } from './lib/capabilities/embed.ts';
 import { type KvCacheDeletionResult } from './lib/capabilities/kv-cache.ts';
 import type { LlmGenerationParams } from './lib/models/llm-presets.ts';
-import { type SpeakContext, type SpeakResult, type SpeakStreamContext, type TranscribeContext } from './lib/capabilities/voice.ts';
-import type { CapabilityInfo, CredentialEntry, HarnessDiagnostics, InfraModel, LoadModelResult, SkillsOptions, SkillWriteResult, UnloadModelContext, UnloadModelResult } from './lib/contract-types.ts';
+import type { SpeakContext, SpeakResult, SpeakStreamContext, TranscribeContext } from './lib/contract/speech.ts';
+import type { CapabilityInfo, CredentialEntry, HarnessDiagnostics, InfraModel, LoadModelResult, SkillWriteResult, UnloadModelContext, UnloadModelResult } from './lib/contract-types.ts';
 import { type CustomModelEntry } from './lib/models/model-catalog.ts';
 import { type ListModelsOptions, type ModelInfo } from './lib/models/model-list.ts';
 import { type DeleteModelSummary } from './lib/models/model-delete.ts';
-import { type EmbedDevice } from './lib/models/embed-config.ts';
+import { type LlamaLoadKnobs } from './lib/models/model-pool.ts';
+import type { EmbedDevice } from './lib/models/embed-config.ts';
 import { type SdkLoader } from './lib/sdk-loader.ts';
-import type { ImageClamps } from './lib/models/model-catalog.ts';
+import { type WarmModelOptions } from './lib/residency/index.ts';
 import { type ToolCatalogEntry } from './lib/tools/catalog.ts';
-import { type MusicClamps, type MusicModelStages } from './lib/tools/generate-music.ts';
+import { type HarnessSkillsOptions } from './lib/skills-host/index.ts';
 import type { CredentialStoreFn, CredentialStoreValue } from './lib/tools/skills/auth-resolver.ts';
-import { type CopyBaseResult, type DeleteOverlayResult, type ManagedSkill, type SkillFileContent } from './lib/tools/skills/overlay-crud.ts';
+import type { CopyBaseResult, DeleteOverlayResult, ManagedSkill, SkillFileContent } from './lib/tools/skills/overlay-crud.ts';
 import { type DriveOpFn, type GrantedDrive } from './lib/tools/fs/remote.ts';
 import type { ResolvedSkillCatalogEntry } from './lib/tools/skills/catalog.ts';
-import { type SkillSettingEntry } from './lib/tools/skills/skill-settings.ts';
-export * from './lib/capabilities/completion.ts';
+import type { SkillSettingEntry } from './lib/tools/skills/skill-settings.ts';
+export type * from './lib/contract/index.ts';
+export { CompletionEngine, type CompletionArgs, type CompletionEngineOptions, type CompletionRun } from './lib/capabilities/completion-engine/index.ts';
+export declare const CONTEXT_OVERFLOW_MESSAGE: string;
+export { imageSettingsFrom } from './lib/helpers/image-settings.ts';
+export { skillInContext, unreadySkillState, type CompletionSkillEntry } from './lib/capabilities/skill-entry.ts';
+export { toSdkTool } from './lib/capabilities/sdk-tool.ts';
 export { attachmentTurn, loadedSkillsFrom, skillLoadedTurn } from './lib/capabilities/tool-turns.ts';
 export { CAPABILITIES, isCapability, type Capability } from './lib/capabilities/invoke.ts';
 export type { EnhanceMode } from './lib/capabilities/enhance.ts';
-export { EURONANO_LANGUAGES, NMT_FROM_ENGLISH, NMT_TO_ENGLISH, SLM_LANGUAGE_CODES, SLM_LANGUAGE_NAMES, translationPlanFor, type TranslationPlan } from './lib/models/nmt-catalog.ts';
 export type { DetectLanguageContext, DetectedLanguage } from './lib/capabilities/detect-language.ts';
-export type { ModelFitVerdict, ModelSourceFile, ModelSourcePreview, ModelSourceRefusal, PreviewModelSourceContext } from './lib/capabilities/preview-model-source.ts';
+export type { ModelSourceFile, ModelSourcePreview, ModelSourceRefusal, PreviewModelSourceContext } from './lib/capabilities/preview-model-source.ts';
+export type { ModelFitBasis, ModelFitEvidence, ModelFitVerdict } from './lib/models/model-fit.ts';
 export * from './lib/capabilities/download.ts';
 export type { EmbedContext } from './lib/capabilities/embed.ts';
-export type { SpeakContext, SpeakResult, SpeakStreamContext, TranscribeContext } from './lib/capabilities/voice.ts';
+export type { SpeakContext, SpeakResult, SpeakStreamContext, SpeechService, TranscribeContext } from './lib/contract/speech.ts';
 export type { EmbedDevice } from './lib/models/embed-config.ts';
 export type { MemoryBudget } from './lib/hardware/memory-budget.ts';
 export * from './lib/models/model-catalog.ts';
 export * from './lib/models/model-list.ts';
 export type { ModelTaskType } from './lib/models/model-task.ts';
 export type { DeleteModelResult, DeleteModelSummary } from './lib/models/model-delete.ts';
-export type { RecoveryResolution, RecoveryOperation } from './lib/machine/index.ts';
-export { harnessChild, spawnHarness, type HarnessChildOptions, type SpawnHarnessOptions } from './lib/spawn.ts';
-export { settingsDimension, settingsSteps } from './lib/tools/generate-image.ts';
+export type { RecoveryResolution } from './lib/run-log/index.ts';
+export { harnessChild, spawnHarness, type HarnessChildOptions, type HarnessKnowledgeConfig, type HarnessMcpServer, type HarnessPluginOptions, type HarnessSpeechOptions, type SpawnHarnessOptions } from './lib/spawn.ts';
 export * from './lib/tools/skills/catalog.ts';
 export { requiredSettings, settingEnvName, type SkillSettingEntry, type SkillSettingsFn } from './lib/tools/skills/skill-settings.ts';
 export type { ToolCatalogEntry } from './lib/tools/catalog.ts';
@@ -56,40 +61,40 @@ export { isAvailableState, SKILL_STATE, type SkillState } from './lib/tools/skil
 export { connectHarness, HARNESS_DIED, RemoteHarness } from './lib/connect.ts';
 export type { ConnectOptions, HostRunLog, HostRunLogLease } from './lib/connect.ts';
 export type { KvCacheDeletionResult } from './lib/capabilities/kv-cache.ts';
-export type { AgentKnobs, ApprovalCall, ChatMessage, CredentialEntry, DownloadContext, HarnessContract, HarnessDiagnostics, HarnessEvent, HarnessInfo, HarnessStatus, InfraModel, ModelState, SkillsOptions, SkillWriteResult } from './lib/contract-types.ts';
+export type { AgentKnobs, ApprovalCall, ChatMessage, CredentialEntry, DownloadContext, HarnessContract, HarnessDiagnostics, HarnessEvent, HarnessInfo, HarnessStatus, InfraModel, LoadedModel, LoadFit, ModelState, SkillsOptions, SkillWriteResult } from './lib/contract-types.ts';
 import type { HarnessInfo } from './lib/contract-types.ts';
 export { serveHarness } from './lib/serve.ts';
 export { hlog, setHarnessLog, setHarnessLogSink } from './lib/log.ts';
-export { harnessHooks } from './lib/hooks/registry.ts';
-export { EgressGuardHook, SkillCatalogGuardHook } from './lib/hooks/built-in/index.ts';
-export type { ToolCallDisplay, ToolExecutionOutcome } from './lib/tool-call-display.ts';
-export type { HarnessHook, HookContext, HookResult } from './lib/hooks/types.ts';
-export interface ImageModelOptions {
-    model: string;
-    llmModel?: string;
-    vaeModel?: string;
-    prediction?: 'flux2_flow';
-}
-export interface MusicModelOptions extends MusicModelStages {
-    inferenceSteps?: number;
-    useGpu?: boolean;
-}
+import { HookPipeline } from './lib/hooks/index.ts';
+export { HookPipeline };
+import type { HarnessHook } from './lib/contract/index.ts';
+export type { HarnessHook, HookContext, HookResult } from './lib/contract/index.ts';
+import type { KnowledgeArtifact, KnowledgeGrant, KnowledgeHit, KnowledgeQuery, KnowledgeRemoved, KnowledgeStatus, KnowledgeUpsertResult } from './lib/contract/knowledge.ts';
+export type * from './lib/contract/knowledge.ts';
+export type { EmbedHost, EmbedRequest, VectorIndexSdk } from './lib/contract/models.ts';
+import { type HarnessPlugin } from './lib/plugins/index.ts';
+import { type ExecToolOptions } from './lib/tools/exec.ts';
+export declare const PLUGIN_API_VERSION = 1;
+export type { AddonLoaders } from './lib/contract/index.ts';
+export type { ExecLanguage, ExecRoute, ExecShell } from './lib/contract/exec.ts';
+export type { HarnessPlugin, PluginContext, PluginExec, PluginSetup, Services } from './lib/plugins/index.ts';
+export type HarnessExecOptions = Pick<ExecToolOptions, 'spawn' | 'killProcess' | 'realpath' | 'policyVersion'>;
 export interface HarnessOptions {
     tools?: ToolDefinition[];
     gpuStats?: unknown;
     sdkLoader?: SdkLoader;
     skillsDir?: string;
     modelsDir?: string;
+    sdkHome?: string;
+    exec?: boolean | HarnessExecOptions;
     projectionModel?: string | Record<string, string>;
-    imageModel?: string | ImageModelOptions;
-    imageClamps?: ImageClamps;
-    musicModel?: string | MusicModelOptions;
-    musicClamps?: MusicClamps;
     llmDevice?: 'cpu' | 'gpu';
     llmGpuLayers?: number;
     contextSize?: number;
     kvCacheK?: string;
     kvCacheV?: string;
+    llmLoad?: LlamaLoadKnobs;
+    slots?: number;
     embedDevice?: EmbedDevice;
     embedGpuLayers?: number;
     embedBatchSize?: number;
@@ -97,13 +102,31 @@ export interface HarnessOptions {
     credentialStore?: CredentialStoreFn;
     platform?: string;
     completionModelCap?: number;
+    hooks?: readonly HarnessHook[];
+    plugins?: readonly HarnessPlugin[];
+    pluginMode?: 'frozen' | 'dynamic';
 }
 export interface CompletionContext {
     runId?: string;
+    parentRunId?: string;
+    tools?: ToolDefinition[];
+    now?: () => number;
+    maxToolRounds?: number;
+    knowledge?: KnowledgeGrant;
+    planMode?: boolean;
+    goal?: RunGoal;
+    wording?: {
+        toolContinuation?: string;
+        fileDelivered?: string;
+        toolDenied?: string;
+        toolCutOff?: string;
+        goalContinuation?: string;
+    };
     resume?: boolean;
     recovery?: RecoveryResolution[];
     model: string;
-    agent?: Agent;
+    agent?: AgentConfig;
+    agents?: Record<string, AgentConfig>;
     messages: Message[];
     cacheKey?: string;
     thinkingDefault?: string;
@@ -118,7 +141,6 @@ export interface CompletionContext {
     approve?: ApproveFn;
     attach?: AttachFn;
     fetchAttachment?: FetchAttachmentFn;
-    ragSearch?: RagSearchFn;
     progress?: ProgressFn;
     askUser?: AskUserFn;
     boot?: EngineBoot;
@@ -126,6 +148,7 @@ export interface CompletionContext {
     hostAppendTimeoutMs?: number;
     requestDigestKey?: Uint8Array;
     signal?: BareAbortSignal;
+    input?: AsyncIterable<RunInput>;
 }
 export type ResumeCompletionContext = Omit<Partial<CompletionContext>, 'runId' | 'resume'> & {
     runId: string;
@@ -135,107 +158,69 @@ export interface InvokeContext {
     capability: Capability;
     args: Record<string, unknown>;
     enhance?: EnhanceMode;
-    agent?: Agent;
+    agent?: AgentConfig;
     attach?: AttachFn;
     fetchAttachment?: FetchAttachmentFn;
     progress?: ProgressFn;
     signal?: BareAbortSignal;
 }
-export interface HarnessSkillsOptions extends SkillsOptions {
-    readonly skipBinProbe?: boolean;
-}
-export interface WarmModelOptions {
-    model: string;
-    agent?: Agent;
-    signal?: BareAbortSignal;
-}
+export type { HarnessSkillsOptions } from './lib/skills-host/index.ts';
+export type { WarmModelOptions } from './lib/residency/index.ts';
 export declare class Harness extends ReadyResource {
+    private readonly _hostTools;
     private _tools;
+    private _capabilities;
     private _sdk;
     private readonly _loads;
-    private readonly _pinned;
-    private readonly _replying;
-    private readonly _modelStatus;
-    private _models;
-    private _embedModels;
-    private readonly _retiredEmbedModels;
-    private readonly _faultedEmbedKeys;
-    private _embedLane;
-    private _embedFaults;
-    private readonly _embedGpuLayers?;
-    private readonly _embedBatchSize;
-    private _embedControl;
-    private _ttsModels;
-    private _transcriptionModels;
-    private _voiceLane;
+    private readonly _residency;
+    private readonly _embeddings;
+    private readonly _voicePools;
+    private readonly _skills;
     private readonly _lifecycle;
-    private readonly _detachedRuns;
-    private readonly _effectDrainWaiters;
-    private _activeWork;
-    private readonly _workDrainWaiters;
-    private _runtimeDraining;
-    private _runtimeUnloadFailed;
-    private _poolUnloadFailed;
-    private _poolCleanupFailed;
-    private readonly _failedModelUnloads;
-    private _sdkClosed;
-    private _runtimesReleased;
     private _closeRetryNeeded;
-    private _closeRequested;
-    private _skillsDir?;
     private readonly _modelsDir?;
-    private _overlayWatcher;
-    private _supportedSkills;
+    private readonly _skillsDir?;
+    private readonly _exec;
+    private readonly _deniedRoots;
     private _projectionModel;
     private _customProjection;
-    private readonly _llmDevice?;
-    private readonly _llmGpuLayers?;
-    private readonly _contextSize?;
-    private readonly _kvCacheK?;
-    private readonly _kvCacheV?;
-    private readonly _transcriptionDevice?;
     private readonly _gpuStats?;
-    private readonly _completionModelCap;
-    private _allSkills;
-    private _credentialStore?;
-    private _credentials;
-    private _settings;
-    private _platform?;
-    private _diffusionSdk;
-    private _imageRuntime;
-    private _musicSdk;
-    private _translationSdk;
-    private _musicRuntime;
-    private readonly _completionRuns;
-    private _translationRuntime;
-    private _capabilityTools;
     private _capability;
     private _capabilityInflight;
-    private readonly _modelFaults;
-    private readonly _idle;
-    constructor({ tools, sdkLoader, skillsDir, modelsDir, projectionModel, imageModel, imageClamps, musicModel, musicClamps, llmDevice, llmGpuLayers, contextSize, kvCacheK, kvCacheV, embedDevice, embedGpuLayers, embedBatchSize, transcriptionDevice, completionModelCap, credentialStore, platform, gpuStats }?: HarnessOptions);
+    private readonly _hostHooks;
+    private _hooks;
+    private readonly _plugins;
+    private readonly _pluginMode;
+    private _pluginsStarted;
+    constructor({ tools, sdkLoader, skillsDir, modelsDir, sdkHome, exec, projectionModel, llmDevice, llmGpuLayers, contextSize, kvCacheK, kvCacheV, llmLoad, slots, embedDevice, embedGpuLayers, embedBatchSize, transcriptionDevice, completionModelCap, credentialStore, platform, gpuStats, hooks, plugins, pluginMode }?: HarnessOptions);
     _open(): Promise<void>;
+    private _startPlugins;
+    private _runPluginStart;
+    private _publishPlugins;
+    private _execTools;
+    addPlugin(plugin: HarnessPlugin): Promise<void>;
+    removePlugin(name: string): Promise<void>;
+    reloadPlugin(name: string, plugin: HarnessPlugin): Promise<void>;
+    private _dynamicPlugins;
+    private _modelHost;
+    private _registerPool;
+    private _createVoicePool;
+    private _embedHost;
+    private _loadAddons;
+    private _teardownPlugins;
     get suspended(): boolean;
     get skillNames(): string[];
     setCredentials(entries: ReadonlyArray<CredentialEntry>): void;
     setSkillSettings(entries: ReadonlyArray<SkillSettingEntry>): void;
     skillSettings(skill: string, agentId?: string | null): Record<string, string>;
-    private _baseSkillsDir;
     listManagedSkills(): Promise<ManagedSkill[]>;
     readSkillFile(name: string): Promise<SkillFileContent | null>;
     writeSkillFile(name: string, content: string): Promise<SkillWriteResult>;
     copyBaseForEdit(name: string): Promise<CopyBaseResult>;
     deleteOverlaySkill(name: string): Promise<DeleteOverlayResult>;
     resolveCredential(key: string, ctx?: ToolExecuteContext): Promise<CredentialStoreValue> | CredentialStoreValue;
-    private _completionSkills;
     skills(agentId?: string | null, modelName?: string | null, options?: HarnessSkillsOptions): Promise<ResolvedSkillCatalogEntry[]>;
-    private _reloadSkills;
-    private _startOverlayWatch;
     tools(): Promise<ToolCatalogEntry[]>;
-    private _binVersionCache;
-    private _binVersionInflight;
-    private _probeBinVersions;
-    private _runBinVersionProbes;
     get toolNames(): string[];
     get supportsImages(): boolean;
     supportsImagesFor(model: string): boolean;
@@ -243,65 +228,26 @@ export declare class Harness extends ReadyResource {
     setCustomModels(entries: ReadonlyArray<CustomModelEntry>): void;
     setModelIdleTimeout(ms: number): void;
     previewModelSource(context: PreviewModelSourceContext): Promise<ModelSourcePreview>;
-    private _assessFit;
     describe(): Promise<HarnessInfo>;
     diagnostics(): HarnessDiagnostics;
-    private _loadedModels;
-    private _loadingModels;
-    private _settledModels;
-    private _pools;
-    private _loadPluginSdk;
-    private _loadDiffusionSdk;
-    private _slmTranslate;
-    private _loadTranslationSdk;
-    private _loadMusicSdk;
-    private _deviceConfig;
-    private _createPool;
-    private _loadModelLifecycleSdk;
-    private _createEmbedPool;
-    private _createTtsPool;
-    private _createTranscriptionPool;
-    private _recordModelUnloadFailure;
-    private _notifyModel;
-    private _collectRetiredEmbedPool;
-    private _releaseEmbedResource;
-    private _releaseEmbedResourceBeforeWork;
-    private _markEmbedFault;
-    private _releaseEmbedResourceAfter;
-    private _destroyEmbedPools;
-    private _enqueueEmbedControl;
-    private _runLifecycle;
-    private _abortCompletions;
-    private _assertNotClosing;
-    private _enterWork;
-    private _waitForWorkDrain;
-    private _effectsSettled;
-    private _notifyEffectDrain;
-    private _waitForEffectDrain;
-    private _trackDetachedRun;
-    private _closeCompletions;
     getEmbeddingDevice(): EmbedDevice;
     setEmbeddingDevice(device: EmbedDevice): Promise<void>;
-    private _setEmbeddingDevice;
     presuspend(): Promise<void>;
     suspend(): Promise<void>;
-    private _suspendRuntimes;
-    private _sdkLifecycle;
-    private _releaseRuntimes;
-    private _unloadIdleModels;
     resume(): Promise<void>;
-    private _resumeRuntimes;
     wakeup(): Promise<void>;
     ready(): Promise<void>;
     _close(): Promise<void>;
     close(): Promise<void>;
     private _closeWhileOpening;
-    private _finishClose;
     download(args: DownloadArgs): DownloadEventStream;
     embed(context: EmbedContext): Promise<number[][]>;
-    private _embed;
-    private _defaultVoiceSrc;
-    private _voiceJob;
+    private _speechService;
+    private _knowledgeService;
+    knowledgeUpsert(artifact: KnowledgeArtifact): Promise<KnowledgeUpsertResult>;
+    knowledgeRemove(artifactId: string): Promise<KnowledgeRemoved>;
+    knowledgeSearch(query: KnowledgeQuery): Promise<KnowledgeHit[]>;
+    knowledgeStatus(): Promise<KnowledgeStatus>;
     transcribe(context: TranscribeContext): Promise<string>;
     private _transcribe;
     detectLanguage(context: DetectLanguageContext): DetectedLanguage[];
@@ -309,6 +255,7 @@ export declare class Harness extends ReadyResource {
     private _speak;
     speakStream(context: SpeakStreamContext): AsyncIterable<SpeakResult>;
     private _speakStream;
+    private _defaultTts;
     list(options?: ListModelsOptions): Promise<ModelInfo[]>;
     deleteModel(name: string): Promise<DeleteModelSummary>;
     clearKvCache(): Promise<KvCacheDeletionResult>;
@@ -316,28 +263,13 @@ export declare class Harness extends ReadyResource {
     infraModels(profile: string): Promise<InfraModel[]>;
     capability(): Promise<CapabilityInfo>;
     warmModel(context: WarmModelOptions): Promise<void>;
-    private _warmModel;
     loadModel(context: WarmModelOptions): Promise<LoadModelResult>;
-    private _loadModel;
     unloadModel(context: UnloadModelContext): Promise<UnloadModelResult>;
-    private _unloadModel;
-    private _loadAndRelease;
-    private _unloadIdleGenerators;
-    private _fits;
-    private _yieldPins;
-    private _residency;
-    private _completionLoadOptions;
-    private _acquireModelLease;
     invoke(context: InvokeContext): AsyncGenerator<CompletionEvent>;
     private _invoke;
     completion(context: CompletionContext | ResumeCompletionContext): AsyncGenerator<CompletionEvent>;
+    private _completion;
     private _runCompletion;
     private _completionFailed;
-    private _completionRuntime;
     private _residentEnhancer;
-    private _makeRoomForCompletion;
-    private _evictWedgedModel;
-    private _evictAfterLeases;
-    private _busy;
-    private _busyStream;
 }