@primo-ai/core 0.1.4 → 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';
@@ -41,6 +41,8 @@ export declare class Agent {
     private sessionManager?;
     private contextBuilder;
     private activeAbortController;
+    private lastContext?;
+    constructor(config: AgentSimpleConfig);
     constructor(config: AgentConfig, deps?: AgentDependencies);
     use(factory: Processor | PluginFactory): void;
     teardown(): Promise<void>;
@@ -50,6 +52,12 @@ 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>;
@@ -57,22 +65,20 @@ export declare class Agent {
     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;
-    /**
-     * Continue an existing session by restoring its context and running the pipeline
-     * with a new user message.
-     */
-    continue(sessionId: string, message: string, signal?: globalThis.AbortSignal): Promise<AgentRunResult>;
-    /**
-     * Continue an existing session with streaming. Yields StreamEvents for the
-     * continued conversation.
-     */
-    continueStream(sessionId: string, message: string, signal?: globalThis.AbortSignal): AsyncGenerator<import('@primo-ai/sdk').StreamEvent>;
+    /** 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

@@ -23,6 +23,7 @@ export class Agent {
     sessionManager;
     contextBuilder;
     activeAbortController = null;
+    lastContext;
     constructor(config, deps) {
         this.config = config;
         this.modelFactory = deps?.modelFactory ?? new ModelFactory();
@@ -72,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;
     }
@@ -79,7 +92,7 @@ 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 }, {});
@@ -97,6 +110,7 @@ export class Agent {
                 sessionId: context.request.sessionId,
                 autoCheckpoint: this._autoCheckpoint,
             });
+            this.lastContext = finalCtx;
             return {
                 response: finalCtx.iteration.response ?? '',
                 tokenUsage: finalCtx.session.totalTokenUsage ?? { input: 0, output: 0 },
@@ -151,7 +165,7 @@ 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 }, {});
@@ -162,13 +176,22 @@ export class Agent {
             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: 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;
@@ -181,7 +204,7 @@ 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;
@@ -191,13 +214,19 @@ export class Agent {
             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: 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;
@@ -215,103 +244,9 @@ export class Agent {
         this.activeAbortController?.abort();
         this.activeAbortController = null;
     }
-    /**
-     * Continue an existing session by restoring its context and running the pipeline
-     * with a new user message.
-     */
-    async continue(sessionId, message, signal) {
-        if (signal?.aborted)
-            throw new DOMException('Agent continue aborted', 'AbortError');
-        if (!this.sessionManager)
-            throw new Error('Session manager is required for continue()');
-        const context = await this.sessionManager.restore(sessionId);
-        context.request.input = message;
-        if (context.session.messageHistory) {
-            context.session.messageHistory.push({ role: 'user', content: message });
-        }
-        else {
-            context.session.messageHistory = [{ role: 'user', content: message }];
-        }
-        context.iteration = { step: 0 };
-        this._pluginManager.freezeHarnessInstances();
-        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 {
-            const { context: finalCtx, compatRetries } = await this.orchestrator.runLoop(context, {
-                maxIterations: maxIter,
-                signal: controller.signal,
-                modelString: this.config.model,
-                sessionId: context.request.sessionId,
-                autoCheckpoint: this._autoCheckpoint,
-            });
-            return {
-                response: finalCtx.iteration.response ?? '',
-                tokenUsage: finalCtx.session.totalTokenUsage ?? { input: 0, output: 0 },
-                sessionId: context.request.sessionId,
-                compatRetries,
-            };
-        }
-        catch (error) {
-            this.autoInvalidateModel(error);
-            throw error;
-        }
-        finally {
-            this.activeAbortController = null;
-            try {
-                await hm.invoke('agent.end', { sessionId: context.request.sessionId }, {});
-            }
-            catch { /* hook error must not mask original */ }
-        }
-    }
-    /**
-     * Continue an existing session with streaming. Yields StreamEvents for the
-     * continued conversation.
-     */
-    async *continueStream(sessionId, message, signal) {
-        if (signal?.aborted)
-            throw new DOMException('Agent continue stream aborted', 'AbortError');
-        if (!this.sessionManager)
-            throw new Error('Session manager is required for continueStream()');
-        const context = await this.sessionManager.restore(sessionId);
-        context.request.input = message;
-        if (context.session.messageHistory) {
-            context.session.messageHistory.push({ role: 'user', content: message });
-        }
-        else {
-            context.session.messageHistory = [{ role: 'user', content: message }];
-        }
-        context.iteration = { step: 0 };
-        this._pluginManager.freezeHarnessInstances();
-        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, {
-                maxIterations: maxIter,
-                signal: controller.signal,
-                modelString: this.config.model,
-                sessionId: context.request.sessionId,
-                autoCheckpoint: this._autoCheckpoint,
-            });
-        }
-        finally {
-            this.activeAbortController = null;
-            try {
-                await hm.invoke('agent.end', { sessionId: context.request.sessionId }, {});
-            }
-            catch { /* hook error must not mask original */ }
-        }
+    /** 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() {
@@ -334,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) {
@@ -373,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,5 +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;
-    once(eventType: string): Promise<unknown>;
+    /** 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,7 +32,23 @@ export class EventBus {
         set.add(handler);
         return () => set.delete(handler);
     }
-    once(eventType) {
+    /** 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();

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';

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';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@primo-ai/core",
-  "version": "0.1.4",
+  "version": "0.1.5",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -21,9 +21,9 @@
     "ai": "^6.0.177",
     "js-tiktoken": "^1.0.21",
     "zod": "^4.4.3",
-    "@primo-ai/sdk": "0.1.4",
-    "@primo-ai/observability": "0.1.4",
-    "@primo-ai/tools": "0.1.4"
+    "@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",