@schlenkr/ragents 0.1.13 → 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.documents/web/DocumentViewer.tsx

@@ -92,7 +92,7 @@ const formatTime = (iso: string) => {
   const date = new Date(iso);
   return Number.isNaN(date.getTime())
     ? iso
-    : date.toLocaleString("en-US", { day: "2-digit", month: "2-digit", hour: "2-digit", minute: "2-digit" });
+    : date.toLocaleString(undefined, { day: "2-digit", month: "2-digit", hour: "2-digit", minute: "2-digit" });
 };
 
 export const documentMessagesFrom = (
@@ -182,7 +182,7 @@ export function DocumentToolCall({ active, document, onOpen, status }: DocumentT
         <span className="text-[0.62rem] font-semibold tracking-[0.05em] text-primary uppercase">Document</span>
         <strong className="truncate text-[0.84rem] leading-[1.35]" title={document.title}>{document.title}</strong>
         <span className="text-[0.7rem] leading-[1.35] text-muted-foreground">
-          {formatLabels[document.format]}, {lineCount.toLocaleString("en-US")} {lineCount === 1 ? "line" : "lines"}
+          {formatLabels[document.format]}, {lineCount.toLocaleString()} {lineCount === 1 ? "line" : "lines"}
         </span>
       </span>
       <span className="flex items-center gap-1 text-[0.7rem] font-semibold text-primary group-data-[status=error]/call:text-destructive">

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.orchestration/web/ExecutionsPanel.tsx

@@ -91,7 +91,7 @@ function ExecutionEntry({ execution, now }: { execution: TypeScriptExecution; no
       <span className="truncate font-[650]" title={`${execution.actorName} (${execution.actorId})`}>@{execution.actorHandle}</span>
       <Badge className={`h-auto rounded-[5px] px-[5px] py-0.5 text-[0.64rem] ${statusBadgeClass[execution.status] ?? "bg-secondary text-muted-foreground"}`}>{executionStatusLabel(execution.status)}</Badge>
       <span className="col-span-full truncate font-mono text-[0.68rem]" title={preview}>{preview}</span>
-      <span className="col-span-full flex flex-wrap justify-between gap-x-3 gap-y-1.5 text-[0.65rem] tabular-nums text-muted-foreground"><time dateTime={execution.startedAt} title={new Date(execution.startedAt).toLocaleString("en-US")}>{new Date(execution.startedAt).toLocaleString("en-US", { day: "2-digit", month: "2-digit", hour: "2-digit", minute: "2-digit", second: "2-digit" })}</time><span>{executionDuration(execution, now)}</span></span>
+      <span className="col-span-full flex flex-wrap justify-between gap-x-3 gap-y-1.5 text-[0.65rem] tabular-nums text-muted-foreground"><time dateTime={execution.startedAt} title={new Date(execution.startedAt).toLocaleString()}>{new Date(execution.startedAt).toLocaleString(undefined, { day: "2-digit", month: "2-digit", hour: "2-digit", minute: "2-digit", second: "2-digit" })}</time><span>{executionDuration(execution, now)}</span></span>
     </summary>
     {expanded && <div className={contentClass}>
       {execution.path && <p className="mt-2.5 grid gap-1 text-[0.68rem] text-muted-foreground"><span>Path</span><code className="[overflow-wrap:anywhere]">{execution.path}</code></p>}

package/plugins/ragents.orchestration/web/FlowInspector.tsx

@@ -128,7 +128,7 @@ const runCostUsd = (view: RunView): number | undefined => {
 };
 
 const formatCostUsd = (value: number) =>
-  `${value.toLocaleString("en-US", { minimumFractionDigits: 2, maximumFractionDigits: value > 0 && value < 0.005 ? 4 : 2 })} USD`;
+  `${value.toLocaleString(undefined, { minimumFractionDigits: 2, maximumFractionDigits: value > 0 && value < 0.005 ? 4 : 2 })} USD`;
 
 interface RunIndex {
   view: RunView;

package/plugins/ragents.orchestration/web/JournalStatus.tsx

@@ -80,7 +80,7 @@ function JournalEntry({ actor, event }: { actor: string | undefined; event: Jour
       <span className="text-muted-foreground tabular-nums">{event.sequence}</span>
       <span className="font-mono [overflow-wrap:anywhere]">{event.type}</span>
       <span className="truncate max-[550px]:col-start-2 max-[550px]:row-start-2" title={event.actorId}>{actor ? `@${actor}` : event.actorId}</span>
-      <time className="text-muted-foreground tabular-nums max-[550px]:col-start-3 max-[550px]:row-start-1" dateTime={event.occurredAt}>{new Date(event.occurredAt).toLocaleTimeString("en-US")}</time>
+      <time className="text-muted-foreground tabular-nums max-[550px]:col-start-3 max-[550px]:row-start-1" dateTime={event.occurredAt}>{new Date(event.occurredAt).toLocaleTimeString()}</time>
     </summary>
     {expanded && <SourceCode className="m-0 mb-2 text-[0.68rem]" content={JSON.stringify(event, null, 2)} language="json" path="event.json" />}
   </details>;

package/plugins/ragents.orchestration/web/format.ts

@@ -1,4 +1,4 @@
 export const formatTime = (iso: string) => {
   const date = new Date(iso);
-  return Number.isNaN(date.getTime()) ? iso : date.toLocaleString("en-US");
+  return Number.isNaN(date.getTime()) ? iso : date.toLocaleString();
 };

package/plugins/ragents.overseer/web/index.tsx

@@ -3,7 +3,7 @@ import { Button, Dialog, DialogContent, DialogDescription, DialogFooter, DialogH
 import { RunModalContext } from "@ragents/web/ui/dialog";
 import { XIcon } from "lucide-react";
 import { useCallback, useEffect, useMemo, useRef, useState } from "react";
-import { ChatMessages, ChatInputToolbar, type ChatInputHandle, type ChatEvent } from "quassel";
+import { ChatMessages, ChatInputToolbar, ChatPanel, type ChatInputHandle, type ChatEvent } from "quassel";
 import { useChat } from "@ragents/web/chat/useChat";
 import { useAttachmentCapabilities } from "@ragents/web/chat/useAttachmentCapabilities";
 import { ChatStepsProvider, type OverviewPanelContext, type WebPlugin } from "@ragents/web/PluginRegistry";
@@ -30,7 +30,7 @@ const interruptCoordinator = async (runId: string) => {
 const errorClass = "mx-4 my-2 flex-none text-[0.8rem] text-destructive";
 
 /** Every user has their own coordinator; only the server knows its id. */
-function OverseerToolbar(context: OverviewPanelContext) {
+function useCoordinator() {
   const user = useAccess().user?.id;
   const [coordinator, setCoordinator] = useState<{ runId?: string; error?: string }>({});
   useEffect(() => {
@@ -42,6 +42,11 @@ function OverseerToolbar(context: OverviewPanelContext) {
     );
     return () => { current = false; };
   }, [user]);
+  return coordinator;
+}
+
+function OverseerToolbar(context: OverviewPanelContext) {
+  const coordinator = useCoordinator();
   if (!coordinator.runId) {
     return <div className={toolbarClass} data-slot="overseer-toolbar" role="status">
       {coordinator.error && <span className="text-[0.7rem] font-bold text-destructive" title={coordinator.error} aria-label={coordinator.error}>!</span>}
@@ -226,8 +231,51 @@ function OverseerConversation({ open, onOpen, onClose, onBusy, userLocation, run
   </div>;
 }
 
+/** The coordinator's chat fills the main area while no run is open. */
+function OverseerIdleView({ userLocation }: OverviewPanelContext) {
+  const coordinator = useCoordinator();
+  if (!coordinator.runId) {
+    return <p className={coordinator.error ? "m-auto p-6 text-center text-destructive" : "m-auto p-6 text-center text-muted-foreground"} role="status">
+      {coordinator.error ?? "Connecting to the global coordinator ..."}
+    </p>;
+  }
+  return <ChatStepsProvider policy={overseerChatDisplayPolicy} storageKeyPrefix={overseerChatStorageKeyPrefix}>
+    <OverseerIdleChat key={coordinator.runId} runId={coordinator.runId} userLocation={userLocation} />
+  </ChatStepsProvider>;
+}
+
+function OverseerIdleChat({ runId, userLocation }: { runId: string; userLocation: OverviewPanelContext["userLocation"] }) {
+  const writable = useAccess().can("ragents.overseer.write");
+  const chat = useChat(runId);
+  const chatView = useChatViewSettings(runId, "primary", "coordinator");
+  const modelState = useModelSettings();
+  const attachments = useAttachmentCapabilities(runId, "primary", JSON.stringify(modelState.settings && [modelState.settings.provider, modelState.settings.model]));
+  const messages = useMemo(() => withToolSummaries(chat.messages), [chat.messages]);
+  const [error, setError] = useState<string>();
+  const problem = error ?? (chat.connected ? undefined : "No connection. Your draft is kept; sending is disabled.");
+  return <ChatPanel className="flex h-full min-h-0 w-full min-w-0 flex-1 flex-col overflow-hidden" maxWidth="880px"
+    composer={<div className="[--qsl-input-card-radius:var(--radius-lg)]">
+      {problem && <p className="text-[0.8rem] text-destructive" role="alert">{problem}</p>}
+      <ChatInputToolbar {...attachments} disabled={!writable} sendDisabled={!chat.connected || modelState.status === "saving"} maxRows={6} rows={1}
+        onErrorChange={setError} onSend={(text, attachments) => chat.send(text, attachments, userLocation)}
+        onStop={writable && chat.running ? () => { setError(undefined); void interruptCoordinator(runId).catch((cause: unknown) => setError(cause instanceof Error ? cause.message : String(cause))); } : undefined}
+        running={chat.running}
+        texts={{ placeholder: writable ? "Ask the global coordinator" : "Read access to the global coordinator", steeringPlaceholder: "Ask the global coordinator" }}
+        toolbarLeft={<ChatViewSwitches settings={chatView} />}
+      />
+    </div>}>
+    <ChatMessages detailMode={chatView.detailMode}
+      emptyState={<div className="m-auto max-w-[480px] p-8 text-center text-[0.9rem] leading-[1.6] text-muted-foreground max-md:p-5"><strong className="text-foreground">Global coordinator</strong><p>No run is open. Ask about your runs or give a task; open or start a run through the overview at the top left.</p></div>}
+      messages={messages} running={chat.running} showTimestamps={chatView.showTimestamps} stepsExpandable={chatView.stepsExpandable}
+    />
+  </ChatPanel>;
+}
+
 export const webPlugin: WebPlugin = {
   id: OVERSEER_PLUGIN_ID,
   settings: [{ category: "models", order: 10, readRight: "ragents.overseer.read", id: `${OVERSEER_PLUGIN_ID}.model`, label: "Global coordinator", Settings: ModelSettings }],
-  overviewPanels: [{ id: `${OVERSEER_PLUGIN_ID}.chat`, placement: "toolbar", order: 100, readRight: "ragents.overseer.read", Panel: OverseerToolbar }],
+  overviewPanels: [
+    { id: `${OVERSEER_PLUGIN_ID}.chat`, placement: "toolbar", order: 100, readRight: "ragents.overseer.read", Panel: OverseerToolbar },
+    { id: `${OVERSEER_PLUGIN_ID}.idle`, placement: "idle", order: 100, readRight: "ragents.overseer.read", Panel: OverseerIdleView },
+  ],
 };

package/plugins/ragents.processes/web/processes.ts

@@ -54,7 +54,7 @@ const originText = (origin: RunProcess["origin"]): string =>
 
 const timeText = (iso: string): string => {
   const parsed = new Date(iso);
-  return Number.isNaN(parsed.getTime()) ? iso : parsed.toLocaleTimeString("en-US");
+  return Number.isNaN(parsed.getTime()) ? iso : parsed.toLocaleTimeString();
 };
 
 export const titleOf = (process: RunProcess): string => {

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 });
+  },
+});