@schlenkr/ragents 0.1.0

package/packages/ragents/src/agents/catalog.ts

@@ -0,0 +1,220 @@
+import type { AgentDriverKind, AgentExecution, ModelSelection, ThinkingLevel } from "../domain/driver.ts";
+import { agentDriverKinds } from "../domain/driver.ts";
+import { DomainError } from "../runtime/domain-error.ts";
+
+export type CatalogModel = {
+    driver: AgentDriverKind;
+    provider: string;
+    model: string;
+    label: string;
+    thinking: readonly ThinkingLevel[];
+};
+
+type ProfileBase = {
+    name: string;
+    description: string;
+    turnTimeoutMs: number | null;
+    isolateWorkspace: boolean;
+};
+
+export type AgentProfile = ProfileBase & (
+    | { driver: "manual" | "script" }
+    | { driver: "agent"; provider: string; model: string; thinking?: ThinkingLevel }
+);
+
+type AgentDriverProfile = Extract<AgentProfile, { driver: "agent" }>;
+
+export type ExecutionRequest = {
+    profile?: string;
+    driver?: AgentDriverKind;
+    provider?: string;
+    model?: string;
+    thinking?: ThinkingLevel;
+    turnTimeoutMs?: number;
+    isolateWorkspace?: boolean;
+};
+
+export interface ModelCatalog {
+    models(): Promise<readonly CatalogModel[]>;
+    profiles(): readonly AgentProfile[];
+}
+
+const defaultProfiles: AgentProfile[] = [
+    {
+        name: "manual",
+        description: "Kein automatischer Treiber. Ein Mensch führt die Turns.",
+        driver: "manual",
+        turnTimeoutMs: null,
+        isolateWorkspace: false,
+    },
+];
+
+const spawnFormsOf = (models: readonly CatalogModel[]) => {
+    const byProvider = new Map<string, string[]>();
+
+    for (const entry of models)
+        byProvider.set(entry.provider, [...(byProvider.get(entry.provider) ?? []), entry.model]);
+
+    return [...byProvider.entries()]
+        .map(([provider, names]) => `provider "${provider}" with model ${names.map((name) => `"${name}"`).join(", ")}`)
+        .join("; ") || "none";
+};
+
+const providerFor = (models: readonly CatalogModel[], driver: AgentDriverKind, model: string): string => {
+    const known = models.filter((entry) => entry.driver === driver);
+    const providers = [...new Set(known.flatMap((entry) => (entry.model === model ? [entry.provider] : [])))];
+    const [only] = providers;
+
+    if (providers.length > 1)
+        throw new DomainError(
+            "model-ambiguous",
+            `Model ${model} is offered by several providers for driver ${driver}: ${providers.join(", ")}. Name the provider explicitly.`,
+            400,
+        );
+
+    if (!only)
+        throw new DomainError(
+            "model-not-found",
+            `Model ${model} is unknown for driver ${driver}. Pass provider and model as SEPARATE fields, exactly as listed: ${spawnFormsOf(known)}. Or spawn with a profile from model_list.`,
+            400,
+        );
+
+    return only;
+};
+
+const unprefixed = (
+    models: readonly CatalogModel[],
+    driver: AgentDriverKind,
+    named: string | null,
+    model: string | null,
+): { named: string | null; model: string | null } => {
+    if (!model || !model.includes("/"))
+        return { named, model };
+
+    const known = models.filter((entry) => entry.driver === driver);
+    const [head, ...rest] = model.split("/");
+    const tail = rest.join("/");
+
+    if (!head || !tail || (named && named !== head))
+        return { named, model };
+
+    if (known.some((entry) => entry.provider === head && entry.model === tail))
+        return { named: head, model: tail };
+
+    return { named, model };
+};
+
+const thinkingFor = (
+    models: readonly CatalogModel[],
+    driver: AgentDriverKind,
+    provider: string,
+    model: string,
+    request: ExecutionRequest,
+    profile: AgentDriverProfile | undefined,
+): ThinkingLevel | null => {
+    const thinking = request.thinking ?? profile?.thinking ?? null;
+    const requested = thinking;
+
+    if (!requested)
+        return thinking;
+
+    const entry = models.find((candidate) =>
+        candidate.driver === driver
+        && candidate.model === model
+        && candidate.provider === provider);
+
+    if (entry && !entry.thinking.includes(requested))
+        throw new DomainError(
+            "thinking-not-supported",
+            `Model ${model} does not offer thinking ${requested}. Valid levels for it: ${entry.thinking.join(", ")}. `
+            + "model_list names them per model.",
+            400,
+        );
+
+    return thinking;
+};
+
+const selectionFor = (
+    models: readonly CatalogModel[],
+    driver: AgentDriverKind,
+    request: ExecutionRequest,
+    profile: AgentDriverProfile | undefined,
+    profiles: readonly AgentProfile[],
+): ModelSelection => {
+    const requested = unprefixed(
+        models,
+        driver,
+        request.provider ?? profile?.provider ?? null,
+        request.model ?? profile?.model ?? null,
+    );
+    const model = requested.model;
+    const named = requested.named;
+
+    if (!model)
+        throw new DomainError(
+            "model-missing",
+            `Driver ${driver} needs a model to run turns. Spawn with a profile from model_list, or pass provider and model. `
+            + `Known profiles for ${driver}: ${profiles.filter((entry) => entry.driver === driver).map((entry) => entry.name).join(", ") || "none"}.`,
+            400,
+        );
+
+    const provider = named ?? providerFor(models, driver, model);
+
+    const thinking = thinkingFor(models, driver, provider, model, request, profile);
+
+    return { provider, model, ...(thinking ? { thinking } : {}) };
+};
+
+export const resolveExecution = (
+    catalog: ModelCatalog,
+    request: ExecutionRequest,
+    agentId: string,
+    models: readonly CatalogModel[] = [],
+): AgentExecution => {
+    const profiles = catalog.profiles();
+    const profile = request.profile ? profiles.find((entry) => entry.name === request.profile) : undefined;
+
+    if (request.profile && !profile)
+        throw new DomainError(
+            "profile-not-found",
+            `Profile ${request.profile} does not exist. Known profiles: ${profiles.map((entry) => entry.name).join(", ")}.`,
+            400,
+        );
+
+    const kind = request.driver ?? profile?.driver ?? "agent";
+
+    if (!agentDriverKinds.includes(kind))
+        throw new DomainError("driver-not-found", `Driver ${kind} does not exist.`, 400);
+
+    const isolate = request.isolateWorkspace ?? profile?.isolateWorkspace ?? kind !== "manual";
+
+    const workspacePath = isolate ? agentId : null;
+    const turnTimeoutMs = request.turnTimeoutMs ?? profile?.turnTimeoutMs ?? null;
+
+    if (kind === "manual" || kind === "script")
+        return { driver: { kind, config: {} }, workspacePath, turnTimeoutMs };
+
+    const agentProfile = profile?.driver === "agent" ? profile : undefined;
+
+    return { driver: { kind, config: selectionFor(models, kind, request, agentProfile, profiles) }, workspacePath, turnTimeoutMs };
+};
+
+export class StaticModelCatalog implements ModelCatalog {
+    readonly #models: readonly CatalogModel[];
+    readonly #profiles: readonly AgentProfile[];
+
+    constructor(models: readonly CatalogModel[] = [], profiles: readonly AgentProfile[] = defaultProfiles) {
+        this.#models = models;
+        this.#profiles = profiles;
+    }
+
+    async models() {
+        return this.#models;
+    }
+
+    profiles() {
+        return this.#profiles;
+    }
+}
+
+export const builtinProfiles = defaultProfiles;

