@schlenkr/ragents 0.1.0

package/packages/ragents/src/typescript/index.ts

@@ -0,0 +1,48 @@
+export {
+    canonicalTypeScriptBuildContract,
+    compileVirtualTypeScript,
+    typeScriptBuildContractHash,
+    type CompileVirtualTypeScriptRequest,
+    type VirtualTypeScriptCompilation,
+    type VirtualTypeScriptDiagnostic,
+    type VirtualTypeScriptDiagnosticCategory,
+    type VirtualTypeScriptEmit,
+    type VirtualTypeScriptFile,
+    type VirtualTypeScriptLibrary,
+    type VirtualTypeScriptPosition,
+} from "./compiler.ts";
+export {
+    VirtualTypeScriptWorkerError,
+    compileVirtualTypeScriptAsync,
+    type CompileVirtualTypeScriptAsyncOptions,
+    type VirtualTypeScriptWorkerErrorCode,
+} from "./async-compiler.ts";
+export { typeScriptTypeFromSchema, typeScriptTypesFromSchema } from "./schema.ts";
+export {
+    createRunContextDeclarations,
+    runCapabilityBindingHash,
+    runCapabilityContract,
+    runCapabilityContractHash,
+    runContextApiVersion,
+    createRunContext,
+    type RunCapabilityDescriptor,
+    type RunCapabilityPolicyBinding,
+    type RunCapabilityPrincipalBinding,
+    type RunCapabilityPort,
+    type RunContextBinding,
+    type RunContextDeclarationsOptions,
+    type RunInvocationKind,
+    type RunPrincipalKind,
+    type RunStatePort,
+} from "./run-context.ts";
+export type { NativeTypeScriptProgram, NativeTypeScriptRequest, NativeTypeScriptBinding, NativeTypeScriptResult, NativeTypeScriptExecutor } from "./native-executor.ts";
+export {
+    compileTypeScriptSnippet,
+    executeTypeScriptSnippet,
+    typeScriptSnippetDeclarations,
+    TypeScriptSnippetCompilationError,
+    TypeScriptSnippetExecutionError,
+    type TypeScriptSnippetSource,
+    type TypeScriptSnippetExecution,
+    type TypeScriptSnippetResult,
+} from "./snippet.ts";

package/packages/ragents/src/typescript/native-executor.ts

@@ -0,0 +1,40 @@
+import type { JsonValue } from "../domain/json.ts";
+import type { RunCapabilityDescriptor, RunInvocationKind, RunPrincipalKind } from "./run-context.ts";
+import type { NativeTypeScriptProgram } from "./native-program.ts";
+
+export type { NativeTypeScriptProgram } from "./native-program.ts";
+
+export interface NativeTypeScriptRequest {
+    readonly program: NativeTypeScriptProgram;
+    readonly input: unknown;
+    readonly state?: unknown;
+    readonly context: {
+        readonly runId: string;
+        readonly invocationId: string;
+        readonly invocationKind: RunInvocationKind;
+        readonly actor?: { readonly id: string; readonly handle: string };
+        readonly principal: { readonly id: string; readonly kind: RunPrincipalKind };
+        readonly capabilities: readonly RunCapabilityDescriptor[];
+    };
+    readonly std?: { readonly now: string; readonly idPrefix: string };
+    readonly cwd?: string;
+    readonly instanceId?: string;
+}
+
+export interface NativeTypeScriptBinding {
+    readonly signal?: AbortSignal | undefined;
+    readonly call: (name: string, input: JsonValue) => Promise<JsonValue>;
+    readonly log: (value: unknown) => void;
+}
+
+export interface NativeTypeScriptResult {
+    readonly result: unknown;
+    readonly state: unknown;
+}
+
+export interface NativeTypeScriptExecutor {
+    execute(request: NativeTypeScriptRequest, binding: NativeTypeScriptBinding): Promise<NativeTypeScriptResult>;
+    stopRun(runId: string): Promise<void>;
+    stopInstance(runId: string, instanceId: string): Promise<void>;
+    shutdown(): Promise<void>;
+}

