@schlenkr/ragents 0.1.0

package/plugins/ragents.actor-programs/server/tailwind.ts

@@ -0,0 +1,22 @@
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { compile } from "@tailwindcss/node";
+import { Scanner } from "@tailwindcss/oxide";
+
+const hostDirectory = fileURLToPath(new URL("../../../apps/web/src/", import.meta.url));
+const clientUiDirectory = fileURLToPath(new URL("../client-ui/", import.meta.url));
+export const frameStylesheet = path.join(hostDirectory, "ui/frame.css");
+
+export type TailwindSource = string | { base: string; pattern: string };
+
+/** Compiles the frame stylesheet against the host components plus the given sources; a plain string scans a whole directory. */
+export const buildTailwind = async (sources: readonly TailwindSource[], entry = frameStylesheet): Promise<string> => {
+  const css = await readFile(entry, "utf8");
+  const compiler = await compile(css, { base: path.dirname(entry), onDependency: () => {} });
+  const scanner = new Scanner({ sources: [
+    ...compiler.sources,
+    ...[hostDirectory, clientUiDirectory, ...sources].map((source) => typeof source === "string" ? { base: source, pattern: "**/*", negated: false } : { ...source, negated: false }),
+  ] });
+  return compiler.build(scanner.scan());
+};

package/plugins/ragents.actor-programs/server/templates.ts

