@looopy-ai/core 1.0.1

package/LICENSE

@@ -0,0 +1,9 @@
+MIT License
+
+Copyright (c) 2025 Greg Bacchus
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/dist/core/agent.d.ts

@@ -0,0 +1,53 @@
+import { Observable } from 'rxjs';
+import type { MessageStore } from '../stores/messages/interfaces';
+import type { AgentState, AgentStore } from '../types/agent';
+import type { AuthContext } from '../types/context';
+import type { AnyEvent } from '../types/event';
+import type { LLMProvider } from '../types/llm';
+import type { Message } from '../types/message';
+import type { ToolProvider } from '../types/tools';
+export interface AgentConfig {
+    agentId: string;
+    contextId: string;
+    llmProvider: LLMProvider;
+    toolProviders: ToolProvider[];
+    messageStore: MessageStore;
+    agentStore?: AgentStore;
+    autoCompact?: boolean;
+    maxMessages?: number;
+    systemPrompt?: string;
+    logger?: import('pino').Logger;
+}
+export interface GetMessagesOptions {
+    maxMessages?: number;
+    maxTokens?: number;
+}
+export declare class Agent {
+    private readonly config;
+    private _state;
+    private logger;
+    private sigtermHandler?;
+    private sigintHandler?;
+    private shuttingDown;
+    private shutdownComplete;
+    constructor(config: AgentConfig);
+    get state(): Readonly<AgentState>;
+    get agentId(): string;
+    get contextId(): string;
+    private initialize;
+    startTurn(userMessage: string | null, options?: {
+        authContext?: AuthContext;
+        taskId?: string;
+    }): Promise<Observable<AnyEvent>>;
+    private executeInternal;
+    shutdown(): Promise<void>;
+    getMessages(options?: GetMessagesOptions): Promise<Message[]>;
+    clear(): Promise<void>;
+    private persistState;
+    private persistStateSafely;
+    private loadPersistedState;
+    private loadMessages;
+    private checkAndCompact;
+    private registerSignalHandlers;
+    private removeSignalHandlers;
+}

package/dist/core/agent.js

