wotann 0.5.0

package/dist/core/types.d.ts

@@ -0,0 +1,203 @@
+/**
+ * Core type definitions for WOTANN agent harness.
+ * Provider-agnostic types shared across the entire system.
+ */
+/**
+ * Provider identifier. Any string keying into PROVIDER_DEFAULTS (or an
+ * adapter the registry knows how to construct) is valid. The eight
+ * first-class providers — anthropic, openai, codex, copilot, ollama,
+ * openrouter, gemini, huggingface — have dedicated registry cases;
+ * every other entry in PROVIDER_DEFAULTS (mistral, deepseek, xai, groq,
+ * cerebras, together, fireworks, perplexity, sambanova, vertex, azure,
+ * bedrock, anthropic-cli, openai-compat, free) reaches an adapter
+ * through the registry's openai-compat default branch.
+ */
+export type ProviderName = string;
+export type TransportType = "anthropic" | "chat_completions" | "codex_responses";
+export type BillingType = "subscription" | "api-key" | "free";
+export type AuthMethod = "oauth-token" | "subscription-direct" | "api-key" | "codex-jwt" | "github-pat" | "local" | "azure-ad" | "aws-iam" | "gcp-sa";
+export interface ProviderAuth {
+    readonly provider: ProviderName;
+    readonly method: AuthMethod;
+    readonly token: string;
+    readonly billing: BillingType;
+    readonly label?: string;
+    readonly priority?: number;
+    readonly transport?: TransportType;
+    readonly models: readonly string[];
+    readonly subscription?: string;
+}
+export interface ProviderStatus {
+    readonly provider: ProviderName;
+    readonly available: boolean;
+    readonly authMethod: AuthMethod;
+    readonly billing: BillingType;
+    readonly models: readonly string[];
+    readonly label: string;
+    readonly error?: string;
+}
+export type ModelTier = 0 | 1 | 2 | 3 | 4;
+export interface RoutingDecision {
+    readonly tier: ModelTier;
+    readonly provider: ProviderName;
+    readonly model: string;
+    readonly cost: number;
+    readonly method?: "wasm";
+}
+export type TaskCategory = "utility" | "classify" | "code" | "plan" | "review" | "vision" | "computer-use";
+export interface TaskDescriptor {
+    readonly category: TaskCategory;
+    readonly requiresComputerUse: boolean;
+    readonly requiresVision: boolean;
+    readonly estimatedTokens: number;
+    readonly priority: "latency" | "balanced" | "quality" | "cost";
+}
+export type RiskLevel = "low" | "medium" | "high";
+export interface AgentMessage {
+    readonly role: "user" | "assistant" | "system" | "tool";
+    readonly content: string;
+    readonly toolName?: string;
+    readonly toolCallId?: string;
+    readonly model?: string;
+    readonly provider?: ProviderName;
+    readonly tokensUsed?: number;
+    readonly cost?: number;
+    /** Stable identifier for O(1) lookup via the runtime's message index. */
+    readonly id?: string;
+}
+export interface WotannQueryOptions {
+    readonly prompt: string;
+    readonly context?: readonly AgentMessage[];
+    readonly systemPrompt?: string;
+    readonly model?: string;
+    readonly provider?: ProviderName;
+    readonly maxTokens?: number;
+    readonly temperature?: number;
+    readonly tools?: readonly ToolDefinition[];
+    /** TurboQuant KV cache compression params for Ollama local models. */
+    readonly ollamaParams?: {
+        readonly numCtx: number;
+        readonly kvCacheType: string;
+        readonly flashAttention: boolean;
+    };
+    /**
+     * Phase-13 wire: task-class tag. When set to "tau-bench-retail" or
+     * "tau-bench-airline", the runtime prepends the built-in τ-bench
+     * policy document to the system prompt via policy-injector. Other
+     * strings are passed through unchanged (future task-type routing).
+     */
+    readonly taskClass?: "tau-bench-retail" | "tau-bench-airline" | string;
+    /**
+     * LLMFlow tag — describes the AGENT INTENT of this query so the
+     * cost-tracker can group spans by purpose, not just by provider.
+     *
+     * Resurrected from Round 26 (commit 2d5256e): `LLMFlow` registry
+     * shipped without thread-through. Adding the field here threads
+     * flow from the runtime caller -> bridge.query() -> provider adapter
+     * -> cost-tracker.record(), so observability dashboards can answer
+     * "what fraction of cost goes to context-compression vs primary
+     * chat vs critic review?".
+     *
+     * Honest default (QB #3): undefined. The runtime fills in
+     * CHAT_RESPONSE for primary chat; specialised callers
+     * (architect, critic, memory) override with their own tag.
+     */
+    readonly flow?: import("../intelligence/llm-flows.js").LLMFlowName;
+    /**
+     * Round 63 turn-23 — vision/multimodal media inputs. Threading
+     * audit finding H3: the four major adapters (anthropic / openai-
+     * compat / gemini-native / ollama) consume `options.media` from
+     * UnifiedQueryOptions, but the runtime's public `query()` was
+     * never accepting media so callers couldn't forward images at all.
+     *
+     * Each VisionInput is a pre-ingested image/video frame with a
+     * normalized base64 data URL + mime + bytes count. Build via
+     * `src/vision/ingest.ts` (fromBuffer/fromPath/fromDataUrl) before
+     * calling — `WotannQueryOptions` does NOT accept raw paths to
+     * keep this layer transport-agnostic.
+     *
+     * Honest default (QB #3): undefined → adapters operate text-only.
+     */
+    readonly media?: readonly import("../vision/types.js").VisionInput[];
+}
+export interface ToolDefinition {
+    readonly name: string;
+    readonly description: string;
+    readonly inputSchema: Record<string, unknown>;
+}
+/**
+ * All hook events the engine recognises. Session-10 audit: 9 of 19
+ * variants are actually fired by the runtime / daemon (PreToolUse,
+ * PostToolUse, ToolResultReceived, UserPromptSubmit, Stop, PreCompact,
+ * PostCompact, SessionStart, SessionEnd). The remaining 10 —
+ * `PostToolUseFailure`, `SubagentStart`, `SubagentStop`,
+ * `Notification`, `PermissionRequest`, `Setup`, `TeammateIdle`,
+ * `TaskCompleted`, `ConfigChange`, `WorktreeCreate`, `WorktreeRemove`
+ * — are NEVER dispatched by any producer. They remain in the union so
+ * external plugins that register handlers against them typecheck, but
+ * are explicitly marked advisory-only: handlers registered against
+ * them will not fire unless / until a producer is wired. See
+ * `src/hooks/engine.ts` for the live dispatch table.
+ *
+ * Rule of thumb: if you are adding a new feature and reach for one of
+ * the ADVISORY events, you must ALSO add the producer call site in
+ * the same change. Otherwise the event stays dead letter.
+ */
+export type HookEvent = "PreToolUse" | "PostToolUse" | "ToolResultReceived" | "UserPromptSubmit" | "Stop" | "PreCompact" | "PostCompact" | "SessionStart" | "SessionEnd" | "mcp_tool" | "PostToolUseFailure" | "SubagentStop" | "Notification" | "SubagentStart" | "PermissionRequest" | "Setup" | "TeammateIdle" | "TaskCompleted" | "ConfigChange" | "WorktreeCreate" | "WorktreeRemove" | "VerifierGate";
+export type HookProfile = "minimal" | "standard" | "strict";
+export interface WotannConfig {
+    readonly version: string;
+    readonly providers: Partial<Record<ProviderName, ProviderConfig>>;
+    readonly hooks: HookConfig;
+    readonly memory: MemoryConfig;
+    readonly ui: UIConfig;
+    readonly daemon: DaemonConfig;
+}
+export interface ProviderConfig {
+    readonly enabled: boolean;
+    readonly model?: string;
+    readonly apiKey?: string;
+    readonly baseUrl?: string;
+    readonly priority?: number;
+}
+export interface HookConfig {
+    readonly profile: HookProfile;
+    readonly custom?: readonly string[];
+}
+export interface MemoryConfig {
+    readonly enabled: boolean;
+    readonly dbPath?: string;
+    readonly maxEntries?: number;
+}
+export interface UIConfig {
+    readonly theme: string;
+    readonly panels: readonly string[];
+}
+export interface DaemonConfig {
+    readonly enabled: boolean;
+    readonly tickInterval?: number;
+    readonly heartbeatPath?: string;
+}
+export type PermissionMode = "default" | "acceptEdits" | "plan" | "auto" | "bypassPermissions" | "dontAsk";
+export type PermissionDecision = "allow" | "deny" | "always-allow";
+export interface SessionState {
+    readonly id: string;
+    readonly startedAt: Date;
+    readonly provider: ProviderName;
+    readonly model: string;
+    readonly totalTokens: number;
+    readonly totalCost: number;
+    readonly toolCalls: number;
+    readonly messages: readonly AgentMessage[];
+    /** When true, conversation is not saved to history, memory is not captured, and learning is skipped */
+    readonly incognito: boolean;
+    /**
+     * Auto-generated conversation title, stamped by TitleMiddleware once the
+     * conversation has enough signal. Read by `wotann session list` and the
+     * Desktop conversations panel — empty/undefined sessions render their
+     * truncated id instead. Persisted by saveSession alongside the rest of
+     * the session state.
+     */
+    readonly title?: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/core/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/core/types.ts"],"names":[],"mappings":"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"}

package/dist/core/types.js

@@ -0,0 +1,6 @@
+/**
+ * Core type definitions for WOTANN agent harness.
+ * Provider-agnostic types shared across the entire system.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/core/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/core/types.ts"],"names":[],"mappings":"AAAA;;;GAGG"}

package/dist/core/virtual-paths.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Virtual Path System — isolate agents from the real filesystem layout.
+ *
+ * Inspired by DeerFlow's virtual path mapping. Agents operate against
+ * virtual path prefixes (e.g. `/mnt/workspace/`) which are transparently
+ * resolved to physical locations on disk.
+ *
+ * Benefits:
+ * - Agents never see the user's real home directory or absolute paths
+ * - Multiple workspaces can be mounted under different prefixes
+ * - Read-only mounts prevent accidental writes to protected directories
+ * - Path translation is consistent and reversible
+ */
+export interface VirtualPathConfig {
+    readonly prefix: string;
+    readonly physicalRoot: string;
+    readonly readOnly: boolean;
+}
+export interface ResolvedPath {
+    readonly virtualPath: string;
+    readonly physicalPath: string;
+    readonly mount: VirtualPathConfig;
+    readonly readOnly: boolean;
+    readonly relativePath: string;
+}
+export interface MountValidation {
+    readonly valid: boolean;
+    readonly errors: readonly string[];
+}
+export declare class VirtualPathResolver {
+    private readonly mounts;
+    constructor(mounts?: readonly VirtualPathConfig[]);
+    /**
+     * Resolve a virtual path to a physical path.
+     * Returns null if no mount matches the virtual path.
+     */
+    resolve(virtualPath: string): ResolvedPath | null;
+    /**
+     * Convert a physical path to its virtual equivalent.
+     * Returns null if the physical path is not under any mount.
+     */
+    virtualize(physicalPath: string): string | null;
+    /**
+     * Check whether a virtual path is writable (not in a read-only mount).
+     */
+    isWritable(virtualPath: string): boolean;
+    /**
+     * Check whether a virtual path is valid (matches a mount).
+     */
+    isValid(virtualPath: string): boolean;
+    /**
+     * Get all configured mounts.
+     */
+    getMounts(): readonly VirtualPathConfig[];
+    /**
+     * Create a new resolver with an additional mount.
+     * Returns a new instance (immutable pattern).
+     */
+    withMount(mount: VirtualPathConfig): VirtualPathResolver;
+    /**
+     * Create a new resolver without the specified prefix.
+     * Returns a new instance (immutable pattern).
+     */
+    withoutMount(prefix: string): VirtualPathResolver;
+    /**
+     * Validate mount configurations for common issues.
+     */
+    static validateMounts(mounts: readonly VirtualPathConfig[]): MountValidation;
+    private findMount;
+}
+//# sourceMappingURL=virtual-paths.d.ts.map

package/dist/core/virtual-paths.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"virtual-paths.d.ts","sourceRoot":"","sources":["../../src/core/virtual-paths.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAMH,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;CAC5B;AAED,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,KAAK,EAAE,iBAAiB,CAAC;IAClC,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;CAC/B;AAED,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;CACpC;AAID,qBAAa,mBAAmB;IAC9B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA+B;gBAE1C,MAAM,CAAC,EAAE,SAAS,iBAAiB,EAAE;IAQjD;;;OAGG;IACH,OAAO,CAAC,WAAW,EAAE,MAAM,GAAG,YAAY,GAAG,IAAI;IAsBjD;;;OAGG;IACH,UAAU,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI;IAc/C;;OAEG;IACH,UAAU,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO;IAMxC;;OAEG;IACH,OAAO,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO;IAIrC;;OAEG;IACH,SAAS,IAAI,SAAS,iBAAiB,EAAE;IAIzC;;;OAGG;IACH,SAAS,CAAC,KAAK,EAAE,iBAAiB,GAAG,mBAAmB;IAIxD;;;OAGG;IACH,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,mBAAmB;IAOjD;;OAEG;IACH,MAAM,CAAC,cAAc,CACnB,MAAM,EAAE,SAAS,iBAAiB,EAAE,GACnC,eAAe;IAwClB,OAAO,CAAC,SAAS;CAGlB"}

package/dist/core/virtual-paths.js

@@ -0,0 +1,157 @@
+/**
+ * Virtual Path System — isolate agents from the real filesystem layout.
+ *
+ * Inspired by DeerFlow's virtual path mapping. Agents operate against
+ * virtual path prefixes (e.g. `/mnt/workspace/`) which are transparently
+ * resolved to physical locations on disk.
+ *
+ * Benefits:
+ * - Agents never see the user's real home directory or absolute paths
+ * - Multiple workspaces can be mounted under different prefixes
+ * - Read-only mounts prevent accidental writes to protected directories
+ * - Path translation is consistent and reversible
+ */
+import { join, normalize, relative, isAbsolute } from "node:path";
+// ── Virtual Path Resolver ────────────────────────────────────
+export class VirtualPathResolver {
+    mounts;
+    constructor(mounts) {
+        const validated = (mounts ?? []).map(normalizeMount);
+        // Sort by prefix length descending so more specific mounts match first
+        this.mounts = [...validated].sort((a, b) => b.prefix.length - a.prefix.length);
+    }
+    /**
+     * Resolve a virtual path to a physical path.
+     * Returns null if no mount matches the virtual path.
+     */
+    resolve(virtualPath) {
+        const normalized = normalizePath(virtualPath);
+        const mount = this.findMount(normalized);
+        if (!mount)
+            return null;
+        const relativePath = normalized.slice(mount.prefix.length);
+        const physicalPath = normalize(join(mount.physicalRoot, relativePath));
+        // Security: ensure the resolved path is still under the mount root
+        if (!isUnderRoot(physicalPath, mount.physicalRoot)) {
+            return null;
+        }
+        return {
+            virtualPath: normalized,
+            physicalPath,
+            mount,
+            readOnly: mount.readOnly,
+            relativePath: relativePath || ".",
+        };
+    }
+    /**
+     * Convert a physical path to its virtual equivalent.
+     * Returns null if the physical path is not under any mount.
+     */
+    virtualize(physicalPath) {
+        const normalizedPhysical = normalize(physicalPath);
+        for (const mount of this.mounts) {
+            if (isUnderRoot(normalizedPhysical, mount.physicalRoot)) {
+                const rel = relative(mount.physicalRoot, normalizedPhysical);
+                if (rel.startsWith(".."))
+                    continue;
+                return normalizePath(join(mount.prefix, rel));
+            }
+        }
+        return null;
+    }
+    /**
+     * Check whether a virtual path is writable (not in a read-only mount).
+     */
+    isWritable(virtualPath) {
+        const resolved = this.resolve(virtualPath);
+        if (!resolved)
+            return false;
+        return !resolved.readOnly;
+    }
+    /**
+     * Check whether a virtual path is valid (matches a mount).
+     */
+    isValid(virtualPath) {
+        return this.resolve(virtualPath) !== null;
+    }
+    /**
+     * Get all configured mounts.
+     */
+    getMounts() {
+        return this.mounts;
+    }
+    /**
+     * Create a new resolver with an additional mount.
+     * Returns a new instance (immutable pattern).
+     */
+    withMount(mount) {
+        return new VirtualPathResolver([...this.mounts, mount]);
+    }
+    /**
+     * Create a new resolver without the specified prefix.
+     * Returns a new instance (immutable pattern).
+     */
+    withoutMount(prefix) {
+        const normalizedPrefix = ensureTrailingSep(normalizePath(prefix));
+        return new VirtualPathResolver(this.mounts.filter((m) => m.prefix !== normalizedPrefix));
+    }
+    /**
+     * Validate mount configurations for common issues.
+     */
+    static validateMounts(mounts) {
+        const errors = [];
+        const seen = new Set();
+        for (const mount of mounts) {
+            const normalized = ensureTrailingSep(normalizePath(mount.prefix));
+            if (normalized.length === 0 || normalized === "/") {
+                errors.push(`Mount prefix "${mount.prefix}" is too broad (root mount).`);
+            }
+            if (seen.has(normalized)) {
+                errors.push(`Duplicate mount prefix: "${mount.prefix}".`);
+            }
+            seen.add(normalized);
+            if (!isAbsolute(mount.physicalRoot)) {
+                errors.push(`Physical root for "${mount.prefix}" must be absolute, got "${mount.physicalRoot}".`);
+            }
+        }
+        // Check for overlapping prefixes
+        const prefixes = [...seen];
+        for (let i = 0; i < prefixes.length; i++) {
+            for (let j = i + 1; j < prefixes.length; j++) {
+                const a = prefixes[i];
+                const b = prefixes[j];
+                if (a.startsWith(b) || b.startsWith(a)) {
+                    errors.push(`Overlapping mount prefixes: "${a}" and "${b}".`);
+                }
+            }
+        }
+        return { valid: errors.length === 0, errors };
+    }
+    // ── Private Helpers ────────────────────────────────────────
+    findMount(normalizedVirtualPath) {
+        return this.mounts.find((m) => normalizedVirtualPath.startsWith(m.prefix));
+    }
+}
+// ── Module-Level Helpers ─────────────────────────────────────
+function normalizePath(p) {
+    // Normalize to forward slashes for consistency
+    return normalize(p).replace(/\\/g, "/");
+}
+function ensureTrailingSep(p) {
+    const normalizedSep = "/";
+    return p.endsWith(normalizedSep) ? p : p + normalizedSep;
+}
+function normalizeMount(mount) {
+    return {
+        prefix: ensureTrailingSep(normalizePath(mount.prefix)),
+        physicalRoot: normalize(mount.physicalRoot),
+        readOnly: mount.readOnly,
+    };
+}
+function isUnderRoot(path, root) {
+    const normalizedPath = normalize(path);
+    const normalizedRoot = normalize(root);
+    const rel = relative(normalizedRoot, normalizedPath);
+    return !rel.startsWith("..") && !isAbsolute(rel);
+}
+//# sourceMappingURL=virtual-paths.js.map

package/dist/core/virtual-paths.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"virtual-paths.js","sourceRoot":"","sources":["../../src/core/virtual-paths.ts"],"names":[],"mappings":"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"}