@@ -0,0 +1,400 @@
+import { controlsTemplate } from "./controls-template";
+
+export interface ActorProgramTemplate {
+  id: string;
+  title: string;
+  description: string;
+  files: Readonly<Record<string, string>>;
+}
+
+const blank: ActorProgramTemplate = {
+  id: "blank",
+  title: "Leere Mini-App",
+  description: "Eine reine React-View am vorhandenen Actor ohne zusätzliche Serverfunktion.",
+  files: {
+    "package.json": `{
+  "name": "actor-view",
+  "private": true,
+  "type": "module",
+  "ragents": {
+    "title": "Meine View",
+    "description": "Eine kleine Bedienoberfläche des vorhandenen Actors.",
+    "views": [
+      {
+        "id": "main",
+        "client": "src/client.tsx"
+      }
+    ]
+  }
+}
+`,
+    "src/client.tsx": `import { createRoot } from "react-dom/client";
+import * as UI from "@ragents/client/ui";
+
+const App = () => (
+  <UI.AppLayout title="Meine View">
+    <UI.Stack><p>Bereit für deine Inhalte.</p></UI.Stack>
+  </UI.AppLayout>
+);
+
+const root = document.getElementById("root");
+if (!root) throw new Error("Das Wurzelelement #root fehlt.");
+createRoot(root).render(<App />);
+`,
+  },
+};
+
+const chat: ActorProgramTemplate = {
+  id: "chat",
+  title: "Actor-Chat",
+  description: "Wiederverwendbarer Chat mit Verlauf und optionaler Eingabe an den Actor dieser View.",
+  files: {
+    "package.json": `{
+  "name": "actor-chat",
+  "private": true,
+  "type": "module",
+  "ragents": {
+    "title": "Actor-Chat",
+    "description": "Zeigt das Gespräch mit einem Actor und sendet ihm Benutzereingaben.",
+    "views": [
+      {
+        "id": "main",
+        "client": "src/client.tsx",
+        "width": 480,
+        "height": 420
+      }
+    ]
+  }
+}
+`,
+    "src/client.tsx": `import { createRoot } from "react-dom/client";
+import * as UI from "@ragents/client/ui";
+import { context } from "@ragents/client";
+
+const App = () => (
+  <UI.Chat actor={"@" + context.actor.handle} className="h-full" showInput placeholder="Nachricht an den Actor" />
+);
+
+const root = document.getElementById("root");
+if (!root) throw new Error("Das Wurzelelement #root fehlt.");
+createRoot(root).render(<App />);
+`,
+  },
+};
+
+const textAnalysis: ActorProgramTemplate = {
+  id: "text-analysis",
+  title: "Textanalyse",
+  description: "Ein TypeScript-Actor analysiert Texte mit eigener Funktion, Zustand und React-View.",
+  files: {
+    "package.json": `{
+  "name": "text-analysis",
+  "private": true,
+  "type": "module",
+  "ragents": {
+    "title": "Textanalyse",
+    "description": "Zählt Zeichen, Wörter und Zeilen und merkt sich die Zahl der Analysen.",
+    "backend": "src/server.ts",
+    "views": [
+      {
+        "id": "main",
+        "client": "src/client.tsx"
+      }
+    ]
+  }
+}
+`,
+    "src/client.tsx": `import React from "react";
+import { createRoot } from "react-dom/client";
+import { context, useAppState } from "@ragents/client";
+import * as UI from "@ragents/client/ui";
+
+type FormValues = Parameters<typeof UI.Form>[0]["values"];
+
+const App = () => {
+  const state = useAppState();
+  const [values, setValues] = React.useState<FormValues>({ text: "" });
+  const [result, setResult] = React.useState("Bereit");
+
+  const analyse = async (next: FormValues): Promise<void> => {
+    const answer = await context.capabilities.call("analyse", { text: String(next.text ?? "") });
+    setResult([
+      \`Zeichen: \${answer.characters}\`,
+      \`Wörter: \${answer.words}\`,
+      \`Zeilen: \${answer.lines}\`,
+    ].join("\\n"));
+  };
+
+  return (
+    <UI.AppLayout title="Textanalyse" description={<>Analysen: {state.analyses ?? 0}</>}>
+      <UI.Grid>
+        <UI.Form fields={[
+          { id: "text", label: "Text", type: "textarea", rows: 6, placeholder: "Text eingeben" },
+        ]} values={values} onChange={setValues} onSubmit={analyse} submitLabel="Analysieren" />
+        <UI.Stack><pre aria-live="polite" className="min-h-[90px] overflow-auto rounded-md border border-border bg-muted p-2.5 font-mono whitespace-pre-wrap">{result}</pre></UI.Stack>
+      </UI.Grid>
+    </UI.AppLayout>
+  );
+};
+
+const root = document.getElementById("root");
+if (!root) throw new Error("Das Wurzelelement #root fehlt.");
+createRoot(root).render(<App />);
+`,
+    "src/contract.ts": `import { Type } from "typebox";
+
+export const contract = {
+  state: Type.Object({ analyses: Type.Optional(Type.Integer({"minimum": 0})) }, {"additionalProperties": false}),
+  functions: {
+    analyse: {
+      label: "Text analysieren",
+      description: "Zählt Wörter, Zeichen und Zeilen ohne externe Wirkung.",
+      tool: { name: "analyse_text" },
+      input: Type.Object({ text: Type.String({"description": "Der zu analysierende Text."}) }, {"additionalProperties": false}),
+      output: Type.Object({ text: Type.String(), characters: Type.Integer({"minimum": 0}), words: Type.Integer({"minimum": 0}), lines: Type.Integer({"minimum": 0}), analyses: Type.Integer({"minimum": 1}) }, {"additionalProperties": false}),
+      capabilities: [],
+    },
+  },
+} as const;
+`,
+    "src/server.ts": `import { defineActor } from "@ragents/server";
+import { contract } from "./contract.ts";
+
+export default defineActor(contract, {
+  functions: {
+    analyse: async (input, context) => {
+      const text = input.text.trim();
+      const state = context.state.read();
+      const analyses = (state.analyses ?? 0) + 1;
+      context.state.replace({ analyses });
+
+      return {
+        text,
+        characters: text.length,
+        words: text ? text.split(/\\s+/).length : 0,
+        lines: text ? text.split(/\\r?\\n/).length : 0,
+        analyses,
+      };
+    },
+  },
+});
+`,
+    "tests/program.test.ts": `import assert from "node:assert/strict";
+import test from "node:test";
+import type { Static } from "typebox";
+import { createTestContext } from "@ragents/server/testing";
+import { contract } from "../src/contract.ts";
+import program from "../src/server.ts";
+
+test("zählt Wörter, Zeilen und weitere Analysen", async () => {
+  const context = createTestContext<Static<typeof contract.state>>({ state: {} });
+  assert.deepEqual(await program.functions.analyse({"text": "  Hallo Welt\\nNeue Zeile  "}, context), {"text": "Hallo Welt\\nNeue Zeile", "characters": 21, "words": 4, "lines": 2, "analyses": 1});
+  assert.deepEqual(await program.functions.analyse({"text": ""}, context), {"text": "", "characters": 0, "words": 0, "lines": 0, "analyses": 2});
+  assert.deepEqual(context.state.read(), {"analyses": 2});
+});
+`,
+  },
+};
+
+const headlessCounter: ActorProgramTemplate = {
+  id: "headless-counter",
+  title: "Zähler ohne Oberfläche",
+  description: "Ein TypeScript-Actor zählt Eingaben in seinem Zustand und bietet dieselbe Arbeit als Funktion an.",
+  files: {
+    "package.json": `{
+  "name": "headless-counter",
+  "private": true,
+  "type": "module",
+  "ragents": {
+    "title": "Zähler",
+    "description": "Sammelt eingehende Texte ohne Modellaufrufe oder Oberfläche.",
+    "backend": "src/server.ts"
+  }
+}
+`,
+    "src/contract.ts": `import { Type } from "typebox";
+
+const state = Type.Object({
+  texts: Type.Optional(Type.Array(Type.String())),
+  count: Type.Optional(Type.Integer({ minimum: 0 })),
+}, { additionalProperties: false });
+
+export const contract = {
+  state,
+  functions: {
+    record: {
+      label: "Text zählen",
+      input: Type.Object({ text: Type.String() }, { additionalProperties: false }),
+      output: Type.Object({ count: Type.Integer(), texts: Type.Array(Type.String()) }, { additionalProperties: false }),
+      tool: { name: "record_text" },
+    },
+    inspect: {
+      label: "Zähler lesen",
+      input: Type.Object({}, { additionalProperties: false }),
+      output: state,
+      tool: { name: "read_counter" },
+    },
+  },
+  input: { capabilities: [] },
+} as const;
+`,
+    "src/server.ts": `import { defineActor } from "@ragents/server";
+import type { Static } from "typebox";
+import { contract } from "./contract.ts";
+
+const record = (state: Static<typeof contract.state>, text: string) => {
+  const texts = [...(state.texts ?? []), text];
+  return { texts, count: texts.length };
+};
+
+export default defineActor(contract, {
+  functions: {
+    record: (input, context) => {
+      const result = record(context.state.read(), input.text);
+      context.state.replace(result);
+      return result;
+    },
+    inspect: (_input, context) => context.state.read(),
+  },
+  onInput: (input, context) => {
+    context.state.replace(record(context.state.read(), input.content));
+  },
+});
+`,
+    "tests/program.test.ts": `import assert from "node:assert/strict";
+import test from "node:test";
+import type { Static } from "typebox";
+import { createTestContext } from "@ragents/server/testing";
+import { contract } from "../src/contract.ts";
+import program from "../src/server.ts";
+
+test("Eingaben und Funktionen teilen denselben Zähler", async () => {
+  const context = createTestContext<Static<typeof contract.state>>({ state: {} });
+  for (const content of ["eins", "zwei", "drei"]) {
+    await program.onInput!({ id: content, content, artifactIds: [], sourceEventIds: [], subscriptionId: null, event: null }, context);
+  }
+  assert.deepEqual(await program.functions.inspect({}, context), { texts: ["eins", "zwei", "drei"], count: 3 });
+  assert.deepEqual(await program.functions.record({ text: "vier" }, context), { texts: ["eins", "zwei", "drei", "vier"], count: 4 });
+  assert.deepEqual(context.state.read(), { texts: ["eins", "zwei", "drei", "vier"], count: 4 });
+});
+`,
+  },
+};
+
+const sharedList: ActorProgramTemplate = {
+  id: "shared-list",
+  title: "Gemeinsame Liste eines Actors",
+  description: "Ein Actor besitzt eine Funktion und eine React-View für denselben Listenstand.",
+  files: {
+    "package.json": `{
+  "name": "shared-list",
+  "private": true,
+  "type": "module",
+  "ragents": {
+    "title": "Gemeinsame Liste",
+    "description": "Sammelt Texte aus der App und aus einem Agenten-Werkzeug in einer gemeinsamen Liste.",
+    "backend": "src/server.ts",
+    "views": [
+      {
+        "id": "main",
+        "client": "src/client.tsx"
+      }
+    ]
+  }
+}
+`,
+    "src/client.tsx": `import React from "react";
+import { createRoot } from "react-dom/client";
+import { context, useAppState } from "@ragents/client";
+import * as UI from "@ragents/client/ui";
+
+type FormValues = Parameters<typeof UI.Form>[0]["values"];
+
+const App = () => {
+  const state = useAppState();
+  const [values, setValues] = React.useState<FormValues>({ text: "" });
+  const [status, setStatus] = React.useState("Bereit");
+  const entries = state.entries ?? [];
+
+  const append = async (next: FormValues): Promise<void> => {
+    const answer = await context.capabilities.call("append", { text: String(next.text ?? "") });
+    setValues({ text: "" });
+    setStatus(\`Hinzugefügt: \${answer.text}\`);
+  };
+
+  return (
+    <UI.AppLayout title="Gemeinsame Liste" description={<>{entries.length} {entries.length === 1 ? "Eintrag" : "Einträge"}</>}>
+      <UI.Grid>
+        <UI.Form fields={[
+          { id: "text", label: "Neuer Eintrag", type: "textarea", placeholder: "Text eingeben" },
+        ]} values={values} onChange={setValues} onSubmit={append} submitLabel="Hinzufügen" />
+        <UI.Stack>
+          <p className="text-muted-foreground" role="status">{status}</p>
+          <ul className="border-t border-border">
+            {entries.map((entry, index) => <li className="min-h-[31px] border-b border-border-soft py-1.5 [overflow-wrap:anywhere]" key={index}>{entry}</li>)}
+          </ul>
+        </UI.Stack>
+      </UI.Grid>
+    </UI.AppLayout>
+  );
+};
+
+const root = document.getElementById("root");
+if (!root) throw new Error("Das Wurzelelement #root fehlt.");
+createRoot(root).render(<App />);
+`,
+    "src/contract.ts": `import { Type } from "typebox";
+
+export const contract = {
+  state: Type.Object({ entries: Type.Optional(Type.Array(Type.String())) }, {"additionalProperties": false}),
+  functions: {
+    append: {
+      label: "Eintrag hinzufügen",
+      description: "Hängt den eingegebenen Text an die gemeinsame Liste an.",
+      input: Type.Object({ text: Type.String({"description": "Der Text für den neuen Listeneintrag."}) }, {"additionalProperties": false}),
+      output: Type.Object({ text: Type.String(), entries: Type.Array(Type.String()) }, {"additionalProperties": false}),
+      capabilities: [],
+      tool: { name: "append_to_list", card: true },
+    },
+  },
+} as const;
+`,
+    "src/server.ts": `import { defineActor } from "@ragents/server";
+import { contract } from "./contract.ts";
+
+export default defineActor(contract, {
+  functions: {
+    append: async (input, context) => {
+      const text = input.text.trim();
+      const state = context.state.read();
+      const entries = [...(state.entries ?? []), text];
+      context.state.replace({ entries });
+      return { text, entries };
+    },
+  },
+});
+`,
+    "tests/program.test.ts": `import assert from "node:assert/strict";
+import test from "node:test";
+import type { Static } from "typebox";
+import { createTestContext } from "@ragents/server/testing";
+import { contract } from "../src/contract.ts";
+import program from "../src/server.ts";
+
+test("ergänzt Einträge ohne vorhandene Einträge zu verlieren", async () => {
+  const context = createTestContext<Static<typeof contract.state>>({ state: {} });
+  assert.deepEqual(await program.functions.append({"text": "  Erster Eintrag  "}, context), {"text": "Erster Eintrag", "entries": ["Erster Eintrag"]});
+  assert.deepEqual(await program.functions.append({"text": "Zweiter Eintrag"}, context), {"text": "Zweiter Eintrag", "entries": ["Erster Eintrag", "Zweiter Eintrag"]});
+  assert.deepEqual(context.state.read(), {"entries": ["Erster Eintrag", "Zweiter Eintrag"]});
+});
+`,
+  },
+};
+
+export const runModuleTemplates = [blank, chat, controlsTemplate, textAnalysis, headlessCounter, sharedList] as const;
+
+export const templateById = (id: string): ActorProgramTemplate => {
+  const template = runModuleTemplates.find((candidate) => candidate.id === id);
+  if (!template) throw new Error(`Unbekannte Actor-Programm-Vorlage ${id}. Gültig: ${runModuleTemplates.map((entry) => entry.id).join(", ")}.`);
+  return template;
+};

