@schlenkr/ragents 0.1.6 → 0.1.8

package/packages/agent/src/core/auth-guidance.ts

@@ -1,14 +0,0 @@
-const UNKNOWN_PROVIDER = "unknown";
-
-export function getProviderLoginHelp(): string {
-	return "Kein Zugang zu einem Provider. Der Schlüssel kommt aus der Konfiguration des Profils.";
-}
-
-export function formatNoModelSelectedMessage(): string {
-	return `No model selected.\n\n${getProviderLoginHelp()}\n\nThen use /model to select a model.`;
-}
-
-export function formatNoApiKeyFoundMessage(provider: string): string {
-	const providerDisplay = provider === UNKNOWN_PROVIDER ? "the selected model" : provider;
-	return `No API key found for ${providerDisplay}.\n\n${getProviderLoginHelp()}`;
-}

package/packages/agent/src/core/defaults.ts

@@ -1,3 +0,0 @@
-import type { ThinkingLevel } from "../loop/index.ts";
-
-export const DEFAULT_THINKING_LEVEL: ThinkingLevel = "medium";

package/packages/agent/src/core/extensions/index.ts

@@ -1,38 +0,0 @@
-/**
- * Extension system for agent hooks and custom tools.
- */
-
-export type { SourceInfo } from "../source-info.ts";
-export { createExtensionRuntime, loadExtensionFromFactory } from "./loader.ts";
-export type { ExtensionContextSource, ExtensionErrorListener } from "./runner.ts";
-export { ExtensionRunner, STALE_EXTENSION_MESSAGE } from "./runner.ts";
-export type {
-	AgentToolResult,
-	AgentToolUpdateCallback,
-	BeforeAgentStartEvent,
-	BeforeAgentStartEventResult,
-	BuildSystemPromptOptions,
-	ContextEvent,
-	ContextEventResult,
-	Extension,
-	ExtensionActions,
-	ExtensionAPI,
-	ExtensionContext,
-	ExtensionError,
-	ExtensionEvent,
-	ExtensionFactory,
-	ExtensionFactoryContext,
-	ExtensionFactorySettlementObserver,
-	ExtensionHandler,
-	ExtensionRuntime,
-	InlineExtension,
-	LoadExtensionsResult,
-	RegisteredTool,
-	ToolDefinition,
-	ToolExecutionMode,
-	ToolInfo,
-	ToolResultEvent,
-	ToolResultEventResult,
-} from "./types.ts";
-export { defineTool } from "./types.ts";
-export { wrapRegisteredTools } from "./wrapper.ts";

package/packages/agent/src/core/extensions/loader.ts

