@schlenkr/ragents 0.1.14 → 0.1.15

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

@@ -10,6 +10,7 @@ const metadata = [
     { 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 surface 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." },
+    { name: "actor_program_ensure", label: "Ensure Actor Program", description: "Make a package active once: return it when active, restart its stopped actor, activate it when installed, or install a shared package of the profile.", longDescription: "Safe to call on every start: an active package is returned unchanged and not rebuilt. status names what happened. actor_program_activate instead rebuilds and reactivates." },
 ] as const;
 export const actorProgramManagementToolNames = metadata.map((entry) => entry.name);
 export const actorProgramToolsAvailable = defineToolAvailability({ availability: "conditional", availabilityDetail: "For executable actors with agent.spawn and plugin.state.write." }, actor => actor.kind !== "human" && holdsUsable(actor, "agent.spawn") && holdsUsable(actor, "plugin.state.write"));
@@ -22,6 +23,7 @@ const managementTools = (runtime: ActorProgramRuntime, diagnostics: Diagnostics)
     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 surface 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) }),
+    defineRunFunction({ ...metadata[6], schema: Type.Object({ name }, { additionalProperties: false }), resultSchema: Type.Object({ actorId: Type.String(), handle: Type.String(), status: Type.Union([Type.Literal("active"), Type.Literal("restarted"), Type.Literal("activated"), Type.Literal("installed")]) }, { additionalProperties: false }), available: actorProgramToolsAvailable, executionMode: "sequential", run: (scope, id, input) => runtime.ensure(scope.context(id), scope.caller.runId, input.name, scope.signal) }),
 ];
 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) },

package/plugins/ragents.ask/server/ask-tool.ts