package/plugins/ragents.actor-programs/server/tool-contributor.ts

@@ -0,0 +1,29 @@
+import { Type } from "typebox";
+import { defineRunFunction, defineToolAvailability, holdsUsable, type RunFunction, type ToolContributor } from "@aicontainer/ragents";
+import { toolDescriptorFrom } from "@aicontainer/server/plugin-support/agent-tool.js";
+import type { ActorProgramRuntime } from "./runtime.js";
+import type { createProjectDiagnostics } from "./project-diagnostics.js";
+const metadata = [
+    { name: "actor_program_create", label: "Create Actor Program", description: "Create a private TypeScript package with fixed libraries.", longDescription: "Edit files under @actors/name using workspace tools." },
+    { name: "actor_program_activate", label: "Activate Actor Program", description: "Typecheck, build and test a package, then activate its functions and optional views.", longDescription: "actor self or @handle attaches to an existing actor; omitted creates a TypeScript actor for a backend, or attaches static views to self." },
+    { name: "actor_program_list", label: "List Actor Programs", description: "List active actor packages, functions and views." },
+    { name: "actor_program_remove", label: "Remove Actor Program", description: "Detach functions and views and stop the backend.", longDescription: "A TypeScript actor is stopped; an LLM actor retains its agent behavior." },
+    { name: "actor_view_set_visibility", label: "Show or hide Actor View", description: "Set Canvas visibility by package-name/view-key or @handle/view-key.", longDescription: "Use names you chose; the server resolves the view ID. A unique view title also works." },
+    { name: "actor_program_diagnostics", label: "Actor Program Diagnostics", description: "Read the last project diagnostics.", longDescription: "Changed errors are automatically supplied before the next model request." },
+] as const;
+export const actorProgramManagementToolNames = metadata.map((entry) => entry.name);
+export const actorProgramToolsAvailable = defineToolAvailability({ availability: "conditional", availabilityDetail: "Für ausführbare Actors mit agent.spawn und plugin.state.write." }, actor => actor.kind !== "human" && holdsUsable(actor, "agent.spawn") && holdsUsable(actor, "plugin.state.write"));
+const name = Type.String({ pattern: "^[a-z][a-z0-9-]{0,63}$" });
+type Diagnostics = Pick<ReturnType<typeof createProjectDiagnostics>, "latest">;
+const managementTools = (runtime: ActorProgramRuntime, diagnostics: Diagnostics): RunFunction[] => [
+    defineRunFunction({ ...metadata[0], schema: Type.Object({ name, template: Type.Union(runtime.templates().map((entry) => Type.Literal(entry.id, { description: entry.description }))) }, { additionalProperties: false }), resultSchema: Type.Object({ name: Type.String(), directory: Type.String(), files: Type.Array(Type.String()) }, { additionalProperties: false }), available: actorProgramToolsAvailable, executionMode: "sequential", run: (scope, _id, input) => runtime.scaffold(scope.caller.runId, input.name, input.template) }),
+    defineRunFunction({ ...metadata[1], schema: Type.Object({ name, actor: Type.Optional(Type.String()) }, { additionalProperties: false }), resultSchema: Type.Object({ name: Type.String(), actor: Type.String(), views: Type.Number(), active: Type.Literal(true) }, { additionalProperties: false }), available: actorProgramToolsAvailable, executionMode: "sequential", run: (scope, id, input) => runtime.activate(scope.context(id), scope.caller.runId, input.name, scope.signal, input.actor) }),
+    defineRunFunction({ ...metadata[2], schema: Type.Object({}, { additionalProperties: false }), resultSchema: Type.Array(Type.Object({ name: Type.String(), actor: Type.String(), functions: Type.Array(Type.String()), views: Type.Array(Type.Object({ name: Type.String(), title: Type.String(), visible: Type.Boolean() })) })), available: actorProgramToolsAvailable, executionMode: "sequential", run: (scope) => runtime.list(scope.caller.runId) }),
+    defineRunFunction({ ...metadata[3], schema: Type.Object({ name }, { additionalProperties: false }), resultSchema: Type.Object({ removed: Type.String() }, { additionalProperties: false }), available: actorProgramToolsAvailable, executionMode: "sequential", run: (scope, id, input) => runtime.remove(scope.context(id), scope.caller.runId, input.name) }),
+    defineRunFunction({ ...metadata[4], schema: Type.Object({ view: Type.String({ minLength: 1, description: "package-name/view-key or @handle/view-key of an activated view, without the Canvas entity prefix app:. No generated IDs needed." }), visible: Type.Boolean() }, { additionalProperties: false }), resultSchema: Type.Object({ view: Type.String(), visible: Type.Boolean() }, { additionalProperties: false }), available: actorProgramToolsAvailable, executionMode: "sequential", run: (scope, id, input) => runtime.setVisibility(scope.context(id), scope.caller.runId, input.view, input.visible) }),
+    defineRunFunction({ ...metadata[5], schema: Type.Object({ name: Type.Optional(name) }, { additionalProperties: false }), resultSchema: Type.String(), available: actorProgramToolsAvailable, executionMode: "sequential", run: (scope, _id, input) => diagnostics.latest(scope.caller.runId, scope.caller.actorId, input.name) }),
+];
+export const createActorProgramToolContributors = (runtime: ActorProgramRuntime, diagnostics: Diagnostics): readonly ToolContributor[] => [
+    { name: "ragents.actor-programs.management", descriptors: metadata.map((item) => toolDescriptorFrom(item, actorProgramToolsAvailable)), tools: () => managementTools(runtime, diagnostics) },
+    { name: "ragents.actor-programs.functions", descriptors: [], dynamic: true, tools: (context) => runtime.installedTools(context) },
+];

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