@@ -0,0 +1,416 @@
+import { catchError, concat, Observable, of, tap } from 'rxjs';
+import { createTaskStatusEvent } from '../events';
+import { addMessagesCompactedEvent, addMessagesLoadedEvent, completeAgentInitializeSpan, completeAgentTurnSpan, failAgentInitializeSpan, failAgentTurnSpan, setResumeAttributes, setTurnCountAttribute, startAgentInitializeSpan, startAgentTurnSpan, } from '../observability/spans';
+import { serializeError } from '../utils/error';
+import { registerSignalListener, unregisterSignalListener } from '../utils/process-signals';
+import { getLogger } from './logger';
+import { runLoop } from './loop';
+export class Agent {
+    config;
+    _state;
+    logger;
+    sigtermHandler;
+    sigintHandler;
+    shuttingDown = false;
+    shutdownComplete = false;
+    constructor(config) {
+        this.config = {
+            autoCompact: false,
+            maxMessages: 100,
+            systemPrompt: 'You are a helpful AI assistant.',
+            ...config,
+            logger: config.logger?.child({ contextId: config.contextId }) ||
+                getLogger({ contextId: config.contextId }),
+        };
+        this.logger = this.config.logger.child({ component: 'agent' });
+        this._state = {
+            status: 'created',
+            turnCount: 0,
+            lastActivity: new Date(),
+            createdAt: new Date(),
+        };
+        this.logger.debug('Agent created');
+        this.persistStateSafely();
+        this.registerSignalHandlers();
+    }
+    get state() {
+        return { ...this._state };
+    }
+    get agentId() {
+        return this.config.agentId;
+    }
+    get contextId() {
+        return this.config.contextId;
+    }
+    async initialize(parentContext) {
+        if (this._state.status !== 'created') {
+            return;
+        }
+        const { span } = startAgentInitializeSpan({
+            agentId: this.config.agentId,
+            contextId: this.config.contextId,
+            parentContext,
+        });
+        try {
+            this.logger.info('Initializing agent');
+            const hasStoredState = await this.loadPersistedState();
+            const existingMessages = await this.config.messageStore.getAll(this.config.contextId);
+            if (existingMessages.length > 0) {
+                this.logger.info({ messageCount: existingMessages.length }, 'Resuming agent with existing message history');
+                if (!hasStoredState) {
+                    this._state.turnCount = Math.floor(existingMessages.length / 2);
+                }
+                setResumeAttributes(span, existingMessages.length);
+            }
+            this._state.status = 'ready';
+            this._state.lastActivity = new Date();
+            await this.persistState();
+            this.logger.info({ status: this._state.status }, 'Agent initialized');
+            completeAgentInitializeSpan(span);
+        }
+        catch (error) {
+            this._state.status = 'error';
+            this._state.error = serializeError(error);
+            this.logger.error({ error: serializeError(error) }, 'Failed to initialize agent');
+            await this.persistState();
+            failAgentInitializeSpan(span, error);
+            throw error;
+        }
+    }
+    async startTurn(userMessage, options) {
+        const turnNumber = this._state.turnCount + 1;
+        const taskId = options?.taskId || `${this.config.contextId}-turn-${turnNumber}-${Date.now()}`;
+        const logger = this.logger.child({ taskId, turnNumber });
+        const { span: rootSpan, traceContext: rootContext, tapFinish, } = startAgentTurnSpan({
+            agentId: this.config.agentId,
+            taskId,
+            contextId: this.config.contextId,
+            turnNumber,
+            userMessage,
+        });
+        logger.trace({ userMessage, spanName: `agent.turn[${this.config.agentId}]` }, 'Created agent turn span with input');
+        try {
+            if (this._state.status === 'created') {
+                await this.initialize(rootContext);
+            }
+            if (this._state.status === 'shutdown') {
+                const error = new Error('Cannot execute turn: Agent has been shutdown');
+                logger.error(error.message);
+                failAgentTurnSpan(rootSpan, error);
+                return of(createTaskStatusEvent({
+                    contextId: this.config.contextId,
+                    taskId,
+                    status: 'failed',
+                    message: error.message,
+                    metadata: { error: error.message },
+                }));
+            }
+            if (this._state.status === 'error') {
+                const error = new Error(`Cannot execute turn: Agent is in error state: ${this._state.error?.message}`);
+                logger.error(error.message);
+                failAgentTurnSpan(rootSpan, error);
+                return of(createTaskStatusEvent({
+                    contextId: this.config.contextId,
+                    taskId,
+                    status: 'failed',
+                    message: error.message,
+                    metadata: { error: error.message },
+                }));
+            }
+            if (this._state.status === 'busy') {
+                const error = new Error('Cannot execute turn: Agent is already executing a turn');
+                logger.error(error.message);
+                failAgentTurnSpan(rootSpan, error);
+                return of(createTaskStatusEvent({
+                    contextId: this.config.contextId,
+                    taskId,
+                    status: 'failed',
+                    message: error.message,
+                    metadata: { error: error.message },
+                }));
+            }
+            logger.info({ userMessage }, 'Starting turn');
+            this._state.status = 'busy';
+            this._state.lastActivity = new Date();
+            await this.persistState();
+            return this.executeInternal(userMessage, taskId, options?.authContext, rootSpan, rootContext, this.logger.child({ taskId, turnNumber })).pipe(tapFinish);
+        }
+        catch (error) {
+            const err = error;
+            logger.error({ error: err }, 'Failed to start turn');
+            failAgentTurnSpan(rootSpan, err);
+            return of(createTaskStatusEvent({
+                contextId: this.config.contextId,
+                taskId,
+                status: 'failed',
+                message: err.message,
+                metadata: { error: err.message },
+            }));
+        }
+    }
+    executeInternal(userMessage, taskId, authContext, turnSpan, turnContext, logger) {
+        const turnNumber = this._state.turnCount + 1;
+        return concat(new Observable((observer) => {
+            const execute = async () => {
+                try {
+                    const messages = await this.loadMessages();
+                    addMessagesLoadedEvent(turnSpan, messages.length);
+                    if (userMessage) {
+                        messages.push({
+                            role: 'user',
+                            content: userMessage,
+                        });
+                        await this.config.messageStore.append(this.config.contextId, [
+                            { role: 'user', content: userMessage },
+                        ]);
+                    }
+                    logger.debug({
+                        messageCount: messages.length,
+                    }, 'Loaded messages for turn');
+                    const turnEvents$ = runLoop({
+                        agentId: this.config.agentId,
+                        contextId: this.config.contextId,
+                        taskId,
+                        authContext,
+                        parentContext: turnContext,
+                        toolProviders: this.config.toolProviders,
+                        logger: this.config.logger.child({ taskId, turnNumber }),
+                        turnNumber,
+                    }, {
+                        llmProvider: this.config.llmProvider,
+                        maxIterations: 5,
+                        stopOnToolError: false,
+                    }, messages).pipe(tap(async (event) => {
+                        switch (event.kind) {
+                            case 'content-complete':
+                                if (event.content || event.toolCalls) {
+                                    await this.config.messageStore.append(this.config.contextId, [
+                                        {
+                                            role: 'assistant',
+                                            content: event.content,
+                                            toolCalls: event.toolCalls?.map((toolCall) => ({
+                                                id: toolCall.id,
+                                                type: toolCall.type,
+                                                function: {
+                                                    name: toolCall.function.name,
+                                                    arguments: toolCall.function.arguments || {},
+                                                },
+                                            })),
+                                        },
+                                    ]);
+                                }
+                                break;
+                            case 'tool-complete': {
+                                const message = {
+                                    role: 'tool',
+                                    content: JSON.stringify({
+                                        success: event.success,
+                                        result: event.result,
+                                        error: event.error,
+                                    }),
+                                    toolCallId: event.toolCallId,
+                                };
+                                logger.debug({ message }, 'Saving tool message to message store');
+                                await this.config.messageStore.append(this.config.contextId, [message]);
+                                break;
+                            }
+                            default:
+                                break;
+                        }
+                    }));
+                    turnEvents$.subscribe({
+                        next: (event) => {
+                            observer.next(event);
+                        },
+                        error: (error) => {
+                            logger.error({ error }, 'Turn execution failed');
+                            failAgentTurnSpan(turnSpan, error);
+                            observer.error(error);
+                        },
+                        complete: async () => {
+                            try {
+                                this._state.turnCount++;
+                                this._state.lastActivity = new Date();
+                                this._state.status = 'ready';
+                                await this.persistState();
+                                setTurnCountAttribute(turnSpan, this._state.turnCount);
+                                if (this.config.autoCompact) {
+                                    await this.checkAndCompact();
+                                    addMessagesCompactedEvent(turnSpan);
+                                }
+                                logger.info({ turnCount: this._state.turnCount }, 'Turn completed');
+                                completeAgentTurnSpan(turnSpan);
+                                observer.complete();
+                            }
+                            catch (error) {
+                                logger.error({ error }, 'Failed to save turn results');
+                                failAgentTurnSpan(turnSpan, error);
+                                observer.error(error);
+                            }
+                        },
+                    });
+                }
+                catch (error) {
+                    logger.error({ error }, 'Failed to prepare turn');
+                    failAgentTurnSpan(turnSpan, error);
+                    observer.error(error);
+                }
+            };
+            execute();
+        }).pipe(catchError((error) => {
+            this._state.status = 'error';
+            this._state.error = error;
+            this.persistStateSafely();
+            failAgentTurnSpan(turnSpan, error);
+            return of(createTaskStatusEvent({
+                contextId: this.config.contextId,
+                taskId,
+                status: 'failed',
+                message: error.message,
+                metadata: { error: error.message },
+            }));
+        })));
+    }
+    async shutdown() {
+        if (this.shutdownComplete) {
+            this.logger.debug('Agent already shutdown');
+            return;
+        }
+        if (this.shuttingDown) {
+            this.logger.debug('Shutdown already in progress');
+            return;
+        }
+        this.shuttingDown = true;
+        this.logger.info('Shutting down agent');
+        try {
+            this._state.status = 'shutdown';
+            this._state.lastActivity = new Date();
+            await this.persistState();
+            this.removeSignalHandlers();
+            this.shutdownComplete = true;
+            this.config.logger.info('Agent shutdown complete');
+        }
+        catch (error) {
+            this.config.logger.error({ error }, 'Failed to shutdown agent');
+            throw error;
+        }
+        finally {
+            this.shuttingDown = false;
+        }
+    }
+    async getMessages(options = {}) {
+        if (options.maxMessages || options.maxTokens) {
+            return this.config.messageStore.getRecent(this.config.contextId, options);
+        }
+        return this.config.messageStore.getAll(this.config.contextId);
+    }
+    async clear() {
+        this.logger.info('Clearing agent data');
+        try {
+            await this.config.messageStore.clear(this.config.contextId);
+            this._state.turnCount = 0;
+            this._state.lastActivity = new Date();
+            await this.persistState();
+            this.logger.info('Agent data cleared');
+        }
+        catch (error) {
+            this.logger.error({ error }, 'Failed to clear agent');
+            throw error;
+        }
+    }
+    async persistState() {
+        if (!this.config.agentStore) {
+            return;
+        }
+        const stateToPersist = {
+            ...this._state,
+            lastActivity: new Date(this._state.lastActivity),
+            createdAt: new Date(this._state.createdAt),
+        };
+        await this.config.agentStore.save(this.config.contextId, stateToPersist);
+    }
+    persistStateSafely() {
+        if (!this.config.agentStore) {
+            return;
+        }
+        void this.persistState().catch((error) => {
+            this.logger.error({ error }, 'Failed to persist agent state');
+        });
+    }
+    async loadPersistedState() {
+        if (!this.config.agentStore) {
+            return false;
+        }
+        const persistedState = await this.config.agentStore.load(this.config.contextId);
+        if (!persistedState) {
+            return false;
+        }
+        this._state = {
+            ...persistedState,
+            lastActivity: new Date(persistedState.lastActivity),
+            createdAt: new Date(persistedState.createdAt),
+        };
+        this.logger.debug({ turnCount: this._state.turnCount, status: this._state.status }, 'Loaded agent state from agent store');
+        return true;
+    }
+    async loadMessages() {
+        return this.config.messageStore.getRecent(this.config.contextId, {
+            maxMessages: this.config.maxMessages,
+        });
+    }
+    async checkAndCompact() {
+        const allMessages = await this.config.messageStore.getAll(this.config.contextId);
+        if (allMessages.length > this.config.maxMessages) {
+            this.logger.info({
+                messageCount: allMessages.length,
+                maxMessages: this.config.maxMessages,
+            }, 'Auto-compacting message history');
+            await this.config.messageStore.compact(this.config.contextId, {
+                strategy: 'summarization',
+                keepRecent: Math.floor(this.config.maxMessages * 0.5),
+            });
+        }
+    }
+    registerSignalHandlers() {
+        if (typeof process === 'undefined') {
+            return;
+        }
+        if (this.sigtermHandler || typeof process === 'undefined') {
+            return;
+        }
+        if (!this.sigtermHandler) {
+            this.sigtermHandler = async () => {
+                this.logger.info('Received SIGTERM signal. Initiating graceful shutdown.');
+                try {
+                    await this.shutdown();
+                }
+                catch (error) {
+                    this.logger.error({ error }, 'Failed to shutdown agent after SIGTERM signal');
+                }
+            };
+            registerSignalListener('SIGTERM', this.sigtermHandler);
+        }
+        if (!this.sigintHandler) {
+            const sigintHandler = async () => {
+                this.logger.info('Received SIGINT signal. Initiating graceful shutdown.');
+                try {
+                    await this.shutdown();
+                }
+                catch (error) {
+                    this.logger.error({ error }, 'Failed to shutdown agent after SIGINT signal');
+                }
+            };
+            registerSignalListener('SIGINT', sigintHandler);
+        }
+    }
+    removeSignalHandlers() {
+        if (this.sigtermHandler) {
+            unregisterSignalListener('SIGTERM', this.sigtermHandler);
+            this.sigtermHandler = undefined;
+        }
+        if (this.sigintHandler) {
+            unregisterSignalListener('SIGINT', this.sigintHandler);
+            this.sigintHandler = undefined;
+        }
+    }
+}

