@agntk/core 0.2.0 → 0.3.1

package/dist/streaming/data-parts.d.ts

@@ -0,0 +1,163 @@
+/**
+ * @fileoverview Custom data part types for AI SDK streaming.
+ * These types define the shape of transient data streamed during agent execution.
+ *
+ * Usage with AI SDK:
+ * ```typescript
+ * import type { DataStreamWriter } from 'ai';
+ *
+ * const writer: DataStreamWriter = ...;
+ * writer.writeData({ type: 'file-content', data: { path: '/foo.ts', content: '...', truncated: false } });
+ * ```
+ */
+/**
+ * Union type of all custom data parts supported by the agent SDK.
+ * These are streamed transiently and not persisted to conversation context.
+ */
+export type AgentDataParts = {
+    /**
+     * Streaming output from a spawned sub-agent.
+     * Displayed as nested collapsible in UI.
+     */
+    'sub-agent-stream': SubAgentStreamData;
+    /**
+     * Search results from grep/glob/codebase search.
+     */
+    'search-result': SearchResultData;
+    /**
+     * File content streamed transiently (not added to context).
+     */
+    'file-content': FileContentData;
+    /**
+     * Shell command execution output.
+     */
+    'shell-output': ShellOutputData;
+    /**
+     * Progress indicator for long-running tools.
+     */
+    'tool-progress': ToolProgressData;
+    /**
+     * Reasoning/thinking step from deep reasoning tool.
+     */
+    'reasoning-step': ReasoningStepData;
+    /**
+     * Memory retrieval results.
+     */
+    'memory-result': MemoryResultData;
+};
+/** Sub-agent streaming data. */
+export interface SubAgentStreamData {
+    /** Unique identifier for the sub-agent instance. */
+    agentId: string;
+    /** Role of the sub-agent. */
+    role: string;
+    /** Streamed text content. */
+    text: string;
+    /** Status of the sub-agent stream. */
+    status: 'streaming' | 'complete' | 'error';
+    /** Error message if status is 'error'. */
+    error?: string;
+}
+/** Search result data from file/code search. */
+export interface SearchResultData {
+    /** File path relative to workspace root. */
+    path: string;
+    /** Matched content snippet. */
+    content: string;
+    /** Number of matches in the file. */
+    matches: number;
+    /** Line number of the first match. */
+    line?: number;
+    /** Search pattern used. */
+    pattern?: string;
+}
+/** File content data for transient streaming. */
+export interface FileContentData {
+    /** Absolute or relative file path. */
+    path: string;
+    /** File content. */
+    content: string;
+    /** Whether content was truncated due to size limits. */
+    truncated: boolean;
+    /** Total file size in bytes. */
+    totalBytes?: number;
+    /** MIME type of the file. */
+    mimeType?: string;
+    /** Language identifier for syntax highlighting. */
+    language?: string;
+    /** Line range if partial content. */
+    lineRange?: {
+        start: number;
+        end: number;
+    };
+}
+/** Shell command output data. */
+export interface ShellOutputData {
+    /** Command that was executed. */
+    command: string;
+    /** Command output (stdout + stderr). */
+    output: string;
+    /** Exit code of the command. */
+    exitCode: number;
+    /** Working directory where command was executed. */
+    cwd?: string;
+    /** Whether output was truncated. */
+    truncated?: boolean;
+    /** Execution duration in milliseconds. */
+    durationMs?: number;
+}
+/** Tool progress indicator data. */
+export interface ToolProgressData {
+    /** Name of the tool being executed. */
+    toolName: string;
+    /** Progress percentage (0-100). */
+    progress: number;
+    /** Human-readable progress message. */
+    message: string;
+    /** Estimated time remaining in milliseconds. */
+    estimatedRemaining?: number;
+    /** Current step/total steps format. */
+    step?: {
+        current: number;
+        total: number;
+    };
+}
+/** Reasoning step from deep reasoning tool. */
+export interface ReasoningStepData {
+    /** Step number in the reasoning chain. */
+    stepNumber: number;
+    /** Total estimated steps. */
+    totalSteps: number;
+    /** The reasoning thought content. */
+    thought: string;
+    /** Whether this is a revision of a previous thought. */
+    isRevision?: boolean;
+    /** Which thought number is being revised. */
+    revisesThought?: number;
+    /** Branch identifier for alternative reasoning paths. */
+    branchId?: string;
+}
+/** Memory retrieval result data. */
+export interface MemoryResultData {
+    /** Memory entry content. */
+    content: string;
+    /** Similarity score (0-1). */
+    score: number;
+    /** Metadata associated with the memory. */
+    metadata?: Record<string, unknown>;
+    /** When the memory was stored. */
+    timestamp?: string;
+}
+/** Type helper to get data type for a specific part type. */
+export type DataPartType<K extends keyof AgentDataParts> = AgentDataParts[K];
+/** Type helper for creating typed data parts. */
+export interface TypedDataPart<K extends keyof AgentDataParts> {
+    type: K;
+    id?: string;
+    data: AgentDataParts[K];
+}
+/** Union of all possible data parts. */
+export type AnyDataPart = {
+    [K in keyof AgentDataParts]: TypedDataPart<K>;
+}[keyof AgentDataParts];
+//# sourceMappingURL=data-parts.d.ts.map

