@schlenkr/ragents 0.1.0

package/plugins/ragents.actor-programs/prompt.hbs

@@ -0,0 +1,79 @@
+## Actor programs
+
+Inspect types with `typescript_api`; call `context.functions` in `typescript_eval` or an actor
+program. Use snippets for one-time work, programs for persistent state, later inputs or views.
+
+Actors can own TypeScript functions, journaled state and React views. An LLM actor still uses
+its model for ActorInputs; a TypeScript actor can handle them with `onInput`. Calling a function
+from a view executes that function directly and does not start a model turn.
+
+1. Create the closest template with `actor_program_create`; read and reuse its package, contract,
+   implementation, view and tests under `@actors/<name>/`. Language servers use that alias;
+   Bash uses `$RAGENTS_ACTORS_DIR/<name>/`.
+2. Edit with ordinary file tools; preserve imports and structure. Changed errors arrive before
+   model requests; `actor_program_diagnostics` returns the full last check.
+3. Adapt meaningful `node:test` cases in `tests/**/*.test.ts`. Query `actor_program_controls`
+   for unclear props. Templates demonstrate controls; pure views need no server function.
+4. `actor_program_activate` typechecks, builds, tests and activates. Fix errors and reactivate.
+   List, removal and visibility have separate functions.
+
+Published functions enter the shared API in the same turn. Inspect with `typescript_api`, call
+`context.functions.<name>(input)`. Reactivation updates the contract; removal withdraws it.
+Native tool exposure is optional and explicit.
+
+Use `actor: "self"` or `actor: "@handle"` to bind to an existing actor. Without a binding, a
+backend creates a TypeScript actor with the program name; a pure view uses the calling actor.
+Reactivation preserves the existing binding. Do not create a dummy actor for a pure view.
+An LLM actor cannot receive an `onInput` backend; its inputs remain model work. Each actor owns
+one active program package; add further functions and views to that package.
+
+`package.json` contains `name`, `private: true`, `type: "module"` and `ragents` metadata:
+`title`, optional `description`, optional `backend`, and optional `views`. Each view has an
+`id`, `client`, optional `title`, `styles`, `width` and `height`. At least a backend or a view
+is required. The host supplies the HTML root and fixed local dependencies.
+
+Import `defineActor` from `@ragents/server` and `Type` from `typebox`. Its contract contains
+`state`, `functions` and optional `input: { capabilities }`. Each function declares `label`,
+`input`, `output` and optional `capabilities`; `tool: { name, targets?, card? }` exposes the same
+function in the shared API. Omitted targets mean all active executable actors; `self` means the owner.
+Export `defineActor(contract, { functions: { ... }, onInput? })` as default. Callbacks receive
+`(input, context)`; returned values are results. Only `context.state.replace` changes actor state.
+The state schema must accept the initial `{}`. `context.actor` identifies the owning actor.
+Server code calls run functions through `context.functions`; declared `capabilities` select the
+functions it needs. An `onInput` acts as its actor. A function owns that actor's state but calls
+run functions as its caller. A subscription therefore belongs to the caller; initialize an
+actor's own event handling through its `onInput`. Snippets act as their caller.
+
+Import React and `createRoot` normally. Import `context` and `useAppState` from `@ragents/client`
+and controls from `@ragents/client/ui`: shadcn/ui components (`Button`, `Select`, `Tabs`, `Dialog`,
+`Badge`, `Input`, `Table`, ...) with their usual props, plus `Form`, `DataTable`, `FilePicker`,
+`AppLayout`, `Stack`, `Grid` and chat. Icons: `lucide-react`; Tailwind works.
+The hook reads actor state; `context.capabilities.call`
+calls its declared functions. Local drafts remain React state. A real chat binds to the owning
+actor through `context.actor.handle`; sending a chat message deliberately starts its next turn.
+Use `AppLayout` for title, description, content and actions, `Stack` for spacing or rows,
+and `Grid` for columns responsive to frame width. `AppLayout fill` needs a height-constrained
+parent: content scrolls while header and actions remain visible. Mount in the supplied `#root`.
+The host supplies fonts, box sizing, page size, scrolling and outer padding. Do not reset
+`html`, `body` or `#root`, or add outer padding; style only content.
+Use `Form` for labeled inputs and interview steps, `type: "textarea"` for long answers.
+It handles layout, validation and async `onSubmit`. Keep progression in app state; avoid fixed
+field heights and absolute form layouts. Where Form does not fit, use `Input`, `Textarea`,
+`Field` and `Label`. Do not duplicate control colors, borders or fonts.
+Share steps, prompts and freedoms via `defineWorkflow` from `@ragents/workflow`.
+Compose prompts with `workflowInstructions` and server-only `readPrompt` from
+`@ragents/workflow/prompts`. Render `UI.WorkflowDiagram` with definition, state and label;
+The actor enforces completion and extensions; see learning-afternoon.
+Use `FlowDiagram` for other graphs (star layout, fit, actions). Keep local IDs stable.
+See `controls`. For custom SVG use `SvgEdge`, Tailwind utilities, responsive `viewBox` and
+accessible descriptions.
+Address view visibility with `package-name/view-key`, `@handle/view-key` or a unique title;
+canvas nodes and lines use the same names with the `app:` prefix.
+The host controls resizing, collapse and full view. Views appear on the canvas; owner cards
+start hidden but remain in the Actors list. Personal actor visibility is separate from
+`actor_view_set_visibility` and cannot be changed by layouts.
+
+Tests call `program.functions.<name>(input, context)` or `program.onInput(input, context)`.
+`createTestContext` from `@ragents/server/testing` supplies state and explicit typed `functions` mocks.
+Inspect results and `context.state.read()` separately. Subscription delivery is an ActorInput;
+`onInput` uses the same state and function API as the actor's functions.

