omnius 1.0.922 → 1.0.924

package/dist/{providerRegistry.d.ts → _types/backend-vllm/providerRegistry.d.ts}

@@ -83,4 +83,3 @@ export interface ProviderHeaderOptions {
 /** Build provider-correct authentication and client headers. */
 export declare function buildProviderHeaders(provider: ProviderDescriptor | ResolvedProviderTransport, options?: ProviderHeaderOptions): Record<string, string>;
 export declare function providerUrl(provider: ResolvedProviderTransport, kind: ProviderPathKind): string;
-//# sourceMappingURL=providerRegistry.d.ts.map

package/dist/_types/backend-vllm/types.d.ts

@@ -0,0 +1,209 @@
+/**
+ * Backend-specific types for the vLLM backend implementation.
+ * Extends / augments the shared @omnius/schemas types.
+ */
+import type { AgentMessage } from "../schemas/messages.js";
+/**
+ * Backend-specific types for the vLLM backend implementation.
+ * Extends / augments the shared @omnius/schemas types.
+ */
+import type { ToolCall } from "../schemas/tools.js";
+import type { ProviderProtocol } from "./providerRegistry.js";
+export interface VllmBackendConfig {
+    /** Provider endpoint URL. Known providers are detected from this URL. */
+    baseUrl: string;
+    /** Model name as registered in vLLM */
+    model: string;
+    /** Optional Bearer token for authenticated deployments */
+    apiKey?: string;
+    /** Request timeout in milliseconds (default: 60_000) */
+    timeoutMs?: number;
+    /** Maximum retries on transient network errors (default: 3) */
+    maxRetries?: number;
+    /** Stable provider id or alias, for example gemini, anthropic, or openai. */
+    providerId?: string;
+    /**
+     * Required for unknown/custom endpoints. Known providers may omit it, but a
+     * supplied value must agree with the registry.
+     */
+    protocol?: ProviderProtocol;
+    /** Deterministic migration hint for pre-protocol saved configurations. */
+    legacyBackendType?: string;
+    /** Omnius client version inserted into provider-specific telemetry headers. */
+    clientVersion?: string;
+}
+/** Kept for backwards-compat with the existing test that imports VllmClient */
+export interface VllmConfig {
+    baseUrl: string;
+    apiKey?: string;
+    model: string;
+    maxTokens?: number;
+    temperature?: number;
+    timeout?: number;
+    providerId?: string;
+    protocol?: ProviderProtocol;
+    legacyBackendType?: string;
+    clientVersion?: string;
+}
+export interface ChatMessage {
+    role: "system" | "user" | "assistant" | "tool";
+    content: string | null;
+    /** Tool call id when role === "tool" */
+    tool_call_id?: string;
+    /** Only present when role === "assistant" and the model requested tool calls */
+    tool_calls?: WireToolCall[];
+    name?: string;
+}
+export interface WireToolCall {
+    id: string;
+    type: "function";
+    function: {
+        name: string;
+        /** JSON-serialised arguments */
+        arguments: string;
+    };
+}
+export interface ToolDefinition {
+    type: "function";
+    function: {
+        name: string;
+        description?: string;
+        parameters: Record<string, unknown>;
+    };
+}
+export interface ResponseFormat {
+    type: "json_schema";
+    json_schema: {
+        name: string;
+        strict?: boolean;
+        schema: Record<string, unknown>;
+    };
+}
+export interface ChatCompletionRequest {
+    model: string;
+    messages: ChatMessage[];
+    temperature?: number;
+    max_tokens?: number;
+    tools?: ToolDefinition[];
+    tool_choice?: "auto" | "none" | "required" | {
+        type: "function";
+        function: {
+            name: string;
+        };
+    };
+    response_format?: ResponseFormat;
+}
+export interface ChatCompletionChoice {
+    index: number;
+    message: ChatMessage;
+    finish_reason: "stop" | "tool_calls" | "length" | "content_filter" | null;
+}
+export interface UsageStats {
+    prompt_tokens: number;
+    completion_tokens: number;
+    total_tokens: number;
+    cache_creation_input_tokens?: number;
+    cache_read_input_tokens?: number;
+    prompt_eval_count?: number;
+}
+export interface ChatCompletionResponse {
+    id: string;
+    object: "chat.completion";
+    created: number;
+    model: string;
+    choices: ChatCompletionChoice[];
+    usage: UsageStats;
+}
+export interface CompletionRequest {
+    messages: AgentMessage[];
+    tools?: ToolDefinition[];
+    responseFormat?: ResponseFormat;
+    temperature?: number;
+    maxTokens?: number;
+    /**
+     * Routing hint: prefix hash computed from the conversation prefix.
+     * Used by the router for APC (Automatic Prefix Caching) optimisation.
+     */
+    prefixHash?: string;
+    /**
+     * Optional stable memory prefix produced by a memory prefill adapter.
+     * Backends without raw KV injection may still benefit from identical
+     * prefixes through their native prompt-prefix cache.
+     */
+    memoryPrefix?: string;
+    /**
+     * Weighted memory prefill references. These require backend-specific raw
+     * KV/prefill support; OpenAI-compatible HTTP backends generally ignore them.
+     */
+    weightedMemoryPrefill?: Array<{
+        itemId: string;
+        chunkId: string;
+        weight: number;
+    }>;
+}
+export interface CompletionResult {
+    /** Full text response when no tool calls were made */
+    content: string | null;
+    /** Tool calls requested by the model */
+    toolCalls: ToolCall[];
+    /** Whether the model's output was cut short due to max_tokens */
+    truncated: boolean;
+    usage: UsageStats;
+    /** Wall-clock milliseconds elapsed for the request */
+    latencyMs: number;
+}
+export interface LLMBackend {
+    /** Returns true when the backend is reachable and the model is loaded */
+    healthCheck(): Promise<boolean>;
+    /** Perform a chat completion */
+    complete(request: CompletionRequest): Promise<CompletionResult>;
+    /** Report backend memory prefill support, if implemented. */
+    memoryPrefillCapabilities?(): BackendMemoryPrefillCapability;
+    /** Put the backend into sleep / low-power mode */
+    sleep(): Promise<void>;
+    /** Wake the backend from sleep mode */
+    wake(): Promise<void>;
+}
+export interface BackendMemoryPrefillCapability {
+    backend: string;
+    supportsRawKvPrefill: boolean;
+    supportsPrefixCache: boolean;
+    supportsWeightedPrefill: boolean;
+    strategy: "raw_kv" | "prefix_cache" | "prompt_text" | "none";
+    reason?: string;
+}
+export interface MetricsSnapshot {
+    /** Running GPU KV-cache utilisation in the range [0, 1] */
+    gpuCacheUsage: number;
+    /** Number of requests currently waiting in the scheduler queue */
+    numWaitingRequests: number;
+    /** Number of requests currently being processed */
+    numRunningRequests: number;
+    /** Total requests fulfilled since the server started */
+    totalRequestsCompleted: number;
+    /** Raw Prometheus text (unparsed) */
+    rawPrometheus: string;
+}
+export interface RoutingDecision {
+    /** Selected replica base URL */
+    targetUrl: string;
+    /** The prefix hash used for the routing decision */
+    prefixHash: string;
+    /** All candidate URLs that were considered */
+    candidates: string[];
+}
+export interface CompletionResponse {
+    id: string;
+    content: string;
+    toolCalls?: Array<{
+        id: string;
+        name: string;
+        arguments: string;
+    }>;
+    usage: {
+        promptTokens: number;
+        completionTokens: number;
+        totalTokens: number;
+    };
+    finishReason: "stop" | "tool_calls" | "length" | "error";
+}

package/dist/_types/execution/av/media-capability.d.ts

@@ -0,0 +1,94 @@
+/**
+ * media-capability.ts — single hardware-capability probe that selects the AV
+ * model stack (edge | baseline | forensic, spec §6) and per-adapter device +
+ * precision hints (spec §22), so the entity-comprehension system autodetects
+ * what it can run instead of hard-coding a deployment.
+ *
+ * This generalizes the existing per-tool video-scan tier ladder
+ * (`~/.omnius/video-scan.json`, tiers extended|standard|reduced|forced_cpu)
+ * into ONE selector shared by every AV adapter. Result is cached to
+ * `~/.omnius/av-capability.json` (capability metadata stays in the omnius home,
+ * NOT the relocatable media store) and re-probed when stale.
+ */
+export type AVStack = "edge" | "baseline" | "forensic";
+export type AVDevice = "cuda" | "cpu";
+export type AVPrecision = "bf16" | "fp16" | "fp32";
+export interface GpuInfo {
+    name: string;
+    memTotalMiB: number;
+    memFreeMiB: number;
+    index: number;
+    /** Compute capability like "8.0" (A100) or "6.1" (GT 1030); "" if unknown. */
+    computeCap?: string;
+}
+/** Whether a GPU's compute capability is usable by the modern torch build. */
+export declare function gpuComputeUsable(computeCap?: string): boolean;
+export interface MediaCapability {
+    /** Selected model stack per spec §6. */
+    stack: AVStack;
+    /** Primary accelerator. */
+    accelerator: AVDevice;
+    /** Default precision for heavy adapters on the primary accelerator. */
+    precision: AVPrecision;
+    /** Largest single-GPU VRAM in GiB (0 when CPU-only). */
+    vramGiB: number;
+    /** Count of usable CUDA GPUs (>= ~8 GiB). */
+    gpuCount: number;
+    /** All detected GPUs (including small/unusable ones). */
+    gpus: GpuInfo[];
+    /** Logical CPU cores. */
+    cpuCores: number;
+    /** Total system RAM in GiB. */
+    ramGiB: number;
+    /** Free disk (GiB) on the omnius home volume. */
+    diskFreeGiB: number;
+    /** ffmpeg available on PATH (required for ingest). */
+    hasFfmpeg: boolean;
+    /** Auto-selected CUDA_VISIBLE_DEVICES — only torch-compatible, ≥8 GiB GPUs
+     *  (excludes pre-Volta cards like a GT 1030 that hang CUDA init). "" = CPU. */
+    cudaVisibleDevices: string;
+    /** Human-readable reason for the stack choice. */
+    reason: string;
+    /** ISO timestamp the probe ran. */
+    probedAt: string;
+}
+/** Probe NVIDIA GPUs via nvidia-smi; returns [] when unavailable. */
+export declare function probeGpus(): GpuInfo[];
+/**
+ * Select the stack + precision from raw hardware facts. Pure (no I/O) so it is
+ * directly unit-testable with synthetic hardware.
+ *
+ * §6 mapping:
+ *  - forensic : multi-GPU (>=2 usable) OR a single >=48 GiB GPU — multi-pass,
+ *               thinking-variant LALM, high-res reinspection.
+ *  - baseline : one usable GPU (>= ~16 GiB) — V-JEPA2-L/VideoPrism, YOLOE+SAM2,
+ *               event-triggered 7B VLM/LALM.
+ *  - edge     : small/no GPU — keyframe detectors, lite encoders, CPU fallbacks.
+ */
+export declare function selectStack(facts: {
+    gpus: GpuInfo[];
+    cpuCores: number;
+    ramGiB: number;
+}): {
+    stack: AVStack;
+    accelerator: AVDevice;
+    precision: AVPrecision;
+    vramGiB: number;
+    gpuCount: number;
+    cudaVisibleDevices: string;
+    reason: string;
+};
+/** Per-adapter device/precision hints derived from the capability (spec §22). */
+export interface AdapterPlacement {
+    device: AVDevice;
+    precision: AVPrecision;
+    /** Whether the adapter should only run on event windows (cost control). */
+    eventTriggered: boolean;
+}
+export declare function adapterPlacement(cap: MediaCapability, role: "video_temporal" | "grounding" | "tracking" | "audio_event" | "audio_lalm" | "video_llm" | "cross_modal" | "asr"): AdapterPlacement;
+/** Full hardware probe (does I/O). */
+export declare function probeCapability(): MediaCapability;
+/** Probe with a cached result (re-probes when older than the TTL or forced). */
+export declare function getMediaCapability(opts?: {
+    force?: boolean;
+}): MediaCapability;

package/dist/_types/execution/delegation-contract.d.ts

@@ -0,0 +1,102 @@
+/**
+ * delegation-contract.ts — evidence-bound request and outcome envelopes.
+ *
+ * Delegation is a semantic boundary, not merely a fresh context window. These
+ * compact contracts preserve the parent question, the observations that made
+ * the work necessary, and the proof the parent needs back. They are deliberately
+ * dependency-free so every spawn surface (in-process, subprocess, explorer,
+ * planner, and handoff) can use the same wire shape without a package cycle.
+ */
+export type DelegationKind = "subagent" | "exploration" | "plan" | "decomposition" | "feature" | "recovery" | "handoff";
+export type EvidenceFreshness = "fresh" | "stale" | "unknown";
+export interface DelegationEvidence {
+    /** Stable label the generator may cite; never an instruction channel. */
+    ref: string;
+    detail: string;
+    freshness?: EvidenceFreshness;
+}
+/**
+ * A concrete, parent-owned todo/workboard leaf. This is intentionally a data
+ * capsule rather than a transcript: a worker receives the current bounded
+ * contract, while the parent retains authority to accept its result.
+ */
+export interface DelegationWorkItem {
+    cardId: string;
+    title: string;
+    taskEpoch?: number;
+    todoIds?: string[];
+    ownedFiles?: string[];
+    verifierCommand?: string;
+    evidenceRequirements?: string[];
+    expectedArtifacts?: string[];
+}
+export interface DelegationBrief {
+    schemaVersion: 1;
+    kind: DelegationKind;
+    /** The exact question or bounded work the child must answer. */
+    request: string;
+    /** Why this child is needed at this point in the parent trajectory. */
+    whyNow: string;
+    /** Bounded observations supporting the request. */
+    evidence: DelegationEvidence[];
+    /** What territory is owned and what is explicitly out of scope. */
+    scope: string;
+    /** The evidence-bearing result shape the child must return. */
+    returnContract: string;
+    /** The decision/action this result should unlock for the parent. */
+    parentUnblock: string;
+    /** Present only for a uniquely identified active todo/workboard leaf. */
+    workItem?: DelegationWorkItem;
+    /** Optional original child task, retained as reference rather than the brief's thesis. */
+    originalTask?: string;
+    /** True only when a bounded tool-less grounding pass refined this brief. */
+    groundingSource: "model" | "deterministic";
+    groundingEvidenceRefs: string[];
+}
+export interface DelegationBriefInput {
+    kind: DelegationKind;
+    task: string;
+    currentIntent?: string;
+    whyNow?: string;
+    scope?: string;
+    returnContract?: string;
+    parentUnblock?: string;
+    evidence?: DelegationEvidence[];
+    workItem?: DelegationWorkItem;
+}
+export interface GeneratedDelegationBrief {
+    request: string;
+    whyNow?: string;
+    scope?: string;
+    returnContract?: string;
+    parentUnblock?: string;
+    evidenceRefs: string[];
+}
+export interface DelegationOutcome {
+    schemaVersion: 1;
+    status: "completed" | "partial" | "blocked" | "failed" | "unknown";
+    summary: string;
+    evidence: string[];
+    files: string[];
+    verification: string[];
+    blockers: string[];
+    recommendedNextAction: string;
+    confidence: "high" | "medium" | "low";
+    acceptedFindingIds: string[];
+    receiptIds: string[];
+    source: "declared" | "derived";
+}
+export declare function sanitizeDelegationText(value: unknown, max?: number): string;
+export declare function buildDelegationBrief(input: DelegationBriefInput): DelegationBrief;
+/** Render the model-facing child request. Safe to include inside another prompt. */
+export declare function renderDelegationBrief(brief: DelegationBrief, maxChars?: number): string;
+/** Prompt for the optional bounded model pass that refines a deterministic brief. */
+export declare function buildDelegationBriefGroundingPrompt(brief: DelegationBrief): string;
+/** Parse a bounded model refinement. Null is a safe deterministic fallback. */
+export declare function parseGeneratedDelegationBrief(raw: unknown, fallback: DelegationBrief): GeneratedDelegationBrief | null;
+export declare function mergeGeneratedDelegationBrief(fallback: DelegationBrief, generated: GeneratedDelegationBrief | null | undefined): DelegationBrief;
+/** Instruction appended to every worker's fold-back contract. */
+export declare function delegationOutcomeInstruction(): string;
+/** Parse a worker's declared outcome, falling back to a conservative evidence extract. */
+export declare function parseDelegationOutcome(raw: unknown): DelegationOutcome;
+export declare function renderDelegationOutcome(outcome: DelegationOutcome, maxChars?: number): string;

package/dist/_types/execution/evidence.d.ts

@@ -0,0 +1,68 @@
+export type EvidenceSurface = "browser" | "desktop" | "filesystem" | "shell" | "network" | "memory";
+export type EvidenceVerificationStatus = "proven" | "unchanged" | "contradicted" | "inconclusive" | "blocked";
+export interface EvidenceObservation {
+    capturedAtIso: string;
+    screenshotPath?: string;
+    screenshotHash?: string;
+    width?: number;
+    height?: number;
+    url?: string;
+    title?: string;
+    domSummaryHash?: string;
+    readableTextHash?: string;
+    visibleTextExcerpt?: string;
+    consoleErrorCount?: number;
+    pageErrorCount?: number;
+    networkFailureCount?: number;
+    gateKind?: string;
+    gateConfidence?: number;
+    gateEvidence?: string[];
+    metadata?: Record<string, unknown>;
+}
+export interface EvidenceDelta {
+    screenshotChanged?: boolean;
+    urlChanged?: boolean;
+    titleChanged?: boolean;
+    domChanged?: boolean;
+    textChanged?: boolean;
+    newVisibleText?: string;
+    removedVisibleText?: string;
+    errorDelta?: number;
+    metadata?: Record<string, unknown>;
+}
+export interface EvidenceVerification {
+    status: EvidenceVerificationStatus;
+    confidence: number;
+    reason: string;
+    nextSuggestedObservation?: string;
+}
+export interface EvidenceEvent {
+    schemaVersion: 1;
+    id: string;
+    sessionId?: string;
+    createdAtIso: string;
+    monotonicMs?: number;
+    tool: string;
+    action: string;
+    surface: EvidenceSurface;
+    target?: string;
+    claim?: string;
+    before?: EvidenceObservation;
+    after?: EvidenceObservation;
+    delta?: EvidenceDelta;
+    verification?: EvidenceVerification;
+    staleAfterTurn?: number;
+    staleAfterActionCount?: number;
+    metadata?: Record<string, unknown>;
+}
+export declare function sha256Text(text: string): string;
+export declare function sha256Buffer(buffer: Buffer): string;
+export declare function sha256FileIfExists(path: string | undefined): string | undefined;
+export declare function clipEvidenceText(text: unknown, maxChars?: number): string | undefined;
+export declare function createEvidenceObservation(input: Omit<EvidenceObservation, "capturedAtIso"> & {
+    capturedAtIso?: string;
+}): EvidenceObservation;
+export declare function createEvidenceEvent(input: Omit<EvidenceEvent, "schemaVersion" | "id" | "createdAtIso"> & {
+    id?: string;
+    createdAtIso?: string;
+}): EvidenceEvent;

package/dist/_types/execution/html-source-evidence.d.ts

@@ -0,0 +1,65 @@
+/** UTF-16 source offsets, zero-based and end-exclusive, in the complete HTML. */
+export interface HtmlSourceRange {
+    charStart: number;
+    charEndExclusive: number;
+}
+/** Decoded/whitespace-normalized HTML text; the range locates its containing source. */
+export interface HtmlSourceText {
+    text: string;
+    sourceRange?: HtmlSourceRange;
+    partial: boolean;
+}
+export interface HtmlSourceImage {
+    id: string;
+    relationship: "figure" | "inline_image" | "page_representative" | "linked_image" | "structured_image";
+    urls: ReadonlyArray<{
+        url: string;
+        attribute: string;
+        sourceRange?: HtmlSourceRange;
+    }>;
+    omittedUrls?: number;
+    sourceRange?: HtmlSourceRange;
+    caption?: HtmlSourceText;
+    alt?: HtmlSourceText;
+    credits: ReadonlyArray<HtmlSourceText>;
+    /** Explicit image/figure fields only, never inherited from page publication dates. */
+    imageDates: ReadonlyArray<{
+        property: string;
+        value: string;
+        sourceRange?: HtmlSourceRange;
+    }>;
+}
+export interface HtmlSourceEvidence {
+    schema: "omnius.html-source-evidence.v1";
+    responseSha256: string;
+    finalUrl: string;
+    baseUrl: string;
+    page: {
+        title?: HtmlSourceText;
+        dates: ReadonlyArray<{
+            kind: "published" | "modified";
+            value: string;
+            sourceRange?: HtmlSourceRange;
+        }>;
+    };
+    /** Complete static body text, including every article/main/table/code section.
+     * This is not JavaScript execution or a claim about live browser visibility. */
+    textCoverage: {
+        scope: "all_static_body_text";
+        partial: false;
+        rendered: false;
+        excludedElements: ReadonlyArray<"script" | "style" | "template">;
+        includedAttributes: ReadonlyArray<string>;
+    };
+    /** Legacy field name; contains the whole static body, not a first-article preview. */
+    article: HtmlSourceText & {
+        selection: "article" | "main" | "body";
+        matchingArticles: number;
+    };
+    images: ReadonlyArray<HtmlSourceImage>;
+    omittedImages: number;
+}
+/** Static quoted evidence only: no execution, network access, relevance judgement or authority grant. */
+export declare function extractHtmlSourceEvidence(body: string, finalUrl: string): HtmlSourceEvidence | undefined;
+/** Bounded model view. URLs are never cut; decoded text excerpts and omissions are explicit. */
+export declare function renderHtmlSourceEvidence(evidence: HtmlSourceEvidence, maxChars: number, includeArticle?: boolean): string;