package/dist/streaming/data-parts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"data-parts.d.ts","sourceRoot":"","sources":["../../src/streaming/data-parts.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAMH;;;GAGG;AACH,MAAM,MAAM,cAAc,GAAG;IAC3B;;;OAGG;IACH,kBAAkB,EAAE,kBAAkB,CAAC;IAEvC;;OAEG;IACH,eAAe,EAAE,gBAAgB,CAAC;IAElC;;OAEG;IACH,cAAc,EAAE,eAAe,CAAC;IAEhC;;OAEG;IACH,cAAc,EAAE,eAAe,CAAC;IAEhC;;OAEG;IACH,eAAe,EAAE,gBAAgB,CAAC;IAElC;;OAEG;IACH,gBAAgB,EAAE,iBAAiB,CAAC;IAEpC;;OAEG;IACH,eAAe,EAAE,gBAAgB,CAAC;CACnC,CAAC;AAMF,gCAAgC;AAChC,MAAM,WAAW,kBAAkB;IACjC,oDAAoD;IACpD,OAAO,EAAE,MAAM,CAAC;IAEhB,6BAA6B;IAC7B,IAAI,EAAE,MAAM,CAAC;IAEb,6BAA6B;IAC7B,IAAI,EAAE,MAAM,CAAC;IAEb,sCAAsC;IACtC,MAAM,EAAE,WAAW,GAAG,UAAU,GAAG,OAAO,CAAC;IAE3C,0CAA0C;IAC1C,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,gDAAgD;AAChD,MAAM,WAAW,gBAAgB;IAC/B,4CAA4C;IAC5C,IAAI,EAAE,MAAM,CAAC;IAEb,+BAA+B;IAC/B,OAAO,EAAE,MAAM,CAAC;IAEhB,qCAAqC;IACrC,OAAO,EAAE,MAAM,CAAC;IAEhB,sCAAsC;IACtC,IAAI,CAAC,EAAE,MAAM,CAAC;IAEd,2BAA2B;IAC3B,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,iDAAiD;AACjD,MAAM,WAAW,eAAe;IAC9B,sCAAsC;IACtC,IAAI,EAAE,MAAM,CAAC;IAEb,oBAAoB;IACpB,OAAO,EAAE,MAAM,CAAC;IAEhB,wDAAwD;IACxD,SAAS,EAAE,OAAO,CAAC;IAEnB,gCAAgC;IAChC,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB,6BAA6B;IAC7B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB,mDAAmD;IACnD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB,qCAAqC;IACrC,SAAS,CAAC,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,CAAC;CAC5C;AAED,iCAAiC;AACjC,MAAM,WAAW,eAAe;IAC9B,iCAAiC;IACjC,OAAO,EAAE,MAAM,CAAC;IAEhB,wCAAwC;IACxC,MAAM,EAAE,MAAM,CAAC;IAEf,gCAAgC;IAChC,QAAQ,EAAE,MAAM,CAAC;IAEjB,oDAAoD;IACpD,GAAG,CAAC,EAAE,MAAM,CAAC;IAEb,oCAAoC;IACpC,SAAS,CAAC,EAAE,OAAO,CAAC;IAEpB,0CAA0C;IAC1C,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,oCAAoC;AACpC,MAAM,WAAW,gBAAgB;IAC/B,uCAAuC;IACvC,QAAQ,EAAE,MAAM,CAAC;IAEjB,mCAAmC;IACnC,QAAQ,EAAE,MAAM,CAAC;IAEjB,uCAAuC;IACvC,OAAO,EAAE,MAAM,CAAC;IAEhB,gDAAgD;IAChD,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAE5B,uCAAuC;IACvC,IAAI,CAAC,EAAE;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC;CAC3C;AAED,+CAA+C;AAC/C,MAAM,WAAW,iBAAiB;IAChC,0CAA0C;IAC1C,UAAU,EAAE,MAAM,CAAC;IAEnB,6BAA6B;IAC7B,UAAU,EAAE,MAAM,CAAC;IAEnB,qCAAqC;IACrC,OAAO,EAAE,MAAM,CAAC;IAEhB,wDAAwD;IACxD,UAAU,CAAC,EAAE,OAAO,CAAC;IAErB,6CAA6C;IAC7C,cAAc,CAAC,EAAE,MAAM,CAAC;IAExB,yDAAyD;IACzD,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,oCAAoC;AACpC,MAAM,WAAW,gBAAgB;IAC/B,4BAA4B;IAC5B,OAAO,EAAE,MAAM,CAAC;IAEhB,8BAA8B;IAC9B,KAAK,EAAE,MAAM,CAAC;IAEd,2CAA2C;IAC3C,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAEnC,kCAAkC;IAClC,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAMD,6DAA6D;AAC7D,MAAM,MAAM,YAAY,CAAC,CAAC,SAAS,MAAM,cAAc,IAAI,cAAc,CAAC,CAAC,CAAC,CAAC;AAE7E,iDAAiD;AACjD,MAAM,WAAW,aAAa,CAAC,CAAC,SAAS,MAAM,cAAc;IAC3D,IAAI,EAAE,CAAC,CAAC;IACR,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,cAAc,CAAC,CAAC,CAAC,CAAC;CACzB;AAED,wCAAwC;AACxC,MAAM,MAAM,WAAW,GAAG;KACvB,CAAC,IAAI,MAAM,cAAc,GAAG,aAAa,CAAC,CAAC,CAAC;CAC9C,CAAC,MAAM,cAAc,CAAC,CAAC"}

