@schlenkr/ragents 0.1.0

package/plugins/ragents.watch/server/observation.ts

@@ -0,0 +1,69 @@
+import type { ExecutableActor, JournalEvent, JsonValue, RunView } from "@aicontainer/ragents";
+
+const OUTPUT_CHARS = 600;
+
+export interface ActorObservation {
+  lifecycle: "idle" | "running" | "stopped";
+  stopReason?: string;
+  completedTurns: number;
+  lastTurn?: { status: string; reason?: string };
+  pendingInputs: number;
+  openQuestions: number;
+  lastOutput?: string;
+}
+
+export const actorByReference = (view: RunView, reference: string): ExecutableActor | undefined => {
+  const handle = reference.startsWith("@") ? reference.slice(1) : reference;
+  return view.actors.find((actor): actor is ExecutableActor => actor.kind !== "human" && (actor.id === reference || actor.handle === handle));
+};
+
+export const observeActor = (view: RunView, actorId: string): ActorObservation | undefined => {
+  const actor = view.actors.find((candidate): candidate is ExecutableActor => candidate.kind !== "human" && candidate.id === actorId);
+  if (!actor) return undefined;
+  const turns = view.turns.filter((turn) => turn.actorId === actorId);
+  const last = turns.at(-1);
+  const output = turns.findLast((turn) => turn.status !== "running" && turn.outputs.length > 0)?.outputs.at(-1)?.text;
+  return {
+    lifecycle: actor.lifecycle.kind,
+    ...(actor.lifecycle.kind === "stopped" ? { stopReason: actor.lifecycle.reason } : {}),
+    completedTurns: turns.filter((turn) => turn.status !== "running").length,
+    ...(last ? { lastTurn: { status: last.status, ...(last.reason ? { reason: last.reason } : {}) } } : {}),
+    pendingInputs: view.inputs.filter((input) => input.actorId === actorId && input.lifecycle.kind === "pending").length,
+    openQuestions: view.actions.filter((action) => action.askedBy === actorId && action.kind === "question" && action.status === "pending").length,
+    ...(output ? { lastOutput: output.length > OUTPUT_CHARS ? `...${output.slice(-OUTPUT_CHARS)}` : output } : {}),
+  };
+};
+
+export const lastActivityOf = (events: readonly JournalEvent[], actor: ExecutableActor): string => {
+  const event = events.findLast((candidate) => candidate.actorId === actor.id
+    || candidate.type === "actor.input.enqueued" && candidate.payload.actorId === actor.id
+    || (candidate.type === "turn.finished" || candidate.type === "turn.interrupted") && candidate.actorId === actor.id);
+  return event?.occurredAt ?? actor.createdAt;
+};
+
+const isObject = (value: JsonValue): value is { [key: string]: JsonValue } => typeof value === "object" && value !== null && !Array.isArray(value);
+
+export const flattenJson = (value: JsonValue, prefix = "", into = new Map<string, string>()): Map<string, string> => {
+  if (Array.isArray(value)) {
+    if (value.length === 0 && prefix) into.set(prefix, "[]");
+    value.forEach((entry, index) => flattenJson(entry, prefix ? `${prefix}.${index}` : String(index), into));
+  } else if (isObject(value)) {
+    const keys = Object.keys(value);
+    if (keys.length === 0 && prefix) into.set(prefix, "{}");
+    for (const key of keys) flattenJson(value[key], prefix ? `${prefix}.${key}` : key, into);
+  } else into.set(prefix || "$", JSON.stringify(value));
+  return into;
+};
+
+export const changesBetween = (before: JsonValue | undefined, after: JsonValue): string[] => {
+  const previous = before === undefined ? new Map<string, string>() : flattenJson(before);
+  const current = flattenJson(after);
+  const lines: string[] = [];
+  for (const [path, value] of current) {
+    const old = previous.get(path);
+    if (old === undefined) lines.push(`${path}: ${value}${before === undefined ? "" : " (neu)"}`);
+    else if (old !== value) lines.push(`${path}: ${old} -> ${value}`);
+  }
+  for (const path of previous.keys()) if (!current.has(path)) lines.push(`${path}: entfernt`);
+  return lines;
+};

package/plugins/ragents.watch/server/service.ts