@@ -1,125 +0,0 @@
-/**
- * Extension loader - creates extensions from inline factories.
- */
-
-import { createSyntheticSourceInfo } from "../source-info.ts";
-import type {
-	Extension,
-	ExtensionAPI,
-	ExtensionFactory,
-	ExtensionFactorySettlementObserver,
-	ExtensionRuntime,
-	ToolDefinition,
-} from "./types.ts";
-
-type HandlerFn = (...args: unknown[]) => Promise<unknown>;
-
-function abortReason(signal: AbortSignal): Error {
-	return signal.reason instanceof Error ? signal.reason : new Error("Extension creation was aborted.");
-}
-
-function awaitWithSignal<T>(operation: Promise<T>, signal: AbortSignal | undefined): Promise<T> {
-	if (!signal) {
-		return operation;
-	}
-	if (signal.aborted) {
-		return Promise.reject(abortReason(signal));
-	}
-
-	return new Promise<T>((resolve, reject) => {
-		const abort = () => reject(abortReason(signal));
-		signal.addEventListener("abort", abort, { once: true });
-		operation.then(resolve, reject).finally(() => signal.removeEventListener("abort", abort));
-	});
-}
-
-/**
- * Create a runtime with throwing stubs for action methods.
- * Runner.bindCore() replaces these with real implementations.
- */
-export function createExtensionRuntime(): ExtensionRuntime {
-	const notInitialized = () => {
-		throw new Error("Extension runtime not initialized. Action methods cannot be called during extension loading.");
-	};
-	const state: { staleMessage?: string } = {};
-
-	return {
-		appendEntry: notInitialized,
-		getAllTools: notInitialized,
-		setActiveTools: notInitialized,
-		// registerTool() is valid during extension load; refresh is only needed post-bind.
-		refreshTools: () => {},
-		assertActive: () => {
-			if (state.staleMessage) {
-				throw new Error(state.staleMessage);
-			}
-		},
-		invalidate: (message) => {
-			state.staleMessage ??= message ?? "This extension is stale.";
-		},
-	};
-}
-
-/** Registration methods write to the extension object, action methods delegate to the shared runtime. */
-function createExtensionAPI(extension: Extension, runtime: ExtensionRuntime): ExtensionAPI {
-	return {
-		on(event: string, handler: HandlerFn): void {
-			runtime.assertActive();
-			const list = extension.handlers.get(event) ?? [];
-			list.push(handler);
-			extension.handlers.set(event, list);
-		},
-
-		registerTool(tool: ToolDefinition): void {
-			runtime.assertActive();
-			extension.tools.set(tool.name, {
-				definition: tool,
-				sourceInfo: extension.sourceInfo,
-			});
-			runtime.refreshTools();
-		},
-
-		appendEntry(customType: string, data?: unknown): void {
-			runtime.assertActive();
-			runtime.appendEntry(customType, data);
-		},
-
-		getAllTools() {
-			runtime.assertActive();
-			return runtime.getAllTools();
-		},
-
-		setActiveTools(toolNames: string[]): void {
-			runtime.assertActive();
-			runtime.setActiveTools(toolNames);
-		},
-	} as ExtensionAPI;
-}
-
-/** Create an Extension from an inline factory function. */
-export async function loadExtensionFromFactory(
-	factory: ExtensionFactory,
-	runtime: ExtensionRuntime,
-	extensionPath: string,
-	signal?: AbortSignal,
-	onFactorySettlement?: ExtensionFactorySettlementObserver,
-): Promise<Extension> {
-	const extension: Extension = {
-		path: extensionPath,
-		sourceInfo: createSyntheticSourceInfo(extensionPath, { source: "inline" }),
-		handlers: new Map(),
-		tools: new Map(),
-	};
-	const api = createExtensionAPI(extension, runtime);
-	try {
-		const factorySettlement = Promise.resolve(factory(api, { signal: signal ?? new AbortController().signal }));
-		onFactorySettlement?.(factorySettlement);
-		await awaitWithSignal(factorySettlement, signal);
-	} catch (error) {
-		if (signal?.aborted) {
-			runtime.invalidate("Extension creation was aborted.");
-		}
-		throw error;
-	}
-	return extension;
-}

package/packages/agent/src/core/extensions/runner.ts