package/dist/streaming/data-parts.js

@@ -0,0 +1,14 @@
+/**
+ * @fileoverview Custom data part types for AI SDK streaming.
+ * These types define the shape of transient data streamed during agent execution.
+ *
+ * Usage with AI SDK:
+ * ```typescript
+ * import type { DataStreamWriter } from 'ai';
+ *
+ * const writer: DataStreamWriter = ...;
+ * writer.writeData({ type: 'file-content', data: { path: '/foo.ts', content: '...', truncated: false } });
+ * ```
+ */
+export {};
+//# sourceMappingURL=data-parts.js.map

package/dist/streaming/data-parts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"data-parts.js","sourceRoot":"","sources":["../../src/streaming/data-parts.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG"}

package/dist/streaming/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * @agntk/core - Streaming Module
+ *
+ * Exports for transient streaming and custom data parts.
+ */
+export { type AgentDataParts, type SubAgentStreamData, type SearchResultData, type FileContentData, type ShellOutputData, type ToolProgressData, type ReasoningStepData, type MemoryResultData, type DataPartType, type TypedDataPart, type AnyDataPart, } from './data-parts.js';
+export { withTransientStreaming, writeTransient, streamTransient, streamFileContent, streamShellOutput, streamSearchResult, streamProgress, streamReasoningStep, streamSubAgent, type TransientStreamWriter, type TransientToolContext, } from './transient.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/streaming/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/streaming/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,EACL,KAAK,cAAc,EACnB,KAAK,kBAAkB,EACvB,KAAK,gBAAgB,EACrB,KAAK,eAAe,EACpB,KAAK,eAAe,EACpB,KAAK,gBAAgB,EACrB,KAAK,iBAAiB,EACtB,KAAK,gBAAgB,EACrB,KAAK,YAAY,EACjB,KAAK,aAAa,EAClB,KAAK,WAAW,GACjB,MAAM,cAAc,CAAC;AAGtB,OAAO,EACL,sBAAsB,EACtB,cAAc,EACd,eAAe,EACf,iBAAiB,EACjB,iBAAiB,EACjB,kBAAkB,EAClB,cAAc,EACd,mBAAmB,EACnB,cAAc,EACd,KAAK,qBAAqB,EAC1B,KAAK,oBAAoB,GAC1B,MAAM,aAAa,CAAC"}