@@ -0,0 +1,294 @@
+import { randomUUID } from "node:crypto";
+import { DomainError, type ExecutableActor, type JournalEvent, type JsonValue, type Orchestration, type RunView } from "@aicontainer/ragents";
+import { WATCH_PLUGIN_ID, type WatchDefinition, type WatchRequest, type WatchServiceApi, type WatchSummary, type WatchVerdict } from "../contract.js";
+import { actorByReference, changesBetween, lastActivityOf, observeActor } from "./observation.js";
+import type { WatchPredicate } from "./condition.js";
+
+const CONDITION_CHARS = 4_000;
+const INSTRUCTION_CHARS = 2_000;
+const HISTORY_LENGTH = 10;
+
+type StoredWatch = WatchDefinition & { baseline?: JsonValue; wakes: number; history?: WatchVerdict[] };
+interface WatchState { version: 1; watches: StoredWatch[] }
+
+interface WatchRuntime {
+  definition: WatchDefinition;
+  predicate: WatchPredicate;
+  baseline?: JsonValue;
+  wakes: number;
+  lastEvaluated?: string;
+  lastEvaluatedAt?: string;
+  lastJudgedChanges?: string;
+  history: WatchVerdict[];
+}
+
+interface RunWatches {
+  runId: string;
+  unsubscribe: () => void;
+  abort: AbortController;
+  watches: Map<string, WatchRuntime>;
+  debounce?: ReturnType<typeof setTimeout>;
+  stallTimer?: ReturnType<typeof setInterval>;
+  evaluating?: Promise<void>;
+  dirty: boolean;
+}
+
+export interface WatchServiceOptions {
+  runtime: () => Orchestration;
+  compile: (condition: string, signal: AbortSignal) => Promise<WatchPredicate>;
+  observe: (runId: string, operationId: string, signal: AbortSignal) => Promise<JsonValue>;
+  operationExists: (operationId: string) => boolean;
+  debounceMs?: number;
+  stallCheckMs?: number;
+  now?: () => number;
+  log?: (message: string, error?: unknown) => void;
+}
+
+const summaryOf = (watch: WatchRuntime): WatchSummary => ({
+  id: watch.definition.id,
+  source: `@${watch.definition.sourceHandle}`,
+  target: `@${watch.definition.targetHandle}`,
+  condition: watch.definition.condition,
+  ...(watch.definition.observe ? { observe: watch.definition.observe } : {}),
+  ...(watch.definition.stallAfterSeconds ? { stallAfterSeconds: watch.definition.stallAfterSeconds } : {}),
+  wakes: watch.wakes,
+  ...(watch.lastEvaluatedAt ? { lastEvaluatedAt: watch.lastEvaluatedAt } : {}),
+  ...(watch.history.length ? { lastVerdict: watch.history[watch.history.length - 1] } : {}),
+});
+
+const invalid = (message: string) => new DomainError("watch-invalid", message, 400);
+
+const cleanText = (value: string | undefined, field: string, limit: number): string | undefined => {
+  if (value === undefined) return undefined;
+  const text = value.trim();
+  if (!text) throw invalid(`${field} darf nicht leer sein.`);
+  if (text.length > limit) throw invalid(`${field} darf höchstens ${limit} Zeichen enthalten.`);
+  return text;
+};
+
+export const wakeMessage = (definition: WatchDefinition, reason: string, changes: readonly string[]): string => [
+  `Der Wächter weckt Dich: ${reason}`,
+  `Änderungen bei @${definition.sourceHandle} seit der letzten Weckung:\n${changes.length ? changes.map((line) => `- ${line}`).join("\n") : "- keine"}`,
+  ...(definition.instruction ? [definition.instruction] : []),
+].join("\n");
+
+export class WatchService implements WatchServiceApi {
+  readonly #options: WatchServiceOptions;
+  readonly #runs = new Map<string, RunWatches>();
+  #closed = false;
+
+  constructor(options: WatchServiceOptions) {
+    this.#options = options;
+  }
+
+  #now(): number {
+    return this.#options.now ? this.#options.now() : Date.parse(this.#options.runtime().now());
+  }
+
+  async create(runId: string, callerActorId: string, request: WatchRequest): Promise<WatchSummary> {
+    const runtime = this.#options.runtime();
+    const view = runtime.view(runId);
+    const source = actorByReference(view, request.source);
+    if (!source) throw invalid(`Der beobachtete Actor ${request.source} existiert in diesem Run nicht.`);
+    const target = request.target ? actorByReference(view, request.target) : actorByReference(view, callerActorId);
+    if (!target) throw invalid(`Der zu weckende Actor ${request.target ?? callerActorId} existiert in diesem Run nicht oder ist kein Agent.`);
+    const condition = cleanText(request.condition, "condition", CONDITION_CHARS)!;
+    const instruction = cleanText(request.instruction, "instruction", INSTRUCTION_CHARS);
+    if (request.observe !== undefined && !this.#options.operationExists(request.observe)) throw invalid(`Die Operation ${request.observe} ist nicht registriert.`);
+    if (request.stallAfterSeconds !== undefined && (!Number.isInteger(request.stallAfterSeconds) || request.stallAfterSeconds < 1)) throw invalid("stallAfterSeconds muss eine positive ganze Zahl sein.");
+    const run = this.#ensure(runId);
+    const existing = [...run.watches.values()].find((watch) => watch.definition.sourceActorId === source.id && watch.definition.targetActorId === target.id && watch.definition.condition === condition);
+    if (existing) return summaryOf(existing);
+    const predicate = await this.#options.compile(condition, run.abort.signal);
+    if (this.#runs.get(runId) !== run) throw invalid("Der Run wurde während des Anlegens beendet.");
+    const definition: WatchDefinition = {
+      id: `watch_${randomUUID()}`,
+      sourceActorId: source.id,
+      sourceHandle: source.handle,
+      targetActorId: target.id,
+      targetHandle: target.handle,
+      condition,
+      ...(request.observe !== undefined ? { observe: request.observe } : {}),
+      ...(instruction !== undefined ? { instruction } : {}),
+      ...(request.stallAfterSeconds !== undefined ? { stallAfterSeconds: request.stallAfterSeconds } : {}),
+      createdBy: callerActorId,
+    };
+    const watch: WatchRuntime = { definition, predicate, wakes: 0, history: [] };
+    run.watches.set(definition.id, watch);
+    this.#persist(run);
+    this.#updateStallTimer(run);
+    this.#schedule(run, true);
+    return summaryOf(watch);
+  }
+
+  list(runId: string): WatchSummary[] {
+    return [...(this.#runs.get(runId)?.watches.values() ?? [])].map(summaryOf);
+  }
+
+  remove(runId: string, watchId: string, reason: string): void {
+    const run = this.#runs.get(runId);
+    const watch = run?.watches.get(watchId);
+    if (!run || !watch) throw new DomainError("watch-unknown", `Der Wächter ${watchId} existiert in diesem Run nicht.`, 404);
+    if (!reason.trim()) throw invalid("reason darf nicht leer sein.");
+    run.watches.delete(watchId);
+    this.#persist(run);
+    this.#updateStallTimer(run);
+  }
+
+  async prepare(runId: string): Promise<void> {
+    if (this.#closed || this.#runs.has(runId)) return;
+    const runtime = this.#options.runtime();
+    if (runtime.events(runId).length === 0) return;
+    const stored = this.#stored(runtime.view(runId));
+    if (stored.length === 0) return;
+    const run = this.#ensure(runId);
+    for (const entry of stored) {
+      const { baseline, wakes, history, ...definition } = entry;
+      const predicate = await this.#options.compile(definition.condition, run.abort.signal);
+      if (this.#runs.get(runId) !== run) return;
+      run.watches.set(definition.id, { definition, predicate, ...(baseline !== undefined ? { baseline } : {}), wakes, history: history ?? [] });
+    }
+    this.#updateStallTimer(run);
+    this.#schedule(run, true);
+  }
+
+  stop(runId: string): void {
+    const run = this.#runs.get(runId);
+    if (!run) return;
+    this.#runs.delete(runId);
+    run.unsubscribe();
+    run.abort.abort();
+    if (run.debounce) clearTimeout(run.debounce);
+    if (run.stallTimer) clearInterval(run.stallTimer);
+  }
+
+  shutdown(): void {
+    for (const runId of [...this.#runs.keys()]) this.stop(runId);
+    this.#closed = true;
+  }
+
+  #stored(view: RunView): StoredWatch[] {
+    const state = view.pluginStates.find((entry) => entry.pluginId === WATCH_PLUGIN_ID && entry.scope.kind === "run")?.state as unknown as WatchState | undefined;
+    return state?.watches ?? [];
+  }
+
+  #ensure(runId: string): RunWatches {
+    if (this.#closed) throw new Error("Der Wächterdienst ist beendet.");
+    const existing = this.#runs.get(runId);
+    if (existing) return existing;
+    const runtime = this.#options.runtime();
+    const run: RunWatches = {
+      runId,
+      unsubscribe: runtime.subscribe((events) => { if (events.some((event) => event.runId === runId)) this.#schedule(run); }),
+      abort: new AbortController(),
+      watches: new Map(),
+      dirty: false,
+    };
+    this.#runs.set(runId, run);
+    return run;
+  }
+
+  #persist(run: RunWatches): void {
+    const runtime = this.#options.runtime();
+    const view = runtime.view(run.runId);
+    const state: WatchState = { version: 1, watches: [...run.watches.values()].map((watch) => ({ ...watch.definition, ...(watch.baseline !== undefined ? { baseline: watch.baseline } : {}), wakes: watch.wakes, history: watch.history })) };
+    runtime.replacePluginState({ actorId: view.ownerId, commandId: `ragents.watch:state:${randomUUID()}` }, run.runId, { pluginId: WATCH_PLUGIN_ID, scope: { kind: "run" }, state: state as unknown as JsonValue });
+  }
+
+  #updateStallTimer(run: RunWatches): void {
+    const needed = [...run.watches.values()].some((watch) => watch.definition.stallAfterSeconds !== undefined);
+    if (!needed && run.stallTimer) { clearInterval(run.stallTimer); run.stallTimer = undefined; }
+    if (needed && !run.stallTimer) {
+      run.stallTimer = setInterval(() => this.#schedule(run), this.#options.stallCheckMs ?? 30_000);
+      run.stallTimer.unref();
+    }
+  }
+
+  #schedule(run: RunWatches, immediate = false): void {
+    if (this.#runs.get(run.runId) !== run) return;
+    if (run.evaluating) { run.dirty = true; return; }
+    if (immediate) {
+      if (run.debounce) { clearTimeout(run.debounce); run.debounce = undefined; }
+      this.#start(run);
+      return;
+    }
+    if (run.debounce) return;
+    run.debounce = setTimeout(() => { run.debounce = undefined; this.#start(run); }, this.#options.debounceMs ?? 1_000);
+    run.debounce.unref();
+  }
+
+  #start(run: RunWatches): void {
+    run.evaluating = this.#evaluateAll(run).finally(() => {
+      run.evaluating = undefined;
+      if (run.dirty) { run.dirty = false; this.#schedule(run); }
+    });
+  }
+
+  async #evaluateAll(run: RunWatches): Promise<void> {
+    for (const watch of [...run.watches.values()]) {
+      if (this.#runs.get(run.runId) !== run || !run.watches.has(watch.definition.id)) return;
+      try { await this.#evaluate(run, watch); }
+      catch (error) {
+        if (run.abort.signal.aborted) return;
+        (this.#options.log ?? ((message, cause) => console.error(message, cause)))(`Wächter ${watch.definition.id} in Run ${run.runId} konnte nicht bewerten:`, error);
+      }
+    }
+  }
+
+  async #evaluate(run: RunWatches, watch: WatchRuntime): Promise<void> {
+    const runtime = this.#options.runtime();
+    const view = runtime.view(run.runId);
+    const source = view.actors.find((actor): actor is ExecutableActor => actor.kind !== "human" && actor.id === watch.definition.sourceActorId);
+    const target = view.actors.find((actor): actor is ExecutableActor => actor.kind !== "human" && actor.id === watch.definition.targetActorId);
+    if (!source || !target || target.lifecycle.kind === "stopped") return;
+    const observation = await this.#observe(run, watch, view, source, runtime.events(run.runId));
+    if (this.#runs.get(run.runId) !== run || !run.watches.has(watch.definition.id)) return;
+    const key = JSON.stringify(observation);
+    if (watch.baseline === undefined) {
+      watch.baseline = observation;
+      watch.lastEvaluated = key;
+      this.#persist(run);
+      return;
+    }
+    if (key === watch.lastEvaluated) return;
+    const current = runtime.view(run.runId);
+    const busy = current.actors.find((actor): actor is ExecutableActor => actor.kind !== "human" && actor.id === target.id)?.lifecycle.kind !== "idle"
+      || current.inputs.some((input) => input.actorId === target.id && input.lifecycle.kind === "pending")
+      || current.actions.some((action) => action.askedBy === target.id && action.kind === "question" && action.status === "pending");
+    if (busy) return;
+    const unsettled = source.lifecycle.kind === "running" || current.inputs.some((input) => input.actorId === source.id && input.lifecycle.kind === "pending");
+    if (unsettled && !(typeof observation === "object" && observation !== null && "stalledForSeconds" in observation)) return;
+    const changes = changesBetween(watch.baseline, observation);
+    const judged = JSON.stringify(changes);
+    if (changes.length === 0 || judged === watch.lastJudgedChanges) { watch.lastEvaluated = key; return; }
+    const reason = watch.predicate(observation, watch.baseline);
+    const at = new Date(this.#now()).toISOString();
+    watch.lastEvaluated = key;
+    watch.lastEvaluatedAt = at;
+    watch.lastJudgedChanges = judged;
+    watch.history = [...watch.history, { at, wake: reason !== undefined, reason: reason ?? "Bedingung nicht erfüllt", changes }].slice(-HISTORY_LENGTH);
+    if (reason === undefined) {
+      if (changes.some((line) => !line.startsWith("stalledForSeconds:"))) this.#persist(run);
+      return;
+    }
+    runtime.enqueueInput({ actorId: current.ownerId, commandId: `ragents.watch:wake:${watch.definition.id}:${randomUUID()}` }, run.runId, {
+      actorId: target.id,
+      presentation: "background",
+      content: wakeMessage(watch.definition, reason, changes),
+    });
+    watch.baseline = observation;
+    watch.wakes += 1;
+    this.#persist(run);
+  }
+
+  async #observe(run: RunWatches, watch: WatchRuntime, view: RunView, source: ExecutableActor, events: readonly JournalEvent[]): Promise<JsonValue> {
+    const observed = watch.definition.observe ? await this.#options.observe(run.runId, watch.definition.observe, run.abort.signal) : undefined;
+    const stall = watch.definition.stallAfterSeconds;
+    const age = stall ? this.#now() - Date.parse(lastActivityOf(events, source)) : 0;
+    return {
+      source: observeActor(view, source.id) as unknown as JsonValue,
+      ...(observed !== undefined ? { observed } : {}),
+      ...(stall && age >= stall * 1_000 ? { stalledForSeconds: Math.floor(age / (stall * 1_000)) * stall } : {}),
+    };
+  }
+}

package/plugins/ragents.workspace/client/transport.ts

@@ -0,0 +1,13 @@
+import { RpcClient } from "../../../apps/web/src/rpc/client";
+import type { WorkspaceClientTransport } from "./workspace-client";
+
+/** Ein Arbeitsplatz-Zugang ohne Oberfläche: die Nachrichtenschicht mit Bearer-Token. */
+export const workspaceClientTransport = (baseUrl: string, token: string | undefined): WorkspaceClientTransport => ({
+  rpc: new RpcClient({
+    baseUrl: new URL(baseUrl).origin,
+    fetch: (input, init) => {
+      const headers = init?.headers as Record<string, string> | undefined ?? {};
+      return fetch(input, { ...init, headers: token === undefined ? headers : { ...headers, authorization: `Bearer ${token}` } });
+    },
+  }),
+});

package/plugins/ragents.workspace/client/workspace-client.ts

@@ -0,0 +1,247 @@
+import { realpath } from "node:fs/promises";
+import { homedir, tmpdir } from "node:os";
+import { basename, dirname, join, resolve, sep } from "node:path";
+import {
+  SandboxWorkspaceExecutor,
+  WORKSPACE_EXECUTOR_VERSION,
+  WORKSPACE_STOP_OPERATION,
+  workspaceLanguageServers,
+  workspaceProcessContext,
+  type WorkspaceProcessContext,
+} from "@aicontainer/workspace-executor";
+import type { RpcClient } from "../../../apps/web/src/rpc/client";
+import type { OperationInput } from "../../../packages/ragents/src/rpc/contract";
+import type { RpcHandlerContext } from "../../../packages/ragents/src/rpc/peer";
+import {
+  workspaceClientContracts,
+  workspaceContracts,
+  type WorkspaceBinding,
+  type WorkspaceClientDescription,
+} from "../contract";
+
+export type WorkspaceClientStatus =
+  | { kind: "idle" }
+  | { kind: "registered" }
+  | { kind: "failed"; message: string };
+
+export interface WorkspaceClientIdentity extends WorkspaceClientDescription {
+  id: string;
+}
+
+/** Ein abgeschlossener Auftrag des Servers; der Aufrufer entscheidet, wohin die Zeile geht. */
+export interface WorkspaceClientExecution {
+  runId: string;
+  tool: string;
+  durationMs: number;
+  error: string | undefined;
+}
+
+export interface WorkspaceClientOptions {
+  onExecuted?: (execution: WorkspaceClientExecution) => void;
+}
+
+/** Was der Arbeitsplatz zum Server braucht: die Nachrichtenschicht. */
+export interface WorkspaceClientTransport {
+  readonly rpc: RpcClient;
+}
+
+type ExecuteInput = OperationInput<typeof workspaceClientContracts.execute>;
+
+const messageOf = (cause: unknown): string => cause instanceof Error ? cause.message : String(cause);
+
+/** Der echte Pfad des nächsten vorhandenen Elternordners, um die noch fehlenden Namen ergänzt. */
+const realPathOf = async (target: string): Promise<string> => {
+  try {
+    return await realpath(target);
+  } catch {
+    const parent = dirname(target);
+    return parent === target ? target : join(await realPathOf(parent), basename(target));
+  }
+};
+
+const sameFolders = (left: readonly string[], right: readonly string[]): boolean =>
+  left.length === right.length && left.every((folder, index) => folder === right[index]);
+
+/** Der Arbeitsplatz: meldet seine Ordner an und führt die Aufträge des Servers mit dem Executor dieser Maschine aus. */
+export class WorkspaceClient {
+  #identity: WorkspaceClientIdentity;
+  #status: WorkspaceClientStatus = { kind: "idle" };
+  #announcing: Promise<void> | undefined;
+  readonly #listeners = new Set<() => void>();
+  readonly #attached: Array<() => void> = [];
+  readonly #runs = new Map<string, WorkspaceProcessContext>();
+  readonly #executor: SandboxWorkspaceExecutor;
+
+  constructor(
+    private readonly transport: WorkspaceClientTransport,
+    identity: WorkspaceClientIdentity,
+    private readonly options: WorkspaceClientOptions = {},
+  ) {
+    this.#identity = { ...identity, folders: [...identity.folders] };
+    this.#executor = new SandboxWorkspaceExecutor({
+      contextFor: (runId) => this.#contextFor(runId),
+      languageServers: workspaceLanguageServers,
+    });
+  }
+
+  get id(): string {
+    return this.#identity.id;
+  }
+
+  get label(): string {
+    return this.#identity.label;
+  }
+
+  get folders(): readonly string[] {
+    return this.#identity.folders;
+  }
+
+  get status(): WorkspaceClientStatus {
+    return this.#status;
+  }
+
+  onChange(listener: () => void): () => void {
+    this.#listeners.add(listener);
+    return () => { this.#listeners.delete(listener); };
+  }
+
+  /** Erst die Operation anbieten - das öffnet den Strom -, dann anmelden, sobald er steht; der Strom ist der Rückweg des Servers. */
+  async register(): Promise<void> {
+    this.#attach();
+    try {
+      await this.#connected();
+    } catch (cause) {
+      this.#set({ kind: "failed", message: messageOf(cause) });
+      return;
+    }
+    await this.#announce();
+  }
+
+  /** Geänderte Ordner werden erneut angemeldet; ohne Ordner meldet sich der Arbeitsplatz ab. */
+  async update(folders: readonly string[]): Promise<void> {
+    if (sameFolders(this.#identity.folders, folders)) return;
+    this.#identity = { ...this.#identity, folders: [...folders] };
+    if (this.#status.kind === "idle") return;
+    if (folders.length === 0) await this.unregister();
+    else await this.register();
+  }
+
+  async unregister(): Promise<void> {
+    for (const release of this.#attached.splice(0)) release();
+    this.#set({ kind: "idle" });
+    this.#runs.clear();
+    await this.#executor.shutdown();
+    try {
+      await this.transport.rpc.call(workspaceContracts.clients.unregister, { id: this.id });
+    } catch (cause) {
+      this.#set({ kind: "failed", message: messageOf(cause) });
+    }
+  }
+
+  /** Der Arbeitsplatz bindet immer sich selbst; wo der Server läuft, ändert daran nichts. */
+  binding(folder: string): WorkspaceBinding {
+    return { kind: "client", client: this.id, label: this.label, path: folder };
+  }
+
+  #attach(): void {
+    if (this.#attached.length > 0) return;
+    const rpc = this.transport.rpc;
+    this.#attached.push(
+      rpc.handle(workspaceClientContracts.execute, (input, context) => this.#execute(input, context)),
+      rpc.onConnected(() => void this.#announce()),
+    );
+  }
+
+  /** Wartet auf den Ereignisstrom; ohne ihn nimmt der Server die Anmeldung nicht an. */
+  #connected(): Promise<void> {
+    const rpc = this.transport.rpc;
+    if (rpc.status.kind === "connected") return Promise.resolve();
+    return new Promise((settle, fail) => {
+      const release = rpc.onStatus((status) => {
+        if (status.kind === "connecting") return;
+        release();
+        if (status.kind === "connected") settle();
+        else if (status.kind === "retrying") fail(new Error(status.message));
+        else if (status.kind === "unauthorized") fail(new Error("Der Server verlangt eine Anmeldung."));
+        else fail(new Error("Der Ereignisstrom des Servers ist geschlossen."));
+      });
+    });
+  }
+
+  #announce(): Promise<void> {
+    this.#announcing ??= this.#send().finally(() => { this.#announcing = undefined; });
+    return this.#announcing;
+  }
+
+  async #send(): Promise<void> {
+    try {
+      await this.transport.rpc.call(workspaceContracts.clients.register, {
+        id: this.#identity.id,
+        label: this.#identity.label,
+        hostname: this.#identity.hostname,
+        platform: this.#identity.platform,
+        folders: [...this.#identity.folders],
+        executor: WORKSPACE_EXECUTOR_VERSION,
+      });
+      this.#set({ kind: "registered" });
+    } catch (cause) {
+      this.#set({ kind: "failed", message: messageOf(cause) });
+    }
+  }
+
+  /** Der Entwickler arbeitet auf seinem Arbeitsplatz mit seinen eigenen Zugangsdaten; HOME bleibt sein Home. */
+  async #execute(input: ExecuteInput, context: RpcHandlerContext): Promise<{ value: unknown }> {
+    const cwd = await this.#inside(input.cwd);
+    this.#runs.set(input.runId, workspaceProcessContext({
+      runId: input.runId,
+      cwd,
+      root: await realPathOf(cwd),
+      home: { home: homedir() },
+      logDirectory: join(tmpdir(), "ragents-workspace-logs", input.runId),
+      additions: input.env,
+    }));
+    const startedAt = Date.now();
+    let failure: string | undefined;
+    try {
+      const value = await this.#executor.execute(input.runId, input.tool, input.input, {
+        toolCallId: input.toolCallId,
+        signal: context.signal,
+        onProgress: (text) => context.progress({ text }),
+      });
+      return { value };
+    } catch (cause) {
+      failure = messageOf(cause);
+      throw cause;
+    } finally {
+      if (input.tool === WORKSPACE_STOP_OPERATION) this.#runs.delete(input.runId);
+      this.options.onExecuted?.({
+        runId: input.runId,
+        tool: input.tool,
+        durationMs: Date.now() - startedAt,
+        error: failure,
+      });
+    }
+  }
+
+  #contextFor(runId: string): Promise<WorkspaceProcessContext> {
+    const context = this.#runs.get(runId);
+    if (!context) throw new Error(`Für den Run ${runId} liegt auf diesem Arbeitsplatz kein Auftrag vor`);
+    return Promise.resolve(context);
+  }
+
+  /** Jeder Auftrag muss in einem der angebotenen Ordner liegen; fehlende Pfade zählen über ihren vorhandenen Elternordner. */
+  async #inside(candidate: string): Promise<string> {
+    const target = resolve(candidate);
+    const real = await realPathOf(target);
+    const roots = await Promise.all(this.#identity.folders.map((folder) => realPathOf(resolve(folder))));
+    if (!roots.some((root) => real === root || real.startsWith(`${root}${sep}`))) {
+      throw new Error(`Pfad außerhalb des angebotenen Ordners: ${candidate}`);
+    }
+    return target;
+  }
+
+  #set(status: WorkspaceClientStatus): void {
+    this.#status = status;
+    for (const listener of [...this.#listeners]) listener();
+  }
+}