package/packages/ragents/src/typescript/native-program.ts

@@ -0,0 +1,5 @@
+export type NativeTypeScriptProgram = {
+    entry: string;
+    files: { fileName: string; text: string }[];
+    exportName?: string;
+};

package/packages/ragents/src/typescript/run-context.ts

@@ -0,0 +1,199 @@
+import type { TSchema } from "typebox";
+
+import { assertJsonValue, type JsonValue } from "../domain/json.ts";
+import { canonicalTypeScriptBuildContract, typeScriptBuildContractHash } from "./build-contract.ts";
+import { typeScriptTypesFromSchema } from "./schema.ts";
+
+export const runContextApiVersion = 1;
+
+export type RunInvocationKind = "input" | "tool" | "snippet" | "app-action" | "event" | "schedule";
+export type RunPrincipalKind = "agent" | "script" | "operator" | "service";
+
+export interface RunCapabilityDescriptor {
+    readonly id: string;
+    readonly label: string;
+    readonly description: string;
+    readonly schema: TSchema;
+    readonly resultSchema: TSchema;
+}
+
+export interface RunCapabilityPrincipalBinding {
+    readonly id: string;
+    readonly kind: RunPrincipalKind;
+    readonly grants?: readonly unknown[];
+}
+
+export interface RunCapabilityPolicyBinding {
+    readonly id: string;
+    readonly policy: string;
+}
+
+export const runCapabilityContract = (capabilities: readonly RunCapabilityDescriptor[]): string =>
+    canonicalTypeScriptBuildContract({
+        apiVersion: runContextApiVersion,
+        capabilities: [...capabilities]
+            .sort((left, right) => left.id.localeCompare(right.id))
+            .map((capability) => ({
+                id: capability.id,
+                schema: capability.schema,
+                resultSchema: capability.resultSchema,
+            })),
+    });
+
+export const runCapabilityContractHash = (capabilities: readonly RunCapabilityDescriptor[]): string =>
+    typeScriptBuildContractHash(runCapabilityContract(capabilities));
+
+export const runCapabilityBindingHash = (binding: {
+    readonly principal: RunCapabilityPrincipalBinding;
+    readonly capabilities: readonly RunCapabilityDescriptor[];
+    readonly policies?: readonly RunCapabilityPolicyBinding[];
+}): string => typeScriptBuildContractHash(canonicalTypeScriptBuildContract({
+    apiVersion: runContextApiVersion,
+    principal: {
+        id: binding.principal.id,
+        kind: binding.principal.kind,
+        grants: binding.principal.grants ?? [],
+    },
+    capabilities: [...binding.capabilities]
+        .sort((left, right) => left.id.localeCompare(right.id))
+        .map((capability) => ({
+            id: capability.id,
+            schema: capability.schema,
+            resultSchema: capability.resultSchema,
+        })),
+    policies: [...binding.policies ?? []]
+        .sort((left, right) => left.id.localeCompare(right.id)),
+}));
+
+export interface RunCapabilityPort {
+    readonly descriptors: () => readonly RunCapabilityDescriptor[];
+    readonly call: (name: string, input: JsonValue) => Promise<JsonValue>;
+}
+
+export interface RunStatePort {
+    readonly read: () => unknown;
+    readonly replace: (value: unknown) => void;
+}
+
+export interface RunContextBinding {
+    readonly runId: string;
+    readonly invocationId: string;
+    readonly invocationKind: RunInvocationKind;
+    readonly principal: {
+        readonly id: string;
+        readonly kind: RunPrincipalKind;
+    };
+    readonly state: RunStatePort;
+    readonly capabilities: RunCapabilityPort;
+    readonly log: (value: unknown) => void;
+    readonly signal: AbortSignal;
+}
+
+const requiredName = (value: unknown): string => {
+    if (typeof value !== "string" || !value.trim()) throw new Error("Capability name must be a non-empty string.");
+    return value;
+};
+
+export const createRunContext = (binding: RunContextBinding) => ({
+    run: { id: binding.runId },
+    invocation: { id: binding.invocationId, kind: binding.invocationKind },
+    principal: { ...binding.principal },
+    state: {
+        read: () => structuredClone(binding.state.read()),
+        replace: (value: unknown) => {
+            assertJsonValue(value, "Run state");
+            binding.state.replace(structuredClone(value));
+        },
+    },
+    functions: Object.freeze(Object.fromEntries(binding.capabilities.descriptors().map(({ id: name }) => [name,
+        (input: JsonValue = {}) => {
+            binding.signal.throwIfAborted();
+            assertJsonValue(input, `Capability ${requiredName(name)} input`);
+            return binding.capabilities.call(requiredName(name), input);
+        },
+    ]))),
+    signal: binding.signal,
+    log: (value: unknown) => binding.log(value),
+    throwIfAborted: () => binding.signal.throwIfAborted(),
+});
+
+export interface RunContextDeclarationsOptions {
+    readonly stateType: string;
+    readonly capabilities: readonly RunCapabilityDescriptor[];
+    readonly program: string;
+}
+
+const capabilityMap = (capabilities: readonly RunCapabilityDescriptor[]): string => {
+    const seen = new Set<string>();
+    const declarations: string[] = [];
+    const sorted = [...capabilities].sort((left, right) => left.id.localeCompare(right.id));
+    const uses = new Map<object, number>();
+    for (const capability of sorted) for (const schema of [capability.schema, capability.resultSchema]) uses.set(schema, (uses.get(schema) ?? 0) + 1);
+    const shared = new Map<object, string>();
+    const typeOf = (schema: RunCapabilityDescriptor["schema"], prefix: string): string => {
+        const existing = shared.get(schema);
+        if (existing) return existing;
+        const rendered = typeScriptTypesFromSchema(schema, prefix);
+        declarations.push(...rendered.declarations);
+        if ((uses.get(schema) ?? 0) < 2) return rendered.type;
+        const name = `RAgentsShared${shared.size}`;
+        shared.set(schema, name);
+        declarations.push(`type ${name} = ${rendered.type};`);
+        return name;
+    };
+    const fields = sorted.map((capability, index) => {
+        if (!capability.id.trim()) throw new Error("A capability declaration has no id.");
+        if (seen.has(capability.id)) throw new Error(`Capability ${capability.id} is declared more than once.`);
+        seen.add(capability.id);
+        const input = typeOf(capability.schema, `RAgentsCapability${index}Input`);
+        const output = typeOf(capability.resultSchema, `RAgentsCapability${index}Output`);
+        return [
+            `  readonly ${JSON.stringify(capability.id)}: {`,
+            `    readonly input: ${input};`,
+            `    readonly output: ${output};`,
+            "  };",
+        ].join("\n");
+    });
+
+    const map = fields.length > 0 ? `{\n${fields.join("\n")}\n}` : "{}";
+    return `${declarations.join("\n")}${declarations.length > 0 ? "\n\n" : ""}type RAgentsCapabilityMap = ${map};`;
+};
+
+export const createRunContextDeclarations = (options: RunContextDeclarationsOptions): string => `
+${capabilityMap(options.capabilities)}
+
+interface RAgentsRunState<State> {
+  read(): State;
+  replace(value: State): void;
+}
+
+type RAgentsRunInput<Input> = {} extends Input ? [input?: Input] : [input: Input];
+
+type RAgentsRunFunctions<Capabilities> = {
+  readonly [Name in keyof Capabilities]: (
+    ...args: RAgentsRunInput<Capabilities[Name] extends { readonly input: infer Input } ? Input : never>
+  ) => Promise<Capabilities[Name] extends { readonly output: infer Output } ? Output : never>;
+};
+
+interface RAgentsRunContext<State, Capabilities> {
+  readonly run: { readonly id: string };
+  readonly actor: { readonly id: string; readonly handle: string };
+  readonly invocation: {
+    readonly id: string;
+    readonly kind: "input" | "tool" | "snippet" | "app-action" | "event" | "schedule";
+  };
+  readonly principal: {
+    readonly id: string;
+    readonly kind: "agent" | "script" | "operator" | "service";
+  };
+  readonly signal: AbortSignal;
+  readonly state: RAgentsRunState<State>;
+  readonly functions: RAgentsRunFunctions<Capabilities>;
+  log(value: unknown): void;
+  throwIfAborted(): void;
+}
+
+type RunContext = RAgentsRunContext<${options.stateType}, RAgentsCapabilityMap>;
+
+${options.program.trim()}
+`.trimStart();