package/packages/ragents/src/agents/delivery.ts

@@ -0,0 +1,187 @@
+import { isObservableEventType, type ObservableEventType } from "../domain/vocabulary.ts";
+import { validatedEventPayloadOf } from "../domain/event-validation.ts";
+import type { EventPayloads } from "../domain/events.ts";
+import type { ActorInput, RunView } from "../domain/model.ts";
+import { canonicalJson } from "../runtime/canonical-json.ts";
+
+export type DeliveredEvent = {
+    [Name in ObservableEventType]: {
+        readonly type: Name;
+        readonly eventId: string;
+        readonly sequence: number;
+        readonly occurredAt: string;
+        readonly sourceActorId: string;
+        readonly sourceActorHandle: string;
+        readonly payload: Readonly<EventPayloads[Name]>;
+    };
+}[ObservableEventType];
+
+export type DeliveredInput = ActorInput & {
+    readonly event: DeliveredEvent | null;
+};
+
+const eventTypesWithText = ["model.output.completed", "model.reasoning.completed", "runtime.output.recorded"] as const;
+
+type TextEventType = (typeof eventTypesWithText)[number];
+
+export const carriesText = (type: ObservableEventType): type is TextEventType =>
+    (eventTypesWithText as readonly ObservableEventType[]).includes(type);
+
+const carriesTextEvent = (event: DeliveredEvent): event is Extract<DeliveredEvent, { type: TextEventType }> =>
+    carriesText(event.type);
+
+const recordOf = (value: unknown, what: string): Readonly<Record<string, unknown>> => {
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        throw new Error(`${what} ist kein Objekt.`);
+
+    return value as Record<string, unknown>;
+};
+
+const stringOf = (source: Readonly<Record<string, unknown>>, field: string, what: string): string => {
+    const value = source[field];
+
+    if (typeof value !== "string")
+        throw new Error(`${what} hat kein Textfeld ${field}.`);
+
+    return value;
+};
+
+const numberOf = (source: Readonly<Record<string, unknown>>, field: string, what: string): number => {
+    const value = source[field];
+
+    if (typeof value !== "number" || !Number.isFinite(value))
+        throw new Error(`${what} hat kein Zahlenfeld ${field}.`);
+
+    return value;
+};
+
+export const deliveredContentOf = (event: DeliveredEvent): string =>
+    carriesTextEvent(event) ? event.payload.text : canonicalJson(event.payload);
+
+export const deliveredEventOf = (
+    source: {
+        readonly eventId: string;
+        readonly sequence: number;
+        readonly occurredAt: string;
+        readonly actorId: string;
+        readonly type: string;
+        readonly payload: unknown;
+    },
+    sourceActorHandle: string,
+): DeliveredEvent => {
+    if (!isObservableEventType(source.type))
+        throw new Error(`Der Eventtyp ${source.type} ist nicht beobachtbar und wird nicht zugestellt.`);
+
+    return {
+        type: source.type,
+        eventId: source.eventId,
+        sequence: source.sequence,
+        occurredAt: source.occurredAt,
+        sourceActorId: source.actorId,
+        sourceActorHandle,
+        payload: validatedEventPayloadOf(source.type, source.payload, `event ${source.eventId} payload`),
+    } as DeliveredEvent;
+};
+
+const sourceEventOf = (inputId: string, content: string): Readonly<Record<string, unknown>> => {
+    try {
+        return recordOf(JSON.parse(content), `Der zugestellte Inhalt von Input ${inputId}`);
+    } catch (error) {
+        throw new Error(
+            `Der Subscription-Input ${inputId} trägt kein Event-JSON: `
+            + (error instanceof Error ? error.message : String(error)),
+        );
+    }
+};
+
+export const deliveredEventFromJson = (view: RunView, inputId: string, content: string): DeliveredEvent => {
+    const what = `Das zugestellte Event von Input ${inputId}`;
+    const source = sourceEventOf(inputId, content);
+    const actorId = stringOf(source, "actorId", what);
+    const author = view.actors.find((entry) => entry.id === actorId);
+
+    if (!author)
+        throw new Error(`${what} stammt von Actor ${actorId}, den dieser Run nicht kennt.`);
+
+    return deliveredEventOf({
+        eventId: stringOf(source, "eventId", what),
+        sequence: numberOf(source, "sequence", what),
+        occurredAt: stringOf(source, "occurredAt", what),
+        actorId,
+        type: stringOf(source, "type", what),
+        payload: source.payload,
+    }, author.handle);
+};
+
+export const deliveredInputOf = (view: RunView, input: ActorInput): DeliveredInput => {
+    if (input.subscriptionId === null)
+        return { ...input, event: null };
+
+    const event = deliveredEventFromJson(view, input.id, input.content);
+
+    return { ...input, content: deliveredContentOf(event), event };
+};
+
+export type ScriptInput = {
+    readonly id: string;
+    readonly content: string;
+    readonly artifactIds: readonly string[];
+    readonly sourceEventIds: readonly string[];
+    readonly subscriptionId: string | null;
+    readonly event: DeliveredEvent | null;
+};
+
+export const scriptInputOf = (input: DeliveredInput): ScriptInput => ({
+    id: input.id,
+    content: input.content,
+    artifactIds: [...input.artifactIds],
+    sourceEventIds: [...input.sourceEventIds],
+    subscriptionId: input.subscriptionId,
+    event: input.event,
+});
+
+export const subscriptionSummaryFor = (view: RunView, actorId: string): readonly string[] => {
+    const handleOf = (id: string) => {
+        const found = view.actors.find((entry) => entry.id === id);
+
+        return found ? `@${found.handle}` : id;
+    };
+
+    return view.subscriptions
+        .filter((subscription) => subscription.subscriberId === actorId && subscription.status === "active")
+        .map((subscription) => {
+            const sources = subscription.sourceActorIds
+                ? subscription.sourceActorIds.map(handleOf).join(", ")
+                : subscription.sourceActorKinds
+                    ? `alle Actors der Art ${subscription.sourceActorKinds.join(", ")}`
+                    : "alle Actors";
+
+            return `${subscription.id}: Quellen ${sources}; Events ${subscription.eventTypes.join(", ")}`;
+        });
+};
+
+export const actorRosterText = (view: RunView, actorId: string): string => [
+    "[Actors im Run, Stand bei Turn-Beginn]",
+    "Diese Actors sind bereits angelegt. Verwende passende Beteiligte weiter; actor_list aktualisiert den Bestand.",
+    "agent: Gespräch mit einem Modell. script: Programm mit festem Eingabeprotokoll, kein Chatpartner; dokumentierte Funktionen oder Programmeingaben verwenden. primär bezeichnet das Standardziel, keine Dialogfähigkeit.",
+    ...view.actors.map((actor) => {
+        const status = actor.kind === "human" ? "human" : actor.lifecycle.kind;
+        const markers = [actor.id === actorId ? "du" : "", actor.id === view.primaryActorId ? "primär" : ""]
+            .filter(Boolean);
+
+        return `- @${actor.handle}: ${JSON.stringify(actor.displayName)}, ${actor.kind}, ${status}`
+            + (markers.length > 0 ? ` (${markers.join(", ")})` : "");
+    }),
+].join("\n");
+
+export const renderedPromptFor = (view: RunView, actorId: string, input: DeliveredInput): string => {
+    const subscriptions = subscriptionSummaryFor(view, actorId);
+    const header = [
+        ...(input.event
+            ? [`[Event ${input.event.type} von @${input.event.sourceActorHandle}, Sequenz ${input.event.sequence}]`]
+            : []),
+        ...(subscriptions.length > 0 ? [`[Aktive Subscriptions] ${subscriptions.join(" | ")}`] : []),
+    ];
+
+    return header.length > 0 ? `${header.join("\n")}\n\n${input.content}` : input.content;
+};