package/plugins/ragents.actor-programs/server/agent-tools.ts

@@ -0,0 +1,31 @@
+import { ToolRegistry, type RunFunction, type ExecutableActor, type PluginHost } from "@aicontainer/ragents";
+import { runtimeProviderToken, sessionWorkspaceProviderToken } from "@aicontainer/server/ragents/host-services.js";
+
+export const agentToolsFrom = (host: PluginHost) =>
+  async (runId: string, actorId: string, provisional?: ExecutableActor): Promise<readonly RunFunction[]> => {
+    const runtime = host.service(runtimeProviderToken)();
+    const view = runtime.view(runId);
+    const actor = provisional ?? view.actors.find((candidate) => candidate.id === actorId);
+    if (!actor || actor.kind === "human" || actor.lifecycle.kind === "stopped") {
+      throw new Error(`${actorId} bezeichnet keinen aktiven Agenten in diesem Run.`);
+    }
+    const registry = new ToolRegistry();
+    host.tools.entries().forEach((contributor) => registry.register(contributor));
+    const workspace = await host.service(sessionWorkspaceProviderToken)(runId);
+    const tools = await registry.resolve({
+      runId,
+      actorId,
+      turnId: null,
+      actor,
+      view: provisional ? {...view,actors:[...view.actors,provisional]} : view,
+      workspace: workspace.cwd,
+    });
+    if (actor.toolNames === null) return tools;
+    const availableNames = new Set(tools.map((tool) => tool.name));
+    const unknown = actor.toolNames.filter((name) => !availableNames.has(name));
+    if (unknown.length > 0) {
+      throw new Error(`Actor ${actorId} verlangt unbekannte Werkzeuge: ${unknown.join(", ")}.`);
+    }
+    const selected = new Set(actor.toolNames);
+    return tools.filter((tool) => selected.has(tool.name));
+  };

package/plugins/ragents.actor-programs/server/app-project.ts