package/dist/streaming/index.js

@@ -0,0 +1,10 @@
+/**
+ * @agntk/core - Streaming Module
+ *
+ * Exports for transient streaming and custom data parts.
+ */
+// Data part types
+export {} from './data-parts.js';
+// Transient streaming
+export { withTransientStreaming, writeTransient, streamTransient, streamFileContent, streamShellOutput, streamSearchResult, streamProgress, streamReasoningStep, streamSubAgent, } from './transient.js';
+//# sourceMappingURL=index.js.map

package/dist/streaming/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/streaming/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,kBAAkB;AAClB,OAAO,EAYN,MAAM,cAAc,CAAC;AAEtB,sBAAsB;AACtB,OAAO,EACL,sBAAsB,EACtB,cAAc,EACd,eAAe,EACf,iBAAiB,EACjB,iBAAiB,EACjB,kBAAkB,EAClB,cAAc,EACd,mBAAmB,EACnB,cAAc,GAGf,MAAM,aAAa,CAAC"}

package/dist/streaming/transient.d.ts

@@ -0,0 +1,136 @@
+/**
+ * @agntk/core - Transient Streaming Infrastructure
+ *
+ * Enables tools to stream data to the UI without persisting to conversation context.
+ * This keeps the context window lean while providing rich UI feedback.
+ */
+import type { Tool } from 'ai';
+import type { ToolContext } from '../types/lifecycle.js';
+import type { AgentDataParts } from './data-parts.js';
+/**
+ * Interface for UI stream writer.
+ * Compatible with AI SDK's DataStreamWriter.
+ */
+export interface TransientStreamWriter {
+    writeData(data: unknown): void;
+}
+/**
+ * Enhanced tool context with transient streaming capabilities.
+ * Uses intersection type to extend ToolContext without conflicts.
+ */
+export type TransientToolContext = ToolContext & {
+    /** Helper to stream typed transient data */
+    stream: <K extends keyof AgentDataParts>(type: K, data: AgentDataParts[K]) => void;
+};
+/**
+ * Tool set is a record of tools keyed by name.
+ */
+type ToolSet = Record<string, Tool>;
+/**
+ * Wrap tools to enable transient streaming.
+ *
+ * Tools wrapped with this function will have access to a `stream()` helper
+ * in their context that allows streaming data to the UI without adding
+ * it to the conversation context.
+ *
+ * @param tools - Record of tools to wrap
+ * @param writer - Stream writer for sending data to the client
+ * @returns Wrapped tools with transient streaming enabled
+ *
+ * @example
+ * ```typescript
+ * const wrappedTools = withTransientStreaming(myTools, dataStream);
+ *
+ * // Inside a tool's execute function:
+ * execute: async (input, ctx) => {
+ *   ctx.stream('file-content', {
+ *     path: input.path,
+ *     content: fileContent,
+ *     truncated: false,
+ *   });
+ *   return `Read ${input.path}`;
+ * }
+ * ```
+ */
+export declare function withTransientStreaming(tools: ToolSet, writer: TransientStreamWriter): ToolSet;
+/**
+ * Stream typed transient data to the UI.
+ *
+ * @param writer - Stream writer instance
+ * @param type - Data part type
+ * @param data - Data to stream
+ */
+export declare function writeTransient<K extends keyof AgentDataParts>(writer: TransientStreamWriter, type: K, data: AgentDataParts[K]): void;
+/**
+ * Helper for tools to stream transient data from within their execute function.
+ *
+ * @param ctx - Tool context (must have writer)
+ * @param type - Data part type
+ * @param data - Data to stream
+ *
+ * @example
+ * ```typescript
+ * // Inside a tool's execute function:
+ * streamTransient(ctx, 'shell-output', {
+ *   command: 'npm test',
+ *   output: result.stdout,
+ *   exitCode: result.code,
+ * });
+ * ```
+ */
+export declare function streamTransient<K extends keyof AgentDataParts>(ctx: ToolContext, type: K, data: AgentDataParts[K]): void;
+/**
+ * Stream file content transiently.
+ */
+export declare function streamFileContent(ctx: ToolContext, path: string, content: string, options?: {
+    truncated?: boolean;
+    totalBytes?: number;
+    language?: string;
+    lineRange?: {
+        start: number;
+        end: number;
+    };
+}): void;
+/**
+ * Stream shell output transiently.
+ */
+export declare function streamShellOutput(ctx: ToolContext, command: string, output: string, exitCode: number, options?: {
+    cwd?: string;
+    truncated?: boolean;
+    durationMs?: number;
+}): void;
+/**
+ * Stream search results transiently.
+ */
+export declare function streamSearchResult(ctx: ToolContext, path: string, content: string, matches: number, options?: {
+    line?: number;
+    pattern?: string;
+}): void;
+/**
+ * Stream tool progress update transiently.
+ */
+export declare function streamProgress(ctx: ToolContext, toolName: string, progress: number, message: string, options?: {
+    estimatedRemaining?: number;
+    step?: {
+        current: number;
+        total: number;
+    };
+}): void;
+/**
+ * Stream reasoning step transiently.
+ *
+ * @internal Forward-designed for CLI streaming feature. No production callers yet.
+ */
+export declare function streamReasoningStep(ctx: ToolContext, stepNumber: number, totalSteps: number, thought: string, options?: {
+    isRevision?: boolean;
+    revisesThought?: number;
+    branchId?: string;
+}): void;
+/**
+ * Stream sub-agent output transiently.
+ *
+ * @internal Forward-designed for CLI streaming feature. No production callers yet.
+ */
+export declare function streamSubAgent(ctx: ToolContext, agentId: string, role: string, text: string, status: 'streaming' | 'complete' | 'error', error?: string): void;
+export {};
+//# sourceMappingURL=transient.d.ts.map

