@aria-cli/types 1.0.18 → 1.0.31

package/dist-cjs/native-tools.js

@@ -0,0 +1,33 @@
+"use strict";
+/**
+ * Native tool types and type guards for provider-native capabilities
+ * @module @aria/types/native-tools
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isFunctionTool = isFunctionTool;
+exports.isNativeTool = isNativeTool;
+/**
+ * Type guard to check if a tool call is a function/custom tool
+ * (as opposed to a native provider tool like search or code execution)
+ */
+function isFunctionTool(toolCall) {
+    // Function tools are the default - they don't have special name prefixes
+    return !isNativeTool(toolCall);
+}
+/**
+ * Type guard to check if a tool call is a native provider tool
+ * Native tools have special name prefixes like "brave_search", "computer", etc.
+ */
+function isNativeTool(toolCall) {
+    const nativePrefixes = [
+        "brave_search",
+        "computer",
+        "code_interpreter",
+        "text_editor",
+        "bash",
+        "dalle",
+        "file_search",
+    ];
+    return nativePrefixes.some((prefix) => toolCall.name.startsWith(prefix));
+}
+//# sourceMappingURL=native-tools.js.map

package/dist-cjs/relaunch.js

@@ -0,0 +1,67 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RESTART_KIND_ENV = exports.RESUME_ARION_ENV = exports.RESUME_SESSION_ENV = exports.NO_RELAUNCH_ENV = exports.RELAUNCH_EXIT_CODE = void 0;
+exports.getRelaunchMarkerDir = getRelaunchMarkerDir;
+exports.getRelaunchMarkerPath = getRelaunchMarkerPath;
+exports.writeRelaunchMarker = writeRelaunchMarker;
+exports.readRelaunchMarker = readRelaunchMarker;
+exports.clearRelaunchMarker = clearRelaunchMarker;
+const node_fs_1 = require("node:fs");
+const node_os_1 = require("node:os");
+const node_path_1 = require("node:path");
+/**
+ * Magic exit code that tells the parent supervisor to respawn the child.
+ */
+exports.RELAUNCH_EXIT_CODE = 199;
+/**
+ * Environment variables used by relaunch/supervisor flows.
+ */
+exports.NO_RELAUNCH_ENV = "ARIA_NO_RELAUNCH";
+exports.RESUME_SESSION_ENV = "ARIA_RESUME_SESSION_ID";
+exports.RESUME_ARION_ENV = "ARIA_RESUME_ARION";
+exports.RESTART_KIND_ENV = "ARIA_RESTART_KIND";
+function getAriaDir() {
+    const ariaHome = process.env.ARIA_HOME?.trim();
+    if (ariaHome)
+        return ariaHome;
+    return (0, node_path_1.join)((0, node_os_1.homedir)(), ".aria");
+}
+function getRelaunchMarkerDir() {
+    return (0, node_path_1.join)(getAriaDir(), "relaunch-pending");
+}
+function getRelaunchMarkerPath(pid = process.pid) {
+    return (0, node_path_1.join)(getRelaunchMarkerDir(), `${pid}.json`);
+}
+function writeRelaunchMarker(marker) {
+    try {
+        const markerPath = getRelaunchMarkerPath(marker.pid);
+        (0, node_fs_1.mkdirSync)((0, node_path_1.dirname)(markerPath), { recursive: true });
+        (0, node_fs_1.writeFileSync)(markerPath, JSON.stringify(marker), "utf-8");
+    }
+    catch {
+        // Best-effort — must never prevent restart
+    }
+}
+function readRelaunchMarker(pid = process.pid) {
+    try {
+        const markerPath = getRelaunchMarkerPath(pid);
+        if (!(0, node_fs_1.existsSync)(markerPath))
+            return null;
+        const raw = (0, node_fs_1.readFileSync)(markerPath, "utf-8");
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+}
+function clearRelaunchMarker(pid = process.pid) {
+    try {
+        const markerPath = getRelaunchMarkerPath(pid);
+        if ((0, node_fs_1.existsSync)(markerPath))
+            (0, node_fs_1.unlinkSync)(markerPath);
+    }
+    catch {
+        // Best-effort
+    }
+}
+//# sourceMappingURL=relaunch.js.map

package/dist-cjs/stall-phase.js

@@ -0,0 +1,18 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.setGlobalStallPhase = setGlobalStallPhase;
+exports.clearGlobalStallPhase = clearGlobalStallPhase;
+function getGlobalPhaseStore() {
+    return globalThis;
+}
+function setGlobalStallPhase(label) {
+    const store = getGlobalPhaseStore();
+    store.__aria_stall_phase = label;
+    store.__aria_stall_phase_ts = performance.now();
+}
+function clearGlobalStallPhase() {
+    const store = getGlobalPhaseStore();
+    store.__aria_stall_phase = undefined;
+    store.__aria_stall_phase_ts = undefined;
+}
+//# sourceMappingURL=stall-phase.js.map

package/dist-cjs/tool-outputs.js

@@ -0,0 +1,5 @@
+"use strict";
+/** Canonical output shapes for tools with dedicated renderers.
+ *  Executors MUST return these shapes. Renderers consume them directly. */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=tool-outputs.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aria-cli/types",
-  "version": "1.0.18",
+  "version": "1.0.31",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -23,7 +23,9 @@
     "dist/",
     "dist-cjs/",
     "!**/*.map",
-    "!**/*.tsbuildinfo"
+    "!**/*.tsbuildinfo",
+    "!**/*.d.ts",
+    "!**/*.d.ts.map"
   ],
   "engines": {
     "node": ">=20.0.0"

package/dist/errors.d.ts

@@ -1,29 +0,0 @@
-/**
- * Error narrowing utilities for replacing `catch (err: any)` patterns.
- * @module @aria/types/errors
- */
-/**
- * Extract a human-readable message from an unknown caught value.
- *
- * Replaces the pattern:
- *   `catch (err: any) { ... err.message ... }`
- * with:
- *   `catch (err: unknown) { ... getErrorMessage(err) ... }`
- */
-export declare function getErrorMessage(err: unknown): string;
-/**
- * Extract an HTTP-style status code from an unknown caught value.
- *
- * Replaces the pattern:
- *   `(error as any).statusCode`
- * with:
- *   `getErrorStatusCode(error)`
- */
-export declare function getErrorStatusCode(err: unknown): number | undefined;
-/**
- * Type guard: is this caught value an Error with a `.code` property?
- * Common for Node.js system errors (ENOENT, ECONNREFUSED, etc.)
- */
-export declare function isNodeError(err: unknown): err is Error & {
-    code: string;
-};

package/dist/index.d.ts

@@ -1,11 +0,0 @@
-/**
- * @aria/types - Minimal shared types
- */
-export * from "./models.js";
-export * from "./memoria.js";
-export * from "./errors.js";
-export * from "./native-tools.js";
-export * from "./relaunch.js";
-export * from "./stall-phase.js";
-export { log, type LogLevel, type LogSink } from "./logger.js";
-export type { EditFileOutput, WriteFileOutput, BashToolOutput, NotebookEditOutput, } from "./tool-outputs.js";

package/dist/logger.d.ts

@@ -1,54 +0,0 @@
-/**
- * Lightweight leveled logger for ARIA.
- *
- * Respects `ARIA_LOG_LEVEL` env var (debug | info | warn | error | silent).
- * Default level: "info" — debug messages are suppressed in normal usage.
- *
- * Architecture: logs dispatch through pluggable sinks. The default console
- * sink writes to stdout/stderr with ANSI styling. Execution contexts that
- * lack a terminal (daemon, headless server) replace or supplement it with
- * durable sinks (e.g., JSONL file sink). This decoupling makes it impossible
- * for diagnostic output to silently go to /dev/null — every context
- * configures the sink that matches its output channel.
- *
- * Usage:
- *   import { log } from "@aria-cli/types";
- *   log.debug("[PhaseTimer] ...");   // only prints when ARIA_LOG_LEVEL=debug
- *   log.info("[runner] ...");        // prints at info level and above
- *   log.warn("[runner] ...");        // prints at warn level and above
- *   log.error("[runner] ...");       // always prints (unless level > error)
- *
- * Sink configuration (daemon example):
- *   import { log } from "@aria-cli/types";
- *   log.addSink(myFileLogSink);
- *   log.removeConsoleSink();  // stdio is /dev/null in detached mode
- */
-export type LogLevel = "debug" | "info" | "warn" | "error" | "silent";
-/**
- * A log sink receives raw (unstyled) log arguments and writes them
- * to a destination. Each sink decides its own formatting.
- */
-export interface LogSink {
-    write(level: LogLevel, args: unknown[]): void;
-    close?(): void;
-}
-export declare const log: {
-    debug(...args: unknown[]): void;
-    info(...args: unknown[]): void;
-    warn(...args: unknown[]): void;
-    error(...args: unknown[]): void;
-    setLevel(level: LogLevel): void;
-    getLevel(): LogLevel;
-    /** Add a log sink. All subsequent log calls dispatch to it. */
-    addSink(sink: LogSink): void;
-    /** Remove a previously added sink. */
-    removeSink(sink: LogSink): void;
-    /**
-     * Remove the built-in console sink.
-     *
-     * Use this in execution contexts where stdio is unavailable (detached
-     * daemon, headless server) AFTER adding a durable file sink. Prevents
-     * wasted console.* calls that go to /dev/null.
-     */
-    removeConsoleSink(): void;
-};

package/dist/memoria.d.ts

@@ -1,428 +0,0 @@
-/**
- * Minimal IMemoria interface for consumers that need memory capabilities
- * without depending on the concrete @aria/memoria package.
- *
- * Structural types (MemoryItem, ToolItem, RecallResult) replace bare
- * `unknown` returns so consumers get usable shapes without coupling to
- * the full Memoria domain model.
- */
-/** A single stored memory. */
-export interface MemoryItem {
-    id: string;
-    content: string;
-    summary?: string;
-    network?: string;
-    importance?: number;
-    confidence?: number;
-    createdAt?: Date;
-    metadata?: Record<string, unknown>;
-}
-/** A single tool-store entry. */
-export interface ToolItem {
-    id: string;
-    name: string;
-    description: string;
-    source?: ToolSourceItem;
-    importance?: number;
-    confidence?: number;
-    tags?: string[];
-    createdAt?: Date;
-    updatedAt?: Date;
-    accessedAt?: Date;
-    accessCount?: number;
-    evidenceIds?: string[];
-    category?: "filesystem" | "code" | "shell" | "web" | "data" | "memory" | "meta" | "arion";
-    parameters?: Record<string, unknown>;
-    riskLevel?: "safe" | "moderate" | "dangerous";
-    responseTemplate?: string;
-    knowledge?: string;
-    usageHint?: string;
-    adoptedAt?: number;
-    lastUsedAt?: number;
-    usageCount?: number;
-    schema?: Record<string, unknown>;
-    capabilities?: string[];
-    metrics?: Record<string, unknown>;
-}
-export type ToolSourceItem = {
-    type: "built-in";
-} | {
-    type: "external";
-    ref: string;
-    format: "skill-file" | "markdown" | "json" | "web-search";
-} | {
-    type: "organic";
-    method: "execution" | "observation" | "feedback";
-    episodeId?: string;
-};
-/** Result shape returned by observation query primitives. */
-export interface ObservationQueryResult {
-    observations: string;
-    currentTask: string | null;
-    suggestedResponse: string | null;
-    sessionId: string;
-    updatedAt: number;
-}
-/** Result envelope returned by the APR pipeline. */
-export interface RecallResult {
-    memories: MemoryItem[];
-    /** @deprecated Legacy alias retained for compatibility with older callers. */
-    data?: MemoryItem[];
-    query?: string;
-    totalCount?: number;
-    degradationLevel?: "full" | "reduced" | "minimal";
-    skippedStages?: string[];
-    warnings?: string[];
-}
-/** Result from lightweight FTS5-only recall. */
-export interface LightweightRecallResult {
-    memories: MemoryItem[];
-    formattedContext: {
-        context: string;
-    };
-    query: string;
-}
-export interface ExtractedConversationMemoryItem {
-    content: string;
-    network: "world" | "episodes" | "beliefs" | "entities" | "procedures" | "strategies";
-    /** Optional durability marker describing how the memory was routed */
-    durability?: "permanent" | "session";
-}
-export interface ConversationExtractionResult {
-    learned: ExtractedConversationMemoryItem[];
-    error?: string;
-}
-export interface SkillTriggerItem {
-    type: "keyword" | "intent" | "context" | "entity";
-    pattern: string;
-    confidence: number;
-}
-export interface SkillRequirementsItem {
-    bins?: string[];
-    env?: string[];
-    os?: ("darwin" | "linux" | "win32")[];
-}
-export type SkillSourceItem = {
-    type: "auto-learned";
-    sequenceId: string;
-} | {
-    type: "file";
-    path: string;
-    format: "skill-file";
-} | {
-    type: "cli";
-    command: string;
-} | {
-    type: "web";
-    url: string;
-} | {
-    type: "user";
-    ref?: string;
-};
-export interface SkillItem {
-    id: string;
-    name: string;
-    description: string;
-    content: string;
-    toolIds: string[];
-    triggers: SkillTriggerItem[];
-    requires?: SkillRequirementsItem;
-    tags: string[];
-    source: SkillSourceItem;
-    executionCount: number;
-    successCount: number;
-    lastExecuted: Date | null;
-    averageDurationMs: number | null;
-    confidence: number;
-    importance: number;
-    createdAt: Date;
-    updatedAt: Date;
-    accessedAt: Date;
-    accessCount: number;
-    archivedAt?: Date;
-}
-export interface SkillExecutionRecord {
-    id: string;
-    skillId: string;
-    success: boolean;
-    durationMs?: number;
-    notes?: string;
-    episodeId?: string;
-    timestamp: Date;
-}
-export interface ToolUseSequenceRecord {
-    tool: string;
-    input?: Record<string, unknown>;
-    output?: string;
-    success: boolean;
-    timestamp: Date;
-}
-/**
- * Minimal observation engine interface for consumers that need observation
- * capabilities without depending on the concrete @aria/memoria package.
- *
- * Matches the public surface of ObservationEngine from @aria/memoria.
- */
-export interface IObservationEngine {
-    /** Prepare context before model call — may trigger observation and filter messages. */
-    prepareContext(opts: {
-        sessionId: string;
-        messages: unknown[];
-        originalSystemPrompt: string;
-        readOnly?: boolean;
-        signal?: AbortSignal;
-    }): Promise<{
-        messagesToSend: unknown[];
-        filteredMessageIds: Set<string>;
-        observationTriggered: boolean;
-    }>;
-    /** Track new message IDs added to the conversation since last observation. */
-    trackNewMessages(messageIds: string[]): void;
-    /** Force observation of remaining unobserved messages at session end. */
-    finalObservation(sessionId: string, messages?: unknown[], signal?: AbortSignal): Promise<void>;
-    /** Observe messages — used for explicit observation triggers. */
-    observe(sessionId: string, messages: unknown[], signal?: AbortSignal, opts?: {
-        force?: boolean;
-    }): Promise<void>;
-    /** Get the observation record for a session, or null. */
-    getRecord(sessionId: string): unknown;
-    /** Get the active observation text for a session. */
-    getActiveObservations(sessionId: string): string;
-    /** Drain pending observation work (wait for in-flight observations to complete). */
-    drain(): Promise<void>;
-}
-export interface IMemoria {
-    /** Store a memory. Returns an object with `id` on success, or null. */
-    remember(content: string, options?: Record<string, unknown>): Promise<{
-        id: string;
-    } | null>;
-    /**
-     * Internal fast-path for storing execution-trace episodes without the full
-     * entity extraction pipeline. Optional for backward compatibility.
-     */
-    storeEpisode?(content: string): Promise<{
-        id: string;
-    } | null>;
-    /** Retrieve memories matching a query. Includes degradation metadata when available. */
-    recall(query: string, options?: Record<string, unknown>): Promise<RecallResult>;
-    /** Lightweight FTS5-only recall for session seeding. No LLM calls. */
-    recallLightweight(query: string, options?: {
-        limit?: number;
-        networks?: string[];
-    }): Promise<LightweightRecallResult>;
-    /**
-     * Planner-first unified recall: 1 LLM call for classification + plan + expansion.
-     * Routes to direct lookup (skipping APR) or mixed APR + primitive execution.
-     * This is the preferred recall path — recallWithAPR delegates to this.
-     */
-    recallUnified?(query: string, options?: {
-        limit?: number;
-        networks?: string[];
-    }): Promise<{
-        memories: MemoryItem[];
-        formattedContext?: {
-            context?: string;
-            text?: string;
-            tokenCount?: number;
-        } | null;
-        intent?: {
-            type?: string;
-            confidence?: number;
-            entities?: string[];
-            temporalFocus?: string | null;
-            extractedEntities?: string[];
-            extractedTimeframe?: Record<string, unknown>;
-        };
-        sourceStats?: unknown;
-        plan?: Array<{
-            primitive: string;
-            args: Record<string, unknown>;
-        }>;
-        planReasoning?: string;
-        primitiveResults?: Array<{
-            source: string;
-            data: unknown;
-        }>;
-    }>;
-    /** Retrieve memories via the Adaptive Parallel Retrieval pipeline. */
-    recallWithAPR(query: string, options?: {
-        limit?: number;
-        networks?: string[];
-    }): Promise<{
-        memories: MemoryItem[];
-        formattedContext?: {
-            context?: string;
-            text?: string;
-            tokenCount?: number;
-        };
-        intent?: {
-            type?: string;
-            confidence?: number;
-            entities?: string[];
-            temporalFocus?: string | null;
-            extractedEntities?: string[];
-            extractedTimeframe?: Record<string, unknown>;
-        };
-        sourceStats?: unknown;
-        query?: string;
-        totalCount?: number;
-        degradationLevel?: "full" | "reduced" | "minimal";
-        skippedStages?: string[];
-        warnings?: string[];
-    }>;
-    /**
-     * Lightweight vector-only recall with network filtering. Bypasses the full APR
-     * pipeline (no classification, no multi-index fusion, no diversity). Designed
-     * for time-critical paths like session bootstrap.
-     */
-    recallDirect(query: string, options: {
-        networks: string[];
-        limit: number;
-        threshold?: number;
-    }): Promise<MemoryItem[]>;
-    /** Recall memories by network type. Direct SQL query, no LLM classification. */
-    recallByNetwork(network: string, options?: {
-        limit?: number;
-    }): Promise<MemoryItem[]>;
-    /** Recall recent memories, optionally filtered by network. Direct SQL query sorted by created_at DESC. */
-    recallRecent(options?: {
-        limit?: number;
-        network?: string;
-    }): Promise<MemoryItem[]>;
-    /** Recall memories by vector similarity. Uses embedding model only (0 LLM calls). */
-    recallSimilar(query: string, options?: {
-        k?: number;
-        threshold?: number;
-    }): Promise<MemoryItem[]>;
-    /** Store a tool with semantic indexing. Returns the generated id. */
-    rememberTool(tool: {
-        name: string;
-        description: string;
-    } & Record<string, unknown>): Promise<string>;
-    /** Query the tool store. */
-    recallTools(options: {
-        query: string;
-        limit?: number;
-        /** Optional offset used for paged list retrieval (matchAll mode). */
-        offset?: number;
-        minConfidence?: number;
-        /** When true, bypasses semantic/keyword matching and lists stored tools. */
-        matchAll?: boolean;
-        /** When false, recall becomes read-only and does not mutate access stats. */
-        updateAccessStats?: boolean;
-    }): Promise<ToolItem[]>;
-    /** Retrieve a single tool entry by ID. */
-    getToolById(id: string): Promise<ToolItem | null>;
-    /** Delete a tool entry by ID. Returns true if deleted, false if not found. */
-    forgetTool(id: string): Promise<boolean>;
-    /** Store a skill directly. Returns the generated skill ID. */
-    rememberSkill(skill: {
-        name: string;
-        description: string;
-        content: string;
-        toolIds?: string[];
-        triggers?: SkillTriggerItem[];
-        requires?: SkillRequirementsItem;
-        tags?: string[];
-        source: SkillSourceItem;
-        importance?: number;
-        confidence?: number;
-    }): Promise<string>;
-    /** Skill retrieval API. */
-    recallSkills(options?: {
-        query?: string;
-        triggerType?: SkillTriggerItem["type"];
-        limit?: number;
-    }): Promise<SkillItem[]>;
-    /** Skill lookup API. */
-    getSkill(idOrName: string): Promise<SkillItem | null>;
-    /** Record skill execution metrics. */
-    recordSkillExecution(options: {
-        skillId: string;
-        success: boolean;
-        durationMs?: number;
-        notes?: string;
-        episodeId?: string;
-    }): Promise<SkillExecutionRecord>;
-    /** Start recording a tool-use sequence for procedural learning. */
-    startToolSequence?(task: string, options?: {
-        sessionId?: string;
-    }): void;
-    /** Record a single tool execution within the active sequence. */
-    recordToolUse?(record: ToolUseSequenceRecord, options?: {
-        sessionId?: string;
-    }): void;
-    /** Finalize the active tool-use sequence and trigger learning. */
-    endToolSequence?(success: boolean, options?: {
-        sessionId?: string;
-    }): Promise<void>;
-    /** Delete a single memory by ID. */
-    deleteMemory(id: string): Promise<boolean>;
-    /** Merge a JSON patch into a memory's metadata. */
-    updateMemoryMetadata(id: string, patch: Record<string, unknown>): void;
-    /** Soft-invalidate a memory in place (sets confidence to 0, marks reason). Allows recovery. */
-    invalidateMemoryInPlace(memoryId: string, reason?: string): Promise<void>;
-    /** Requeue failed embedding jobs and return how many were scheduled. */
-    retryFailedEmbeddings?(): Promise<number>;
-    /** Extract memories from a user/assistant conversation turn. */
-    extractFromConversation(userMessage: string, assistantResponse: string, options?: {
-        signal?: AbortSignal;
-    }): Promise<ConversationExtractionResult>;
-    /** Observation engine for Mastra-style observation/reflection memory layer. */
-    readonly observationEngine?: IObservationEngine;
-    /**
-     * Extract durable knowledge from observation text into the knowledge graph.
-     * Optional for backward compatibility — always present on concrete Memoria instances.
-     */
-    extractFromObservations?(observations: string, options?: {
-        sessionId?: string;
-        signal?: AbortSignal;
-    }): Promise<ConversationExtractionResult>;
-    /**
-     * Return the most recently updated observation session ID.
-     * When `arionId` is provided, scope to that arion's observation records.
-     */
-    getMostRecentSessionId?(options?: {
-        arionId?: string;
-    }): Promise<string | null>;
-    /**
-     * Fetch persisted active observations for a session.
-     * Returns null when no observation record exists for the session.
-     */
-    getSessionObservations?(sessionId: string): Promise<string | null>;
-    /**
-     * Full-text search across observation records (LIKE on observations, current_task, suggested_response).
-     * Returns matching records ordered by recency.
-     */
-    searchObservations?(query: string, limit?: number): Promise<ObservationQueryResult[]>;
-    /**
-     * Retrieve a specific field from the most recent observation record.
-     * Valid fields: "suggested_response", "current_task", "active_observations".
-     */
-    getObservationField?(field: "suggested_response" | "current_task" | "active_observations"): Promise<string | null>;
-    /**
-     * Retrieve the N most recent observation records, ordered by updated_at DESC.
-     */
-    getRecentObservations?(limit?: number): Promise<ObservationQueryResult[]>;
-    /** Shut down the memory system and release resources. */
-    close(): Promise<void>;
-    /**
-     * Entity-first recall — fast-path for entity/self queries.
-     * Returns a formatted string when the query matches a known entity or
-     * self-query pattern. Returns null to signal fallback to APR.
-     */
-    entityRecall(query: string): Promise<string | null>;
-    /** Whether this instance has been closed. */
-    readonly isClosed: boolean;
-    /** Return the total number of stored memories. */
-    count(): Promise<number>;
-    /** List stored memories. */
-    list(options?: {
-        limit?: number;
-        network?: string;
-    }): Promise<MemoryItem[]>;
-    /** Get a config value by key. Returns null if not found. */
-    getConfig(key: string): Promise<string | null>;
-    /** Set a config value by key. Creates or overwrites. */
-    setConfig(key: string, value: string): Promise<void>;
-}