@schlenkr/ragents 0.1.13 → 0.1.15

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@schlenkr/ragents",
-  "version": "0.1.13",
+  "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": "2fe07b19a1aa4533d20428b040e88960fedc44cb"
+    "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({