package/dist/core/cleanup.d.ts

@@ -0,0 +1,12 @@
+import type { ArtifactStore } from '../types/artifact';
+import type { TaskStateStore } from '../types/state';
+export declare class StateCleanupService {
+    private taskStateStore;
+    private artifactStore;
+    private intervalMs;
+    private intervalHandle?;
+    constructor(taskStateStore: TaskStateStore, artifactStore: ArtifactStore, intervalMs?: number);
+    start(): void;
+    stop(): void;
+    cleanupExpiredTasks(): Promise<void>;
+}

package/dist/core/cleanup.js

@@ -0,0 +1,45 @@
+export class StateCleanupService {
+    taskStateStore;
+    artifactStore;
+    intervalMs;
+    intervalHandle;
+    constructor(taskStateStore, artifactStore, intervalMs = 60 * 60 * 1000) {
+        this.taskStateStore = taskStateStore;
+        this.artifactStore = artifactStore;
+        this.intervalMs = intervalMs;
+    }
+    start() {
+        if (this.intervalHandle) {
+            throw new Error('Cleanup service already started');
+        }
+        this.intervalHandle = setInterval(() => this.cleanupExpiredTasks(), this.intervalMs);
+    }
+    stop() {
+        if (this.intervalHandle) {
+            clearInterval(this.intervalHandle);
+            this.intervalHandle = undefined;
+        }
+    }
+    async cleanupExpiredTasks() {
+        const cutoffDate = new Date(Date.now() - 24 * 60 * 60 * 1000);
+        const taskIds = await this.taskStateStore.listTasks({
+            completedAfter: cutoffDate,
+        });
+        for (const taskId of taskIds) {
+            try {
+                const state = await this.taskStateStore.load(taskId);
+                if (!state)
+                    continue;
+                if (state.artifactIds && state.contextId) {
+                    for (const artifactId of state.artifactIds) {
+                        await this.artifactStore.deleteArtifact(state.contextId, artifactId);
+                    }
+                }
+                await this.taskStateStore.delete(taskId);
+            }
+            catch (error) {
+                console.error(`Failed to cleanup task ${taskId}:`, error);
+            }
+        }
+    }
+}

