@primo-ai/core 0.1.3 → 0.1.5

package/dist/agent.d.ts

@@ -1,4 +1,4 @@
-import type { AgentConfig, CheckpointStore, PipelineStageConfig, Processor, SessionManager, Tracer } from '@primo-ai/sdk';
+import type { AgentConfig, AgentSimpleConfig, CheckpointStore, PipelineStageConfig, Processor, SessionManager, Tracer } from '@primo-ai/sdk';
 import { PipelineRunner } from './pipeline.js';
 import { serialize } from './serialize.js';
 import { ToolRegistry } from './tool-registry.js';
@@ -40,6 +40,9 @@ export declare class Agent {
     private orchestrator;
     private sessionManager?;
     private contextBuilder;
+    private activeAbortController;
+    private lastContext?;
+    constructor(config: AgentSimpleConfig);
     constructor(config: AgentConfig, deps?: AgentDependencies);
     use(factory: Processor | PluginFactory): void;
     teardown(): Promise<void>;
@@ -49,17 +52,33 @@ export declare class Agent {
     get eventBus(): import('./event-bus.js').EventBus;
     get eventSystem(): import('./event-system.js').EventSystem;
     get state(): import('./state-machine.js').AgentState;
+    /** Subscribe to an event type. Returns an unsubscribe function. */
+    on(eventType: string, handler: (data?: unknown) => void): () => void;
+    /** Subscribe to an event type for at most one emission. */
+    once(eventType: string, handler: (data?: unknown) => void): void;
+    /** Remove a specific handler for an event type. */
+    off(eventType: string, handler: (data?: unknown) => void): void;
     get _contextBuilder(): ContextBuilder;
     run(input: string, signal?: globalThis.AbortSignal): Promise<AgentRunResult>;
     resume(sessionId: string, signal?: globalThis.AbortSignal): Promise<AgentRunResult>;
     stream(input: string, signal?: globalThis.AbortSignal): AsyncGenerator<string>;
     streamEvents(input: string, signal?: globalThis.AbortSignal): AsyncGenerator<import('@primo-ai/sdk').StreamEvent>;
+    /** Abort a running agent. Idempotent — no-op if agent is not running. */
+    abort(): void;
+    /** Clear conversation state so the next run/stream starts a fresh session. */
+    reset(): void;
     /** Clear the cached model so the next run re-resolves from the factory. */
     invalidateModel(): void;
     /** Auto-invalidate cached model when the error indicates auth failure or model-not-found. */
     private autoInvalidateModel;
     private getLLM;
+    private buildContext;
     private createContext;
     private registerTools;
     private registerBuiltinProcessors;
 }
+/**
+ * Create an Agent from a simple config. Convenience wrapper for single-agent usage.
+ * For advanced usage (Dynamic config, providerOptions, custom dependencies), use `new Agent(config, deps)`.
+ */
+export declare function createAgent(config: AgentSimpleConfig): Agent;

package/dist/agent.js

@@ -22,6 +22,8 @@ export class Agent {
     orchestrator;
     sessionManager;
     contextBuilder;
+    activeAbortController = null;
+    lastContext;
     constructor(config, deps) {
         this.config = config;
         this.modelFactory = deps?.modelFactory ?? new ModelFactory();
@@ -71,6 +73,18 @@ export class Agent {
     get state() {
         return this.orchestrator.state;
     }
+    /** Subscribe to an event type. Returns an unsubscribe function. */
+    on(eventType, handler) {
+        return this.eventBus.subscribe(eventType, handler);
+    }
+    /** Subscribe to an event type for at most one emission. */
+    once(eventType, handler) {
+        this.eventBus.once(eventType, handler);
+    }
+    /** Remove a specific handler for an event type. */
+    off(eventType, handler) {
+        this.eventBus.unsubscribe(eventType, handler);
+    }
     get _contextBuilder() {
         return this.contextBuilder;
     }
@@ -78,19 +92,25 @@ export class Agent {
         if (signal?.aborted)
             throw new DOMException('Agent run aborted', 'AbortError');
         this._pluginManager.freezeHarnessInstances();
-        const context = await this.createContext(input);
+        const context = await this.buildContext(input);
         const hm = this._pluginManager.hookManager;
         // agent.start hook
         await hm.invoke('agent.start', { sessionId: context.request.sessionId, request: context.request, agentConfig: this.config }, {});
         const maxIter = typeof this.config.maxIterations === 'number' ? this.config.maxIterations : 10;
+        const controller = new AbortController();
+        this.activeAbortController = controller;
+        if (signal) {
+            signal.addEventListener('abort', () => controller.abort(), { once: true });
+        }
         try {
             const { context: finalCtx, compatRetries } = await this.orchestrator.runLoop(context, {
                 maxIterations: maxIter,
-                signal,
+                signal: controller.signal,
                 modelString: this.config.model,
                 sessionId: context.request.sessionId,
                 autoCheckpoint: this._autoCheckpoint,
             });
+            this.lastContext = finalCtx;
             return {
                 response: finalCtx.iteration.response ?? '',
                 tokenUsage: finalCtx.session.totalTokenUsage ?? { input: 0, output: 0 },
@@ -103,6 +123,7 @@ export class Agent {
             throw error;
         }
         finally {
+            this.activeAbortController = null;
             // agent.end hook — always fires, even on error; suppress hook errors to preserve original
             try {
                 await hm.invoke('agent.end', { sessionId: context.request.sessionId }, {});
@@ -144,21 +165,36 @@ export class Agent {
     async *stream(input, signal) {
         if (signal?.aborted)
             throw new DOMException('Agent stream aborted', 'AbortError');
-        const context = await this.createContext(input);
+        const context = await this.buildContext(input);
         const hm = this._pluginManager.hookManager;
         // agent.start hook
         await hm.invoke('agent.start', { sessionId: context.request.sessionId, request: context.request, agentConfig: this.config }, {});
         const maxIter = typeof this.config.maxIterations === 'number' ? this.config.maxIterations : 10;
+        const controller = new AbortController();
+        this.activeAbortController = controller;
+        if (signal) {
+            signal.addEventListener('abort', () => controller.abort(), { once: true });
+        }
         try {
-            yield* this.orchestrator.streamLoop(context, {
+            let finalCtx;
+            for await (const event of this.orchestrator.streamEvents(context, {
                 maxIterations: maxIter,
-                signal,
+                signal: controller.signal,
                 modelString: this.config.model,
                 sessionId: context.request.sessionId,
                 autoCheckpoint: this._autoCheckpoint,
-            });
+            })) {
+                if (event.type === 'text_delta')
+                    yield event.text;
+                if (event.type === 'suspended')
+                    yield ` [suspended: ${event.reason}]`;
+                if (event.type === 'complete')
+                    finalCtx = event.context;
+            }
+            this.lastContext = finalCtx;
         }
         finally {
+            this.activeAbortController = null;
             try {
                 await hm.invoke('agent.end', { sessionId: context.request.sessionId }, {});
             }
@@ -168,26 +204,50 @@ export class Agent {
     async *streamEvents(input, signal) {
         if (signal?.aborted)
             throw new DOMException('Agent stream aborted', 'AbortError');
-        const context = await this.createContext(input);
+        const context = await this.buildContext(input);
         const hm = this._pluginManager.hookManager;
         await hm.invoke('agent.start', { sessionId: context.request.sessionId, request: context.request, agentConfig: this.config }, {});
         const maxIter = typeof this.config.maxIterations === 'number' ? this.config.maxIterations : 10;
+        const controller = new AbortController();
+        this.activeAbortController = controller;
+        if (signal) {
+            signal.addEventListener('abort', () => controller.abort(), { once: true });
+        }
         try {
-            yield* this.orchestrator.streamEvents(context, {
+            let finalCtx;
+            for await (const event of this.orchestrator.streamEvents(context, {
                 maxIterations: maxIter,
-                signal,
+                signal: controller.signal,
                 modelString: this.config.model,
                 sessionId: context.request.sessionId,
                 autoCheckpoint: this._autoCheckpoint,
-            });
+            })) {
+                if (event.type === 'complete')
+                    finalCtx = event.context;
+                yield event;
+            }
+            this.lastContext = finalCtx;
         }
         finally {
+            this.activeAbortController = null;
             try {
                 await hm.invoke('agent.end', { sessionId: context.request.sessionId }, {});
             }
             catch { /* hook error must not mask original */ }
         }
     }
+    /** Abort a running agent. Idempotent — no-op if agent is not running. */
+    abort() {
+        if (!this.orchestrator.stateMachine.canTransition('cancelled'))
+            return;
+        this.orchestrator.stateMachine.transition('cancelled');
+        this.activeAbortController?.abort();
+        this.activeAbortController = null;
+    }
+    /** Clear conversation state so the next run/stream starts a fresh session. */
+    reset() {
+        this.lastContext = undefined;
+    }
     /** Clear the cached model so the next run re-resolves from the factory. */
     invalidateModel() {
         this._model = null;
@@ -209,6 +269,24 @@ export class Agent {
             tracer: this._tracer,
         });
     }
+    async buildContext(input) {
+        if (this.lastContext) {
+            return {
+                request: { input, sessionId: this.lastContext.request.sessionId },
+                agent: { config: { ...this.config }, promptFragments: [], toolDeclarations: [] },
+                iteration: { step: 0 },
+                session: {
+                    messageHistory: [
+                        ...(this.lastContext.session.messageHistory ?? []),
+                        { role: 'user', content: input },
+                    ],
+                    totalTokenUsage: this.lastContext.session.totalTokenUsage,
+                    custom: { ...this.lastContext.session.custom },
+                },
+            };
+        }
+        return this.createContext(input);
+    }
     async createContext(input) {
         let sessionId = crypto.randomUUID();
         if (this.sessionManager) {
@@ -248,6 +326,13 @@ export class Agent {
         this.runner.register(processOutputProcessor);
     }
 }
+/**
+ * Create an Agent from a simple config. Convenience wrapper for single-agent usage.
+ * For advanced usage (Dynamic config, providerOptions, custom dependencies), use `new Agent(config, deps)`.
+ */
+export function createAgent(config) {
+    return new Agent(config);
+}
 function isAuthOrNotFoundError(error) {
     if (error instanceof AuthError || error instanceof ModelNotFoundError)
         return true;

package/dist/event-bus.d.ts

@@ -4,4 +4,10 @@ export declare class EventBus {
     constructor(onError?: ((error: unknown, eventType: string) => void) | undefined);
     emit(eventType: string, data?: unknown): void;
     subscribe(eventType: string, handler: (data?: unknown) => void): () => void;
+    /** Remove a specific handler for an event type. */
+    unsubscribe(eventType: string, handler: (data?: unknown) => void): void;
+    /** Register a handler that fires at most once, then auto-unsubscribes. */
+    once(eventType: string, handler: (data?: unknown) => void): void;
+    /** Promise-based once: returns a Promise that resolves on the next emission. */
+    oncePromise(eventType: string): Promise<unknown>;
 }

package/dist/event-bus.js

@@ -32,4 +32,28 @@ export class EventBus {
         set.add(handler);
         return () => set.delete(handler);
     }
+    /** Remove a specific handler for an event type. */
+    unsubscribe(eventType, handler) {
+        const set = this.handlers.get(eventType);
+        if (set) {
+            set.delete(handler);
+        }
+    }
+    /** Register a handler that fires at most once, then auto-unsubscribes. */
+    once(eventType, handler) {
+        const wrapped = (data) => {
+            handler(data);
+            this.unsubscribe(eventType, wrapped);
+        };
+        this.subscribe(eventType, wrapped);
+    }
+    /** Promise-based once: returns a Promise that resolves on the next emission. */
+    oncePromise(eventType) {
+        return new Promise((resolve) => {
+            const unsub = this.subscribe(eventType, (data) => {
+                unsub();
+                resolve(data);
+            });
+        });
+    }
 }

package/dist/gateways/gateway-chain.d.ts

@@ -5,4 +5,8 @@ export declare class GatewayChain {
     register(gateway: ModelGateway): void;
     resolve(modelString: string): Promise<LanguageModel>;
     get size(): number;
+    listGateways(): Array<{
+        name: string;
+        canResolve: (model: string) => boolean;
+    }>;
 }

package/dist/gateways/gateway-chain.js

@@ -14,4 +14,10 @@ export class GatewayChain {
     get size() {
         return this.gateways.length;
     }
+    listGateways() {
+        return this.gateways.map(gw => ({
+            name: gw.name,
+            canResolve: (model) => gw.canResolve(model),
+        }));
+    }
 }

package/dist/hook-manager.js

@@ -8,6 +8,7 @@ const HOOK_TO_EVENT = {
     'llm.after': 'llm:after',
     'tool.before': 'tool:before',
     'tool.after': 'tool:after',
+    'iteration.end': 'iteration:end',
     'error': 'error',
 };
 export class HookManager {

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 export { PipelineRunner, type PipelineRunnerOptions } from './pipeline.js';
-export { Agent, type AgentDependencies, type AgentRunResult } from './agent.js';
+export { Agent, createAgent, type AgentDependencies, type AgentRunResult } from './agent.js';
 export { LLMInvoker, type LLMInvokerOptions, type LLMInvokeInput, type LLMInvokeResult, type LLMStreamHandle } from './llm-invoker.js';
 export { resolveModel, registerProvider, parseModel, type ParsedModel } from './model-resolver.js';
 export { streamWithRetry, type RetryOptions } from './retry.js';
@@ -10,6 +10,7 @@ export { StorageReplayBackend } from './storage-replay-backend.js';
 export { HookManager, type HookManagerOptions } from './hook-manager.js';
 export { ToolRegistry, type AiSdkToolSchema, type ToolRegistryOptions } from './tool-registry.js';
 export { FilesystemSessionStorage } from './session-storage.js';
+export { SqliteSessionStorage } from './session-storage-sqlite.js';
 export { SessionPersistence } from './session-persistence.js';
 export { SessionManagerImpl } from './session-manager.js';
 export { createSubAgentTool } from './sub-agent.js';
@@ -31,3 +32,5 @@ export { TiktokenCounter } from './token-counter.js';
 export type { StreamEvent } from '@primo-ai/sdk';
 export { OpenAICompatibleGateway } from './gateways/openai-compatible-gateway.js';
 export { AgentForgeError, RecoverableError, FatalError, AuthError, ModelNotFoundError, ToolExecutionError, type AgentErrorOptions, } from './errors.js';
+export { PermissionManager } from './pending-permission.js';
+export type { PendingPermission } from './pending-permission.js';

package/dist/index.js

@@ -1,6 +1,6 @@
 // @primo-ai/core — Agent Loop, Processor Pipeline, Context, Tool Registry
 export { PipelineRunner } from './pipeline.js';
-export { Agent } from './agent.js';
+export { Agent, createAgent } from './agent.js';
 export { LLMInvoker } from './llm-invoker.js';
 export { resolveModel, registerProvider, parseModel } from './model-resolver.js';
 export { streamWithRetry } from './retry.js';
@@ -11,6 +11,7 @@ export { StorageReplayBackend } from './storage-replay-backend.js';
 export { HookManager } from './hook-manager.js';
 export { ToolRegistry } from './tool-registry.js';
 export { FilesystemSessionStorage } from './session-storage.js';
+export { SqliteSessionStorage } from './session-storage-sqlite.js';
 export { SessionPersistence } from './session-persistence.js';
 export { SessionManagerImpl } from './session-manager.js';
 export { createSubAgentTool } from './sub-agent.js';
@@ -31,3 +32,4 @@ export { HarnessAPIImpl } from './harness.js';
 export { TiktokenCounter } from './token-counter.js';
 export { OpenAICompatibleGateway } from './gateways/openai-compatible-gateway.js';
 export { AgentForgeError, RecoverableError, FatalError, AuthError, ModelNotFoundError, ToolExecutionError, } from './errors.js';
+export { PermissionManager } from './pending-permission.js';

package/dist/llm-invoker.d.ts

@@ -17,14 +17,14 @@ export interface LLMInvokeInput {
 }
 export interface LLMInvokeResult {
     response: string;
-    tokenUsage: TokenUsage;
+    tokenUsage: TokenUsage | null;
 }
 export interface LLMStreamHandle {
     fullStream: AsyncIterable<unknown>;
-    usage: Promise<TokenUsage>;
+    usage: Promise<TokenUsage | null>;
     reasoning: Promise<string | undefined>;
 }
-export declare function extractTokenUsage(usage: unknown): TokenUsage;
+export declare function extractTokenUsage(usage: unknown): TokenUsage | null;
 export declare class LLMInvoker {
     private options;
     constructor(options: LLMInvokerOptions);

package/dist/llm-invoker.js

@@ -3,14 +3,15 @@ import { SpanType } from '@primo-ai/sdk';
 import { streamWithRetry } from './retry.js';
 export function extractTokenUsage(usage) {
     const u = usage;
-    return {
-        input: typeof u?.inputTokens === 'number'
-            ? u.inputTokens
-            : u?.inputTokens?.total ?? 0,
-        output: typeof u?.outputTokens === 'number'
-            ? u.outputTokens
-            : u?.outputTokens?.total ?? 0,
-    };
+    if (!u)
+        return null;
+    const input = typeof u?.inputTokens === 'number'
+        ? u.inputTokens
+        : u?.inputTokens?.total ?? 0;
+    const output = typeof u?.outputTokens === 'number'
+        ? u.outputTokens
+        : u?.outputTokens?.total ?? 0;
+    return { input, output };
 }
 export class LLMInvoker {
     options;
@@ -112,7 +113,7 @@ export class LLMInvoker {
                 .catch((err) => {
                 endSpan();
                 this.options.eventBus?.emit('llm:usage_unavailable', { error: err instanceof Error ? err.message : String(err) });
-                return { input: 0, output: 0 };
+                return null;
             }),
             reasoning: Promise.resolve(result.reasoningText).catch((err) => {
                 this.options.eventBus?.emit('llm:reasoning_error', { error: err instanceof Error ? err.message : String(err) });

package/dist/loop-orchestrator.js

@@ -124,6 +124,8 @@ export class LoopOrchestrator {
                     yield event;
                     return;
                 }
+                if (event.type === 'error')
+                    throw event.error;
                 if (event.type === 'complete')
                     loopCtx = event.context;
                 yield event;
@@ -161,6 +163,14 @@ export class LoopOrchestrator {
                             yield event;
                             return;
                         }
+                        if (event.type === 'error') {
+                            if (event.recoverable) {
+                                this.eventBus?.emit('pipeline:stage_error', { stage: event.stage, error: event.error });
+                                loopBreak = true;
+                                break;
+                            }
+                            throw event.error;
+                        }
                         if (event.type === 'complete')
                             loopCtx = event.context;
                         yield event;

package/dist/model-factory.d.ts

@@ -8,5 +8,9 @@ export declare class ModelFactory {
     resolve(modelString: string): Promise<LanguageModel>;
     registerGateway(gateway: ModelGateway): void;
     registerProvider(name: string, factory: ProviderFactory): void;
+    listGateways(): Array<{
+        name: string;
+        canResolve: (model: string) => boolean;
+    }>;
 }
 export {};

package/dist/model-factory.js

@@ -36,4 +36,7 @@ export class ModelFactory {
     registerProvider(name, factory) {
         this.providerGateway.addProvider(name, factory);
     }
+    listGateways() {
+        return this.chain.listGateways();
+    }
 }

package/dist/pending-permission.d.ts

@@ -0,0 +1,16 @@
+export interface PendingPermission {
+    permissionId: string;
+    sessionId: string;
+    toolName: string;
+    args: Record<string, unknown>;
+    reason: string;
+    createdAt: string;
+}
+export declare class PermissionManager {
+    private pending;
+    awaitDecision(permission: PendingPermission): Promise<boolean>;
+    resolve(permissionId: string, approved: boolean): void;
+    list(): PendingPermission[];
+    getBySession(sessionId: string): PendingPermission[];
+    get(permissionId: string): PendingPermission | undefined;
+}

package/dist/pending-permission.js

@@ -0,0 +1,24 @@
+export class PermissionManager {
+    pending = new Map();
+    awaitDecision(permission) {
+        return new Promise((resolve) => {
+            this.pending.set(permission.permissionId, { resolve, permission });
+        });
+    }
+    resolve(permissionId, approved) {
+        const entry = this.pending.get(permissionId);
+        if (!entry)
+            throw new Error(`Permission not found: ${permissionId}`);
+        entry.resolve(approved);
+        this.pending.delete(permissionId);
+    }
+    list() {
+        return Array.from(this.pending.values()).map(e => e.permission);
+    }
+    getBySession(sessionId) {
+        return this.list().filter(p => p.sessionId === sessionId);
+    }
+    get(permissionId) {
+        return this.pending.get(permissionId)?.permission;
+    }
+}

package/dist/pipeline.d.ts

@@ -1,6 +1,6 @@
-import type { AbortSignal, PipelineContext, Processor, StageName, StreamEvent, SuspensionSignal, Tracer } from '@primo-ai/sdk';
+import type { AbortSignal, ErrorResult, PipelineContext, Processor, StageName, StreamEvent, SuspensionSignal, Tracer } from '@primo-ai/sdk';
 import type { HookManager } from './hook-manager.js';
-export type RunResult = PipelineContext | AbortSignal | SuspensionSignal;
+export type RunResult = PipelineContext | AbortSignal | SuspensionSignal | ErrorResult;
 export interface PipelineRunnerOptions {
     tracer?: Tracer;
     hookManager?: HookManager;
@@ -23,5 +23,6 @@ export declare class PipelineRunner {
     private executeStage;
     private isAbort;
     private isSuspend;
+    private isError;
     private consumeStream;
 }

package/dist/pipeline.js

@@ -100,6 +100,17 @@ export class PipelineRunner {
                         rootSpan.end();
                         return stageResult;
                     }
+                    if (this.isError(stageResult)) {
+                        stageSpan.end();
+                        if (this.hookManager) {
+                            try {
+                                await this.hookManager.invoke('error', { error: stageResult.error, stage: stageResult.stage }, {});
+                            }
+                            catch { /* hook error must not mask original */ }
+                        }
+                        rootSpan.end();
+                        return stageResult;
+                    }
                     ctx = stageResult;
                     ctx = await this.consumeStream(ctx);
                     // Fire llm.after after stream is consumed (response is now available)
@@ -155,6 +166,18 @@ export class PipelineRunner {
                         yield { type: 'suspended', suspensionId: stageResult.suspensionId, reason: stageResult.reason, checkpoint: stageResult.checkpoint };
                         return;
                     }
+                    if (this.isError(stageResult)) {
+                        stageSpan.end();
+                        if (this.hookManager) {
+                            try {
+                                await this.hookManager.invoke('error', { error: stageResult.error, stage: stageResult.stage }, {});
+                            }
+                            catch { /* hook error must not mask original */ }
+                        }
+                        rootSpan.end();
+                        yield { type: 'error', error: stageResult.error, stage: stageResult.stage, recoverable: stageResult.recoverable };
+                        return;
+                    }
                     ctx = stageResult;
                     const fullStream = ctx.iteration.fullStream;
                     if (fullStream) {
@@ -197,7 +220,7 @@ export class PipelineRunner {
                                 response: chunks.join('') || ctx.iteration.response || '',
                                 pendingToolCalls: toolCalls.length > 0 ? toolCalls : undefined,
                                 reasoningContent,
-                                tokenUsage: usage ?? pendingUsage,
+                                tokenUsage: usage ?? pendingUsage ?? undefined,
                                 fullStream: undefined,
                                 usagePromise: undefined,
                                 reasoningPromise: undefined,
@@ -242,7 +265,7 @@ export class PipelineRunner {
                 iteration: { ...currentCtx.iteration, span: stageSpan },
             });
             const result = await processor.execute(ctxWithSpan);
-            if ('type' in result && (result.type === 'abort' || result.type === 'suspend')) {
+            if ('type' in result && (result.type === 'abort' || result.type === 'suspend' || result.type === 'error')) {
                 return result;
             }
             currentCtx = deepFreeze({ ...result });
@@ -259,6 +282,9 @@ export class PipelineRunner {
     isSuspend(result) {
         return 'type' in result && result.type === 'suspend';
     }
+    isError(result) {
+        return 'type' in result && result.type === 'error';
+    }
     async consumeStream(ctx) {
         const fullStream = ctx.iteration.fullStream;
         if (!fullStream)
@@ -275,7 +301,7 @@ export class PipelineRunner {
                 response: result.chunks.join('') || ctx.iteration.response,
                 pendingToolCalls: result.toolCalls.length > 0 ? result.toolCalls : undefined,
                 reasoningContent,
-                tokenUsage: result.usage ?? pendingUsage,
+                tokenUsage: result.usage ?? pendingUsage ?? undefined,
                 fullStream: undefined,
                 usagePromise: undefined,
                 reasoningPromise: undefined,

package/dist/plugin-manager.js

@@ -52,10 +52,9 @@ export class PluginManager {
             this.initializePlugin(factory);
         }
         catch (err) {
-            this.errors.push({
-                source: filePath,
-                error: err instanceof Error ? err : new Error(String(err)),
-            });
+            const error = err instanceof Error ? err : new Error(String(err));
+            this.eventBus.emit('plugin:load_error', { source: filePath, error });
+            this.errors.push({ source: filePath, error });
         }
     }
     initializePlugin(factory) {
@@ -97,12 +96,14 @@ export class PluginManager {
                 this.resourceInstances.set(resource.id, instance);
             }
             catch (err) {
-                this.errors.push({
-                    source: `resource:${resource.id}`,
-                    error: err instanceof Error ? err : new Error(String(err)),
-                });
+                const error = err instanceof Error ? err : new Error(String(err));
+                this.eventBus.emit('plugin:resource_init_error', { source: `resource:${resource.id}`, error });
+                this.errors.push({ source: `resource:${resource.id}`, error });
             }
         }
+        if (this.errors.length > 0) {
+            throw new AggregateError(this.errors.map(e => e.error), `Plugin initialization failed for ${this.errors.length} resource(s): ${this.errors.map(e => e.source).join(', ')}`);
+        }
     }
     _shutdown = false;
     async shutdown() {
@@ -116,10 +117,9 @@ export class PluginManager {
                 await resource.stop(instance);
             }
             catch (err) {
-                this.errors.push({
-                    source: `resource:${resource.id}`,
-                    error: err instanceof Error ? err : new Error(String(err)),
-                });
+                const error = err instanceof Error ? err : new Error(String(err));
+                this.eventBus.emit('plugin:shutdown_error', { source: `resource:${resource.id}`, error });
+                this.errors.push({ source: `resource:${resource.id}`, error });
             }
         }
         this.resourceInstances.clear();

package/dist/processors/evaluate-iteration.js

@@ -24,10 +24,14 @@ export function createEvaluateIterationProcessor(deps) {
         stage: 'evaluateIteration',
         execute: async (ctx) => {
             const prevTotal = ctx.session.totalTokenUsage ?? { input: 0, output: 0 };
-            const iterUsage = ctx.iteration.tokenUsage ?? { input: 0, output: 0 };
+            const iterUsage = ctx.iteration.tokenUsage;
+            if (!iterUsage) {
+                eventBus?.emit('token:usage_unavailable', { step: ctx.iteration.step });
+            }
+            const safeUsage = iterUsage ?? { input: 0, output: 0 };
             const totalTokenUsage = {
-                input: prevTotal.input + iterUsage.input,
-                output: prevTotal.output + iterUsage.output,
+                input: prevTotal.input + safeUsage.input,
+                output: prevTotal.output + safeUsage.output,
             };
             const totalTokens = totalTokenUsage.input + totalTokenUsage.output;
             const requiredTools = ctx.agent.config.requiredTools;

package/dist/session-storage-sqlite.d.ts

@@ -0,0 +1,41 @@
+import type { SessionEvent, SessionRecord, SessionStorage, SessionStatus, Message } from '@primo-ai/sdk';
+/**
+ * SqliteSessionStorage — SQLite-backed implementation of SessionStorage.
+ *
+ * Uses `better-sqlite3` as an **optional** dependency. The module is loaded
+ * dynamically so projects that only need FilesystemSessionStorage never pay
+ * the cost (or install penalty) of the native binding.
+ *
+ * Pass `:memory:` as dbPath for an in-memory database (useful for tests).
+ */
+export declare class SqliteSessionStorage implements SessionStorage {
+    private db;
+    private stmtInsertEvent;
+    private stmtSelectEvents;
+    private stmtSelectSession;
+    private stmtUpsertSession;
+    private stmtDeleteSession;
+    private stmtSelectSessionsByStatus;
+    private stmtSelectSessionsByParent;
+    private stmtSelectAllSessions;
+    private stmtNextSeq;
+    constructor(dbPath: string);
+    private initSchema;
+    private prepareStatements;
+    append(sessionId: string, event: SessionEvent): Promise<void>;
+    read(sessionId: string): AsyncIterable<SessionEvent>;
+    list(filter?: {
+        parentSessionId?: string;
+        status?: SessionStatus;
+    }): Promise<SessionRecord[]>;
+    updateMeta(sessionId: string, meta: Partial<SessionRecord>): Promise<void>;
+    get(sessionId: string): Promise<SessionRecord | undefined>;
+    delete(sessionId: string): Promise<void>;
+    getMessages(sessionId: string, options?: {
+        limit?: number;
+        before?: string;
+    }): Promise<Message[]>;
+    /** Close the underlying database connection. */
+    close(): void;
+    private rowToRecord;
+}

package/dist/session-storage-sqlite.js

@@ -0,0 +1,239 @@
+/**
+ * SqliteSessionStorage — SQLite-backed implementation of SessionStorage.
+ *
+ * Uses `better-sqlite3` as an **optional** dependency. The module is loaded
+ * dynamically so projects that only need FilesystemSessionStorage never pay
+ * the cost (or install penalty) of the native binding.
+ *
+ * Pass `:memory:` as dbPath for an in-memory database (useful for tests).
+ */
+export class SqliteSessionStorage {
+    db;
+    // Prepared statements (lazily initialised after DB is set)
+    stmtInsertEvent;
+    stmtSelectEvents;
+    stmtSelectSession;
+    stmtUpsertSession;
+    stmtDeleteSession;
+    stmtSelectSessionsByStatus;
+    stmtSelectSessionsByParent;
+    stmtSelectAllSessions;
+    stmtNextSeq;
+    constructor(dbPath) {
+        // Dynamic import keeps better-sqlite3 truly optional
+        let Database;
+        try {
+            // eslint-disable-next-line @typescript-eslint/no-require-imports
+            Database = require('better-sqlite3');
+        }
+        catch {
+            throw new Error('better-sqlite3 is not installed. Install it as an optional dependency or use FilesystemSessionStorage instead.');
+        }
+        this.db = new Database(dbPath);
+        this.initSchema();
+        this.prepareStatements();
+    }
+    // ---------------------------------------------------------------------------
+    // Schema initialisation
+    // ---------------------------------------------------------------------------
+    initSchema() {
+        this.db.pragma('journal_mode = WAL');
+        this.db.pragma('foreign_keys = ON');
+        this.db.exec(`
+      CREATE TABLE IF NOT EXISTS sessions (
+        session_id   TEXT PRIMARY KEY,
+        parent_session_id TEXT,
+        status       TEXT NOT NULL DEFAULT 'active',
+        model        TEXT,
+        input_tokens INTEGER DEFAULT 0,
+        output_tokens INTEGER DEFAULT 0,
+        created_at   TEXT NOT NULL,
+        updated_at   TEXT NOT NULL
+      );
+
+      CREATE TABLE IF NOT EXISTS events (
+        session_id TEXT NOT NULL,
+        seq        INTEGER NOT NULL,
+        timestamp  TEXT NOT NULL,
+        type       TEXT NOT NULL,
+        payload    TEXT NOT NULL,
+        PRIMARY KEY (session_id, seq),
+        FOREIGN KEY (session_id) REFERENCES sessions(session_id) ON DELETE CASCADE
+      );
+
+      CREATE INDEX IF NOT EXISTS idx_sessions_status ON sessions(status);
+      CREATE INDEX IF NOT EXISTS idx_sessions_parent ON sessions(parent_session_id);
+      CREATE INDEX IF NOT EXISTS idx_events_session_seq ON events(session_id, seq);
+    `);
+    }
+    prepareStatements() {
+        this.stmtInsertEvent = this.db.prepare(`INSERT INTO events (session_id, seq, timestamp, type, payload) VALUES (?, ?, ?, ?, ?)`);
+        this.stmtSelectEvents = this.db.prepare(`SELECT seq, timestamp, type, payload FROM events WHERE session_id = ? ORDER BY seq ASC`);
+        this.stmtSelectSession = this.db.prepare(`SELECT session_id, parent_session_id, status, model, input_tokens, output_tokens, created_at, updated_at FROM sessions WHERE session_id = ?`);
+        this.stmtUpsertSession = this.db.prepare(`INSERT INTO sessions (session_id, parent_session_id, status, model, input_tokens, output_tokens, created_at, updated_at)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+       ON CONFLICT(session_id) DO UPDATE SET
+         parent_session_id = COALESCE(excluded.parent_session_id, sessions.parent_session_id),
+         status            = COALESCE(excluded.status, sessions.status),
+         model             = COALESCE(excluded.model, sessions.model),
+         input_tokens      = CASE WHEN excluded.input_tokens != 0 THEN excluded.input_tokens ELSE sessions.input_tokens END,
+         output_tokens     = CASE WHEN excluded.output_tokens != 0 THEN excluded.output_tokens ELSE sessions.output_tokens END,
+         updated_at        = excluded.updated_at`);
+        this.stmtDeleteSession = this.db.prepare(`DELETE FROM sessions WHERE session_id = ?`);
+        this.stmtSelectSessionsByStatus = this.db.prepare(`SELECT session_id, parent_session_id, status, model, input_tokens, output_tokens, created_at, updated_at FROM sessions WHERE status = ?`);
+        this.stmtSelectSessionsByParent = this.db.prepare(`SELECT session_id, parent_session_id, status, model, input_tokens, output_tokens, created_at, updated_at FROM sessions WHERE parent_session_id = ?`);
+        this.stmtSelectAllSessions = this.db.prepare(`SELECT session_id, parent_session_id, status, model, input_tokens, output_tokens, created_at, updated_at FROM sessions`);
+        this.stmtNextSeq = this.db.prepare(`SELECT COALESCE(MAX(seq), 0) AS max_seq FROM events WHERE session_id = ?`);
+    }
+    // ---------------------------------------------------------------------------
+    // SessionStorage interface
+    // ---------------------------------------------------------------------------
+    async append(sessionId, event) {
+        // Ensure session row exists
+        const now = new Date().toISOString();
+        this.stmtUpsertSession.run(sessionId, null, // parent_session_id
+        'active', null, // model
+        0, 0, now, now);
+        // Determine seq: if event has seq > 0 use it, otherwise auto-increment
+        let seq;
+        if (event.seq && event.seq > 0) {
+            seq = event.seq;
+        }
+        else {
+            const row = this.stmtNextSeq.get(sessionId);
+            seq = (row?.max_seq ?? 0) + 1;
+        }
+        this.stmtInsertEvent.run(sessionId, seq, event.timestamp ?? now, event.type, JSON.stringify(event.payload));
+    }
+    async *read(sessionId) {
+        const rows = this.stmtSelectEvents.all(sessionId);
+        for (const row of rows) {
+            let payload;
+            try {
+                payload = JSON.parse(row.payload);
+            }
+            catch {
+                payload = {};
+            }
+            yield {
+                seq: row.seq,
+                timestamp: row.timestamp,
+                type: row.type,
+                payload,
+            };
+        }
+    }
+    async list(filter) {
+        let rows;
+        if (filter?.status) {
+            rows = this.stmtSelectSessionsByStatus.all(filter.status);
+        }
+        else if (filter?.parentSessionId) {
+            rows = this.stmtSelectSessionsByParent.all(filter.parentSessionId);
+        }
+        else {
+            rows = this.stmtSelectAllSessions.all();
+        }
+        // If both filters are specified, we need to intersect
+        if (filter?.status && filter?.parentSessionId) {
+            // Re-fetch with both filters using a custom query
+            const stmt = this.db.prepare(`SELECT session_id, parent_session_id, status, model, input_tokens, output_tokens, created_at, updated_at
+         FROM sessions WHERE status = ? AND parent_session_id = ?`);
+            rows = stmt.all(filter.status, filter.parentSessionId);
+        }
+        return rows.map(row => this.rowToRecord(row));
+    }
+    async updateMeta(sessionId, meta) {
+        const now = new Date().toISOString();
+        const existing = await this.get(sessionId);
+        this.stmtUpsertSession.run(sessionId, meta.parentSessionId ?? existing?.parentSessionId ?? null, meta.status ?? existing?.status ?? 'active', meta.model ?? existing?.model ?? null, meta.tokenUsage?.input ?? (existing?.tokenUsage?.input ?? 0), meta.tokenUsage?.output ?? (existing?.tokenUsage?.output ?? 0), existing?.createdAt ?? now, now);
+    }
+    async get(sessionId) {
+        const row = this.stmtSelectSession.get(sessionId);
+        if (!row)
+            return undefined;
+        return this.rowToRecord(row);
+    }
+    async delete(sessionId) {
+        this.stmtDeleteSession.run(sessionId);
+    }
+    async getMessages(sessionId, options) {
+        const events = [];
+        for await (const event of this.read(sessionId)) {
+            events.push(event);
+        }
+        if (events.length === 0)
+            return [];
+        const messages = [];
+        let toolCallIdx = 0;
+        for (const event of events) {
+            const payload = event.payload;
+            if (!payload)
+                continue;
+            switch (event.type) {
+                case 'iteration:end':
+                case 'iteration.end': {
+                    if (payload.response) {
+                        messages.push({ role: 'assistant', content: payload.response });
+                    }
+                    break;
+                }
+                case 'tool:after':
+                case 'tool.after': {
+                    const toolName = payload.toolName;
+                    const content = payload.error
+                        ? String(payload.error)
+                        : typeof payload.result === 'string'
+                            ? payload.result
+                            : JSON.stringify(payload.result ?? '');
+                    const msg = {
+                        role: 'tool',
+                        content,
+                        toolCallId: `restored_${toolName}_${toolCallIdx++}`,
+                        toolName,
+                    };
+                    if (payload.error)
+                        msg.error = String(payload.error);
+                    if (payload.result !== undefined)
+                        msg.result = payload.result;
+                    messages.push(msg);
+                    break;
+                }
+                case 'error': {
+                    messages.push({ role: 'assistant', content: `[Error] ${String(payload.error)}` });
+                    break;
+                }
+                default:
+                    break;
+            }
+        }
+        // Apply pagination
+        if (options?.limit && options.limit > 0) {
+            return messages.slice(-options.limit);
+        }
+        return messages;
+    }
+    // ---------------------------------------------------------------------------
+    // Lifecycle
+    // ---------------------------------------------------------------------------
+    /** Close the underlying database connection. */
+    close() {
+        this.db.close();
+    }
+    // ---------------------------------------------------------------------------
+    // Internal helpers
+    // ---------------------------------------------------------------------------
+    rowToRecord(row) {
+        const inputTokens = typeof row.input_tokens === 'number' ? row.input_tokens : 0;
+        const outputTokens = typeof row.output_tokens === 'number' ? row.output_tokens : 0;
+        return {
+            sessionId: row.session_id,
+            parentSessionId: row.parent_session_id ?? undefined,
+            status: row.status ?? 'active',
+            model: row.model ?? undefined,
+            tokenUsage: (inputTokens || outputTokens) ? { input: inputTokens, output: outputTokens } : undefined,
+            createdAt: row.created_at,
+            updatedAt: row.updated_at,
+        };
+    }
+}

package/dist/session-storage.d.ts

@@ -15,4 +15,10 @@ export declare class FilesystemSessionStorage implements SessionStorage {
     private metaPath;
     private readMeta;
     private defaultRecord;
+    get(sessionId: string): Promise<SessionRecord | undefined>;
+    delete(sessionId: string): Promise<void>;
+    getMessages(sessionId: string, options?: {
+        limit?: number;
+        before?: string;
+    }): Promise<import('@primo-ai/sdk').Message[]>;
 }

package/dist/session-storage.js

@@ -99,4 +99,69 @@ export class FilesystemSessionStorage {
             status: 'active',
         };
     }
+    async get(sessionId) {
+        return this.readMeta(sessionId);
+    }
+    async delete(sessionId) {
+        const dir = this.sessionDir(sessionId);
+        const { rm } = await import('node:fs/promises');
+        await rm(dir, { recursive: true, force: true });
+    }
+    async getMessages(sessionId, options) {
+        const events = [];
+        for await (const event of this.read(sessionId)) {
+            events.push(event);
+        }
+        if (events.length === 0)
+            return [];
+        // Rebuild Message[] from events — same logic as SessionManagerImpl.restore()
+        const messages = [];
+        let toolCallIdx = 0;
+        for (const event of events) {
+            const payload = event.payload;
+            if (!payload)
+                continue;
+            switch (event.type) {
+                case 'iteration:end':
+                case 'iteration.end': {
+                    if (payload.response) {
+                        messages.push({ role: 'assistant', content: payload.response });
+                    }
+                    break;
+                }
+                case 'tool:after':
+                case 'tool.after': {
+                    const toolName = payload.toolName;
+                    const content = payload.error
+                        ? String(payload.error)
+                        : typeof payload.result === 'string'
+                            ? payload.result
+                            : JSON.stringify(payload.result ?? '');
+                    const msg = {
+                        role: 'tool',
+                        content,
+                        toolCallId: `restored_${toolName}_${toolCallIdx++}`,
+                        toolName,
+                    };
+                    if (payload.error)
+                        msg.error = String(payload.error);
+                    if (payload.result !== undefined)
+                        msg.result = payload.result;
+                    messages.push(msg);
+                    break;
+                }
+                case 'error': {
+                    messages.push({ role: 'assistant', content: `[Error] ${String(payload.error)}` });
+                    break;
+                }
+                default:
+                    break;
+            }
+        }
+        // Apply pagination
+        if (options?.limit && options.limit > 0) {
+            return messages.slice(-options.limit);
+        }
+        return messages;
+    }
 }

package/dist/task-manager.js

@@ -69,8 +69,12 @@ export class TaskManagerImpl {
         const handle = new InternalAsyncTaskHandle(state);
         this.handles.set(taskId, handle);
         // Fire-and-forget the async work
-        this.executeTask(state, config, prompt).catch(() => {
-            // Errors are handled inside executeTask
+        this.executeTask(state, config, prompt).catch((err) => {
+            if (state.status === 'pending' || state.status === 'running') {
+                state.status = 'failed';
+                state.error = err instanceof Error ? err : new Error(String(err));
+                this.eventBus?.emit('task:error', { taskId: state.taskId, error: state.error });
+            }
         });
         return handle;
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@primo-ai/core",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -21,15 +21,19 @@
     "ai": "^6.0.177",
     "js-tiktoken": "^1.0.21",
     "zod": "^4.4.3",
-    "@primo-ai/observability": "0.1.3",
-    "@primo-ai/sdk": "0.1.3",
-    "@primo-ai/tools": "0.1.3"
+    "@primo-ai/observability": "0.1.5",
+    "@primo-ai/tools": "0.1.5",
+    "@primo-ai/sdk": "0.1.5"
   },
   "devDependencies": {
+    "@types/better-sqlite3": "^7.6.13",
     "@types/node": "^22.15.0",
     "typescript": "^5.7.3",
     "vitest": "^3.0.5"
   },
+  "optionalDependencies": {
+    "better-sqlite3": "^12.9.0"
+  },
   "scripts": {
     "build": "tsc -p tsconfig.build.json",
     "test": "tsc --noEmit && vitest run",