package/dist/streaming/transient.d.ts.map

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

package/dist/streaming/transient.js

@@ -0,0 +1,201 @@
+/**
+ * @agntk/core - Transient Streaming Infrastructure
+ *
+ * Enables tools to stream data to the UI without persisting to conversation context.
+ * This keeps the context window lean while providing rich UI feedback.
+ */
+import { createLogger } from '@agntk/logger';
+const log = createLogger('@agntk/core:streaming');
+// ============================================================================
+// Main API: withTransientStreaming
+// ============================================================================
+/**
+ * Wrap tools to enable transient streaming.
+ *
+ * Tools wrapped with this function will have access to a `stream()` helper
+ * in their context that allows streaming data to the UI without adding
+ * it to the conversation context.
+ *
+ * @param tools - Record of tools to wrap
+ * @param writer - Stream writer for sending data to the client
+ * @returns Wrapped tools with transient streaming enabled
+ *
+ * @example
+ * ```typescript
+ * const wrappedTools = withTransientStreaming(myTools, dataStream);
+ *
+ * // Inside a tool's execute function:
+ * execute: async (input, ctx) => {
+ *   ctx.stream('file-content', {
+ *     path: input.path,
+ *     content: fileContent,
+ *     truncated: false,
+ *   });
+ *   return `Read ${input.path}`;
+ * }
+ * ```
+ */
+export function withTransientStreaming(tools, writer) {
+    const wrappedTools = {};
+    for (const [name, tool] of Object.entries(tools)) {
+        wrappedTools[name] = wrapToolWithTransient(tool, writer, name);
+    }
+    return wrappedTools;
+}
+// ============================================================================
+// Tool Wrapping
+// ============================================================================
+/**
+ * Wrap a single tool with transient streaming capabilities.
+ */
+function wrapToolWithTransient(tool, writer, toolName) {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const originalExecute = tool.execute;
+    if (!originalExecute) {
+        return tool;
+    }
+    return {
+        ...tool,
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        execute: async (input, options) => {
+            // Create enhanced context with streaming helper
+            const enhancedContext = {
+                ...(options || {}),
+                agentId: options?.agentId || 'unknown',
+                stepNumber: options?.stepNumber || 0,
+                writer,
+                stream: (type, data) => {
+                    writeTransient(writer, type, data);
+                },
+            };
+            return originalExecute(input, enhancedContext);
+        },
+    };
+}
+// ============================================================================
+// Transient Data Writers
+// ============================================================================
+/**
+ * Stream typed transient data to the UI.
+ *
+ * @param writer - Stream writer instance
+ * @param type - Data part type
+ * @param data - Data to stream
+ */
+export function writeTransient(writer, type, data) {
+    const dataPart = {
+        type,
+        data,
+    };
+    writer.writeData({
+        ...dataPart,
+        transient: true,
+    });
+}
+/**
+ * Helper for tools to stream transient data from within their execute function.
+ *
+ * @param ctx - Tool context (must have writer)
+ * @param type - Data part type
+ * @param data - Data to stream
+ *
+ * @example
+ * ```typescript
+ * // Inside a tool's execute function:
+ * streamTransient(ctx, 'shell-output', {
+ *   command: 'npm test',
+ *   output: result.stdout,
+ *   exitCode: result.code,
+ * });
+ * ```
+ */
+export function streamTransient(ctx, type, data) {
+    // Cast to TransientStreamWriter - they have compatible interfaces
+    const writer = ctx.writer;
+    if (writer) {
+        writeTransient(writer, type, data);
+    }
+}
+// ============================================================================
+// Specialized Streamers
+// ============================================================================
+/**
+ * Stream file content transiently.
+ */
+export function streamFileContent(ctx, path, content, options = {}) {
+    streamTransient(ctx, 'file-content', {
+        path,
+        content,
+        truncated: options.truncated ?? false,
+        totalBytes: options.totalBytes,
+        language: options.language,
+        lineRange: options.lineRange,
+    });
+}
+/**
+ * Stream shell output transiently.
+ */
+export function streamShellOutput(ctx, command, output, exitCode, options = {}) {
+    streamTransient(ctx, 'shell-output', {
+        command,
+        output,
+        exitCode,
+        cwd: options.cwd,
+        truncated: options.truncated,
+        durationMs: options.durationMs,
+    });
+}
+/**
+ * Stream search results transiently.
+ */
+export function streamSearchResult(ctx, path, content, matches, options = {}) {
+    streamTransient(ctx, 'search-result', {
+        path,
+        content,
+        matches,
+        line: options.line,
+        pattern: options.pattern,
+    });
+}
+/**
+ * Stream tool progress update transiently.
+ */
+export function streamProgress(ctx, toolName, progress, message, options = {}) {
+    streamTransient(ctx, 'tool-progress', {
+        toolName,
+        progress,
+        message,
+        estimatedRemaining: options.estimatedRemaining,
+        step: options.step,
+    });
+}
+/**
+ * Stream reasoning step transiently.
+ *
+ * @internal Forward-designed for CLI streaming feature. No production callers yet.
+ */
+export function streamReasoningStep(ctx, stepNumber, totalSteps, thought, options = {}) {
+    streamTransient(ctx, 'reasoning-step', {
+        stepNumber,
+        totalSteps,
+        thought,
+        isRevision: options.isRevision,
+        revisesThought: options.revisesThought,
+        branchId: options.branchId,
+    });
+}
+/**
+ * Stream sub-agent output transiently.
+ *
+ * @internal Forward-designed for CLI streaming feature. No production callers yet.
+ */
+export function streamSubAgent(ctx, agentId, role, text, status, error) {
+    streamTransient(ctx, 'sub-agent-stream', {
+        agentId,
+        role,
+        text,
+        status,
+        error,
+    });
+}
+//# sourceMappingURL=transient.js.map