@@ -0,0 +1,284 @@
+import { createRequire } from "node:module";
+import { fileURLToPath } from "node:url";
+import { existsSync, readFileSync } from "node:fs";
+import { mkdir, readFile, readdir, realpath, symlink, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { build } from "esbuild";
+import ts from "typescript";
+import { Type, type Static } from "typebox";
+import { Value } from "typebox/value";
+import { canonicalHash, typeScriptTypesFromSchema, type NativeTypeScriptExecutor, type RunCapabilityDescriptor, scriptStdDeclarations } from "@aicontainer/ragents";
+import { runtimeLibraries, webRuntimeLibraries } from "./runtime-libraries.js";
+
+const webRequire = createRequire(new URL("../../../apps/web/package.json", import.meta.url));
+const rootRequire = createRequire(new URL("../../../package.json", import.meta.url));
+const serverRequire = createRequire(new URL("../../../apps/server/package.json", import.meta.url));
+const serverTypeRoot = fileURLToPath(new URL("../../../apps/server/node_modules/@types", import.meta.url));
+const libraryDirectory = (name: string): string => {
+  const resolver = (webRuntimeLibraries as readonly string[]).includes(name) ? webRequire
+    : name === "@types/node" || name === "tsx" ? serverRequire : rootRequire;
+  try { return path.dirname(resolver.resolve(`${name}/package.json`)); }
+  catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== "ERR_PACKAGE_PATH_NOT_EXPORTED") throw error;
+    let directory = path.dirname(resolver.resolve(name));
+    while (directory !== path.dirname(directory)) {
+      const file = path.join(directory, "package.json");
+      if (existsSync(file) && (JSON.parse(readFileSync(file, "utf8")) as { name?: string }).name === name) return directory;
+      directory = path.dirname(directory);
+    }
+    throw new Error(`Das installierte Paket ${name} besitzt keine Paketmetadaten.`);
+  }
+};
+const json = (value: unknown): string => `${JSON.stringify(value, null, 2)}\n`;
+const link = async (source: string, target: string): Promise<void> => {
+  await mkdir(path.dirname(target), { recursive: true });
+  await symlink(source, target).catch(async (error: NodeJS.ErrnoException) => {
+    if (error.code !== "EEXIST") throw error;
+    if (await realpath(target) !== await realpath(source)) throw new Error(`Die vorbereitete Bibliothek ${target} hat einen anderen Ursprung.`);
+  });
+};
+export const prepareAppDependencies = async (directory: string): Promise<void> => {
+  await mkdir(directory, { recursive: true });
+  for (const name of runtimeLibraries) await link(libraryDirectory(name), path.join(directory, "node_modules", name));
+  for (const [name, library, executable] of [["tsc", "typescript", "bin/tsc"], ["tsx", "tsx", "dist/cli.mjs"], ["esbuild", "esbuild", "bin/esbuild"]])
+    await link(path.join(libraryDirectory(library!), executable!), path.join(directory, "node_modules/.bin", name!));
+};
+
+export const prepareAppWorkspace = async (directory: string): Promise<string> => {
+  await prepareAppDependencies(directory);
+  const dependencies = Object.fromEntries(runtimeLibraries.map((name) => [name, `link:${libraryDirectory(name)}`]));
+  await writeFile(path.join(directory, "package.json"), json({ name: "run-actor-workspace", private: true, type: "module", dependencies }));
+  await writeFile(path.join(directory, "pnpm-workspace.yaml"), "packages:\n  - actors/*\n");
+  await mkdir(path.join(directory, "actors"), { recursive: true });
+  const apps = await readdir(path.join(directory, "actors"), { withFileTypes: true });
+  const importers = {
+    ".": { dependencies: Object.fromEntries(Object.entries(dependencies).map(([name, specifier]) => [name, { specifier, version: specifier }])) },
+    ...Object.fromEntries(apps.filter((entry) => entry.isDirectory()).map((entry) => [`actors/${entry.name}`, {}])),
+  };
+  await writeFile(path.join(directory, "pnpm-lock.yaml"), json({ lockfileVersion: "9.0", settings: { autoInstallPeers: true, excludeLinksFromLockfile: false }, importers }));
+  await writeFile(path.join(directory, "tsconfig.json"), json({ files: [], references: [] }));
+  return path.join(directory, "actors");
+};
+
+const schema = Type.Record(Type.String(), Type.Any());
+const actionSchema = Type.Object({
+  label: Type.String({ minLength: 1 }), description: Type.Optional(Type.String()),
+  input: schema, output: schema,
+  capabilities: Type.Optional(Type.Array(Type.String(), { uniqueItems: true })),
+  confirmation: Type.Optional(Type.String()),
+  tool: Type.Optional(Type.Object({ name: Type.String(), targets: Type.Optional(Type.Array(Type.String(), { minItems: 1 })), card: Type.Optional(Type.Boolean()) }, { additionalProperties: false })),
+}, { additionalProperties: false });
+export const appContractSchema = Type.Object({
+  state: schema, functions: Type.Record(Type.String(), actionSchema),
+  input: Type.Optional(Type.Object({ capabilities: Type.Optional(Type.Array(Type.String(), { uniqueItems: true })) }, { additionalProperties: false })),
+}, { additionalProperties: false });
+export type AppContract = Static<typeof appContractSchema>;
+export const appPackageSchema = Type.Object({
+  title: Type.String({ minLength: 1 }), description: Type.Optional(Type.String()), backend: Type.Optional(Type.String({ minLength: 1 })),
+  views: Type.Optional(Type.Array(Type.Object({
+    id: Type.String({ pattern: "^[a-z][a-z0-9-]{0,63}$" }), title: Type.Optional(Type.String({ minLength: 1 })),
+    client: Type.String({ minLength: 1 }), styles: Type.Optional(Type.String()),
+    width: Type.Optional(Type.Integer({ minimum: 280, maximum: 960 })),
+    height: Type.Optional(Type.Integer({ minimum: 180, maximum: 720 })),
+  }, { additionalProperties: false }))),
+}, { additionalProperties: false });
+export type AppPackage = Static<typeof appPackageSchema>;
+
+const sdkRuntime = `export const defineActor = (contract, implementation) => ({ contract, ...implementation });\n`;
+let testingBundle: Promise<string> | undefined;
+const testingRuntime = (): Promise<string> => testingBundle ??= build({
+  stdin: {contents: `
+import {createRunContext} from ${JSON.stringify(fileURLToPath(new URL("../../../packages/ragents/src/typescript/run-context.ts",import.meta.url)))};
+import {assertJsonValue} from ${JSON.stringify(fileURLToPath(new URL("../../../packages/ragents/src/domain/json.ts",import.meta.url)))};
+import {createScriptStd} from ${JSON.stringify(fileURLToPath(new URL("../../../packages/ragents/src/script/std.ts",import.meta.url)))};
+import {Value} from "typebox/value";
+export function createTestContextWithContracts(options, contracts) {
+  let state = structuredClone(options.state);
+  const controller = new AbortController();
+  const statePort = {read:()=>structuredClone(state),replace:value=>{state=structuredClone(value);}};
+  const declared = new Map(contracts.map(contract=>[contract.id,contract]));
+  for (const name of Object.keys(options.functions ?? {})) if (!declared.has(name)) throw new Error("Unbekannte Testfunktion "+name);
+  const capabilities = {descriptors:()=>contracts,call:async(name,input)=>{
+    const contract=declared.get(name);
+    const call=options.functions?.[name];
+    if(!call)throw new Error("Im Test fehlt die Funktion "+name);
+    if(!Value.Check(contract.schema,input))throw new Error("Testeingabe verletzt den Vertrag von "+name);
+    const result=await call(input);
+    assertJsonValue(result,"Testantwort von "+name);
+    if(!Value.Check(contract.resultSchema,result))throw new Error("Testantwort verletzt den Vertrag von "+name);
+    return result;
+  }};
+  return {...createRunContext({runId:"test",invocationId:"test",invocationKind:"tool",principal:{id:"test",kind:"service"},state:statePort,capabilities,log:()=>{},signal:controller.signal}),
+    actor:{id:"test-actor",handle:"test"},std:createScriptStd({turnStartedAt:"2026-01-01T00:00:00.000Z",idPrefix:"test",state:statePort,capabilities})};
+}`, resolveDir:process.cwd(),sourcefile:"actor-testing.ts",loader:"ts"},
+  bundle:true,platform:"node",format:"esm",target:"node22",packages:"external",write:false,
+}).then(result=>result.outputFiles![0]!.text);
+
+export const serverApiDeclarations = (capabilities: readonly RunCapabilityDescriptor[] = []): string => {
+  const declarations: string[] = [];
+  const entries = capabilities.map((capability, index) => {
+    const input = typeScriptTypesFromSchema(capability.schema, `RAgentsCapability${index}Input`);
+    const output = typeScriptTypesFromSchema(capability.resultSchema, `RAgentsCapability${index}Output`);
+    declarations.push(...input.declarations, ...output.declarations);
+    return `${JSON.stringify(capability.id)}: { input: ${input.type}; output: ${output.type} };`;
+  }).join("\n");
+  return `import type { Static, TSchema } from 'typebox';
+${declarations.length > 0 ? `${declarations.join("\n")}\n` : ""}export interface CapabilityContracts { ${entries} }
+export interface RunContext<State> {
+  readonly run: { readonly id: string };
+  readonly actor: {readonly id: string; readonly handle: string};
+  readonly std: RAgentsStd;
+  readonly invocation: { readonly id: string; readonly kind: string };
+  readonly principal: { readonly id: string; readonly kind: string };
+  readonly signal: AbortSignal;
+  readonly state: { read(): Readonly<State>; replace(value: State): void };
+  readonly functions: {readonly [Name in keyof CapabilityContracts]: (...args: {} extends CapabilityContracts[Name]['input'] ? [input?: CapabilityContracts[Name]['input']] : [input: CapabilityContracts[Name]['input']]) => Promise<CapabilityContracts[Name]['output']>};
+  log(value: unknown): void;
+  throwIfAborted(): void;
+}
+${scriptStdDeclarations}
+export interface ActorInput {
+  readonly id: string; readonly content: string; readonly artifactIds: readonly string[];
+  readonly sourceEventIds: readonly string[]; readonly subscriptionId: string | null;
+  readonly event: { readonly type: string; readonly eventId: string; readonly sequence: number; readonly occurredAt: string;
+    readonly sourceActorId: string | null; readonly sourceActorHandle: string | null; readonly payload: {readonly text?:string; readonly [key:string]:unknown} } | null;
+}
+export interface ActorFunction { label: string; description?: string; input: TSchema; output: TSchema; capabilities?: readonly string[]; confirmation?: string; tool?: { name: string; targets?: readonly string[]; card?: boolean } }
+export interface ActorContract { state: TSchema; functions: Readonly<Record<string, ActorFunction>>; input?: {capabilities?: readonly string[]} }
+export type ActorFunctions<C extends ActorContract> = { [K in keyof C['functions']]: (input: Static<C['functions'][K]['input']>, context: RunContext<Static<C['state']>>) => Static<C['functions'][K]['output']> | Promise<Static<C['functions'][K]['output']>> };
+export type ActorImplementation<C extends ActorContract> = {functions: ActorFunctions<C>} & (C extends {input: unknown} ? {onInput: (input: ActorInput, context: RunContext<Static<C['state']>>) => void | Promise<void>} : {onInput?: never});
+export declare function defineActor<const C extends ActorContract>(contract: C, implementation: ActorImplementation<C>): {contract:C} & ActorImplementation<C>;
+`;
+};
+
+let workflowSdk: Promise<{ javaScript: string; declarations: string; promptReader: string; promptDeclarations: string }> | undefined;
+const workflowSource = fileURLToPath(new URL("../workflow/index.ts", import.meta.url));
+const workflowSdkFiles = () => workflowSdk ??= (async () => {
+  let declarations = "";
+  let promptDeclarations = "";
+  const promptSource = fileURLToPath(new URL("../workflow/prompt-reader.ts", import.meta.url));
+  const program = ts.createProgram([workflowSource, promptSource], {
+    target: ts.ScriptTarget.ES2022, module: ts.ModuleKind.ESNext, moduleResolution: ts.ModuleResolutionKind.Bundler,
+    strict: true, skipLibCheck: true, types: ["node"], typeRoots: [serverTypeRoot], declaration: true, emitDeclarationOnly: true,
+  });
+  const diagnostics = ts.getPreEmitDiagnostics(program);
+  if (diagnostics.length) throw new Error(diagnostics.map(diagnostic => ts.flattenDiagnosticMessageText(diagnostic.messageText, "\n")).join("\n"));
+  const emitted = program.emit(undefined, (name, content) => { if (name.endsWith("index.d.ts")) declarations = content; if (name.endsWith("prompt-reader.d.ts")) promptDeclarations = content; });
+  if (emitted.emitSkipped || !declarations) throw new Error("Workflow-SDK-Deklarationen konnten nicht erzeugt werden.");
+  const runtime = await build({ entryPoints: [workflowSource], bundle: true, write: false, platform: "neutral", format: "esm", target: "es2022", logLevel: "silent" });
+  const promptRuntime = await build({ entryPoints: [promptSource], bundle: true, write: false, platform: "node", format: "esm", target: "es2022", logLevel: "silent" });
+  return { javaScript: runtime.outputFiles[0]!.text, declarations, promptReader: promptRuntime.outputFiles[0]!.text, promptDeclarations };
+})();
+
+export const installWorkflowSdk = async (directory: string): Promise<void> => {
+  const target = path.join(directory, "node_modules/@ragents/workflow");
+  const files = await workflowSdkFiles();
+  await mkdir(target, { recursive: true });
+  await writeFile(path.join(target, "package.json"), json({ name: "@ragents/workflow", private: true, type: "module", exports: { ".": { types: "./index.d.ts", default: "./index.js" }, "./prompts": { types: "./prompts.d.ts", default: "./prompts.js" } } }));
+  await writeFile(path.join(target, "index.d.ts"), files.declarations);
+  await writeFile(path.join(target, "index.js"), files.javaScript);
+  await writeFile(path.join(target, "prompt-reader.d.ts"), files.promptDeclarations);
+  await writeFile(path.join(target, "prompt-reader.js"), files.promptReader);
+  await writeFile(path.join(target, "prompts.d.ts"), 'import { createPromptReader } from "./prompt-reader.js";\nexport declare const readPrompt: ReturnType<typeof createPromptReader>;\n');
+  await writeFile(path.join(target, "prompts.js"), `import { createPromptReader } from "./prompt-reader.js";\nexport const readPrompt = createPromptReader(${JSON.stringify(directory)});\n`);
+};
+
+export const installServerSdk = async (directory: string, capabilities: readonly RunCapabilityDescriptor[] = []): Promise<void> => {
+  await installWorkflowSdk(directory);
+  const sdk = path.join(directory, "node_modules/@ragents/server");
+  await mkdir(sdk, { recursive: true });
+  const declarations = serverApiDeclarations(capabilities);
+  await writeFile(path.join(sdk, "package.json"), json({ name: "@ragents/server", private: true, type: "module", exports: {
+    ".": { types: "./index.d.ts", default: "./index.js" }, "./testing": { types: "./testing.d.ts", default: "./testing.js" },
+  } }));
+  await writeFile(path.join(sdk, "index.js"), sdkRuntime);
+  await writeFile(path.join(sdk, "index.d.ts"), declarations);
+  await writeFile(path.join(sdk, "testing.js"), (await testingRuntime()) + `\nexport function createTestContext(options) { return createTestContextWithContracts(options, ${JSON.stringify(capabilities)}); }\n`);
+  await writeFile(path.join(sdk, "testing.d.ts"), "import type { RunContext, CapabilityContracts } from './index.js';\ntype Mocks = {[Name in keyof CapabilityContracts]?: (input: CapabilityContracts[Name]['input']) => CapabilityContracts[Name]['output'] | Promise<CapabilityContracts[Name]['output']>};\nexport declare function createTestContext<State>(options: {state: State; functions?: Mocks}): RunContext<State>;\n");
+};
+
+export const prepareAppProject = async (directory: string): Promise<void> => {
+  await prepareAppDependencies(directory);
+  await installServerSdk(directory);
+  const pkg = await readAppPackage(directory);
+  const writeConfig = async (name: string, value: unknown): Promise<void> => {
+    await writeFile(path.join(directory, name), json(value), { flag: "wx" }).catch((error: NodeJS.ErrnoException) => {
+      if (error.code !== "EEXIST") throw error;
+    });
+  };
+  await writeConfig("tsconfig.client.json", { extends: "./node_modules/@ragents/client/tsconfig.json", include: (pkg.views ?? []).map(view => view.client) });
+  await writeConfig("tsconfig.server.json", { compilerOptions: {
+    target: "ES2022", module: "ESNext", moduleResolution: "Bundler", strict: true, noEmit: true,
+    skipLibCheck: true, types: ["node"], lib: ["ES2022"], allowImportingTsExtensions: true,
+  }, include: [...(pkg.backend ? [pkg.backend] : []), "tests/**/*.ts"] });
+  await writeConfig("tsconfig.json", { files: [], references: [{ path: "./tsconfig.client.json" }, { path: "./tsconfig.server.json" }] });
+};
+
+export const readAppPackage = async (directory: string): Promise<AppPackage> => {
+  const pkg = JSON.parse(await readFile(path.join(directory, "package.json"), "utf8")) as Record<string, unknown>;
+  if (!Value.Check(appPackageSchema, pkg.ragents)) throw new Error("package.json.ragents braucht title und gültige backend/views-Angaben.");
+  if (!pkg.ragents.backend && !pkg.ragents.views?.length) throw new Error("Ein Actor-Paket braucht ein Backend oder mindestens eine Ansicht.");
+  const views = pkg.ragents.views ?? [];
+  if (new Set(views.map((view) => view.id)).size !== views.length) throw new Error("Ansichtsnamen müssen eindeutig sein.");
+  return pkg.ragents;
+};
+
+export const projectSourceFiles = async (directory: string): Promise<{ path: string; content: string }[]> => {
+  const files: { path: string; content: string }[] = [];
+  const walk = async (relative: string): Promise<void> => {
+    for (const entry of await readdir(path.join(directory, relative), { withFileTypes: true })) {
+      if (["node_modules", ".build", "dist", ".git"].includes(entry.name)) continue;
+      const name = path.join(relative, entry.name);
+      if (entry.isSymbolicLink()) throw new Error(`App-Quelldateien dürfen keine Symlinks enthalten: ${name}`);
+      if (entry.isDirectory()) await walk(name);
+      else if (entry.isFile()) files.push({ path: name, content: await readFile(path.join(directory, name), "utf8") });
+    }
+  };
+  await walk("");
+  return files.sort((left, right) => left.path.localeCompare(right.path));
+};
+
+export const typecheckServerProject = (directory: string, backend?: string): string[] => {
+  const configPath = path.join(directory, "tsconfig.server.json");
+  const config = ts.readConfigFile(configPath, ts.sys.readFile);
+  const parsed = ts.parseJsonConfigFileContent(config.config, ts.sys, directory, { noEmit: true }, configPath);
+  const rootNames = [...new Set([...parsed.fileNames, ...(backend ? [path.resolve(directory, backend)] : [])])];
+  const program = ts.createProgram(rootNames, parsed.options);
+  const configErrors = parsed.errors.filter((diagnostic) => !(backend && diagnostic.code === 18003));
+  return [...(config.error ? [config.error] : []), ...configErrors, ...ts.getPreEmitDiagnostics(program)].map((diagnostic) => {
+    const start = diagnostic.file && diagnostic.start !== undefined ? diagnostic.file.getLineAndCharacterOfPosition(diagnostic.start) : undefined;
+    return `${diagnostic.file ? path.relative(directory, diagnostic.file.fileName) : "tsconfig.server.json"}${start ? `:${start.line + 1}:${start.character + 1}` : ""} TS${diagnostic.code}: ${ts.flattenDiagnosticMessageText(diagnostic.messageText, " ")}`;
+  });
+};
+
+export const compileAppBackend = async (options: {
+  directory: string; backend: string; runId: string; executor: NativeTypeScriptExecutor; signal?: AbortSignal;
+}): Promise<{ contract: AppContract; javaScript: string; hash: string }> => {
+  const signal = AbortSignal.any([...(options.signal ? [options.signal] : []), AbortSignal.timeout(15_000)]);
+  const entry = path.resolve(options.directory, options.backend);
+  if (!entry.startsWith(`${options.directory}${path.sep}`)) throw new Error("Der Backend-Einstieg liegt außerhalb der App.");
+  const result = await build({
+    stdin: { contents: `import actor from ${JSON.stringify(`./${options.backend}`)};
+export const describe = () => {
+  for (const name of Object.keys(actor.contract.functions ?? {})) if (typeof actor.functions?.[name] !== 'function') throw new Error('Fehlende Funktion ' + name);
+  if (Boolean(actor.contract.input) !== (typeof actor.onInput === 'function')) throw new Error('input und onInput müssen gemeinsam vorhanden sein.');
+  return JSON.parse(JSON.stringify(actor.contract));
+};
+export const handle = (request, context) => {
+  if (request.kind === 'input') { if (!actor.onInput) throw new Error('Dieser Actor verarbeitet keine Eingaben.'); return actor.onInput(request.input, context); }
+  const handler = actor.functions[request.functionId];
+  if (typeof handler !== 'function') throw new Error('Unbekannte Actor-Funktion ' + request.functionId);
+  return handler(request.input, context);
+};`, resolveDir: options.directory, sourcefile: "actor-entry.ts", loader: "ts" },
+    absWorkingDir: options.directory, platform: "node", format: "esm", target: "node22", bundle: true, packages: "external", write: false,
+  });
+  options.signal?.throwIfAborted();
+  const javaScript = result.outputFiles![0]!.text;
+  const described = await options.executor.execute({
+    program: { entry: "server.mjs", files: [{ fileName: "server.mjs", text: javaScript }], exportName: "describe" },
+    input: {}, state: {}, cwd: options.directory,
+    context: { runId: options.runId, invocationId: "app-contract", invocationKind: "tool", principal: { id: "app-build", kind: "service" }, capabilities: [] },
+  }, { signal, call: async () => { throw new Error("Beim Laden des App-Vertrags sind Run-Aufrufe nicht verfügbar."); }, log: () => undefined });
+  if (!Value.Check(appContractSchema, described.result)) throw new Error("Der Backend-Export braucht defineActor({state, functions, input?}, {functions, onInput?}) mit gültigen Aktionsverträgen.");
+  return { contract: described.result, javaScript, hash: canonicalHash({ javaScript }) };
+};