@@ -6,6 +6,7 @@ import type { AskService } from "./contract.js";
 export const askToolMetadata = {
   name: "ask_user",
   label: "Question",
+  nativeTool: true,
   description: "Asks the user for a required decision with answer options and waits for the answer.",
   longDescription: "Always use this tool when you need a decision from the user "
     + "(e.g. choosing a branch or a time range), instead of only asking the question as text. "

package/plugins/ragents.orchestration/ragents-plugin.json

@@ -1,6 +1,7 @@
 {
   "id": "ragents.orchestration",
   "exports": {
+    "server": ["server/contract"],
     "web": ["web/surface-entities", "web/program-slot", "web/tile-docking"]
   }
 }

package/plugins/ragents.orchestration/server/contract.ts

@@ -0,0 +1,14 @@
+import { serviceToken, type CommandContext, type ServiceToken } from "@ragents/engine";
+
+export interface SurfacePlacementRequest {
+  entity: string;
+  direction?: "horizontal" | "vertical";
+  weight?: number;
+}
+
+/** Places an entity next to a run's surface layout, as canvas_layout_place does; an entity the layout shows already stays. */
+export interface SurfacePlacement {
+  place: (context: CommandContext, runId: string, request: SurfacePlacementRequest) => { placed: boolean };
+}
+
+export const surfacePlacementToken: ServiceToken<SurfacePlacement> = serviceToken("ragents.orchestration.surface-placement");

package/plugins/ragents.orchestration/server/index.ts

@@ -11,7 +11,8 @@ import { runtimeProviderToken } from "@ragents/host/ragents/host-services.js";
 import { pluginAsset } from "@ragents/host/plugin-support/plugin-folder.js";
 import type { PluginModule } from "@ragents/host/plugin-support/plugin-module.js";
 import { boundToTools, handlebarsPrompt } from "@ragents/host/plugin-support/prompt.js";
-import { createSurfaceToolContributor } from "./surface-tool.js";
+import { createSurfaceToolContributor, placeOnSurface } from "./surface-tool.js";
+import { surfacePlacementToken } from "./contract.js";
 import { createRunStopContributor } from "./run-stop-tool.js";
 import { runManagementToken } from "@ragents/host/ragents/global-chat.js";
 
@@ -19,6 +20,7 @@ const orchestrationPlugin: RAgentsPlugin = {
   manifest: { id: "ragents.orchestration" },
   register: (host) => {
     host.functions(createSurfaceToolContributor());
+    host.provide(surfacePlacementToken, placeOnSurface(host.service(runtimeProviderToken)));
     host.functions(createRunStopContributor(
       (runId) => host.service(runManagementToken)().stop(runId),
       (error) => console.error("Run stop by the coordinator failed", error),
@@ -53,6 +55,7 @@ const orchestrationPlugin: RAgentsPlugin = {
       boundToTools(
         handlebarsPrompt("ragents.orchestration.surface", 650, pluginAsset("ragents.orchestration", "surface.hbs")),
         "canvas_layout_replace",
+        "canvas_layout_place",
       ),
     );
   },

package/plugins/ragents.orchestration/server/surface-tool.ts

@@ -5,6 +5,8 @@ import {
   defineRunFunction,
   defineToolAvailability,
   holdsUsable,
+  type CommandContext,
+  type Orchestration,
   type RunFunction,
   type RunView,
   type ToolContributor,
@@ -18,6 +20,7 @@ import {
   type SurfaceLayout,
 } from "../contract.js";
 import { surfaceTileEntities, mapSurfaceTileEntities } from "../tiled-layout.js";
+import type { SurfacePlacement, SurfacePlacementRequest } from "./contract.js";
 
 export const surfaceToolMetadata = {
   name: "canvas_layout_replace",
@@ -34,6 +37,17 @@ export const surfaceToolMetadata = {
     + "Participants you do not place stay reachable through the run header.",
 } as const;
 
+export const placeToolMetadata = {
+  name: "canvas_layout_place",
+  label: "Place on Surface",
+  description: "Place one actor or mini-app next to the current surface layout instead of replacing it.",
+  longDescription: "entity is {entity} of a tile: '@helper' or 'app:@workspace/main'. The current arrangement becomes one side of a new split "
+    + "and the entity the other: direction 'horizontal' (default) puts it to the right, 'vertical' below. weight is its share against "
+    + "the existing arrangement's weight 1, default 1. An entity the layout already shows stays where it is; placed is then false. "
+    + "On an empty surface the entity becomes the only tile. Use it when you join a running run, such as a run script started with "
+    + "start.embedded, so that the tiles others arranged stay.",
+} as const;
+
 export const canDesignSurface = defineToolAvailability({
   availability: "conditional",
   availabilityDetail: "Only for agents and TypeScript actors with the capability plugin.state.write.",
@@ -117,6 +131,48 @@ export const checkLayoutAgainstRun = (view: RunView, input: SurfaceLayout): Surf
   return layout;
 };
 
+const currentLayout = (view: RunView): SurfaceLayout => {
+  const state = view.pluginStates.find((entry) => entry.pluginId === ORCHESTRATION_PLUGIN_ID && entry.scope.kind === "run")?.state;
+  return state === undefined || state === null ? { root: null } : surfaceLayoutOf(state);
+};
+
+/** Splits the root once: the existing arrangement keeps weight 1, the placed tile gets its own. */
+const placed = (view: RunView, request: SurfacePlacementRequest): SurfaceLayout | undefined => {
+  const current = currentLayout(view);
+  const [tile] = surfaceTileEntities(checkLayoutAgainstRun(view, parsedLayout({ root: { entity: request.entity } })).root);
+  if (surfaceTileEntities(current.root).includes(tile!)) return undefined;
+  const root = current.root === null ? { entity: tile! } : {
+    direction: request.direction ?? "horizontal",
+    weights: [1, request.weight ?? 1],
+    children: [current.root, { entity: tile! }],
+  };
+  return parsedLayout({ root });
+};
+
+export const placeOnSurface = (runtime: () => Orchestration): SurfacePlacement => ({
+  place: (context: CommandContext, runId: string, request: SurfacePlacementRequest) => {
+    const layout = placed(runtime().view(runId), request);
+    if (!layout) return { placed: false };
+    runtime().replacePluginState(context, runId, { pluginId: ORCHESTRATION_PLUGIN_ID, scope: { kind: "run" }, state: layout });
+    return { placed: true };
+  },
+});
+
+const placeSchema = Type.Object({
+  entity: Type.String({ minLength: 1, description: "Actor @handle or activated mini-app app:@handle/view-key or app:program-name/view-key" }),
+  direction: Type.Optional(Type.Union([Type.Literal("horizontal"), Type.Literal("vertical")], { description: "horizontal: to the right of the current layout (default); vertical: below it" })),
+  weight: Type.Optional(Type.Number({ exclusiveMinimum: 0, description: "Share of the placed tile against the existing arrangement's weight 1; default 1" })),
+}, { additionalProperties: false });
+
+export const createPlaceTool = (): RunFunction =>
+  defineRunFunction({
+    ...placeToolMetadata,
+    schema: placeSchema,
+    resultSchema: Type.Object({ placed: Type.Boolean() }, { additionalProperties: false }),
+    available: canDesignSurface,
+    run: ({ runtime, caller, context }, toolCallId, input) => placeOnSurface(() => runtime).place(context(toolCallId), caller.runId, input),
+  });
+
 export const createSurfaceTool = (): RunFunction =>
   defineRunFunction({
     ...surfaceToolMetadata,
@@ -137,6 +193,6 @@ export const createSurfaceTool = (): RunFunction =>
 
 export const createSurfaceToolContributor = (): ToolContributor => ({
   name: "ragents.orchestration.surface",
-  descriptors: [toolDescriptorFrom(surfaceToolMetadata, canDesignSurface)],
-  tools: () => [createSurfaceTool()],
+  descriptors: [toolDescriptorFrom(surfaceToolMetadata, canDesignSurface), toolDescriptorFrom(placeToolMetadata, canDesignSurface)],
+  tools: () => [createSurfaceTool(), createPlaceTool()],
 });

package/plugins/ragents.orchestration/surface.hbs

@@ -19,6 +19,11 @@ App left, chat right at 50:50:
 ]}}. Resolve the actual actor and app names before calling; the example names are not existing
 participants.
 
+To add one tile without replacing what is arranged, `context.functions.canvas_layout_place({ entity })`
+splits the current layout once and puts the entity to its right, or below with `direction: "vertical"`;
+`weight` is its share against the existing arrangement's weight 1. An entity the layout shows already
+stays where it is. A run script started inside a running run (`start.embedded`) uses place, not replace.
+
 An actor tile carries {entity:"@helper",chatInput:false} when its chat composer should stay hidden.
 That changes neither permissions nor the inspector. Mini-app tiles have no chatInput.
 

package/plugins/ragents.reference/actors/notebook/package.json

@@ -0,0 +1,16 @@
+{
+  "name": "notebook",
+  "private": true,
+  "type": "module",
+  "ragents": {
+    "title": "Notebook",
+    "description": "Keeps the notes that run scripts send it, newest first.",
+    "backend": "src/server.ts",
+    "views": [
+      {
+        "id": "main",
+        "client": "src/client.tsx"
+      }
+    ]
+  }
+}

package/plugins/ragents.reference/actors/notebook/src/client.tsx

@@ -0,0 +1,31 @@
+import React from "react";
+import { createRoot } from "react-dom/client";
+import { context, useAppState } from "@ragents/client";
+import * as UI from "@ragents/client/ui";
+
+const App = () => {
+  const state = useAppState();
+  const notes = state.notes ?? [];
+  const [status, setStatus] = React.useState("Run scripts add their notes here.");
+
+  const clear = async (): Promise<void> => {
+    const answer = await context.capabilities.call("clear", {});
+    setStatus(`Cleared ${answer.cleared} ${answer.cleared === 1 ? "note" : "notes"}.`);
+  };
+
+  return (
+    <UI.AppLayout title="Notebook" description={<>{notes.length} {notes.length === 1 ? "note" : "notes"}</>}>
+      <UI.Stack>
+        <p className="text-muted-foreground" role="status">{status}</p>
+        <ul className="border-t border-border">
+          {notes.map((note, index) => <li className="min-h-8 border-b border-border-soft py-1.5 [overflow-wrap:anywhere]" key={index}>{note}</li>)}
+        </ul>
+        <UI.Button disabled={notes.length === 0} onClick={() => void clear()} variant="outline">Clear</UI.Button>
+      </UI.Stack>
+    </UI.AppLayout>
+  );
+};
+
+const root = document.getElementById("root");
+if (!root) throw new Error("The #root element is missing.");
+createRoot(root).render(<App />);

package/plugins/ragents.reference/actors/notebook/src/server.ts

@@ -0,0 +1,27 @@
+import { defineActor } from "@ragents/server";
+import { Type } from "typebox";
+
+const KEPT_NOTES = 50;
+
+const contract = {
+  state: Type.Object({ notes: Type.Optional(Type.Array(Type.String())) }, { additionalProperties: false }),
+  functions: {
+    clear: { label: "Clear notes", input: Type.Object({}, { additionalProperties: false }), output: Type.Object({ cleared: Type.Integer() }, { additionalProperties: false }) },
+  },
+  input: { capabilities: [] },
+} as const;
+
+export default defineActor(contract, {
+  functions: {
+    clear: (_input, context) => {
+      const cleared = context.state.read().notes?.length ?? 0;
+      context.state.replace({ notes: [] });
+      return { cleared };
+    },
+  },
+  onInput: (input, context) => {
+    const note = input.content.trim();
+    if (!note) throw new Error("A note needs text.");
+    context.state.replace({ notes: [note, ...context.state.read().notes ?? []].slice(0, KEPT_NOTES) });
+  },
+});

package/plugins/ragents.reference/actors/notebook/tests/program.test.ts

@@ -0,0 +1,27 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { createTestContext } from "@ragents/server/testing";
+import program from "../src/server.ts";
+
+const input = (content: string) => ({ id: "input-1", content, artifactIds: [], sourceEventIds: [], subscriptionId: null, event: null });
+
+test("keeps notes newest first and at most fifty", async () => {
+  const context = createTestContext<{ notes?: string[] }>({ state: { notes: Array.from({ length: 50 }, (_, index) => `old ${index}`) } });
+  await program.onInput!(input("  new note  "), context);
+  const notes = context.state.read().notes!;
+  assert.equal(notes.length, 50);
+  assert.equal(notes[0], "new note");
+  assert.equal(notes.at(-1), "old 48");
+});
+
+test("an empty note is refused and changes nothing", async () => {
+  const context = createTestContext<{ notes?: string[] }>({ state: { notes: ["kept"] } });
+  await assert.rejects(async () => program.onInput!(input("   "), context), /needs text/);
+  assert.deepEqual(context.state.read(), { notes: ["kept"] });
+});
+
+test("clear empties the notebook and names how many notes it removed", async () => {
+  const context = createTestContext<{ notes?: string[] }>({ state: { notes: ["one", "two"] } });
+  assert.deepEqual(await program.functions.clear({}, context), { cleared: 2 });
+  assert.deepEqual(context.state.read(), { notes: [] });
+});

package/plugins/ragents.reference/run-scripts/quick-note/RUN.md

@@ -0,0 +1,14 @@
+---
+title: Add a quick note
+description: "A prepared one-step script shows a shared actor package: it adds a note to the notebook it shares with the roster check, in a new or a running run."
+order: 180
+coordinator: false
+embeddable: true
+shared-programs: notebook
+tags: Run scripts, Concept demo, TypeScript actors
+---
+
+The start value `{ "text": "..." }` is the note; without one, the script notes when it was
+started. The script makes the shared notebook active with `actor_program_ensure`, sends it the
+note, places the notebook's view with `canvas_layout_place`, and ends the start with
+`context.finish`. Whether the roster check or this script comes first, the run has one notebook.

package/plugins/ragents.reference/run-scripts/quick-note/package.json

@@ -0,0 +1,9 @@
+{
+  "name": "quick-note",
+  "private": true,
+  "type": "module",
+  "ragents": {
+    "title": "Quick note",
+    "backend": "src/server.ts"
+  }
+}

package/plugins/ragents.reference/run-scripts/quick-note/src/server.ts

@@ -0,0 +1,29 @@
+import { defineActor } from "@ragents/server";
+import { Type } from "typebox";
+
+const contract = {
+  state: Type.Object({}, { additionalProperties: false }),
+  functions: {},
+  input: { capabilities: ["actor_program_ensure", "actor_input", "canvas_layout_place"] },
+} as const;
+
+const noteOf = (input: unknown, now: string): string => {
+  if (input === null) return `Started at ${now}.`;
+  const text = typeof input === "object" && input !== null && "text" in input ? (input as { text: unknown }).text : undefined;
+  if (typeof text !== "string" || !text.trim()) throw new Error('The start value is { "text": "..." } with the note, or none.');
+  return text.trim();
+};
+
+export default defineActor(contract, {
+  functions: {},
+  onInput: () => {
+    throw new Error("The quick note answers only starts; start it again with the note as its start value.");
+  },
+  onStart: async (start, context) => {
+    const note = noteOf(start.input, context.std.now());
+    const notebook = await context.functions.actor_program_ensure({ name: "notebook" });
+    await context.functions.actor_input({ actor: `@${notebook.handle}`, content: note });
+    await context.functions.canvas_layout_place({ entity: "app:notebook/main" });
+    context.finish({ note, notebook: notebook.status }, { summary: `Noted: ${note}` });
+  },
+});

package/plugins/ragents.reference/run-scripts/quick-note/tests/program.test.ts

@@ -0,0 +1,43 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { createTestContext } from "@ragents/server/testing";
+import program from "../src/server.ts";
+
+const start = (input: unknown) => ({ input, options: {}, embedded: true, startedBy: "owner-id", count: 1 });
+
+const note = (status: "active" | "installed" = "installed") => {
+  const calls: { name: string; input: unknown }[] = [];
+  const record = <T>(name: string, answer: T) => (input: unknown): T => { calls.push({ name, input }); return answer; };
+  const context = createTestContext<Record<string, never>>({ state: {}, functions: {
+    actor_program_ensure: record("actor_program_ensure", { actorId: "id-notebook", handle: "notebook", status }),
+    actor_input: record("actor_input", []),
+    canvas_layout_place: record("canvas_layout_place", { placed: status === "installed" }),
+  } });
+  return { calls, context };
+};
+
+test("sends the note to the shared notebook and reports it", async () => {
+  const { calls, context } = note();
+  await program.onStart!(start({ text: "  Ask about the budget  " }), context);
+  assert.deepEqual(calls.map((call) => [call.name, call.input]), [
+    ["actor_program_ensure", { name: "notebook" }],
+    ["actor_input", { actor: "@notebook", content: "Ask about the budget" }],
+    ["canvas_layout_place", { entity: "app:notebook/main" }],
+  ]);
+  assert.deepEqual(context.finished, [{ result: { note: "Ask about the budget", notebook: "installed" }, summary: "Noted: Ask about the budget" }]);
+});
+
+test("without a start value it notes when it started; an invalid value changes nothing", async () => {
+  const { calls, context } = note("active");
+  await program.onStart!(start(null), context);
+  assert.match(String((calls[1]!.input as { content: string }).content), /^Started at /);
+  const invalid = note();
+  await assert.rejects(async () => program.onStart!(start({ text: "" }), invalid.context), /start value/);
+  assert.deepEqual(invalid.calls, []);
+  assert.deepEqual(invalid.context.finished, []);
+});
+
+test("an ordinary message is refused", async () => {
+  const { context } = note();
+  await assert.rejects(async () => program.onInput!({ id: "input-1", content: "hello", artifactIds: [], sourceEventIds: [], subscriptionId: null, event: null }, context), /answers only starts/);
+});

package/plugins/ragents.reference/run-scripts/run-roster/RUN.md

@@ -0,0 +1,19 @@
+---
+title: Take stock of the run
+description: "A prepared check shows a run script that also joins a running run. It lists the other participants, notes them in the shared notebook, and reports them back as its result."
+order: 170
+coordinator: false
+embeddable: true
+shared-programs: notebook
+tags: Run scripts, Concept demo, TypeScript actors
+---
+
+The TypeScript program reads the participants with `actor_list` and ends each start with
+`context.finish`. The owner reads the summary in the chat; a coordinator that starts it through
+`run_script_start` receives summary and list as a message. Started inside a running run through the
+run menu, `ragents script`, or the coordinator, it changes neither the primary actor nor the tiles,
+and a repeated start reuses the same actor. Started as a new run, it is the run's only participant.
+
+It shares the notebook with the quick note script: `shared-programs: notebook` copies the plugin's
+shared package into the run, `actor_program_ensure` makes it active once, and
+`canvas_layout_place` puts its view next to what is arranged.

package/plugins/ragents.reference/run-scripts/run-roster/package.json

@@ -0,0 +1,9 @@
+{
+  "name": "run-roster",
+  "private": true,
+  "type": "module",
+  "ragents": {
+    "title": "Run roster",
+    "backend": "src/server.ts"
+  }
+}

package/plugins/ragents.reference/run-scripts/run-roster/src/server.ts

@@ -0,0 +1,26 @@
+import { defineActor } from "@ragents/server";
+import { Type } from "typebox";
+
+const contract = {
+  state: Type.Object({ reports: Type.Optional(Type.Number()) }, { additionalProperties: false }),
+  functions: {},
+  input: { capabilities: ["actor_list", "actor_program_ensure", "actor_input", "canvas_layout_place"] },
+} as const;
+
+export default defineActor(contract, {
+  functions: {},
+  onInput: () => {
+    throw new Error("The roster answers only starts; start it again from the run menu or with run_script_start.");
+  },
+  onStart: async (_start, context) => {
+    const actors = await context.functions.actor_list({});
+    const others = actors.filter((actor) => actor.kind !== "human" && actor.handle !== context.actor.handle);
+    const handles = others.map((actor) => `@${actor.handle}`);
+    const summary = handles.length === 0 ? "No other participants yet." : `${handles.length} participant${handles.length === 1 ? "" : "s"}: ${handles.join(", ")}.`;
+    const notebook = await context.functions.actor_program_ensure({ name: "notebook" });
+    await context.functions.actor_input({ actor: `@${notebook.handle}`, content: `Roster: ${summary}` });
+    await context.functions.canvas_layout_place({ entity: "app:notebook/main" });
+    context.state.replace({ reports: (context.state.read().reports ?? 0) + 1 });
+    context.finish({ actors: others.map(({ handle, kind, lifecycle }) => ({ handle, kind, lifecycle })) }, { summary });
+  },
+});

package/plugins/ragents.reference/run-scripts/run-roster/tests/program.test.ts

@@ -0,0 +1,47 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { createTestContext } from "@ragents/server/testing";
+import program from "../src/server.ts";
+
+const start = { input: null, options: {}, embedded: true, startedBy: "owner-id", count: 1 };
+const actor = (handle: string, kind: "human" | "agent" | "script", lifecycle = "idle") =>
+  ({ id: `id-${handle}`, handle, displayName: handle, kind, lifecycle, createdBy: null, description: null, toolCount: null });
+
+const roster = (actors: ReturnType<typeof actor>[], state: { reports?: number } = {}) => {
+  const calls: { name: string; input: unknown }[] = [];
+  const record = <T>(name: string, answer: T) => (input: unknown): T => { calls.push({ name, input }); return answer; };
+  const context = createTestContext<{ reports?: number }>({ state, functions: {
+    actor_list: record("actor_list", actors),
+    actor_program_ensure: record("actor_program_ensure", { actorId: "id-notebook", handle: "notebook", status: "active" as const }),
+    actor_input: record("actor_input", []),
+    canvas_layout_place: record("canvas_layout_place", { placed: true }),
+  } });
+  return { calls, context };
+};
+
+test("reports the other participants as result and summary and notes them in the shared notebook", async () => {
+  const { calls, context } = roster([actor("owner", "human"), actor("coordinator", "agent", "running"), actor("helper", "agent"), actor("test", "script")]);
+  await program.onStart!(start, context);
+  assert.deepEqual(context.finished, [{
+    result: { actors: [{ handle: "coordinator", kind: "agent", lifecycle: "running" }, { handle: "helper", kind: "agent", lifecycle: "idle" }] },
+    summary: "2 participants: @coordinator, @helper.",
+  }]);
+  assert.deepEqual(calls.slice(1).map((call) => [call.name, call.input]), [
+    ["actor_program_ensure", { name: "notebook" }],
+    ["actor_input", { actor: "@notebook", content: "Roster: 2 participants: @coordinator, @helper." }],
+    ["canvas_layout_place", { entity: "app:notebook/main" }],
+  ]);
+  assert.deepEqual(context.state.read(), { reports: 1 });
+});
+
+test("a run without other participants still gets a result, and every start counts", async () => {
+  const { context } = roster([actor("owner", "human"), actor("test", "script")], { reports: 2 });
+  await program.onStart!({ ...start, embedded: false, count: 3 }, context);
+  assert.deepEqual(context.finished, [{ result: { actors: [] }, summary: "No other participants yet." }]);
+  assert.deepEqual(context.state.read(), { reports: 3 });
+});
+
+test("an ordinary message is refused", async () => {
+  const { context } = roster([]);
+  await assert.rejects(async () => program.onInput!({ id: "input-1", content: "hello", artifactIds: [], sourceEventIds: [], subscriptionId: null, event: null }, context), /answers only starts/);
+});

package/scripts/agent/agent-cli.ts

@@ -47,6 +47,11 @@ export const usage = (): string => `Usage: ragents <command> [arguments]
   stop <run> --run [--profile <p>]
       Emergency stop: cancel all turns and stop all actors of the run
   stop --host [--profile <p>]     stop the remembered host
+  script <run> [--profile <p>] [--json]
+      List the run scripts of the profile and whether each can start in the running run.
+  script <run> <entry> [--input <json>] [--profile <p>] [--json]
+      Start the run script inside the run, as its owner; prints its actor and which start of it
+      this is. Only a script whose RUN.md sets embeddable: true joins a running run.
   plugin build <folder...> [--out <o>] [--watch] [--no-typecheck]
       Build plugin source folders into bundles; details with plugin --help.
 
@@ -67,12 +72,14 @@ export type AgentCommand =
   | { readonly kind: "journal"; readonly profile: string; readonly runId: string; readonly json: boolean; readonly tools: boolean }
   | { readonly kind: "stop"; readonly profile: string; readonly runId: string }
   | { readonly kind: "stop-run"; readonly profile: string; readonly runId: string }
-  | { readonly kind: "stop-host"; readonly profile: string };
+  | { readonly kind: "stop-host"; readonly profile: string }
+  | { readonly kind: "script"; readonly profile: string; readonly runId: string; readonly entry: string | undefined; readonly input: unknown; readonly json: boolean };
 
 interface Flags {
   readonly profile: string;
   readonly entry: string | undefined;
   readonly workstation: string | undefined;
+  readonly input: string | undefined;
   readonly json: boolean;
   readonly tools: boolean;
   readonly host: boolean;
@@ -80,7 +87,7 @@ interface Flags {
   readonly positional: readonly string[];
 }
 
-const VALUE_FLAGS = new Set(["--profile", "--entry", "--workstation"]);
+const VALUE_FLAGS = new Set(["--profile", "--entry", "--workstation", "--input"]);
 
 const scan = (argv: readonly string[], allowed: readonly string[]): Flags => {
   const positional: string[] = [];
@@ -106,6 +113,7 @@ const scan = (argv: readonly string[], allowed: readonly string[]): Flags => {
     profile: values.get("--profile") ?? defaultProfile(),
     entry: values.get("--entry"),
     workstation: values.get("--workstation"),
+    input: values.get("--input"),
     json: switches.has("--json"),
     tools: switches.has("--tools"),
     host: switches.has("--host"),
@@ -158,9 +166,26 @@ export const parseArguments = (argv: readonly string[]): AgentCommand => {
     if (!RUN_ID_PATTERN.test(runId)) throw new Error(`Invalid run id: ${runId}`);
     return { kind: flags.run ? "stop-run" : "stop", profile: flags.profile, runId };
   }
+  if (command === "script") {
+    const flags = scan(rest, ["--profile", "--input", "--json"]);
+    const [runId, entry, ...extra] = flags.positional;
+    if (!runId) throw new Error(`script needs <run>, optionally followed by <entry>.\n\n${usage()}`);
+    if (extra.length > 0) throw new Error(`script takes at most two values, not ${flags.positional.length}.`);
+    if (!RUN_ID_PATTERN.test(runId)) throw new Error(`Invalid run id: ${runId}`);
+    if (flags.input !== undefined && entry === undefined) throw new Error("--input needs <entry>, the run script it starts.");
+    return { kind: "script", profile: flags.profile, runId, entry, input: flags.input === undefined ? null : parsedInput(flags.input), json: flags.json };
+  }
   throw new Error(command ? `Unknown command: ${command}\n\n${usage()}` : usage());
 };
 
+const parsedInput = (text: string): unknown => {
+  try {
+    return JSON.parse(text);
+  } catch (error) {
+    throw new Error(`--input is not JSON: ${error instanceof Error ? error.message : String(error)}`);
+  }
+};
+
 export const loadProfile = (selection: string, root = hostRoot()): Promise<ProfileTarget> => selectProfileTarget(selection, root);
 
 const delay = (ms: number): Promise<void> => new Promise((resolve) => setTimeout(resolve, ms));
@@ -544,6 +569,24 @@ const stopCommand = async (command: Extract<AgentCommand, { kind: "stop" | "stop
   return 0;
 };
 
+const scriptCommand = async (command: Extract<AgentCommand, { kind: "script" }>, write: LineWriter): Promise<number> => {
+  const target = await loadProfile(command.profile);
+  const baseUrl = await addressOf(target);
+  if (!await healthy(baseUrl)) throw new Error(`No RAgents server responds at ${baseUrl}; start it with ragents run.`);
+  const rpc = client(baseUrl);
+  if (command.entry === undefined) {
+    const scripts = await withLoginHint(() => rpc.call(coreContracts.runs.scripts, { runId: command.runId }));
+    for (const script of scripts) {
+      write(command.json ? JSON.stringify(script) : `${script.id}  ${script.title}${script.available ? "" : ` (not available: ${script.reason ?? "no reason given"})`}`);
+    }
+    return 0;
+  }
+  const started = await withLoginHint(() => rpc.call(coreContracts.runs.startScript, { runId: command.runId, entry: command.entry!, input: command.input }));
+  write(command.json ? JSON.stringify(started) : `script: @${started.handle}, start ${started.count}`);
+  write(`run: ${command.runId}`);
+  return 0;
+};
+
 const alive = (pid: number): boolean => {
   try {
     process.kill(pid, 0);
@@ -596,6 +639,7 @@ export const execute = async (command: AgentCommand, write: LineWriter = toStdou
   if (command.kind === "send") return sendCommand(command, write);
   if (command.kind === "journal") return journalCommand(command, write);
   if (command.kind === "stop" || command.kind === "stop-run") return stopCommand(command);
+  if (command.kind === "script") return scriptCommand(command, write);
   return stopHostCommand(command);
 };
 

package/scripts/package/ragents.mjs

@@ -17,6 +17,7 @@ export const commands = {
   send: AGENT_CLI,
   journal: AGENT_CLI,
   stop: AGENT_CLI,
+  script: AGENT_CLI,
 };
 
 const usage = `Usage: ragents <command> [arguments]
@@ -25,6 +26,7 @@ const usage = `Usage: ragents <command> [arguments]
   send <run> "<text>"              follow-up task in the same run
   journal <run> [--tools]          read the history of a run
   stop <run> | stop --host         cancel the running turn or stop the remembered host
+  script <run> [<entry>]           list the run scripts or start one inside the run (--input <json>)
   connect <server-url>             fetch the client profile with its bundles and start the local server with it
   start <profile|path>             start a profile of the package, an own profile file or a
                                    fetched revision; the UI comes prebuilt
@@ -33,7 +35,7 @@ const usage = `Usage: ragents <command> [arguments]
   plugin build <folder...>         build plugin source folders into bundles (--out, --watch)
   --help, help                     this usage
 
-run, send, journal and stop take another profile with --profile <profile|path>: a name
+run, send, journal, stop and script take another profile with --profile <profile|path>: a name
 next to the host or the path to an own ragents.config.<profile>.ts. RAGENTS_PROFILE sets
 the same for all commands of a shell; if the profile requires sign-in, the user's
 personal token goes into RAGENTS_TOKEN.