package/dist/core/workspace.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Workspace management: create and manage .wotann/ directory.
+ * Handles the 8-file bootstrap system (SOUL, IDENTITY, USER, AGENTS, TOOLS, HEARTBEAT, BOOTSTRAP, MEMORY).
+ */
+export interface CreateWorkspaceOptions {
+    readonly targetDir: string;
+    readonly freeMode?: boolean;
+    readonly minimal?: boolean;
+    readonly reset?: boolean;
+    readonly extendedContext?: boolean;
+}
+export interface CreateWorkspaceResult {
+    readonly created: boolean;
+    readonly path: string;
+    readonly filesCreated: readonly string[];
+    readonly alreadyExists: boolean;
+}
+export declare function createWorkspace(options: CreateWorkspaceOptions): CreateWorkspaceResult;
+export declare function workspaceExists(targetDir: string): boolean;
+//# sourceMappingURL=workspace.d.ts.map

package/dist/core/workspace.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"workspace.d.ts","sourceRoot":"","sources":["../../src/core/workspace.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAgXH,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;IAC5B,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;IAC3B,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC;IACzB,QAAQ,CAAC,eAAe,CAAC,EAAE,OAAO,CAAC;CACpC;AAED,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,YAAY,EAAE,SAAS,MAAM,EAAE,CAAC;IACzC,QAAQ,CAAC,aAAa,EAAE,OAAO,CAAC;CACjC;AAED,wBAAgB,eAAe,CAAC,OAAO,EAAE,sBAAsB,GAAG,qBAAqB,CAwDtF;AAED,wBAAgB,eAAe,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAE1D"}