package/dist/streaming/transient.js.map

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

package/dist/system-detect.d.ts

@@ -0,0 +1,59 @@
+/**
+ * @fileoverview System hardware detection for automatic Ollama model selection.
+ *
+ * Detects available RAM/VRAM and selects the largest Qwen3 model the system
+ * can comfortably run. Falls back conservatively — better to run a smaller
+ * model fast than a larger model that swaps to disk.
+ *
+ * Memory thresholds (Q4_K_M quantization):
+ *   qwen3:8b   ~5-6 GB  → needs ≥8 GB total RAM
+ *   qwen3:14b  ~8-10 GB → needs ≥16 GB total RAM
+ *   qwen3:32b  ~18-22 GB → needs ≥32 GB total RAM
+ */
+export interface SystemProfile {
+    /** Total system RAM in GB */
+    totalRAMGb: number;
+    /** Usable memory for models in GB (accounts for OS overhead + GPU sharing) */
+    usableForModelsGb: number;
+    /** Platform: darwin, linux, win32 */
+    platform: string;
+    /** Whether this is Apple Silicon (unified memory architecture) */
+    isAppleSilicon: boolean;
+    /** NVIDIA VRAM in GB, if detected */
+    nvidiaVRAMGb: number | null;
+}
+export type OllamaModelTier = 'small' | 'medium' | 'large';
+export interface OllamaModelRecommendation {
+    /** Recommended tier */
+    tier: OllamaModelTier;
+    /** Model tag to pull/use (e.g. "qwen3:8b") */
+    fast: string;
+    standard: string;
+    reasoning: string;
+    powerful: string;
+    /** Human-readable reason */
+    reason: string;
+}
+/**
+ * Detect system hardware profile.
+ */
+export declare function detectSystem(): SystemProfile;
+/**
+ * Select the best Ollama model tier based on system capabilities.
+ *
+ * Thresholds (usable memory for the model weights):
+ *   < 6 GB  → too small, warn user
+ *   6-10 GB → small (qwen3:8b everywhere)
+ *   10-18 GB → medium (qwen3:14b for standard+)
+ *   18+ GB  → large (qwen3:32b for reasoning/powerful)
+ */
+export declare function recommendOllamaModels(profile?: SystemProfile): OllamaModelRecommendation;
+/**
+ * Check which models Ollama already has pulled.
+ */
+export declare function getOllamaModels(baseUrl?: string): Promise<string[]>;
+/**
+ * Check if a specific model is available in Ollama.
+ */
+export declare function hasOllamaModel(model: string, baseUrl?: string): Promise<boolean>;
+//# sourceMappingURL=system-detect.d.ts.map