@@ -0,0 +1,17 @@
+## Actor programs
+
+Use TypeScript snippets for one-time work. Actors can own functions, shared state and React views. Create the closest template with
+`actor_program_create`, read its existing files in `@actors/<name>/`, adapt what is needed,
+then `actor_program_activate`. Reuse its code and tests; Bash uses `$RAGENTS_ACTORS_DIR`.
+Call these functions through `context.functions` in `typescript_eval`; `typescript_api` gives
+the current contracts. Published actor functions join that same API during the current turn.
+Bind existing actors with `self` or `@handle`. A backend without a binding creates a TypeScript
+actor; a pure view binds to the calling actor. UI functions never require a model turn.
+Changed project errors arrive automatically; `actor_program_diagnostics` gives full diagnostics.
+Query `actor_program_controls` when specific props are unclear, or `topic: "guide"` for the workflow.
+Controls are shadcn/ui components with their usual props, icons from `lucide-react`, Tailwind for layout.
+Build views with `AppLayout`, `Stack` and responsive `Grid`; the host supplies base typography.
+Use `Form` for labeled inputs and interview steps, including `type: "textarea"` for long answers.
+Do not rebuild field wrappers, labels or submit handling with custom layout CSS.
+For diagrams, adapt the `controls` SVG example: `SvgEdge` draws styled connections;
+compact labeled nodes and responsive SVG layout remain app code using Tailwind utilities.