package/dist/core/index.d.ts

@@ -0,0 +1,3 @@
+export { Agent, type AgentConfig, type GetMessagesOptions } from './agent';
+export { StateCleanupService } from './cleanup';
+export { createLogger, getLogger, type LoggerConfig, type LogLevel, setDefaultLogger, } from './logger';

package/dist/core/index.js

@@ -0,0 +1,3 @@
+export { Agent } from './agent';
+export { StateCleanupService } from './cleanup';
+export { createLogger, getLogger, setDefaultLogger, } from './logger';

package/dist/core/iteration.d.ts

@@ -0,0 +1,5 @@
+import { type Observable } from 'rxjs';
+import type { AnyEvent } from '../types/event';
+import type { Message } from '../types/message';
+import type { IterationConfig, LoopContext } from './types';
+export declare const runIteration: (context: LoopContext, config: IterationConfig, history: Message[]) => Observable<AnyEvent>;

package/dist/core/iteration.js

@@ -0,0 +1,60 @@
+import { concat, defer, filter, map, mergeMap, shareReplay } from 'rxjs';
+import { startLLMCallSpan, startLoopIterationSpan } from '../observability/spans';
+import { runToolCall } from './tools';
+export const runIteration = (context, config, history) => {
+    const logger = context.logger.child({
+        component: 'iteration',
+        iteration: config.iterationNumber,
+    });
+    const { traceContext: iterationContext, tapFinish: finishIterationSpan } = startLoopIterationSpan({ ...context, logger }, config.iterationNumber);
+    const llmEvents$ = defer(async () => {
+        const messages = prepareMessages(context, history);
+        const tools = await prepareTools(context.toolProviders);
+        return { messages, tools };
+    }).pipe(mergeMap(({ messages, tools }) => {
+        const { tapFinish: finishLLMCallSpan } = startLLMCallSpan({ ...context, parentContext: iterationContext }, messages);
+        return config.llmProvider
+            .call({
+            messages,
+            tools,
+            stream: true,
+            sessionId: context.taskId,
+        })
+            .pipe(map((event) => ({
+            contextId: context.contextId,
+            taskId: context.taskId,
+            ...event,
+        })), finishLLMCallSpan);
+    }), shareReplay());
+    const toolEvents$ = llmEvents$.pipe(filter((event) => event.kind === 'tool-call'), mergeMap((event) => runToolCall({
+        ...context,
+        logger: context.logger.child({ iteration: config.iterationNumber }),
+        parentContext: iterationContext,
+    }, event)));
+    return concat(llmEvents$, toolEvents$).pipe(finishIterationSpan);
+};
+const prepareMessages = (context, history) => {
+    const messages = [];
+    if (context.systemPrompt) {
+        messages.push({
+            role: 'system',
+            content: context.systemPrompt,
+            name: 'system-prompt',
+        });
+    }
+    if (context.skillPrompts) {
+        for (const [name, content] of Object.entries(context.skillPrompts)) {
+            messages.push({
+                role: 'system',
+                content,
+                name,
+            });
+        }
+    }
+    return messages.concat(history);
+};
+const prepareTools = async (toolProviders) => {
+    const toolPromises = toolProviders.map((p) => p.getTools());
+    const toolArrays = await Promise.all(toolPromises);
+    return toolArrays.flat();
+};