@@ -1,211 +0,0 @@
-/**
- * Extension runner - executes extension handlers against one agent session.
- */
-
-import type { AgentMessage } from "../../loop/index.ts";
-import type { Model, UserAttachment } from "@ragents/ai";
-import type { SessionManager } from "../session-manager.ts";
-import type { BuildSystemPromptOptions } from "../system-prompt.ts";
-import type {
-	BeforeAgentStartEvent,
-	BeforeAgentStartEventResult,
-	ContextEvent,
-	ContextEventResult,
-	Extension,
-	ExtensionActions,
-	ExtensionContext,
-	ExtensionError,
-	ExtensionRuntime,
-	RegisteredTool,
-	ToolResultEvent,
-	ToolResultEventResult,
-} from "./types.ts";
-
-export type ExtensionErrorListener = (error: ExtensionError) => void;
-
-/** What the runner reads from its session when it builds a handler context. */
-export interface ExtensionContextSource {
-	getModel: () => Model<any> | undefined;
-	getSignal: () => AbortSignal | undefined;
-}
-
-export const STALE_EXTENSION_MESSAGE = "This extension is stale: its agent session was disposed.";
-
-export class ExtensionRunner {
-	private readonly extensions: Extension[];
-	private readonly runtime: ExtensionRuntime;
-	private readonly sessionManager: SessionManager;
-	private readonly errorListeners: Set<ExtensionErrorListener> = new Set();
-	private contextSource: ExtensionContextSource = { getModel: () => undefined, getSignal: () => undefined };
-	private staleMessage: string | undefined;
-
-	constructor(extensions: Extension[], runtime: ExtensionRuntime, sessionManager: SessionManager) {
-		this.extensions = extensions;
-		this.runtime = runtime;
-		this.sessionManager = sessionManager;
-	}
-
-	bindCore(actions: ExtensionActions, contextSource: ExtensionContextSource): void {
-		this.runtime.appendEntry = actions.appendEntry;
-		this.runtime.getAllTools = actions.getAllTools;
-		this.runtime.setActiveTools = actions.setActiveTools;
-		this.runtime.refreshTools = actions.refreshTools;
-		this.contextSource = contextSource;
-	}
-
-	/** Get all registered tools from all extensions (first registration per name wins). */
-	getAllRegisteredTools(): RegisteredTool[] {
-		const toolsByName = new Map<string, RegisteredTool>();
-		for (const ext of this.extensions) {
-			for (const tool of ext.tools.values()) {
-				if (!toolsByName.has(tool.definition.name)) {
-					toolsByName.set(tool.definition.name, tool);
-				}
-			}
-		}
-		return Array.from(toolsByName.values());
-	}
-
-	invalidate(message = STALE_EXTENSION_MESSAGE): void {
-		if (!this.staleMessage) {
-			this.staleMessage = message;
-			this.runtime.invalidate(message);
-		}
-	}
-
-	private assertActive(): void {
-		if (this.staleMessage) {
-			throw new Error(this.staleMessage);
-		}
-	}
-
-	onError(listener: ExtensionErrorListener): () => void {
-		this.errorListeners.add(listener);
-		return () => this.errorListeners.delete(listener);
-	}
-
-	private emitError(ext: Extension, event: string, err: unknown): void {
-		const error: ExtensionError = {
-			extensionPath: ext.path,
-			event,
-			error: err instanceof Error ? err.message : String(err),
-			stack: err instanceof Error ? err.stack : undefined,
-		};
-		for (const listener of this.errorListeners) {
-			listener(error);
-		}
-	}
-
-	hasHandlers(eventType: string): boolean {
-		return this.extensions.some((ext) => (ext.handlers.get(eventType)?.length ?? 0) > 0);
-	}
-
-	/** Context values are resolved at call time, so a disposed session is detected on every access. */
-	createContext(): ExtensionContext {
-		const runner = this;
-		return {
-			get sessionManager() {
-				runner.assertActive();
-				return runner.sessionManager;
-			},
-			get model() {
-				runner.assertActive();
-				return runner.contextSource.getModel();
-			},
-			get signal() {
-				runner.assertActive();
-				return runner.contextSource.getSignal();
-			},
-		};
-	}
-
-	async emitToolResult(event: ToolResultEvent): Promise<ToolResultEventResult | undefined> {
-		const ctx = this.createContext();
-		const currentEvent: ToolResultEvent = { ...event };
-		let modified = false;
-
-		for (const ext of this.extensions) {
-			for (const handler of ext.handlers.get("tool_result") ?? []) {
-				try {
-					const handlerResult = (await handler(currentEvent, ctx)) as ToolResultEventResult | undefined;
-					if (!handlerResult) continue;
-
-					if (handlerResult.content !== undefined) {
-						currentEvent.content = handlerResult.content;
-						modified = true;
-					}
-					if (handlerResult.details !== undefined) {
-						currentEvent.details = handlerResult.details;
-						modified = true;
-					}
-					if (handlerResult.isError !== undefined) {
-						currentEvent.isError = handlerResult.isError;
-						modified = true;
-					}
-				} catch (err) {
-					this.emitError(ext, "tool_result", err);
-				}
-			}
-		}
-
-		return modified
-			? { content: currentEvent.content, details: currentEvent.details, isError: currentEvent.isError }
-			: undefined;
-	}
-
-	async emitContext(messages: AgentMessage[]): Promise<AgentMessage[]> {
-		const ctx = this.createContext();
-		let currentMessages = structuredClone(messages);
-
-		for (const ext of this.extensions) {
-			for (const handler of ext.handlers.get("context") ?? []) {
-				try {
-					const event: ContextEvent = { type: "context", messages: currentMessages };
-					const handlerResult = (await handler(event, ctx)) as ContextEventResult | undefined;
-					if (handlerResult?.messages) {
-						currentMessages = handlerResult.messages;
-					}
-				} catch (err) {
-					this.emitError(ext, "context", err);
-				}
-			}
-		}
-
-		return currentMessages;
-	}
-
-	/** Chains the system prompt through all before_agent_start handlers; undefined when none changed it. */
-	async emitBeforeAgentStart(
-		prompt: string,
-		systemPrompt: string,
-		systemPromptOptions: BuildSystemPromptOptions,
-		attachments?: UserAttachment[],
-	): Promise<string | undefined> {
-		const ctx = this.createContext();
-		let currentSystemPrompt = systemPrompt;
-		let systemPromptModified = false;
-
-		for (const ext of this.extensions) {
-			for (const handler of ext.handlers.get("before_agent_start") ?? []) {
-				try {
-					const event: BeforeAgentStartEvent = {
-						type: "before_agent_start",
-						prompt,
-						attachments,
-						systemPrompt: currentSystemPrompt,
-						systemPromptOptions,
-					};
-					const handlerResult = (await handler(event, ctx)) as BeforeAgentStartEventResult | undefined;
-					if (handlerResult?.systemPrompt !== undefined) {
-						currentSystemPrompt = handlerResult.systemPrompt;
-						systemPromptModified = true;
-					}
-				} catch (err) {
-					this.emitError(ext, "before_agent_start", err);
-				}
-			}
-		}
-
-		return systemPromptModified ? currentSystemPrompt : undefined;
-	}
-}

