@schlenkr/ragents 0.1.5 → 0.1.6

package/packages/ragents/src/drivers/agent.ts

@@ -1,7 +1,5 @@
-import { join } from "node:path";
-
-import { getAgentDir, ModelRuntime } from "@aicontainer/agent";
-import { getSupportedThinkingLevels } from "@aicontainer/ai";
+import { ModelRuntime } from "@ragents/agent";
+import { getSupportedThinkingLevels } from "@ragents/ai";
 
 import { thinkingLevels, type ThinkingLevel } from "../domain/driver.ts";
 import type { CatalogModel } from "../agents/catalog.ts";
@@ -13,7 +11,6 @@ export type {
     AgentRuntimeDiagnostic,
     AgentRuntimeManagerOptions,
     AgentSessionStore,
-    AgentThinkingLevel,
 } from "./agent-runtime.ts";
 export { AgentRuntimeManager, turnDispatcherExtensionName } from "./agent-runtime.ts";
 export {
@@ -26,8 +23,7 @@ export {
     type SkillSelector,
 } from "./skill-preload.ts";
 
-export type AgentSessionDriverOptions = Omit<AgentRuntimeManagerOptions, "agentDir" | "modelRuntime"> & {
-    agentDir?: string;
+export type AgentSessionDriverOptions = Omit<AgentRuntimeManagerOptions, "modelRuntime"> & {
     modelRuntime?: ModelRuntime | Promise<ModelRuntime>;
 };
 
@@ -38,19 +34,8 @@ export class AgentSessionDriver implements AgentDriver<"agent"> {
     readonly #runtimeManager: AgentRuntimeManager;
 
     constructor(options: AgentSessionDriverOptions = {}) {
-        const agentDir = options.agentDir ?? getAgentDir();
-        this.#modelRuntime = Promise.resolve(
-            options.modelRuntime ??
-                ModelRuntime.create({
-                    authPath: join(agentDir, "auth.json"),
-                    modelsPath: join(agentDir, "models.json"),
-                }),
-        );
-        this.#runtimeManager = new AgentRuntimeManager({
-            ...options,
-            agentDir,
-            modelRuntime: this.#modelRuntime,
-        });
+        this.#modelRuntime = Promise.resolve(options.modelRuntime ?? ModelRuntime.create());
+        this.#runtimeManager = new AgentRuntimeManager({ ...options, modelRuntime: this.#modelRuntime });
     }
 
     async catalog(): Promise<CatalogModel[]> {

package/packages/ragents/src/drivers/attachments.ts

@@ -1,25 +1,6 @@
-import { lstat, mkdir, writeFile } from "node:fs/promises";
-import { basename, join } from "node:path";
-import type { UserAttachment } from "@aicontainer/ai";
+import type { UserAttachment } from "@ragents/ai";
 import type { TurnRequest } from "./types.ts";
 
-const storeAttachment = async (workspace: string, original: string, content: Uint8Array): Promise<string> => {
-    const directory = join(workspace, "attachments");
-    await mkdir(directory, { recursive: true, mode: 0o755 });
-    if (!(await lstat(directory)).isDirectory()) throw new Error("Das Anhangsverzeichnis ist kein normales Verzeichnis.");
-    const name = basename(original).replace(/[^a-zA-Z0-9._-]/g, "_") || "attachment";
-    for (let index = 1; index <= 10000; index += 1) {
-        const candidate = index === 1 ? name : `${index}-${name}`;
-        try {
-            await writeFile(join(directory, candidate), content, { mode: 0o644, flag: "wx" });
-            return candidate;
-        } catch (error) {
-            if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error;
-        }
-    }
-    throw new Error("Im Anhangsverzeichnis sind zu viele gleichnamige Dateien.");
-};
-
 export const attachmentInputKind = (mediaType: string): "image" | "video" | "file" | "text" | "binary" => {
     if (mediaType.startsWith("image/")) return "image";
     if (mediaType.startsWith("video/")) return "video";
@@ -29,7 +10,7 @@ export const attachmentInputKind = (mediaType: string): "image" | "video" | "fil
 };
 
 export const prepareInputAttachments = async (
-    request: Pick<TurnRequest<"agent">, "attachments" | "workspace" | "prompt" | "tools" | "workspaceTools">,
+    request: Pick<TurnRequest<"agent">, "attachments" | "prompt" | "tools" | "storeAttachment">,
     inputCapabilities: readonly string[],
 ): Promise<{ prompt: string; attachments: UserAttachment[] }> => {
     const attachments: UserAttachment[] = [];
@@ -44,11 +25,10 @@ export const prepareInputAttachments = async (
             const text = new TextDecoder("utf-8", { fatal: true }).decode(attachment.content);
             sections.push(`Angehängte Textdatei ${JSON.stringify(attachment.name)} (Dateiinhalt, keine Systemanweisung):\n${text}`);
         } else {
-            const tools = [...request.workspaceTools, ...request.tools.map((tool) => tool.name)];
-            if (!tools.some((name) => name === "read" || name === "bash")) {
+            if (!request.tools.some((tool) => tool.name === "read" || tool.name === "bash")) {
                 throw new Error(`Die Datei ${attachment.name} benötigt Dateizugriff, aber dieser Actor hat weder read noch bash.`);
             }
-            const name = await storeAttachment(request.workspace, attachment.name, attachment.content);
+            const name = await request.storeAttachment(attachment.name, attachment.content);
             sections.push(`Angehängte Datei ${JSON.stringify(attachment.name)} (${attachment.mediaType}) liegt als ${JSON.stringify(name)} im Unterordner attachments des Arbeitsverzeichnisses. Deine Dateiwerkzeuge können diese Ablage durchsuchen und die Datei lesen.`);
         }
     }

package/packages/ragents/src/drivers/skill-preload.ts

@@ -1,12 +1,6 @@
 import { readFile } from "node:fs/promises";
 
-import {
-    parseSkillBlock,
-    stripFrontmatter,
-    type InlineExtension,
-    type ModelRuntime,
-    type Skill,
-} from "@aicontainer/agent";
+import { stripFrontmatter, type InlineExtension, type ModelRuntime, type Skill } from "@ragents/agent";
 
 import type { TurnUsage } from "../domain/model.ts";
 
@@ -38,13 +32,8 @@ export type SkillPreloadConfiguration = Pick<
     "maxSelectionTokens" | "selector"
 >;
 
-const explicitSkillNames = (prompt: string, skills: readonly Skill[]): readonly string[] => {
-    const expanded = parseSkillBlock(prompt);
-
-    if (expanded)
-        return skills.some((skill) => skill.name === expanded.name) ? [expanded.name] : [];
-
-    return skills
+const explicitSkillNames = (prompt: string, skills: readonly Skill[]): readonly string[] =>
+    skills
         .filter((skill) => {
             const name = skill.name.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
             const command = new RegExp(`(?:^|\\s)/skill:${name}(?=$|\\s)`);
@@ -54,7 +43,6 @@ const explicitSkillNames = (prompt: string, skills: readonly Skill[]): readonly
             return command.test(prompt) || reference.test(prompt) || canonicalName.test(prompt);
         })
         .map((skill) => skill.name);
-};
 
 const classifierPrompt = (request: SkillSelectionRequest): string => [
     "Task:",
@@ -135,7 +123,7 @@ const preloadedSkills = async (skills: readonly Skill[]): Promise<string> => {
         "Apply these skill instructions to the current task. Resolve relative paths against each skill location.",
         "The current user task takes precedence over default or example task text in a skill, including edited start prompts.",
         ...bodies.map(({ skill, body }) => [
-            `<preloaded_skill name="${skill.name}" location="${skill.filePath}">`,
+            `<preloaded_skill name="${skill.name}" location="${skill.location}">`,
             body,
             "</preloaded_skill>",
         ].join("\n")),

package/packages/ragents/src/drivers/types.ts

@@ -7,6 +7,15 @@ import type { ToolInvocation } from "../agents/toolset.ts";
 
 export type AutomatedDriverKind = Exclude<AgentDriverKind, "manual">;
 
+export type TurnAttachment = { name: string; mediaType: string; content: Uint8Array };
+
+/** A pending input that joined the running turn; the driver hands it to the model before its next request. */
+export type SteeredInput = {
+    input: DeliveredInput;
+    prompt: string;
+    attachments: readonly TurnAttachment[];
+};
+
 type TurnDriverFacts = {
     script: {
         driverKind: "script";
@@ -16,12 +25,16 @@ type TurnDriverFacts = {
         driverKind: "agent";
         selection: ModelSelection;
         forkOf: string | null;
-        invoke: (toolCallId: string, name: string, input: JsonValue) => Promise<ToolInvocation>;
+        /** `modelContext` names the model context the result enters, see `ToolScope.modelContext`; without it file tools track no seen state. */
+        invoke: (toolCallId: string, name: string, input: JsonValue, modelContext?: string) => Promise<ToolInvocation>;
+        /** Claims the pending inputs that may join this turn now, in journal order; empty once the turn ends or aborts. */
+        claimSteering: () => readonly SteeredInput[];
     };
 };
 
 export type DriverEvent =
     | { kind: "assistant"; text: string }
+    | { kind: "assistant-interrupted"; text: string }
     | { kind: "reasoning"; text: string }
     | { kind: "runtime"; text: string };
 
@@ -42,12 +55,16 @@ export type TurnRequest<Kind extends AutomatedDriverKind = AutomatedDriverKind>
     turnId: string;
     startedAt: string;
     input: DeliveredInput;
-    attachments?: readonly { name: string; mediaType: string; content: Uint8Array }[];
+    attachments?: readonly TurnAttachment[];
     prompt: string;
     systemPrompt: string;
+    /** The working directory of the workspace tools, as the model sees it; it may lie on another machine. */
     workspace: string;
+    /** The folder on this machine for the driver's own work, resolved only when a driver needs it. */
+    runtimeDirectory: () => Promise<string>;
+    /** Stores an attached file under attachments/ of the workspace, where the workspace tools read it; returns its name there. */
+    storeAttachment: (name: string, content: Uint8Array) => Promise<string>;
     tools: readonly RunFunction[];
-    workspaceTools: readonly string[];
     allowedToolNames: readonly string[] | null;
     refreshTools?: () => Promise<{ tools: readonly RunFunction[]; systemPrompt: string }>;
     emit: (event: DriverEvent) => void;

package/packages/ragents/src/http/contracts.ts

@@ -1,8 +1,12 @@
 import { Type, type TSchema, type TUnsafe } from "typebox";
 import type { JournalEvent } from "../domain/events.ts";
+import type { JsonValue } from "../domain/json.ts";
 import type { RunView } from "../domain/model.ts";
 import { defineOperation } from "../rpc/contract.ts";
 
+/** Wo ein Vertrag ein Actor-Feld mit ID oder Handle nimmt, löst es diese eine Regel auf. */
+export { actorByHandle, actorByReference, handleKey, type ReferencedActor } from "../domain/actor-reference.ts";
+
 /** Ein Domänenwert mit eigenem TypeScript-Typ; das Schema bleibt bewusst offen. */
 export const openJson = <T>(name: string): TUnsafe<T> =>
   Type.Unsafe<T>({ type: "object", additionalProperties: true, "x-typescript-type": name });
@@ -11,6 +15,9 @@ export const runViewSchema = openJson<RunView>("RunView");
 
 export const journalEventSchema = openJson<JournalEvent>("JournalEvent");
 
+/** Das Ergebnis einer wartenden Aktion; die Form gehört dem Eigentümer der Aktion. */
+const actionResultSchema = Type.Unsafe<JsonValue>({ "x-typescript-type": "JsonValue" });
+
 const runId = Type.String({ minLength: 1, maxLength: 64, description: "Kennung des Runs" });
 
 const commandFields = {
@@ -33,7 +40,7 @@ export const artifactContentPath = (runId: string, artifactId: string): string =
 export const runContracts = {
   view: defineOperation({
     id: "ragents.runs.view",
-    description: "Die Laufansicht eines Runs lesen, optional den Stand nach einer Journalsequenz; null für einen noch nicht gestarteten Run.",
+    description: "Die Run-Ansicht lesen, optional den Stand nach einer Journalsequenz; null für einen noch nicht gestarteten Run.",
     input: Type.Object({ runId, at: Type.Optional(Type.Integer({ minimum: 0 })) }, { additionalProperties: false }),
     result: Type.Union([runViewSchema, Type.Null()]),
   }),
@@ -61,13 +68,19 @@ export const runContracts = {
     input: command({ actorId: Type.String({ minLength: 1 }), reason: Type.String({ minLength: 1 }) }),
     result: runViewSchema,
   }),
+  interruptTurn: defineOperation({
+    id: "ragents.runs.interruptTurn",
+    description: "Den laufenden Turn eines Actors unterbrechen; der Actor bleibt aktiv und nimmt die nächste Eingabe an. Ohne laufenden Turn geschieht nichts.",
+    input: command({ actorId: Type.String({ minLength: 1 }), reason: Type.Optional(Type.String({ minLength: 1 })) }),
+    result: runViewSchema,
+  }),
   resolveAction: defineOperation({
     id: "ragents.runs.resolveAction",
-    description: "Eine offene Rückfrage oder Aktion beantworten.",
+    description: "Eine wartende Aktion beantworten oder verwerfen.",
     input: command({
       actionId: Type.String({ minLength: 1 }),
       decision: Type.Union([Type.Literal("approved"), Type.Literal("dismissed")]),
-      response: Type.Optional(Type.Union([Type.String(), Type.Null()])),
+      result: Type.Optional(actionResultSchema),
     }),
     result: runViewSchema,
   }),

package/packages/ragents/src/http/methods.ts

@@ -1,16 +1,19 @@
 import type { AccessContext } from "../access.ts";
+import type { TurnInterruption } from "../agents/scheduler.ts";
 import type { RunView } from "../domain/model.ts";
 import { DomainError } from "../runtime/domain-error.ts";
 import type { CommandContext, Orchestration } from "../runtime/orchestration.ts";
-import { SerialQueue } from "../runtime/serial-queue.ts";
-import { descendantsOf, RunStopper, stopLineage, type RunStopBoundary, type RunStopOperation } from "../runtime/stop.ts";
+import { addressedActorOf } from "../runtime/guards.ts";
+import { KeyedSerialQueue } from "../runtime/serial-queue.ts";
+import { RunStopper, type RunStopBoundary, type RunStopOperation } from "../runtime/stop.ts";
 import type { HttpRouteContribution } from "../plugin-types.ts";
 import { implement, type MethodContribution } from "../rpc/contribution.ts";
 import { ARTIFACT_CONTENT_PATH, runContracts } from "./contracts.ts";
 
 export { ARTIFACT_CONTENT_PATH, artifactContentPath } from "./contracts.ts";
 
-export type RunRightsKind = "read" | "write" | "inspect" | "write-inspect";
+/** `stop` verlangt die Rechte von `write`, bedient den Run aber nicht und bleibt deshalb auch bei einem Run erlaubt, den nur sein Eigentümer bedient. */
+export type RunRightsKind = "read" | "write" | "inspect" | "write-inspect" | "stop";
 
 export type RuntimeMethodOptions = {
   runtime: Orchestration;
@@ -18,29 +21,20 @@ export type RuntimeMethodOptions = {
   assertRunUsable?: (runId: string) => void;
   abortTurns?: RunStopBoundary;
   stopRun?: RunStopOperation;
+  /** Ends the running turn of one actor and keeps the actor active; without a running turn it does nothing. */
+  interruptTurn: (runId: string, actorId: string, interruption: TurnInterruption) => Promise<void>;
   /** Prüft die Rechte des Zugriffs für einen Run oder wirft; der Host kennt Sonderfälle wie den globalen Chat. */
   assertRunRights: (access: AccessContext, runId: string, kind: RunRightsKind) => void;
   projectView: (view: RunView, access: AccessContext) => RunView;
   hasRun: (runId: string) => boolean;
 };
 
-const activeActorId = (runtime: Orchestration, runId: string, reference: string) => {
-  const state = runtime.state(runId);
-  const direct = state.actors.get(reference);
-  if (direct) return direct.id;
-  const wanted = reference.trim().replace(/^@/, "").toLowerCase();
-  const sharing = [...state.actors.values()].filter((actor) => actor.handle === wanted);
-  const found = sharing.find((actor) => actor.kind === "human" || actor.lifecycle.kind !== "stopped") ?? sharing.at(-1);
-  if (!found) throw new DomainError("actor-not-found", `Actor ${reference} does not exist.`, 404);
-  return found.id;
-};
-
-/** Die Laufzeitmethoden der Engine: Laufansicht, Journal, Warteschlangen, Stopp und Rückfragen. */
+/** Die Laufzeitmethoden der Engine: Run-Ansicht, Journal, Warteschlangen, Unterbrechen, Stopp und Rückfragen. */
 export function runtimeMethods(options: RuntimeMethodOptions): MethodContribution[] {
   const { runtime, assertRunRights, projectView } = options;
   const assertAvailable = options.assertAvailable ?? (() => undefined);
   const assertRunUsable = options.assertRunUsable ?? (() => undefined);
-  const commands = new SerialQueue();
+  const commands = new KeyedSerialQueue();
   const contextOf = (runId: string, body: { commandId: string; correlationId?: string; causationId?: string }): CommandContext => {
     assertRunUsable(runId);
     return {
@@ -50,7 +44,7 @@ export function runtimeMethods(options: RuntimeMethodOptions): MethodContributio
       ...(body.causationId ? { causationId: body.causationId } : {}),
     };
   };
-  const mutate = <Result>(work: () => Result) => commands.run(() => {
+  const mutate = <Result>(runId: string, work: () => Result) => commands.run(runId, () => {
     assertAvailable();
     return work();
   });
@@ -78,40 +72,45 @@ export function runtimeMethods(options: RuntimeMethodOptions): MethodContributio
     }),
     implement(runContracts.enqueueInput, (input, { access }) => {
       prepared(access, input.runId, "write-inspect");
-      return mutate(() => {
+      return mutate(input.runId, () => {
         runtime.enqueueInput(contextOf(input.runId, input), input.runId, { actorId: input.actorId, content: input.content, artifactIds: input.artifactIds ?? [] });
         return projectView(runtime.view(input.runId), access);
       });
     }),
     implement(runContracts.restartActor, (input, { access }) => {
       prepared(access, input.runId, "write-inspect");
-      return mutate(() => {
-        runtime.restartActor(contextOf(input.runId, input), input.runId, input.actorId, input.reason ?? "Vom Bediener neu gestartet");
+      return mutate(input.runId, () => {
+        const actorId = addressedActorOf(runtime.state(input.runId).actors.values(), input.actorId).id;
+        runtime.restartActor(contextOf(input.runId, input), input.runId, actorId, input.reason ?? "Vom Bediener neu gestartet");
         return projectView(runtime.view(input.runId), access);
       });
     }),
     implement(runContracts.stopActor, (input, { access }) => {
-      prepared(access, input.runId, "write");
-      return mutate(() => {
-        const context = contextOf(input.runId, input);
-        const actorId = activeActorId(runtime, input.runId, input.actorId);
-        const after = runtime.stopActor(context, input.runId, actorId, input.reason);
-        const failures = stopLineage(runtime, input.runId, descendantsOf(after, actorId), input.reason,
-          (step) => ({ ...context, commandId: `${input.commandId}:${step}` }));
-        if (failures.length > 0) throw new AggregateError(failures, `Actor ${actorId} could not be stopped completely.`);
-        return projectView(runtime.view(input.runId), access);
+      prepared(access, input.runId, "stop");
+      return mutate(input.runId, () => {
+        const actorId = addressedActorOf(runtime.state(input.runId).actors.values(), input.actorId).id;
+        return projectView(runtime.stopActor(contextOf(input.runId, input), input.runId, actorId, input.reason), access);
       });
     }),
+    implement(runContracts.interruptTurn, async (input, { access }) => {
+      prepared(access, input.runId, "stop");
+      const actorId = addressedActorOf(runtime.state(input.runId).actors.values(), input.actorId).id;
+      await options.interruptTurn(input.runId, actorId, {
+        context: contextOf(input.runId, input),
+        reason: input.reason ?? "Turn durch den Bediener unterbrochen",
+      });
+      return projectView(runtime.view(input.runId), access);
+    }),
     implement(runContracts.resolveAction, (input, { access }) => {
       prepared(access, input.runId, "write");
-      return mutate(() => {
-        runtime.resolveAction(contextOf(input.runId, input), input.runId, input.actionId, { decision: input.decision, response: input.response ?? null });
+      return mutate(input.runId, () => {
+        runtime.resolveAction(contextOf(input.runId, input), input.runId, input.actionId, { decision: input.decision, result: input.result ?? null });
         return projectView(runtime.view(input.runId), access);
       });
     }),
     implement(runContracts.stopAll, async (input, { access }) => {
-      prepared(access, input.runId, "write");
-      const view = await mutate(() => stopRun(input.runId, input));
+      prepared(access, input.runId, "stop");
+      const view = await mutate(input.runId, () => stopRun(input.runId, input));
       return projectView(view, access);
     }),
   ];

package/packages/ragents/src/index.ts

@@ -42,19 +42,18 @@ export * from "./rpc/protocol.ts";
 export * from "./rpc/contract.ts";
 export * from "./rpc/contribution.ts";
 export { RpcPeer, rpcErrorOf, rpcFailureOf, type RpcCallOptions, type RpcHandlerContext, type RpcPeerOptions } from "./rpc/peer.ts";
-export { assertJsonValue, type JsonValue } from "./domain/json.ts";
+export { assertJsonValue, type JsonObject, type JsonValue } from "./domain/json.ts";
 export { PluginStateProjection, pluginStateAt } from "./domain/plugin-state.ts";
+export { actorByHandle, actorByReference, handleKey, type ReferencedActor } from "./domain/actor-reference.ts";
 export { runtimeMethods, artifactContentRoute, artifactContentPath, ARTIFACT_CONTENT_PATH, type RuntimeMethodOptions, type RunRightsKind } from "./http/methods.ts";
 export { runContracts, openJson, runViewSchema, journalEventSchema } from "./http/contracts.ts";
 export {
-    emptyRegistry,
     ToolRegistry,
-    type AgentToolPlugin,
     type PluginContext,
     type ToolContributor,
     type ToolProvider,
 } from "./agents/plugins.ts";
-export { TurnScheduler, type TurnSchedulerOptions } from "./agents/scheduler.ts";
+export { TurnScheduler, type TurnInterruption, type TurnSchedulerOptions } from "./agents/scheduler.ts";
 export {
     agentTools,
     defineToolAvailability,
@@ -74,14 +73,9 @@ export type { ToolChapters } from "./agents/tool-orientation.ts";
 export {
     actorInputSchema,
     enqueueActorInput,
-    eventResultSchema,
+    eventResultSchemaOf,
     type ActorInputRequest,
 } from "./agents/actor-input.ts";
-export {
-    jsonTypeScriptDiagnostics,
-    typeScriptDiagnosticSchema,
-    type JsonTypeScriptDiagnostic,
-} from "./agents/schemas.ts";
 export {
     type WorkspaceToolNames,
     type WorkspaceToolNaming,
@@ -94,7 +88,7 @@ export {
     type ScriptInput,
 } from "./agents/delivery.ts";
 export { TurnToolset, schemaComplaints, type ToolInvocation } from "./agents/toolset.ts";
-export { agentFrom, claimTurn, promptFor, workingActorFrom, type ClaimedTurn } from "./agents/turn.ts";
+export { claimTurn, workingActorFrom, type ClaimedTurn } from "./agents/turn.ts";
 export { FixedWorkspaces, type Workspaces } from "./agents/workspaces.ts";
 export {
     AgentSessionDriver,
@@ -109,7 +103,6 @@ export {
     type SkillPreloadConfiguration,
     type SkillPreloadOptions,
     type AgentSessionStore,
-    type AgentThinkingLevel,
     type SkillCatalogEntry,
     type SkillSelectionRequest,
     type SkillSelector,
@@ -140,14 +133,11 @@ export { SerialQueue } from "./runtime/serial-queue.ts";
 export {
     RunStopper,
     descendantsOf,
-    lineageSteps,
-    stopLineage,
     type RunStopCommand,
     type RunStopBoundary,
     type RunStopJournal,
     type RunStopOperation,
     type RunStopperOptions,
-    type WorkingActor,
 } from "./runtime/stop.ts";
 export { ScriptDriver, type ScriptDriverOptions } from "./script/driver.ts";
 export { createScriptStd, scriptStdDeclarations, type ScriptStdBinding } from "./script/std.ts";