package/plugins/ragents.actor-programs/server/authoring-contracts.ts

@@ -0,0 +1,10 @@
+import { appContractSchema, appPackageSchema } from "./app-project.js";
+import { clientApiDeclarations } from "./client-compiler.js";
+import { readClientUiExportContracts } from "./client-contracts.js";
+
+export const actorProgramAuthoringContracts = () => ({
+  package: appPackageSchema,
+  backend: appContractSchema,
+  client: clientApiDeclarations(),
+  clientTypes: readClientUiExportContracts("ChatConnection"),
+});

package/plugins/ragents.actor-programs/server/client-compiler.ts

@@ -0,0 +1,174 @@
+import { createHash } from "node:crypto";
+import { mkdir, readFile, realpath, writeFile } from "node:fs/promises";
+import { createRequire } from "node:module";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { build, type Message } from "esbuild";
+import ts from "typescript";
+import { canonicalTypeScriptBuildContract, typeScriptTypeFromSchema, type VirtualTypeScriptDiagnostic } from "@aicontainer/ragents";
+import { installWorkflowSdk } from "./app-project.js";
+import { readClientUiContractFiles } from "./client-contracts.js";
+
+export interface ClientActionContract {
+  id: string;
+  inputSchema: object;
+  resultSchema: object;
+}
+
+export interface ClientContracts {
+  stateSchema: object;
+  actions: readonly ClientActionContract[];
+}
+
+export interface ClientProjectRequest extends ClientContracts {
+  directory: string;
+  entryPoint: string;
+}
+
+const webRequire = createRequire(new URL("../../../apps/web/package.json", import.meta.url));
+const packageRoot = (id: string): string => path.dirname(webRequire.resolve(`${id}/package.json`));
+const uiSource = fileURLToPath(new URL("../client-ui/index.tsx", import.meta.url));
+
+const actionMap = (actions: readonly ClientActionContract[]): string => {
+  const seen = new Set<string>();
+  const fields = [...actions]
+    .sort((left, right) => left.id.localeCompare(right.id))
+    .map((action) => {
+      if (seen.has(action.id)) throw new Error(`App-Aktion ${action.id} ist doppelt deklariert.`);
+      seen.add(action.id);
+      return [
+        `  readonly ${JSON.stringify(action.id)}: {`,
+        `    readonly input: ${typeScriptTypeFromSchema(action.inputSchema)};`,
+        `    readonly output: ${typeScriptTypeFromSchema(action.resultSchema)};`,
+        "  };",
+      ].join("\n");
+    });
+  return fields.length > 0 ? `{\n${fields.join("\n")}\n}` : "{}";
+};
+
+const clientTypeDeclarations = (stateType: string, actionsType: string): string => `
+import type { ChatConnection } from "./ui";
+export type AppState = ${stateType};
+export type AppActions = ${actionsType};
+export interface AppCapabilities<Actions> {
+  list(): ReadonlyArray<keyof Actions & string>;
+  call<Name extends keyof Actions & string>(
+    name: Name,
+    input: Actions[Name] extends { readonly input: infer Input } ? Input : never,
+  ): Promise<Actions[Name] extends { readonly output: infer Output } ? Output : never>;
+}
+export interface AppStateView<State> {
+  read(): Readonly<State>;
+  subscribe(listener: (state: Readonly<State>) => void): () => void;
+}
+export interface AppContext<State, Actions> {
+  readonly ready: Promise<void>;
+  readonly run: { readonly id: string };
+  readonly actor: { readonly id: string; readonly handle: string };
+  readonly principal: { readonly id: string; readonly kind: "operator" };
+  readonly state: AppStateView<State>;
+  readonly chat: ChatConnection;
+  readonly capabilities: AppCapabilities<Actions>;
+}
+export declare const context: AppContext<AppState, AppActions>;
+export declare function useAppState(): Readonly<AppState>;
+`.trimStart();
+
+export const clientDeclarations = (request: ClientContracts): string =>
+  clientTypeDeclarations(typeScriptTypeFromSchema(request.stateSchema), actionMap(request.actions));
+
+export const clientApiDeclarations = (): string => clientTypeDeclarations("Record<string, unknown>", "{}");
+
+export const clientSdkSource = `import { useSyncExternalStore } from "react";
+export const context = globalThis.__ragentsAppContext;
+if (!context) throw new Error("Die Host-Bridge der Actor-Ansicht fehlt.");
+export const useAppState = () => useSyncExternalStore(context.state.subscribe, context.state.read, context.state.read);
+`;
+
+export const clientCompilerConfig = {
+  compilerOptions: {
+    target: "ES2022", module: "ESNext", moduleResolution: "Bundler", jsx: "react-jsx",
+    lib: ["ES2022", "DOM", "DOM.Iterable"], strict: true, skipLibCheck: true,
+    esModuleInterop: true, exactOptionalPropertyTypes: true, noUncheckedIndexedAccess: true, types: [], noEmit: true,
+  },
+};
+
+export const installClientSdk = async (directory: string, contracts: ClientContracts): Promise<void> => {
+  await installWorkflowSdk(directory);
+  const target = path.join(directory, "node_modules/@ragents/client");
+  const files: Record<string, string> = {
+    "package.json": JSON.stringify({ name: "@ragents/client", version: "0.0.0", type: "module",
+      exports: { ".": { types: "./index.d.ts", default: "./index.js" }, "./ui": { types: "./ui.d.ts", default: "./ui.js" } } }, null, 2),
+    "tsconfig.json": JSON.stringify(clientCompilerConfig, null, 2),
+    "index.d.ts": clientDeclarations(contracts),
+    "index.js": clientSdkSource,
+    "ui.d.ts": 'export * from "./contracts/plugins/ragents.actor-programs/client-ui/contracts";\n',
+    "ui.js": `export * from ${JSON.stringify(uiSource)};\n`,
+    ...Object.fromEntries(Object.entries(readClientUiContractFiles()).map(([name, text]) => [`contracts/${name}`, text])),
+  };
+  await Promise.all(Object.entries(files).map(async ([name, text]) => {
+    const filename = path.join(target, name);
+    await mkdir(path.dirname(filename), { recursive: true });
+    await writeFile(filename, text);
+  }));
+};
+
+const diagnosticFrom = (diagnostic: ts.Diagnostic, directory: string): VirtualTypeScriptDiagnostic => {
+  const result: VirtualTypeScriptDiagnostic = {
+    code: diagnostic.code,
+    category: diagnostic.category === ts.DiagnosticCategory.Error ? "error" : diagnostic.category === ts.DiagnosticCategory.Warning ? "warning" : "message",
+    message: ts.flattenDiagnosticMessageText(diagnostic.messageText, "\n"),
+    ...(diagnostic.file ? { fileName: path.relative(directory, diagnostic.file.fileName).replaceAll(path.sep, "/") } : {}),
+  };
+  if (!diagnostic.file || diagnostic.start === undefined) return result;
+  const start = diagnostic.file.getLineAndCharacterOfPosition(diagnostic.start);
+  const end = diagnostic.file.getLineAndCharacterOfPosition(diagnostic.start + (diagnostic.length ?? 0));
+  return { ...result, start: { line: start.line + 1, column: start.character + 1 }, end: { line: end.line + 1, column: end.character + 1 } };
+};
+
+const buildDiagnostic = (message: Message): VirtualTypeScriptDiagnostic => ({
+  code: 0, category: "error", message: message.text,
+  ...(message.location ? { fileName: message.location.file, start: { line: message.location.line, column: message.location.column + 1 } } : {}),
+});
+
+export const compileClientProject = async (request: ClientProjectRequest, signal?: AbortSignal) => {
+  signal?.throwIfAborted();
+  const directory = await realpath(request.directory);
+  const declarations = clientDeclarations(request);
+  const installed = await readFile(path.join(directory, "node_modules/@ragents/client/index.d.ts"), "utf8");
+  if (installed !== declarations) throw new Error("Die Client-SDK-Typen sind nicht aktuell. Das Actor-Projekt muss neu vorbereitet werden.");
+  const configPath = path.join(directory, "tsconfig.client.json");
+  const configFile = ts.readConfigFile(configPath, ts.sys.readFile);
+  if (configFile.error) throw new Error(ts.flattenDiagnosticMessageText(configFile.error.messageText, "\n"));
+  const config = ts.parseJsonConfigFileContent(configFile.config, ts.sys, directory, {}, configPath);
+  const program = ts.createProgram({ rootNames: [...new Set([path.resolve(directory, request.entryPoint), ...config.fileNames])], options: config.options });
+  const diagnostics = [...config.errors, ...ts.getPreEmitDiagnostics(program)]
+    .map((diagnostic) => diagnosticFrom(diagnostic, directory));
+  signal?.throwIfAborted();
+  let javaScript = "";
+  if (!diagnostics.some((diagnostic) => diagnostic.category === "error")) {
+    try {
+      const result = await build({
+        absWorkingDir: directory, entryPoints: [request.entryPoint], bundle: true, write: false,
+        platform: "browser", format: "esm", target: "es2022", jsx: "automatic", tsconfig: configPath,
+        alias: { react: packageRoot("react"), "react-dom": packageRoot("react-dom") },
+        define: { "process.env.NODE_ENV": '"production"' }, legalComments: "none", logLevel: "silent",
+        minify: true,
+      });
+      const output = result.outputFiles.find((file) => file.path.endsWith(".js") || file.path === "<stdout>");
+      if (!output) throw new Error("Der Client-Build hat kein JavaScript erzeugt.");
+      javaScript = output.text;
+    } catch (cause) {
+      if (cause && typeof cause === "object" && "errors" in cause && Array.isArray(cause.errors)) {
+        diagnostics.push(...(cause.errors as Message[]).map(buildDiagnostic));
+      } else throw cause;
+    }
+  }
+  signal?.throwIfAborted();
+  const compilationHash = createHash("sha256").update(canonicalTypeScriptBuildContract({
+    stateSchema: request.stateSchema, actions: request.actions, declarations, javaScript,
+    typescript: ts.version, config: { ...config.options, configFilePath: undefined },
+    sources: program.getSourceFiles().map((file) => ({ path: path.relative(directory, file.fileName), text: file.text })),
+  })).digest("hex");
+  return { valid: !diagnostics.some((diagnostic) => diagnostic.category === "error"), diagnostics, declarations, javaScript, compilationHash };
+};