package/packages/agent/src/core/extensions/types.ts

@@ -1,197 +0,0 @@
-/** Extensions are inline factories: they adjust the system prompt, the messages of a model call and tool results, and register tools. */
-
-import type { AgentMessage, AgentToolResult, AgentToolUpdateCallback, ToolExecutionMode } from "../../loop/index.ts";
-import type { ImageContent, Model, TextContent, UserAttachment } from "@ragents/ai";
-import type { Static, TSchema } from "typebox";
-import type { ReadonlySessionManager } from "../session-manager.ts";
-import type { SourceInfo } from "../source-info.ts";
-import type { BuildSystemPromptOptions } from "../system-prompt.ts";
-
-export type { BuildSystemPromptOptions } from "../system-prompt.ts";
-export type { AgentToolResult, AgentToolUpdateCallback, ToolExecutionMode };
-
-/** Context passed to extension event handlers and tools. */
-export interface ExtensionContext {
-	/** Session manager (read-only) */
-	sessionManager: ReadonlySessionManager;
-	/** Current model (may be undefined) */
-	model: Model<any> | undefined;
-	/** The current abort signal, or undefined when the agent is not streaming. */
-	signal: AbortSignal | undefined;
-}
-
-/** Tool definition for registerTool(). */
-export interface ToolDefinition<TParams extends TSchema = TSchema, TDetails = unknown, TState = any> {
-	/** Tool name (used in LLM tool calls) */
-	name: string;
-	/** Human-readable label */
-	label: string;
-	/** Description for LLM */
-	description: string;
-	/** Optional one-line snippet for the Available tools section in the default system prompt. */
-	promptSnippet?: string;
-	/** Optional guideline bullets appended to the default system prompt Guidelines section when this tool is active. */
-	promptGuidelines?: string[];
-	/** Parameter schema (TypeBox) */
-	parameters: TParams;
-	/** Optional compatibility shim to prepare raw tool call arguments before schema validation. */
-	prepareArguments?: (args: unknown) => Static<TParams>;
-	/** Per-tool execution mode override; if omitted, the default execution mode applies. */
-	executionMode?: ToolExecutionMode;
-	/** Execute the tool. */
-	execute(
-		toolCallId: string,
-		params: Static<TParams>,
-		signal: AbortSignal | undefined,
-		onUpdate: AgentToolUpdateCallback<TDetails> | undefined,
-		ctx: ExtensionContext,
-	): Promise<AgentToolResult<TDetails>>;
-}
-
-type AnyToolDefinition = ToolDefinition<any, any, any>;
-
-/** Preserve parameter inference for standalone tool definitions. */
-export function defineTool<TParams extends TSchema, TDetails = unknown, TState = any>(
-	tool: ToolDefinition<TParams, TDetails, TState>,
-): ToolDefinition<TParams, TDetails, TState> & AnyToolDefinition {
-	return tool as ToolDefinition<TParams, TDetails, TState> & AnyToolDefinition;
-}
-
-/** Fired before each LLM call. Can modify messages. */
-export interface ContextEvent {
-	type: "context";
-	messages: AgentMessage[];
-}
-
-/** Fired after the user submits a prompt but before the agent loop. */
-export interface BeforeAgentStartEvent {
-	type: "before_agent_start";
-	/** The raw user prompt text. */
-	prompt: string;
-	attachments?: UserAttachment[];
-	/** The fully assembled system prompt string. */
-	systemPrompt: string;
-	/** Structured options used to build the system prompt. */
-	systemPromptOptions: BuildSystemPromptOptions;
-}
-
-/** Fired after a tool executes. Can modify the result. */
-export interface ToolResultEvent {
-	type: "tool_result";
-	toolCallId: string;
-	toolName: string;
-	input: Record<string, unknown>;
-	content: (TextContent | ImageContent)[];
-	details: unknown;
-	isError: boolean;
-}
-
-export type ExtensionEvent = ContextEvent | BeforeAgentStartEvent | ToolResultEvent;
-
-export interface ContextEventResult {
-	messages?: AgentMessage[];
-}
-
-export interface ToolResultEventResult {
-	content?: (TextContent | ImageContent)[];
-	details?: unknown;
-	isError?: boolean;
-}
-
-export interface BeforeAgentStartEventResult {
-	/** Replace the system prompt for this turn. If multiple extensions return this, they are chained. */
-	systemPrompt?: string;
-}
-
-/** Handler function type for events */
-export type ExtensionHandler<E, R = undefined> = (event: E, ctx: ExtensionContext) => Promise<R | void> | R | void;
-
-/** ExtensionAPI passed to extension factory functions. */
-export interface ExtensionAPI {
-	on(event: "before_agent_start", handler: ExtensionHandler<BeforeAgentStartEvent, BeforeAgentStartEventResult>): void;
-	on(event: "context", handler: ExtensionHandler<ContextEvent, ContextEventResult>): void;
-	on(event: "tool_result", handler: ExtensionHandler<ToolResultEvent, ToolResultEventResult>): void;
-
-	/** Register a tool that the LLM can call. */
-	registerTool<TParams extends TSchema = TSchema, TDetails = unknown, TState = any>(
-		tool: ToolDefinition<TParams, TDetails, TState>,
-	): void;
-
-	/** Append a custom entry to the session for state persistence (not sent to LLM). */
-	appendEntry<T = unknown>(customType: string, data?: T): void;
-
-	/** Get all configured tools with parameter schema, prompt guidelines, and source metadata. */
-	getAllTools(): ToolInfo[];
-
-	/** Set the active tools by name. */
-	setActiveTools(toolNames: string[]): void;
-}
-
-export interface ExtensionFactoryContext {
-	readonly signal: AbortSignal;
-}
-
-/** Extension factory function type. Supports both sync and async initialization. */
-export type ExtensionFactory = (agent: ExtensionAPI, context: ExtensionFactoryContext) => void | Promise<void>;
-
-/** Observes the actual lifetime of an async extension factory, independently of an aborted loader wait. */
-export type ExtensionFactorySettlementObserver = (settlement: Promise<void>) => void;
-
-export type InlineExtension =
-	| ExtensionFactory
-	| {
-			/** Display name shown as `<inline:name>`. */
-			name: string;
-			factory: ExtensionFactory;
-	  };
-
-export interface RegisteredTool {
-	definition: ToolDefinition;
-	sourceInfo: SourceInfo;
-}
-
-type HandlerFn = (...args: unknown[]) => Promise<unknown>;
-
-/** Tool info with name, description, parameter schema, prompt guidelines, and source metadata. */
-export type ToolInfo = Pick<ToolDefinition, "name" | "description" | "parameters" | "promptGuidelines"> & {
-	sourceInfo: SourceInfo;
-};
-
-/** Action implementations behind the ExtensionAPI, provided by the session. */
-export interface ExtensionActions {
-	appendEntry: <T = unknown>(customType: string, data?: T) => void;
-	getAllTools: () => ToolInfo[];
-	setActiveTools: (toolNames: string[]) => void;
-	refreshTools: () => void;
-}
-
-/** Shared state created by the loader; actions are throwing stubs until the runner binds the session. */
-export interface ExtensionRuntime extends ExtensionActions {
-	/** Throws when this extension instance is stale. */
-	assertActive: () => void;
-	/** Marks this extension instance as stale. */
-	invalidate: (message?: string) => void;
-}
-
-/** Loaded extension with all registered items. */
-export interface Extension {
-	path: string;
-	sourceInfo: SourceInfo;
-	handlers: Map<string, HandlerFn[]>;
-	tools: Map<string, RegisteredTool>;
-}
-
-/** Result of loading extensions. */
-export interface LoadExtensionsResult {
-	extensions: Extension[];
-	errors: Array<{ path: string; error: string }>;
-	/** Shared runtime - actions are throwing stubs until the runner binds the session */
-	runtime: ExtensionRuntime;
-}
-
-export interface ExtensionError {
-	extensionPath: string;
-	event: string;
-	error: string;
-	stack?: string;
-}

package/packages/agent/src/core/extensions/wrapper.ts

@@ -1,24 +0,0 @@
-/**
- * Tool wrappers for extension-registered tools.
- *
- * These wrappers only adapt tool execution so extension tools receive the runner context.
- * Tool result interception is handled by AgentSession via the hooks of the agent loop.
- */
-
-import type { AgentTool } from "../../loop/index.ts";
-import type { ExtensionRunner } from "./runner.ts";
-import type { RegisteredTool } from "./types.ts";
-
-/** Wrap registered tools into AgentTools that receive the runner context on every call. */
-export function wrapRegisteredTools(registeredTools: RegisteredTool[], runner: ExtensionRunner): AgentTool[] {
-	return registeredTools.map(({ definition }) => ({
-		name: definition.name,
-		label: definition.label,
-		description: definition.description,
-		parameters: definition.parameters,
-		prepareArguments: definition.prepareArguments,
-		executionMode: definition.executionMode,
-		execute: (toolCallId, params, signal, onUpdate) =>
-			definition.execute(toolCallId, params, signal, onUpdate, runner.createContext()),
-	}));
-}