package/packages/ragents/src/typescript/schema.ts

@@ -0,0 +1,176 @@
+const MAX_SCHEMA_DEPTH = 64;
+const MAX_SCHEMA_NODES = 10_000;
+
+type JsonSchemaRecord = Record<string, unknown>;
+
+interface SchemaContext {
+    readonly active: WeakSet<object>;
+    readonly definitions: JsonSchemaRecord[];
+    readonly aliases?: { prefix: string; names: Map<object, string>; declarations: string[] };
+    remaining: number;
+}
+
+const isRecord = (value: unknown): value is JsonSchemaRecord =>
+    typeof value === "object" && value !== null && !Array.isArray(value);
+
+const literalType = (value: unknown): string => {
+    if (value === null) return "null";
+    if (typeof value === "string" || typeof value === "boolean") return JSON.stringify(value);
+    if (typeof value === "number" && Number.isFinite(value)) return String(value);
+    return "unknown";
+};
+
+const unionOf = (types: readonly string[]): string => {
+    if (types.includes("unknown")) return "unknown";
+    const distinct = [...new Set(types.filter((type) => type !== "never"))].sort();
+    if (distinct.length === 0) return "never";
+    return distinct.length === 1 ? distinct[0]! : distinct.map((type) => `(${type})`).join(" | ");
+};
+
+const intersectionOf = (types: readonly string[]): string => {
+    if (types.includes("never")) return "never";
+    const distinct = [...new Set(types.filter((type) => type !== "unknown"))].sort();
+    if (distinct.length === 0) return "unknown";
+    return distinct.length === 1 ? distinct[0]! : distinct.map((type) => `(${type})`).join(" & ");
+};
+
+const arrayType = (schema: JsonSchemaRecord, context: SchemaContext, depth: number): string => {
+    const tuple = Array.isArray(schema.prefixItems)
+        ? schema.prefixItems
+        : Array.isArray(schema.items)
+            ? schema.items
+            : undefined;
+    if (tuple) {
+        const entries = tuple.map((entry) => schemaType(entry, context, depth + 1));
+        if (schema.items === false) return `[${entries.join(", ")}]`;
+        const rest = isRecord(schema.items) || typeof schema.items === "boolean"
+            ? schemaType(schema.items, context, depth + 1)
+            : "unknown";
+        return `[${[...entries, `...Array<${rest}>`].join(", ")}]`;
+    }
+    if (schema.items === false) return "[]";
+    return `Array<${schemaType(schema.items, context, depth + 1)}>`;
+};
+
+const documentation = (schema: unknown): string => {
+    const description = isRecord(schema) && typeof schema.description === "string" ? schema.description.trim() : "";
+    return description ? `/** ${description.replace(/\*\//g, "* /").replace(/\s+/g, " ")} */ ` : "";
+};
+
+const objectType = (schema: JsonSchemaRecord, context: SchemaContext, depth: number): string => {
+    const properties = isRecord(schema.properties) ? schema.properties : {};
+    const required = new Set(Array.isArray(schema.required)
+        ? schema.required.filter((entry): entry is string => typeof entry === "string")
+        : []);
+    const fields = Object.keys(properties).sort().map((name) => {
+        const optional = required.has(name) ? "" : "?";
+        return `${documentation(properties[name])}${JSON.stringify(name)}${optional}: ${schemaType(properties[name], context, depth + 1)};`;
+    });
+    const declared = fields.length > 0 ? `{ ${fields.join(" ")} }` : undefined;
+    const additional = schema.additionalProperties;
+    if (additional === false) return declared ?? "{ [key: string]: never }";
+    const additionalType = additional === undefined || additional === true
+        ? "unknown"
+        : schemaType(additional, context, depth + 1);
+    const indexed = `{ [key: string]: ${additionalType} }`;
+    return declared ? intersectionOf([declared, indexed]) : indexed;
+};
+
+const typedSchema = (type: string, schema: JsonSchemaRecord, context: SchemaContext, depth: number): string => {
+    switch (type) {
+        case "null": return "null";
+        case "boolean": return "boolean";
+        case "integer":
+        case "number": return "number";
+        case "string": return "string";
+        case "array": return arrayType(schema, context, depth);
+        case "object": return objectType(schema, context, depth);
+        default: return "unknown";
+    }
+};
+
+const schemaType = (schema: unknown, context: SchemaContext, depth: number): string => {
+    context.remaining -= 1;
+    if (context.remaining < 0 || depth > MAX_SCHEMA_DEPTH) return "unknown";
+    if (schema === true) return "unknown";
+    if (schema === false) return "never";
+    if (!isRecord(schema)) return "unknown";
+    if (context.active.has(schema)) return "unknown";
+
+    context.active.add(schema);
+    const definitions = isRecord(schema.$defs) ? schema.$defs : undefined;
+    if (definitions) context.definitions.push(definitions);
+    try {
+        if (typeof schema.$ref === "string") {
+            const reference = schema.$ref.replace(/^#\/\$defs\//, "").replace(/~1/g, "/").replace(/~0/g, "~");
+            const target = [...context.definitions].reverse().find((entry) => Object.hasOwn(entry, reference))?.[reference];
+            if (!isRecord(target)) return "unknown";
+            if (!context.aliases) return schemaType(target, context, depth + 1);
+            const existing = context.aliases.names.get(target);
+            if (existing) return existing;
+            const name = `${context.aliases.prefix}Reference${context.aliases.names.size}`;
+            context.aliases.names.set(target, name);
+            const type = schemaType(target, context, depth + 1);
+            context.aliases.declarations.push(`type ${name} = ${type};`);
+            return name;
+        }
+        if (Object.hasOwn(schema, "const")) return literalType(schema.const);
+        if (Object.hasOwn(schema, "enum")) {
+            return Array.isArray(schema.enum) ? unionOf(schema.enum.map(literalType)) : "unknown";
+        }
+
+        const alternatives = Array.isArray(schema.anyOf)
+            ? schema.anyOf
+            : Array.isArray(schema.oneOf)
+                ? schema.oneOf
+                : undefined;
+        if (alternatives) {
+            const result = unionOf(alternatives.map((entry) => schemaType(entry, context, depth + 1)));
+            return schema.nullable === true ? unionOf([result, "null"]) : result;
+        }
+        if (Array.isArray(schema.allOf)) {
+            const result = intersectionOf(schema.allOf.map((entry) => schemaType(entry, context, depth + 1)));
+            return schema.nullable === true ? unionOf([result, "null"]) : result;
+        }
+
+        const types = Array.isArray(schema.type)
+            ? schema.type.map((entry) => typeof entry === "string"
+                ? typedSchema(entry, schema, context, depth + 1)
+                : "unknown")
+            : typeof schema.type === "string"
+                ? [typedSchema(schema.type, schema, context, depth + 1)]
+                : schema.properties !== undefined || schema.additionalProperties !== undefined
+                    ? [objectType(schema, context, depth + 1)]
+                    : schema.items !== undefined || schema.prefixItems !== undefined
+                        ? [arrayType(schema, context, depth + 1)]
+                        : ["unknown"];
+        const result = unionOf(types);
+        return schema.nullable === true ? unionOf([result, "null"]) : result;
+    } finally {
+        if (definitions) context.definitions.pop();
+        context.active.delete(schema);
+    }
+};
+
+export const typeScriptTypeFromSchema = (schema: unknown): string => {
+    try {
+        return schemaType(schema, {
+            active: new WeakSet<object>(),
+            definitions: [],
+            remaining: MAX_SCHEMA_NODES,
+        }, 0);
+    } catch {
+        return "unknown";
+    }
+};
+
+export const typeScriptTypesFromSchema = (schema: unknown, prefix: string): { type: string; declarations: string[] } => {
+    const aliases = { prefix, names: new Map<object, string>(), declarations: [] as string[] };
+    const type = schemaType(schema, {
+        active: new WeakSet<object>(),
+        definitions: [],
+        aliases,
+        remaining: MAX_SCHEMA_NODES,
+    }, 0);
+    return { type, declarations: aliases.declarations };
+};

package/packages/ragents/src/typescript/snippet.ts

@@ -0,0 +1,121 @@
+import { randomUUID } from "node:crypto";
+import { inspect } from "node:util";
+
+import { assertJsonValue, type JsonValue } from "../domain/json.ts";
+import { scriptStdDeclarations } from "../script/std.ts";
+import { compileVirtualTypeScriptAsync } from "./async-compiler.ts";
+import type { VirtualTypeScriptDiagnostic } from "./compiler.ts";
+import type { NativeTypeScriptExecutor, NativeTypeScriptProgram, NativeTypeScriptRequest } from "./native-executor.ts";
+import { createRunContextDeclarations, runCapabilityContract, type RunCapabilityDescriptor } from "./run-context.ts";
+
+const snippetFile = "snippet.ts";
+
+export const typeScriptSnippetDeclarations = (capabilities: readonly RunCapabilityDescriptor[]): string =>
+    createRunContextDeclarations({
+        capabilities,
+        stateType: "Record<string, unknown>",
+        program: `${scriptStdDeclarations}\ninterface RAgentsRunContext<State, Capabilities> { readonly std: RAgentsStd; }\ndeclare const context: RunContext;`,
+    });
+
+export interface TypeScriptSnippetSource {
+    readonly code: string;
+    readonly capabilities: readonly RunCapabilityDescriptor[];
+    readonly cwd?: string;
+    readonly signal?: AbortSignal | undefined;
+}
+
+export class TypeScriptSnippetCompilationError extends Error {
+    readonly diagnostics: readonly VirtualTypeScriptDiagnostic[];
+
+    constructor(diagnostics: readonly VirtualTypeScriptDiagnostic[]) {
+        const original = diagnostics.map((diagnostic) => ({
+            ...diagnostic,
+            ...(diagnostic.fileName?.endsWith(`/${snippetFile}`) || diagnostic.fileName === snippetFile ? {
+                fileName: snippetFile,
+                ...(diagnostic.start ? { start: { ...diagnostic.start, line: Math.max(1, diagnostic.start.line - 1) } } : {}),
+                ...(diagnostic.end ? { end: { ...diagnostic.end, line: Math.max(1, diagnostic.end.line - 1) } } : {}),
+            } : {}),
+        }));
+        super(`TypeScript-Snippet wurde nicht ausgeführt:\n${original.map((diagnostic) =>
+            `${diagnostic.fileName ?? "TypeScript"}${diagnostic.start ? `:${diagnostic.start.line}:${diagnostic.start.column}` : ""} TS${diagnostic.code}: ${diagnostic.message}`,
+        ).join("\n")}`);
+        this.name = "TypeScriptSnippetCompilationError";
+        this.diagnostics = original;
+    }
+}
+
+export const compileTypeScriptSnippet = async (source: TypeScriptSnippetSource): Promise<NativeTypeScriptProgram> => {
+    source.signal?.throwIfAborted();
+    if (!source.code.trim()) throw new Error("Das TypeScript-Snippet darf nicht leer sein.");
+    const compiled = await compileVirtualTypeScriptAsync({
+        sources: [{ fileName: snippetFile, text: `export async function handle(_input: unknown, context: RunContext) {\n${source.code}\n}\n` }],
+        declarations: [{ fileName: "snippet-context.d.ts", text: typeScriptSnippetDeclarations(source.capabilities) }],
+        contract: runCapabilityContract(source.capabilities),
+        emit: "node",
+        ...(source.cwd ? { rootDirectory: source.cwd } : {}),
+    }, { signal: source.signal });
+    if (!compiled.valid) throw new TypeScriptSnippetCompilationError(compiled.diagnostics);
+    source.signal?.throwIfAborted();
+    return { entry: "snippet.js", exportName: "handle", files: [...compiled.emittedFiles] };
+};
+
+export interface TypeScriptSnippetExecution extends TypeScriptSnippetSource {
+    readonly executor: NativeTypeScriptExecutor;
+    readonly context: Omit<NativeTypeScriptRequest["context"], "capabilities" | "invocationKind" | "actor"> & {
+        readonly actor: NonNullable<NativeTypeScriptRequest["context"]["actor"]>;
+    };
+    readonly call: (name: string, input: JsonValue) => Promise<JsonValue>;
+}
+
+export interface TypeScriptSnippetResult {
+    readonly result: JsonValue;
+    readonly logs: string[];
+}
+
+export class TypeScriptSnippetExecutionError extends Error {
+    readonly logs: readonly string[];
+
+    constructor(cause: unknown, logs: readonly string[]) {
+        super(`TypeScript-Snippet fehlgeschlagen: ${cause instanceof Error ? cause.message : String(cause)}${logs.length > 0 ? `\nLogs vor dem Fehler:\n${logs.join("\n")}` : ""}`, { cause });
+        this.name = "TypeScriptSnippetExecutionError";
+        this.logs = [...logs];
+    }
+}
+
+export const executeTypeScriptSnippet = async (execution: TypeScriptSnippetExecution): Promise<TypeScriptSnippetResult> => {
+    const program = await compileTypeScriptSnippet(execution);
+    const instanceId = `snippet-${randomUUID()}`;
+    const logs: string[] = [];
+    let failure: TypeScriptSnippetExecutionError | undefined;
+    try {
+        execution.signal?.throwIfAborted();
+        const output = await execution.executor.execute({
+            program,
+            input: null,
+            state: {},
+            std: { now: new Date().toISOString(), idPrefix: execution.context.invocationId },
+            context: { ...execution.context, invocationKind: "snippet", capabilities: execution.capabilities },
+            instanceId,
+            ...(execution.cwd ? { cwd: execution.cwd } : {}),
+        }, {
+            signal: execution.signal,
+            call: execution.call,
+            log: (value) => logs.push(typeof value === "string" ? value : inspect(value, { depth: 8, maxArrayLength: 100, maxStringLength: 16_000 })),
+        });
+        execution.signal?.throwIfAborted();
+        const returned = output.result === undefined ? null : output.result;
+        assertJsonValue(returned, "TypeScript-Snippet result");
+        const result: JsonValue = JSON.parse(JSON.stringify(returned));
+        return { result, logs };
+    } catch (error) {
+        failure = new TypeScriptSnippetExecutionError(error, logs);
+        throw failure;
+    } finally {
+        try {
+            await execution.executor.stopInstance(execution.context.runId, instanceId);
+        } catch (error) {
+            if (failure) throw new AggregateError([failure, error], `${failure.message}\nDie Snippet-Instanz konnte nicht vollständig beendet werden: ${error instanceof Error ? error.message : String(error)}`);
+            throw new TypeScriptSnippetExecutionError(error, logs);
+        }
+    }
+};

package/packages/workspace-executor/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "@aicontainer/workspace-executor",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts",
+    "./src/*.ts": "./src/*.ts",
+    "./src/*": "./src/*.ts"
+  },
+  "scripts": {
+    "test": "node --import tsx --test tests/*.test.ts",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@aicontainer/agent": "workspace:*",
+    "typescript": "^5.9.0",
+    "typescript-language-server": "6.0.0",
+    "vscode-jsonrpc": "^9.0.2"
+  },
+  "devDependencies": {
+    "@types/node": "^24.10.0",
+    "tsx": "^4.20.0"
+  }
+}