package/packages/ragents/src/agents/live.ts

@@ -0,0 +1,71 @@
+import type { LiveEvent } from "../drivers/types.ts";
+
+export type AgentLiveEvent =
+    | LiveEvent
+    | { kind: "turn-started"; turnId: string }
+    | { kind: "turn-finished"; turnId: string; outcome: "waiting" | "completed" | "failed" | "abandoned" };
+
+export type AgentLiveListener = (event: AgentLiveEvent) => unknown;
+
+export type AgentLiveListenerContext = {
+    readonly runId: string;
+    readonly agentId: string;
+    readonly event: AgentLiveEvent;
+};
+
+export type AgentLiveListenerErrorHandler = (
+    error: unknown,
+    context: AgentLiveListenerContext,
+) => void | Promise<void>;
+
+export type LiveBusOptions = {
+    readonly onListenerError?: AgentLiveListenerErrorHandler;
+};
+
+const keyOf = (runId: string, agentId: string) => `${runId}\0${agentId}`;
+
+export class LiveBus {
+    readonly #listeners = new Map<string, Set<AgentLiveListener>>();
+    readonly #onListenerError: AgentLiveListenerErrorHandler;
+
+    constructor(options: LiveBusOptions = {}) {
+        this.#onListenerError = options.onListenerError ?? (() => undefined);
+    }
+
+    subscribe(runId: string, agentId: string, listener: AgentLiveListener) {
+        const key = keyOf(runId, agentId);
+        const set = this.#listeners.get(key) ?? new Set<AgentLiveListener>();
+        set.add(listener);
+        this.#listeners.set(key, set);
+
+        return () => {
+            set.delete(listener);
+
+            if (set.size === 0)
+                this.#listeners.delete(key);
+        };
+    }
+
+    publish(runId: string, agentId: string, event: AgentLiveEvent): void {
+        const context = { runId, agentId, event };
+        const listeners = [...(this.#listeners.get(keyOf(runId, agentId)) ?? [])];
+
+        for (const listener of listeners) {
+            try {
+                const result = listener(event);
+                if (result !== undefined)
+                    void Promise.resolve(result).catch((error: unknown) => this.#report(error, context));
+            } catch (error: unknown) {
+                this.#report(error, context);
+            }
+        }
+    }
+
+    #report(error: unknown, context: AgentLiveListenerContext): void {
+        try {
+            void Promise.resolve(this.#onListenerError(error, context)).catch(() => undefined);
+        } catch {
+            return;
+        }
+    }
+}

package/packages/ragents/src/agents/plugins.ts

@@ -0,0 +1,130 @@
+import type { Actor, RunView } from "../domain/model.ts";
+import {
+    agentTools,
+    describeToolAvailability,
+    type RunFunction,
+    type ToolDescriptor,
+} from "./tools.ts";
+
+export type PluginContext = {
+    runId: string;
+    actorId: string;
+    turnId: string | null;
+    actor: Actor;
+    view: RunView;
+    workspace: string;
+};
+
+export type ToolContributor = {
+    name: string;
+    descriptors: readonly ToolDescriptor[];
+    dynamic?: boolean;
+    tools: (context: PluginContext) => readonly RunFunction[] | Promise<readonly RunFunction[]>;
+};
+
+export type AgentToolPlugin = ToolContributor;
+
+export interface ToolProvider {
+    resolve(context: PluginContext, onUnavailable?: (tool: RunFunction) => void): Promise<RunFunction[]>;
+}
+
+export class ToolRegistry implements ToolProvider {
+    readonly #plugins: ToolContributor[] = [];
+    readonly #descriptorOwners = new Map(agentTools.map((tool) => [tool.name, "ragents.agent-tools"]));
+
+    register(plugin: ToolContributor) {
+        if (this.#plugins.some((entry) => entry.name === plugin.name))
+            throw new Error(`Tool plugin ${plugin.name} is already registered.`);
+
+        if (plugin.dynamic && plugin.descriptors.length > 0)
+            throw new Error(`Dynamic tool plugin ${plugin.name} cannot declare static descriptors.`);
+
+        const names = new Set<string>();
+        for (const descriptor of plugin.descriptors) {
+            if (!descriptor.name.trim() || !descriptor.description.trim() || !descriptor.availabilityDetail.trim())
+                throw new Error(`Tool plugin ${plugin.name} has an incomplete descriptor.`);
+
+            if (descriptor.scope !== "per-turn")
+                throw new Error(`Tool plugin ${plugin.name} must declare ${descriptor.name} with per-turn scope.`);
+
+            if (names.has(descriptor.name))
+                throw new Error(`Tool plugin ${plugin.name} declares ${descriptor.name} more than once.`);
+
+            const owner = this.#descriptorOwners.get(descriptor.name);
+            if (owner)
+                throw new Error(`Tool plugin ${plugin.name} declares ${descriptor.name}, already declared by ${owner}.`);
+
+            names.add(descriptor.name);
+        }
+
+        this.#plugins.push(plugin);
+        for (const name of names) this.#descriptorOwners.set(name, plugin.name);
+
+        return this;
+    }
+
+    get plugins(): readonly ToolContributor[] {
+        return this.#plugins;
+    }
+
+    async resolve(context: PluginContext, onUnavailable?: (tool: RunFunction) => void) {
+        const resolved = agentTools.filter((tool) => {
+            if (tool.available(context.actor, context.view)) return true;
+            onUnavailable?.(tool);
+            return false;
+        });
+        const taken = new Set(agentTools.map((entry) => entry.name));
+
+        for (const plugin of this.#plugins) {
+            const tools = await plugin.tools(context);
+            this.#assertDescriptors(plugin, tools);
+
+            for (const tool of tools) {
+                if (taken.has(tool.name))
+                    throw new Error(`Tool plugin ${plugin.name} redefines tool ${tool.name}.`);
+
+                taken.add(tool.name);
+
+                if (tool.available(context.actor, context.view))
+                    resolved.push(tool);
+                else
+                    onUnavailable?.(tool);
+            }
+        }
+
+        return resolved;
+    }
+
+    #assertDescriptors(plugin: ToolContributor, tools: readonly RunFunction[]) {
+        const actual = new Map<string, RunFunction>();
+        for (const tool of tools) {
+            if (!tool.name.trim() || !tool.description.trim())
+                throw new Error(`Tool plugin ${plugin.name} resolved an incomplete tool.`);
+            if (actual.has(tool.name))
+                throw new Error(`Tool plugin ${plugin.name} resolves ${tool.name} more than once.`);
+            actual.set(tool.name, tool);
+        }
+
+        if (plugin.dynamic)
+            return;
+
+        if (actual.size !== plugin.descriptors.length)
+            throw new Error(`Tool plugin ${plugin.name} resolved a different number of tools than it declares.`);
+
+        for (const descriptor of plugin.descriptors) {
+            const tool = actual.get(descriptor.name);
+            if (!tool)
+                throw new Error(`Tool plugin ${plugin.name} did not resolve declared tool ${descriptor.name}.`);
+
+            const availability = describeToolAvailability(tool.available);
+            if (tool.description !== descriptor.description
+                || availability.availability !== descriptor.availability
+                || availability.availabilityDetail !== descriptor.availabilityDetail
+                || Boolean(tool.nativeTool) !== Boolean(descriptor.nativeTool)) {
+                throw new Error(`Tool plugin ${plugin.name} resolved ${descriptor.name} differently from its descriptor.`);
+            }
+        }
+    }
+}
+
+export const emptyRegistry = () => new ToolRegistry();