@schlenkr/ragents 0.1.14 → 0.1.15

package/bundles/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/bundles/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/bundles/ragents.reference/ragents-bundle.json

@@ -20,8 +20,8 @@
       ]
     }
   },
-  "revision": "809c8770905fa2a4d557425abf27aee27a863aec8a80655b96e40bd82307f493",
-  "sourceRevision": "abe068f9695702223dd49b2169ecca54e5a82fd4b37d02346d0c9df3582cff87",
+  "revision": "2c684e9daab9b2ffe4c002c03d4fa8549b2d4dd0b20513fb5eec0e4f10a396ee",
+  "sourceRevision": "0f2f0bb43908bed73e743ed21d07d35abed4bcc84563c893c5c32117ad559ade",
   "server": "server/index.js",
   "web": {
     "entry": "web/index.js",
@@ -34,6 +34,7 @@
   "uses": [],
   "assets": [
     "skills",
-    "run-scripts"
+    "run-scripts",
+    "actors"
   ]
 }

package/bundles/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/bundles/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/bundles/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/bundles/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/bundles/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/bundles/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/bundles/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/bundles/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/bundles/ragents.todo/ragents-bundle.json

@@ -33,7 +33,7 @@
     }
   },
   "revision": "5e18b249f3c8b53b61820ef05da59823d58163c6962e6d836dcb37c05034aad0",
-  "sourceRevision": "cdb1c230450ed69e96cebcee9da392c02edb499417fc7e2de657b2f89c36c379",
+  "sourceRevision": "e69f899d1733ba54341bfc2fd8c6adbf6025126a4b21a74bdd8206378e86b87e",
   "server": "server/index.js",
   "web": {
     "entry": "web/index.js",

package/bundles/ragents.transcript/ragents-bundle.json

@@ -23,7 +23,7 @@
     "web": {}
   },
   "revision": "e3bb513053f6385f9d78d314d28302324095a5163c4e1563df6fc8b3251305f7",
-  "sourceRevision": "ba610549f1f1b3e87940617518d45b4bc918362fb9c20283b2a5061877bed103",
+  "sourceRevision": "7df3be99d8024c7878a0afe2bcd698909b6389f4484d98f84a0e3bdead954ab4",
   "server": "server/index.js",
   "exports": {
     "server": {},

package/bundles/ragents.watch/ragents-bundle.json

@@ -25,7 +25,7 @@
     "web": {}
   },
   "revision": "007ee50ab186e3070930f23e9795210fa36c723365657325d5440cc2f0b81d60",
-  "sourceRevision": "ebb0ba3e7ca11870abab5787c259c3d2ad3b36247caeb4b4efd9bcceebbb7047",
+  "sourceRevision": "1ce434ee7a1752f72e3d7160d895130948b8bcd5bba466f5555fff6ff278cd19",
   "server": "server/index.js",
   "exports": {
     "server": {

package/bundles/ragents.workspace/ragents-bundle.json

@@ -137,7 +137,7 @@
     }
   },
   "revision": "db9370b7b3449c44be49986b074806351b857c430963aa878e209d2d5c9ba4f8",
-  "sourceRevision": "b86182fd6493e5628df38ed1669e857bd16742645380f76bacd7514446be3514",
+  "sourceRevision": "f91d81de973c9c7b46f1882a8cb4f067fbdf72c2e7617f24f8865f92d9ed05bc",
   "server": "server/index.js",
   "web": {
     "entry": "web/index.js",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@schlenkr/ragents",
-  "version": "0.1.14",
+  "version": "0.1.15",
   "description": "RAgents host: server, engine, plugins and tools without a source checkout",
   "keywords": [
     "agents",
@@ -55,7 +55,7 @@
     "lucide-react": "1.46.0",
     "partial-json": "0.1.7",
     "playwright-core": "1.61.1",
-    "quassel": "0.4.0",
+    "quassel": "0.4.2",
     "react": "19.2.8",
     "react-diff-view": "3.3.3",
     "react-dom": "19.2.8",
@@ -70,6 +70,6 @@
     "yaml": "2.9.0"
   },
   "ragents": {
-    "hostVersion": "7b70e01ffa7c5e09ad393aa630cedb17fb4c2472"
+    "hostVersion": "9d43afb1f899a9b2bf01b46d9173d1ea901c9088"
   }
 }