package/dist/core/logger.d.ts

@@ -0,0 +1,11 @@
+import pino from 'pino';
+export type LogLevel = 'trace' | 'debug' | 'info' | 'warn' | 'error' | 'fatal';
+export interface LoggerConfig {
+    level?: LogLevel;
+    pretty?: boolean;
+    context?: Record<string, unknown>;
+}
+export declare function createLogger(config?: LoggerConfig): pino.Logger;
+export declare let DEFAULT_LOGGER: pino.Logger<never, boolean>;
+export declare function setDefaultLogger(logger: pino.Logger): void;
+export declare function getLogger(context: Record<string, unknown>): pino.Logger;

package/dist/core/logger.js

@@ -0,0 +1,31 @@
+import pino from 'pino';
+export function createLogger(config = {}) {
+    const { level = 'info', pretty = false, context = {} } = config;
+    const pinoConfig = {
+        level,
+        base: context,
+        timestamp: pino.stdTimeFunctions.isoTime,
+    };
+    if (pretty) {
+        return pino(pinoConfig, pino.transport({
+            target: 'pino-pretty',
+            options: {
+                colorize: true,
+                translateTime: 'HH:MM:ss.l',
+                ignore: 'pid,hostname',
+                singleLine: false,
+            },
+        }));
+    }
+    return pino(pinoConfig);
+}
+export let DEFAULT_LOGGER = createLogger({
+    level: process.env.LOG_LEVEL || 'info',
+    pretty: process.env.NODE_ENV !== 'production',
+});
+export function setDefaultLogger(logger) {
+    DEFAULT_LOGGER = logger;
+}
+export function getLogger(context) {
+    return DEFAULT_LOGGER.child(context);
+}

package/dist/core/loop.d.ts

@@ -0,0 +1,5 @@
+import { type Observable } from 'rxjs';
+import type { AnyEvent } from '../types/event';
+import type { Message } from '../types/message';
+import type { LoopConfig, TurnContext } from './types';
+export declare const runLoop: (context: TurnContext, config: LoopConfig, history: Message[]) => Observable<AnyEvent>;