package/dist/system-detect.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"system-detect.d.ts","sourceRoot":"","sources":["../src/system-detect.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAYH,MAAM,WAAW,aAAa;IAC5B,6BAA6B;IAC7B,UAAU,EAAE,MAAM,CAAC;IACnB,8EAA8E;IAC9E,iBAAiB,EAAE,MAAM,CAAC;IAC1B,qCAAqC;IACrC,QAAQ,EAAE,MAAM,CAAC;IACjB,kEAAkE;IAClE,cAAc,EAAE,OAAO,CAAC;IACxB,qCAAqC;IACrC,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;CAC7B;AAED,MAAM,MAAM,eAAe,GAAG,OAAO,GAAG,QAAQ,GAAG,OAAO,CAAC;AAE3D,MAAM,WAAW,yBAAyB;IACxC,uBAAuB;IACvB,IAAI,EAAE,eAAe,CAAC;IACtB,8CAA8C;IAC9C,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,4BAA4B;IAC5B,MAAM,EAAE,MAAM,CAAC;CAChB;AAqED;;GAEG;AACH,wBAAgB,YAAY,IAAI,aAAa,CAuC5C;AAMD;;;;;;;;GAQG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,CAAC,EAAE,aAAa,GAAG,yBAAyB,CA8BxF;AAMD;;GAEG;AACH,wBAAsB,eAAe,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAoBzE;AAED;;GAEG;AACH,wBAAsB,cAAc,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAKtF"}