package/packages/ragents/src/domain/vocabulary.ts

@@ -8,10 +8,14 @@ export const capabilityNames = [
     "workspace.use",
     "execution.stopOwned",
     "run.configure",
+    "script.start",
 ] as const;
 
 export type CapabilityName = (typeof capabilityNames)[number];
 
+/** Whoever gets one of these from the owner holds it without passing it on, so it never reaches the agents they spawn. */
+export const firstHandCapabilities: readonly CapabilityName[] = ["script.start"];
+
 export const isCapabilityName = (value: unknown): value is CapabilityName =>
     typeof value === "string" && (capabilityNames as readonly string[]).includes(value);
 

package/packages/ragents/src/index.ts

@@ -32,6 +32,7 @@ export {
     SessionMetadataContributionRegistry,
     SkillContributionRegistry,
     StartEntryContributionRegistry,
+    ActorPackageContributionRegistry,
     StartOptionContributionRegistry,
     StorageRegistry,
     ToolContributionRegistry,
@@ -123,10 +124,11 @@ export {
 } from "./drivers/types.ts";
 export * from "./domain/model.ts";
 export { isPortableId, isRunId } from "./domain/portable-id.ts";
-export { capabilityNames, isCapabilityName, type CapabilityName } from "./domain/vocabulary.ts";
+export { capabilityNames, firstHandCapabilities, isCapabilityName, type CapabilityName } from "./domain/vocabulary.ts";
 export { DirectoryArtifactContents, MemoryArtifactContents, type ArtifactContents } from "./runtime/artifacts.ts";
 export type { CommandContext } from "./runtime/command.ts";
 export { DomainError } from "./runtime/domain-error.ts";
+export { inheritedGrants } from "./runtime/guards.ts";
 export { throwFailures, throwRejected } from "./runtime/failures.ts";
 export type { JournalEvent } from "./domain/events.ts";
 export { Journal, journalFormatVersion, type CommandRecord, type JournalLoadFailure } from "./runtime/journal.ts";

package/packages/ragents/src/plugin-host.ts

@@ -52,6 +52,8 @@ import type {
   SkillContribution,
   RunScriptPackage,
   StartEntryContribution,
+  ActorPackageContribution,
+  ActorProgramFile,
   StartOptionContext,
   StartOptionContribution,
   ScriptContribution,
@@ -442,6 +444,7 @@ export class SkillContributionRegistry {
 const SKILL_NAME = /^[a-z0-9][a-z0-9-]*$/;
 const GUIDE_ID = /^[a-z0-9][a-z0-9.-]*$/;
 const SCRIPT_HANDLE = /^[a-z0-9][a-z0-9-]*$/;
+const ACTOR_PACKAGE_NAME = /^[a-z][a-z0-9-]{0,63}$/;
 
 const requireText = (entry: { id: unknown }, value: unknown, field: string): void => {
   if (typeof value !== "string" || !value.trim()) {
@@ -456,33 +459,38 @@ const assertKnownFields = (entry: { id: unknown }, value: object, fields: readon
   }
 };
 
-const validateProgramFiles = (entry: StartEntryContribution, files: unknown): void => {
+const validateProgramFiles = (owner: string, files: unknown): void => {
   if (!Array.isArray(files) || files.length === 0)
-    throw new Error(`Run script ${entry.id}: files needs package files`);
+    throw new Error(`${owner}: files needs package files`);
   const names = new Set<string>();
   for (const file of files) {
     if (typeof file !== "object" || file === null || typeof file.path !== "string" || typeof file.content !== "string")
-      throw new Error(`Run script ${entry.id}: every file needs path and content`);
-    assertKnownFields(entry, file, ["path", "content"], "Package file");
+      throw new Error(`${owner}: every file needs path and content`);
+    assertKnownFields({ id: owner }, file, ["path", "content"], "Package file of");
     if (!file.path || file.path.includes("\\") || file.path.includes("\0") || path.posix.isAbsolute(file.path)
       || file.path.split("/").some((part: string) => !part || part === "." || part === ".."))
-      throw new Error(`Run script ${entry.id}: invalid package path ${file.path}`);
-    if (names.has(file.path)) throw new Error(`Run script ${entry.id}: file ${file.path} is duplicated`);
+      throw new Error(`${owner}: invalid package path ${file.path}`);
+    if (names.has(file.path)) throw new Error(`${owner}: file ${file.path} is duplicated`);
     names.add(file.path);
   }
-  if (!names.has("package.json")) throw new Error(`Run script ${entry.id}: package.json is missing`);
+  if (!names.has("package.json")) throw new Error(`${owner}: package.json is missing`);
 };
 
 const validateScriptPackage = (entry: StartEntryContribution, script: unknown): void => {
   if (typeof script !== "object" || script === null)
     throw new Error(`Template ${entry.id} has no run script package`);
-  assertKnownFields(entry, script, ["handle", "coordinator", "files", "programs"], "Run script");
+  assertKnownFields(entry, script, ["handle", "coordinator", "embeddable", "sharedPrograms", "files", "programs"], "Run script");
   const value = script as Record<string, unknown>;
   if (typeof value.handle !== "string" || !SCRIPT_HANDLE.test(value.handle))
     throw new Error(`Run script ${entry.id}: handle must be a handle like roundtable (lowercase letters, digits, hyphen)`);
   if (typeof value.coordinator !== "boolean")
     throw new Error(`Run script ${entry.id}: coordinator must be true or false`);
-  validateProgramFiles(entry, value.files);
+  if (value.embeddable !== undefined && typeof value.embeddable !== "boolean")
+    throw new Error(`Run script ${entry.id}: embeddable must be true or false`);
+  const shared = value.sharedPrograms;
+  if (shared !== undefined && (!Array.isArray(shared) || shared.some((name) => typeof name !== "string" || !ACTOR_PACKAGE_NAME.test(name)) || new Set(shared).size !== shared.length))
+    throw new Error(`Run script ${entry.id}: sharedPrograms must name each shared actor package once`);
+  validateProgramFiles(`Run script ${entry.id}`, value.files);
   if (!Array.isArray(value.programs)) throw new Error(`Run script ${entry.id}: programs must be a list`);
   const names = new Set<string>();
   for (const program of value.programs) {
@@ -492,7 +500,7 @@ const validateScriptPackage = (entry: StartEntryContribution, script: unknown):
     if (program.name === value.handle || names.has(program.name))
       throw new Error(`Run script ${entry.id}: program ${program.name} is duplicated`);
     names.add(program.name);
-    validateProgramFiles(entry, program.files);
+    validateProgramFiles(`Run script ${entry.id}`, program.files);
   }
 };
 
@@ -555,6 +563,29 @@ const skillNameOf = (directory: string): string => directory.split(/[\\/]/).filt
 const byOrderThenId = (left: { order?: number; id: string }, right: { order?: number; id: string }): number =>
   (left.order ?? 0) - (right.order ?? 0) || left.id.localeCompare(right.id);
 
+/** Actor packages a plugin shares with the run scripts of the profile; one name, one package. */
+export class ActorPackageContributionRegistry {
+  readonly #packages = new ContributionRegistry<ActorPackageContribution & { id: string }>("Shared actor package");
+
+  register(owner: string, packages: readonly ActorPackageContribution[]): void {
+    for (const entry of packages) {
+      if (typeof entry.name !== "string" || !ACTOR_PACKAGE_NAME.test(entry.name))
+        throw new Error(`Shared actor package ${String(entry.name)} of ${owner}: the name must be a package name like notes (lowercase letters, digits, hyphen)`);
+      validateProgramFiles(`Shared actor package ${entry.name}`, entry.files);
+    }
+    this.#packages.register(owner, packages.map((entry) => ({ id: entry.name, name: entry.name, files: entry.files })));
+  }
+
+  get(name: string): { pluginId: string; files: readonly ActorProgramFile[] } | undefined {
+    const found = this.#packages.entries().find(({ value }) => value.name === name);
+    return found ? { pluginId: found.owner, files: found.value.files } : undefined;
+  }
+
+  names(): readonly string[] {
+    return this.#packages.entries().map(({ value }) => value.name);
+  }
+}
+
 /** Skills with a start prompt and executable run scripts share one registry. */
 export class StartEntryContributionRegistry {
   readonly #entries = new ContributionRegistry<StartEntryContribution>("Template");
@@ -614,6 +645,24 @@ export class StartEntryContributionRegistry {
     return this.describe().find((candidate) => candidate.id === entryId);
   }
 
+  /** Names share one namespace per run: a shared package is neither a script's handle nor its bundled program, and every name a script needs exists. */
+  assertSharedPrograms(packages: ActorPackageContributionRegistry): void {
+    for (const { value } of this.#entries.entries()) {
+      if (value.action !== "script") continue;
+      const script = value.script;
+      const clash = [script.handle, ...script.programs.map((program) => program.name)].find((name) => packages.get(name));
+      if (clash !== undefined) {
+        throw new Error(`Run script ${value.id} uses the name ${clash}, which is also the shared actor package of ${packages.get(clash)!.pluginId}; `
+          + "run script handles, their bundled programs and shared packages share one namespace per run");
+      }
+      const missing = (script.sharedPrograms ?? []).filter((name) => !packages.get(name));
+      if (missing.length > 0) {
+        throw new Error(`Run script ${value.id} needs the shared actor packages ${missing.join(", ")}, which no plugin of this profile provides`
+          + (packages.names().length > 0 ? `; shared are ${packages.names().join(", ")}` : ""));
+      }
+    }
+  }
+
   /** The run script behind a script template; undefined for unknown ids and templates of another action. */
   scriptPackage(entryId: string): (RunScriptPackage & { entry: PublicStartEntry }) | undefined {
     const found = this.#entries.entries().find(({ value }) => value.id === entryId);
@@ -1164,6 +1213,7 @@ export class PluginHost {
   readonly prompts = new PromptContributionRegistry(this.runConditions);
   readonly skills = new SkillContributionRegistry(this.runConditions);
   readonly startEntries = new StartEntryContributionRegistry();
+  readonly actorPackages = new ActorPackageContributionRegistry();
   readonly profiles = new ProfileContributionRegistry();
   readonly script = new ScriptContributionRegistry();
   readonly lifecycle = new LifecycleContributionRegistry();
@@ -1220,6 +1270,7 @@ export class PluginHost {
       sessionMetadata: (...entries) => this.sessionMetadata.register(manifest.id, entries),
       skills: (...entries) => this.skills.register(manifest.id, entries),
       startEntries: (...entries) => this.startEntries.register(manifest.id, entries),
+      actorPackages: (...entries) => this.actorPackages.register(manifest.id, entries),
       startOptions: (...entries) => this.startOptions.register(manifest.id, entries),
       accessProjections: (...entries) => this.accessProjections.register(manifest.id, entries),
       functions: (...entries) => this.tools.registerFunctions(manifest.id, entries),
@@ -1240,6 +1291,7 @@ export class PluginHost {
       }
     }
     this.startEntries.assertFixedStartOptionsKnown(this.startOptions);
+    this.startEntries.assertSharedPrograms(this.actorPackages);
     const defaultStartEntry = this.#defaultStartEntry;
     if (defaultStartEntry !== undefined) {
       const entries = this.startEntries.describe().map((entry) => entry.id);

package/packages/ragents/src/plugin-types.ts

@@ -242,10 +242,20 @@ export interface BundledActorProgram {
 export interface RunScriptPackage {
   handle: string;
   coordinator: boolean;
+  /** Whether the script may also start inside a run that is already running; without it, only a new run. */
+  embeddable?: boolean;
+  /** Shared actor packages of the profile that the host copies into the run before the setup, by name. */
+  sharedPrograms?: readonly string[];
   files: readonly ActorProgramFile[];
   programs: readonly BundledActorProgram[];
 }
 
+/** An actor package that a plugin shares with the run scripts of the profile; its name is the package name in every run. */
+export interface ActorPackageContribution {
+  name: string;
+  files: readonly ActorProgramFile[];
+}
+
 export type StartEntryContribution = StartEntryBase & (
   | { action: "skill"; skill: string; category: string; prompt: string }
   /** A run script may name a category of its own; without one the start pages group it as a run script. */
@@ -448,6 +458,7 @@ export interface PluginRegistration {
   sessionMetadata: (...contributions: readonly SessionMetadataContribution[]) => void;
   skills: (...contributions: readonly SkillContribution[]) => void;
   startEntries: (...contributions: readonly StartEntryContribution[]) => void;
+  actorPackages: (...contributions: readonly ActorPackageContribution[]) => void;
   startOptions: (...contributions: readonly StartOptionContribution[]) => void;
   /** How accesses without runs.inspect see the states of this plugin and their chat events, per state id. */
   accessProjections: (...contributions: readonly AccessProjectionContribution[]) => void;

package/packages/ragents/src/runtime/guards.ts

@@ -11,6 +11,7 @@ import type {
     Turn,
 } from "../domain/model.ts";
 import { actorByReference, handleKey } from "../domain/actor-reference.ts";
+import { firstHandCapabilities } from "../domain/vocabulary.ts";
 import { DomainError } from "./domain-error.ts";
 
 export const clean = (value: string, name: string) => {
@@ -167,7 +168,7 @@ export const inheritedGrants = (
             scope: grant.scope.kind === "run"
                 ? { kind: "run" as const }
                 : { kind: "workspace" as const, path: grant.scope.path },
-            delegable: true,
+            delegable: !firstHandCapabilities.includes(grant.capability),
         }));
 };
 

package/packages/ragents/src/typescript/async-compiler.ts

@@ -51,9 +51,19 @@ const pool: PooledWorker[] = [];
 const workerWaiters: WorkerWaiter[] = [];
 let nextRequestId = 0;
 
+const LOADER_FLAGS = ["--import", "--loader", "--experimental-loader", "--require", "-r"] as const;
+
+/** Only the loader flags of the host (such as --import tsx); Node strips no types under node_modules, and debugger or memory flags stay behind. */
+const loaderArguments = (execArgv: readonly string[]): readonly string[] =>
+    execArgv.flatMap((argument, index) => {
+        if (LOADER_FLAGS.some((flag) => argument.startsWith(`${flag}=`))) return [argument];
+        if (LOADER_FLAGS.some((flag) => argument === flag) && index + 1 < execArgv.length) return [argument, execArgv[index + 1]!];
+        return [];
+    });
+
 const spawnWorker = (): PooledWorker => {
     const worker = new Worker(new URL("./compiler-worker.ts", import.meta.url), {
-        execArgv: [],
+        execArgv: [...loaderArguments(process.execArgv)],
         name: "ragents-typescript-compiler",
         resourceLimits: COMPILER_RESOURCE_LIMITS,
     });

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

@@ -3,6 +3,7 @@ import type { PluginHost, RAgentsPlugin } from "@ragents/engine";
 import type { PluginModule } from "@ragents/host/plugin-support/plugin-module.js";
 import { runtimeProviderToken, runGuardToken } from "@ragents/host/ragents/host-services.js";
 import { askServiceToken } from "@ragents/plugins/ragents.ask/server/contract.js";
+import { surfacePlacementToken } from "@ragents/plugins/ragents.orchestration/server/contract.js";
 import { agentToolsFrom } from "./agent-tools.js";
 import { createActorProgramMethods } from "./methods.js";
 import { createMiniAppFrameRoutes, miniAppsApiPrefix } from "./routes.js";
@@ -26,6 +27,8 @@ const actorProgramsPlugin = (pluginHost: PluginHost): RAgentsPlugin => ({
                 const script = pluginHost.startEntries.scriptPackage(entryId);
                 return !script ? undefined : script.handle === name ? script.files : script.programs.find((program) => program.name === name)?.files;
             },
+            sharedPackage: (name) => pluginHost.actorPackages.get(name),
+            placeView: (context, runId, entity) => { host.service(surfacePlacementToken).place(context, runId, { entity }); },
         });
         host.provide(actorProgramsToken, runtime);
         const diagnostics = createProjectDiagnostics({