@schlenkr/ragents 0.1.14 → 0.1.16

package/apps/server/package.json

@@ -19,7 +19,7 @@
     "@ragents/engine": "workspace:*",
     "@ragents/workspace-executor": "workspace:*",
     "handlebars": "^4.7.9",
-    "quassel": "^0.4.0",
+    "quassel": "^0.4.2",
     "tsx": "^4.20.0",
     "typebox": "^1.3.13",
     "vscode-jsonrpc": "^9.0.2"

package/apps/server/src/api/contracts.ts

@@ -44,6 +44,24 @@ export const coreContracts = {
       input: Type.Object({ runId }, { additionalProperties: false }),
       result: Type.Null(),
     }),
+    scripts: defineOperation({
+      id: "ragents.runs.scripts",
+      description: "The run scripts the caller may start, and for a running run whether each can start there now: available, otherwise reason (not embeddable, a fixed start option differs from the run's). Rights: runs.read, runs.write.",
+      input: Type.Object({ runId }, { additionalProperties: false }),
+      result: Type.Array(Type.Object({
+        id: Type.String(),
+        title: Type.String(),
+        description: Type.String(),
+        available: Type.Boolean(),
+        reason: Type.Optional(Type.String()),
+      }, { additionalProperties: false })),
+    }),
+    startScript: defineOperation({
+      id: "ragents.runs.startScript",
+      description: "Start a run script and wait until its actor has the start input; errors come back to the caller instead of the chat. A new run starts as with ragents.chat.start. In a running run only a script whose RUN.md sets embeddable: true starts, its fixed start options must match the run's, and the primary actor stays; a repeated start reuses the script's actor. Result: the script actor and which start of its package in the run this was. Rights: runs.read, runs.write and the template's release.",
+      input: Type.Object({ runId, entry: Type.String({ minLength: 1 }), input: Type.Optional(Type.Any()) }, { additionalProperties: false }),
+      result: Type.Object({ actorId: Type.String(), handle: Type.String(), count: Type.Integer({ minimum: 1 }) }, { additionalProperties: false }),
+    }),
   },
   chat: {
     send: defineOperation({
@@ -66,7 +84,7 @@ export const coreContracts = {
     }),
     start: defineOperation({
       id: "ragents.chat.start",
-      description: "Start a run through a script template, without a message; the start options the template fixes apply. Rights: runs.read, runs.write and the template's release.",
+      description: "Start a run through a script template, without a message; the start options the template fixes apply. Returns once the start is accepted; progress and errors appear in the chat. In a running run it starts an embeddable script like ragents.runs.startScript. Rights: runs.read, runs.write and the template's release.",
       input: Type.Object({ runId, entry: Type.String({ minLength: 1 }), input: Type.Optional(Type.Any()) }, { additionalProperties: false }),
       result: Type.Null(),
     }),

package/apps/server/src/api/core-methods.ts

@@ -114,6 +114,18 @@ export const coreMethods = (sources: CoreMethodSources): MethodContribution[] =>
       current.start(trimmed, input === undefined ? null : input, userOf(access));
       return null;
     }),
+    implement(coreContracts.runs.scripts, async ({ runId }, { access }) => {
+      const current = await session(access, runId, "write");
+      if (!current.runScripts) throw new DomainError("script-start-unavailable", "This run cannot start run scripts.", 404);
+      return current.runScripts(sources.plugins.startEntries.describe().filter((entry) => canStartEntry(access, entry.id)), userIdOf(access));
+    }),
+    implement(coreContracts.runs.startScript, async ({ runId, entry, input }, { access }) => {
+      const trimmed = entry.trim();
+      if (!canStartEntry(access, trimmed)) throw new DomainError("access-denied", "This setup is not enabled for this access.", 403);
+      const current = await session(access, runId, "write");
+      if (!current.startAndWait) throw new DomainError("script-start-unavailable", "This run cannot start run scripts.", 404);
+      return current.startAndWait(trimmed, input === undefined ? null : input, userOf(access));
+    }),
     implement(coreContracts.chat.stop, async ({ runId }, { access }) => {
       const current = await session(access, runId, "stop");
       await current.stop();

package/apps/server/src/chat-handler.ts

@@ -1,5 +1,6 @@
 /** The contracts of the runs that core methods and delivery work against. */
 import type { ChatAttachment, ChatAttachmentInput, ChatEvent } from "quassel/events";
+import type { PublicStartEntry } from "@ragents/engine";
 import type { ActorConversations } from "./ragents/actor-chat-history.js";
 
 export interface SessionInfo {
@@ -18,6 +19,22 @@ export interface ChatUser {
 }
 
 /** What the HTTP adapter needs from a run. */
+/** A started run script: its actor and which start of its package in the run this was. */
+export interface StartedScript {
+  readonly actorId: string;
+  readonly handle: string;
+  readonly count: number;
+}
+
+/** A run script as a run lists it: whether it can start there now, and otherwise why not. */
+export interface RunScriptListing {
+  readonly id: string;
+  readonly title: string;
+  readonly description: string;
+  readonly available: boolean;
+  readonly reason?: string;
+}
+
 export interface ChatSessionLike {
   readonly running: boolean;
   subscribe(listener: (event: ChatEvent) => void): () => void;
@@ -27,6 +44,8 @@ export interface ChatSessionLike {
   capabilities?(actor: string, userId: string | null): Promise<{ input: string[]; model: string }>;
   attachment?(artifactId: string): { attachment: ChatAttachment; content: Uint8Array };
   start(entryId: string, input: unknown, user?: ChatUser): void;
+  startAndWait?(entryId: string, input: unknown, user?: ChatUser, startedBy?: string): Promise<StartedScript>;
+  runScripts?(entries: readonly PublicStartEntry[], userId: string | null): RunScriptListing[];
   stop(): void | Promise<void>;
 }
 

package/apps/server/src/host-api.json

@@ -25,6 +25,7 @@
       "holdsUsable",
       "implement",
       "implementChannel",
+      "inheritedGrants",
       "isRunId",
       "isThinkingLevel",
       "modelToolDescriptors",
@@ -77,6 +78,7 @@
     "@ragents/host/plugin-support/actor-programs/app-project": [
       "compileAppBackend",
       "installServerSdk",
+      "packageIdentity",
       "prepareAppProject",
       "prepareAppWorkspace",
       "projectSourceFiles",

package/apps/server/src/host-api.ts

@@ -13,7 +13,7 @@ export const hostApi: { readonly server: HostApiModules; readonly web: HostApiMo
       "DomainError", "RPC_ERROR_CODES", "RpcError", "ScriptDriver", "ToolRegistry", "actorByHandle",
       "actorByReference", "actorDescriptionMaxLength", "actorInputSchema", "agentTools", "assertJsonValue", "builtinProfiles", "canonicalHash",
       "compileVirtualTypeScriptAsync", "defineRunFunction", "defineToolAvailability", "emptyUsage",
-      "enqueueActorInput", "eventResultSchemaOf", "handleKey", "holdsUsable", "implement", "implementChannel",
+      "enqueueActorInput", "eventResultSchemaOf", "handleKey", "holdsUsable", "implement", "implementChannel", "inheritedGrants",
       "isRunId", "isThinkingLevel", "modelToolDescriptors", "pluginStateAt", "runCapabilityBindingHash",
       "runCapabilityContractHash", "schemaComplaints", "scriptInputOf", "serviceToken",
     ],
@@ -31,7 +31,7 @@ export const hostApi: { readonly server: HostApiModules; readonly web: HostApiMo
     ],
     "@ragents/host/host-version": ["readHostApiVersion", "readHostVersion", "readPackageVersion"],
     "@ragents/host/plugin-support/actor-programs/app-project": [
-      "compileAppBackend", "installServerSdk", "prepareAppProject", "prepareAppWorkspace", "projectSourceFiles",
+      "compileAppBackend", "installServerSdk", "packageIdentity", "prepareAppProject", "prepareAppWorkspace", "projectSourceFiles",
       "readAppPackage", "typecheckServerProject",
     ],
     "@ragents/host/plugin-support/actor-programs/client-compiler": ["compileClientProject", "installClientSdk"],

package/apps/server/src/plugin-build/build.ts

@@ -39,7 +39,7 @@ export interface PluginBuildOptions {
   readonly onlyOutdated?: boolean;
 }
 
-const DEFAULT_ASSET_FOLDERS = ["skills", "prompts", "run-scripts"] as const;
+const DEFAULT_ASSET_FOLDERS = ["skills", "prompts", "run-scripts", "actors"] as const;
 const SKIPPED_ASSET_FILES = new Set([".DS_Store"]);
 const WEB_FILE_EXTENSIONS = [".png", ".jpg", ".jpeg", ".gif", ".svg", ".webp", ".avif", ".ico", ".woff", ".woff2", ".ttf", ".otf"];
 const CODE_EXTENSION = /\.(ts|tsx|mts|cts|js|jsx|mjs|cjs)$/;

package/apps/server/src/plugin-support/actor-programs/app-project.ts

@@ -13,7 +13,7 @@ import { runtimeLibraries, webRuntimeLibraries } from "./runtime-libraries.js";
 const webRequire = createRequire(new URL("../../../../web/package.json", import.meta.url));
 const rootRequire = createRequire(new URL("../../../../../package.json", import.meta.url));
 const serverRequire = createRequire(new URL("../../../package.json", import.meta.url));
-const serverTypeRoot = fileURLToPath(new URL("../../../node_modules/@types", import.meta.url));
+const serverTypeRoot = path.dirname(path.dirname(serverRequire.resolve("@types/node/package.json")));
 const libraryDirectory = (name: string): string => {
   const resolver = (webRuntimeLibraries as readonly string[]).includes(name) ? webRequire
     : name === "@types/node" || name === "tsx" ? serverRequire : rootRequire;
@@ -107,8 +107,10 @@ export function createTestContextWithContracts(options, contracts) {
     if(!Value.Check(contract.resultSchema,result))throw new Error("Test response violates the contract of "+name+": "+schemaComplaints(contract.resultSchema,result,"result"));
     return result;
   }};
+  const finished = [];
   return {...createRunContext({runId:"test",invocationId:"test",invocationKind:"tool",principal:{id:"test",kind:"service"},state:statePort,capabilities,log:()=>{},signal:controller.signal}),
-    actor:{id:"test-actor",handle:"test"},std:createScriptStd({turnStartedAt:"2026-01-01T00:00:00.000Z",idPrefix:"test",state:statePort,capabilities})};
+    actor:{id:"test-actor",handle:"test"},std:createScriptStd({turnStartedAt:"2026-01-01T00:00:00.000Z",idPrefix:"test",state:statePort,capabilities}),
+    finished,finish:(result,options={})=>{assertJsonValue(result===undefined?null:result,"Test finish result");finished.push({result:result===undefined?null:result,...options});}};
 }`, resolveDir:process.cwd(),sourcefile:"actor-testing.ts",loader:"ts"},
   bundle:true,platform:"node",format:"esm",target:"node22",packages:"external",write:false,
 }).then(result=>result.outputFiles![0]!.text);
@@ -134,6 +136,8 @@ export interface RunContext<State> {
   readonly functions: {readonly [Name in keyof CapabilityContracts]: (...args: {} extends CapabilityContracts[Name]['input'] ? [input?: CapabilityContracts[Name]['input']] : [input: CapabilityContracts[Name]['input']]) => Promise<CapabilityContracts[Name]['output']>};
   log(value: unknown): void;
   throwIfAborted(): void;
+  /** Ends a start of this run script with a JSON result; the host delivers it once to whoever started it. Only in onStart, onInput and onResult; outside onStart, name the start. */
+  finish(result: unknown, options?: { readonly summary?: string; readonly start?: number }): void;
 }
 ${scriptStdDeclarations}
 export interface ActorInput {
@@ -142,10 +146,15 @@ export interface ActorInput {
   readonly event: { readonly type: string; readonly eventId: string; readonly sequence: number; readonly occurredAt: string;
     readonly sourceActorId: string | null; readonly sourceActorHandle: string | null; readonly payload: {readonly text?:string; readonly [key:string]:unknown} } | null;
 }
+export interface ActorStart {
+  readonly input: unknown; readonly options: Readonly<Record<string, unknown>>;
+  readonly embedded: boolean; readonly startedBy: string; readonly count: number;
+}
+export interface ActorResult { readonly handle: string; readonly count: number; readonly result: unknown; readonly summary?: string }
 export interface ActorFunction { label: string; description?: string; input: TSchema; output: TSchema; capabilities?: readonly string[]; confirmation?: string; tool?: { name: string; targets?: readonly string[]; card?: boolean } }
 export interface ActorContract { state: TSchema; functions: Readonly<Record<string, ActorFunction>>; input?: {capabilities?: readonly string[]} }
 export type ActorFunctions<C extends ActorContract> = { [K in keyof C['functions']]: (input: Static<C['functions'][K]['input']>, context: RunContext<Static<C['state']>>) => Static<C['functions'][K]['output']> | Promise<Static<C['functions'][K]['output']>> };
-export type ActorImplementation<C extends ActorContract> = {functions: ActorFunctions<C>} & (C extends {input: unknown} ? {onInput: (input: ActorInput, context: RunContext<Static<C['state']>>) => void | Promise<void>} : {onInput?: never});
+export type ActorImplementation<C extends ActorContract> = {functions: ActorFunctions<C>} & (C extends {input: unknown} ? {onInput: (input: ActorInput, context: RunContext<Static<C['state']>>) => void | Promise<void>; onStart?: (start: ActorStart, context: RunContext<Static<C['state']>>) => void | Promise<void>; onResult?: (result: ActorResult, context: RunContext<Static<C['state']>>) => void | Promise<void>} : {onInput?: never; onStart?: never; onResult?: never});
 export declare function defineActor<const C extends ActorContract>(contract: C, implementation: ActorImplementation<C>): {contract:C} & ActorImplementation<C>;
 `;
 };
@@ -193,24 +202,45 @@ export const installServerSdk = async (directory: string, capabilities: readonly
   await writeFile(path.join(sdk, "index.js"), sdkRuntime);
   await writeFile(path.join(sdk, "index.d.ts"), declarations);
   await writeFile(path.join(sdk, "testing.js"), (await testingRuntime()) + `\nexport function createTestContext(options) { return createTestContextWithContracts(options, ${JSON.stringify(capabilities)}); }\n`);
-  await writeFile(path.join(sdk, "testing.d.ts"), "import type { RunContext, CapabilityContracts } from './index.js';\ntype Mocks = {[Name in keyof CapabilityContracts]?: (input: CapabilityContracts[Name]['input']) => CapabilityContracts[Name]['output'] | Promise<CapabilityContracts[Name]['output']>};\nexport declare function createTestContext<State>(options: {state: State; functions?: Mocks}): RunContext<State>;\n");
+  await writeFile(path.join(sdk, "testing.d.ts"), "import type { RunContext, CapabilityContracts } from './index.js';\ntype Mocks = {[Name in keyof CapabilityContracts]?: (input: CapabilityContracts[Name]['input']) => CapabilityContracts[Name]['output'] | Promise<CapabilityContracts[Name]['output']>};\ntype Finished = {readonly result: unknown; readonly summary?: string; readonly start?: number};\nexport declare function createTestContext<State>(options: {state: State; functions?: Mocks}): RunContext<State> & {readonly finished: readonly Finished[]};\n");
 };
 
+/** The tsconfig files the host writes into a package that brings none of its own. */
+const generatedConfigs = (pkg: Pick<AppPackage, "backend" | "views">): Readonly<Record<string, string>> => ({
+  "tsconfig.client.json": json({ extends: "./node_modules/@ragents/client/tsconfig.json", include: (pkg.views ?? []).map(view => view.client) }),
+  "tsconfig.server.json": json({ compilerOptions: {
+    target: "ES2022", module: "ESNext", moduleResolution: "Bundler", strict: true, noEmit: true,
+    skipLibCheck: true, types: ["node"], lib: ["ES2022"], allowImportingTsExtensions: true,
+  }, include: [...(pkg.backend ? [pkg.backend] : []), "tests/**/*.ts"] }),
+  "tsconfig.json": json({ files: [], references: [{ path: "./tsconfig.client.json" }, { path: "./tsconfig.server.json" }] }),
+});
+
 export const prepareAppProject = async (directory: string): Promise<void> => {
   await prepareAppDependencies(directory);
   await installServerSdk(directory);
   const pkg = await readAppPackage(directory);
-  const writeConfig = async (name: string, value: unknown): Promise<void> => {
-    await writeFile(path.join(directory, name), json(value), { flag: "wx" }).catch((error: NodeJS.ErrnoException) => {
+  for (const [name, content] of Object.entries(generatedConfigs(pkg))) {
+    await writeFile(path.join(directory, name), content, { flag: "wx" }).catch((error: NodeJS.ErrnoException) => {
       if (error.code !== "EEXIST") throw error;
     });
-  };
-  await writeConfig("tsconfig.client.json", { extends: "./node_modules/@ragents/client/tsconfig.json", include: (pkg.views ?? []).map(view => view.client) });
-  await writeConfig("tsconfig.server.json", { compilerOptions: {
-    target: "ES2022", module: "ESNext", moduleResolution: "Bundler", strict: true, noEmit: true,
-    skipLibCheck: true, types: ["node"], lib: ["ES2022"], allowImportingTsExtensions: true,
-  }, include: [...(pkg.backend ? [pkg.backend] : []), "tests/**/*.ts"] });
-  await writeConfig("tsconfig.json", { files: [], references: [{ path: "./tsconfig.client.json" }, { path: "./tsconfig.server.json" }] });
+  }
+};
+
+/** What a package is, independent of the tsconfig files the host generated into it: two packages with the same identity have the same sources. */
+export const packageIdentity = (files: readonly { path: string; content: string }[]): string => {
+  const normalized = files.map((file) => ({ path: file.path.split(path.sep).join("/"), content: file.content }));
+  const generated = generatedConfigsOf(normalized.find((file) => file.path === "package.json")?.content);
+  return canonicalHash(normalized.filter((file) => generated[file.path] !== file.content).sort((left, right) => left.path.localeCompare(right.path)));
+};
+
+/** A package.json that does not parse has no generated configs; its activation reports the error. */
+const generatedConfigsOf = (packageJson: string | undefined): Readonly<Record<string, string>> => {
+  try {
+    const pkg = (JSON.parse(packageJson ?? "{}") as { ragents?: Pick<AppPackage, "backend" | "views"> }).ragents;
+    return pkg ? generatedConfigs(pkg) : {};
+  } catch {
+    return {};
+  }
 };
 
 export const readAppPackage = async (directory: string): Promise<AppPackage> => {
@@ -261,13 +291,27 @@ export const compileAppBackend = async (options: {
 export const describe = () => {
   for (const name of Object.keys(actor.contract.functions ?? {})) if (typeof actor.functions?.[name] !== 'function') throw new Error('Missing function ' + name);
   if (Boolean(actor.contract.input) !== (typeof actor.onInput === 'function')) throw new Error('input and onInput must be present together.');
+  for (const name of ['onStart', 'onResult']) if (actor[name] !== undefined && (typeof actor[name] !== 'function' || !actor.contract.input)) throw new Error(name + ' needs input and onInput.');
   return JSON.parse(JSON.stringify(actor.contract));
 };
-export const handle = (request, context) => {
-  if (request.kind === 'input') { if (!actor.onInput) throw new Error('This actor does not process input.'); return actor.onInput(request.input, context); }
-  const handler = actor.functions[request.functionId];
-  if (typeof handler !== 'function') throw new Error('Unknown actor function ' + request.functionId);
-  return handler(request.input, context);
+export const handle = async (request, context) => {
+  if (request.kind !== 'input') {
+    const handler = actor.functions[request.functionId];
+    if (typeof handler !== 'function') throw new Error('Unknown actor function ' + request.functionId);
+    return handler(request.input, { ...context, finish: () => { throw new Error('finish works only in onStart, onInput and onResult; a function passes the result as an input to its own actor.'); } });
+  }
+  if (!actor.onInput) throw new Error('This actor does not process input.');
+  const finishes = [];
+  const finish = (result, options = {}) => {
+    const start = options.start ?? request.start?.count;
+    if (!Number.isInteger(start)) throw new Error('finish needs options.start, the count of the start it ends, outside onStart.');
+    finishes.push({ start, result: result === undefined ? null : result, ...(options.summary === undefined ? {} : { summary: options.summary }) });
+  };
+  const handlerContext = { ...context, finish };
+  if (request.result && actor.onResult) await actor.onResult(request.result, handlerContext);
+  else if (request.start && actor.onStart) await actor.onStart(request.start, handlerContext);
+  else await actor.onInput(request.input, handlerContext);
+  return { finishes };
 };`, resolveDir: options.directory, sourcefile: "actor-entry.ts", loader: "ts" },
     absWorkingDir: options.directory, platform: "node", format: "esm", target: "node22", bundle: true, packages: "external", write: false,
   });

package/apps/server/src/plugin-support/actor-programs/client-contracts.ts

@@ -1,16 +1,55 @@
+import { realpathSync } from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import ts from "typescript";
 
-function readContracts(repoRoot: string): { names: string[]; files: Record<string, string> } {
-  const filename = path.join(repoRoot, "apps/web/src/actor-programs/client-ui/contracts.d.ts");
+export function clientUiContractPaths(directory: string, paths: typeof path.posix = path) {
+  const canonical = (name: string) => paths.resolve(name).replaceAll(paths.sep, "/").replace(/^[a-z]:/, (drive) => drive.toUpperCase());
+  const repoRoot = canonical(directory);
+  const root = canonical(paths.join(paths.parse(repoRoot).root, "__ragents_ui_contract__"));
+  const contains = (base: string, name: string) => name === base || name.startsWith(`${base}/`);
+  const physical = (name: string) => {
+    const file = canonical(name);
+    return paths.normalize(contains(root, file) ? repoRoot + file.slice(root.length) : file);
+  };
+  const virtual = (name: string) => {
+    const file = canonical(name);
+    return contains(repoRoot, file) ? root + file.slice(repoRoot.length) : file;
+  };
+  return { root, physical, virtual, isVirtual: (name: string) => contains(root, canonical(name)) };
+}
+
+function readContracts(directory: string): { names: string[]; files: Record<string, string> } {
+  const { root, physical, virtual, isVirtual } = clientUiContractPaths(realpathSync(directory));
+  const filename = `${root}/apps/web/src/actor-programs/client-ui/contracts.d.ts`;
   const options: ts.CompilerOptions = {
     target: ts.ScriptTarget.ES2022, module: ts.ModuleKind.ESNext,
     moduleResolution: ts.ModuleResolutionKind.Bundler, jsx: ts.JsxEmit.ReactJSX,
     strict: true, skipLibCheck: true, esModuleInterop: true,
     declaration: true, emitDeclarationOnly: true,
   };
-  const program = ts.createProgram([filename], options);
+  // TypeScript must see public sources outside node_modules, including during declaration naming.
+  const host = ts.createCompilerHost(options);
+  host.readFile = (name) => ts.sys.readFile(physical(name));
+  host.fileExists = (name) => ts.sys.fileExists(physical(name));
+  host.directoryExists = (name) => ts.sys.directoryExists(physical(name));
+  host.getDirectories = (name) => ts.sys.getDirectories(physical(name));
+  host.realpath = (name) => virtual(ts.sys.realpath!(physical(name)));
+  host.getSourceFile = (name, languageVersion) => {
+    const text = host.readFile(name);
+    return text === undefined ? undefined : ts.createSourceFile(virtual(name), text, languageVersion, true);
+  };
+  const resolveModule = (name: string, containingFile: string) => {
+    const mapped = ts.resolveModuleName(name, containingFile, options, host).resolvedModule;
+    if (mapped) return mapped;
+    const resolved = ts.resolveModuleName(name, physical(containingFile), options, ts.sys).resolvedModule;
+    if (!resolved) return undefined;
+    const resolvedFileName = virtual(resolved.resolvedFileName);
+    return { ...resolved, resolvedFileName, isExternalLibraryImport: isVirtual(resolvedFileName)
+      ? path.posix.relative(root, resolvedFileName).split("/").includes("node_modules") : resolved.isExternalLibraryImport };
+  };
+  host.resolveModuleNames = (names, containingFile) => names.map((name) => resolveModule(name, containingFile));
+  const program = ts.createProgram([filename], options, host);
   const source = program.getSourceFile(filename);
   if (!source) throw new Error("The public UI contract is missing.");
   const checker = program.getTypeChecker();
@@ -27,8 +66,8 @@ function readContracts(repoRoot: string): { names: string[]; files: Record<strin
   const collect = (file: ts.SourceFile) => {
     if (visited.has(file.fileName)) return;
     visited.add(file.fileName);
-    const relative = path.relative(repoRoot, file.fileName).replaceAll(path.sep, "/");
-    if (relative.startsWith("../") || relative.includes("node_modules/")) throw new Error("A local UI type reference leaves the public repository sources.");
+    const relative = path.posix.relative(root, file.fileName);
+    if (!isVirtual(file.fileName) || relative.includes("node_modules/")) throw new Error("A local UI type reference leaves the public repository sources.");
     diagnostics.push(...program.getSyntacticDiagnostics(file), ...program.getSemanticDiagnostics(file));
     let text = file.isDeclarationFile ? file.text : "";
     if (!file.isDeclarationFile) {
@@ -41,13 +80,13 @@ function readContracts(repoRoot: string): { names: string[]; files: Record<strin
     const references = ts.preProcessFile(text, true, true);
     for (const reference of references.importedFiles) {
       if (!reference.fileName.startsWith(".")) continue;
-      const resolved = ts.resolveModuleName(reference.fileName, file.fileName, options, ts.sys).resolvedModule;
+      const resolved = resolveModule(reference.fileName, file.fileName);
       const dependency = resolved && program.getSourceFile(resolved.resolvedFileName);
       if (!dependency) throw new Error(`Unresolvable local UI type reference: ${relative}: ${reference.fileName}`);
       collect(dependency);
     }
     for (const reference of declaration.referencedFiles) {
-      const dependency = program.getSourceFile(path.resolve(path.dirname(file.fileName), reference.fileName));
+      const dependency = program.getSourceFile(path.posix.resolve(path.posix.dirname(file.fileName), reference.fileName));
       if (!dependency) throw new Error(`Unresolvable UI type file reference: ${relative}: ${reference.fileName}`);
       collect(dependency);
     }
@@ -76,7 +115,7 @@ export function readClientUiComponentContracts(component: string, repoRoot?: str
 }
 
 export function readClientUiExportContracts(component: string, repoRoot?: string): Record<string, string> {
-  const root = repoRoot ?? fileURLToPath(new URL("../../../../../", import.meta.url));
+  const root = realpathSync(repoRoot ?? fileURLToPath(new URL("../../../../../", import.meta.url)));
   const catalog = contracts(repoRoot);
   const files = new Map(Object.entries(catalog.files).map(([name, text]) => [path.resolve(root, name), text]));
   const options: ts.CompilerOptions = { target: ts.ScriptTarget.ES2022, module: ts.ModuleKind.ESNext, moduleResolution: ts.ModuleResolutionKind.Bundler, strict: true, skipLibCheck: true };

package/apps/server/src/plugin-support/actor-programs/contract.ts

@@ -47,7 +47,24 @@ export interface ActorProgramDefinition {
   views: ActorViewDefinition[];
 }
 export interface ActorProgramState { version: 1; program: ActorProgramDefinition | null; }
-export interface ActorScriptState { version: 1; entryId: string; }
+/** A start that its program received and has not finished yet. */
+export interface ActorScriptOpenStart { readonly count: number; readonly startedBy: string; }
+/** Where the host took a package from: a run script's template or a plugin's shared packages. */
+export type ActorPackageOrigin = { readonly kind: "script"; readonly entryId: string } | { readonly kind: "shared"; readonly pluginId: string };
+/** identity is the packageIdentity of the sources the host installed; a program whose sources differ is no longer this origin's. */
+export interface ActorScriptPackage { readonly origin: ActorPackageOrigin; readonly identity: string; readonly count: number; readonly open: readonly ActorScriptOpenStart[]; }
+/** An input the host queues for a program to recognize, keyed by the command that queues it: a start, or the result of a start for its starter. */
+export type ActorScriptDelivery = { readonly commandId: string; readonly actorId: string } & (
+  | { readonly kind: "start"; readonly name: string; readonly count: number; readonly embedded: boolean; readonly startedBy: string }
+  | { readonly kind: "result" });
+/** Who an active program is, for plugins that authorize by it: a shared package, a run script's package, or a package created in the run. */
+export type ActorProgramOrigin = ActorPackageOrigin | { readonly kind: "run"; readonly installedBy: string };
+export interface ActorProgramIdentity { readonly name: string; readonly actorId: string; readonly revision: string; readonly origin: ActorProgramOrigin; }
+export interface ActorScriptState {
+  readonly version: 2;
+  readonly packages: Readonly<Record<string, ActorScriptPackage>>;
+  readonly deliveries: readonly ActorScriptDelivery[];
+}
 
 export const resolveActorView = (programs: readonly ActorProgramDefinition[], reference: string) => {
   const normalized = reference.trim().toLowerCase();

package/apps/server/src/plugin-support/actor-programs/service.ts

@@ -1,4 +1,5 @@
 import { serviceToken, type ActorProgramExecutor, type CommandContext } from "@ragents/engine";
+import type { ActorProgramIdentity } from "./contract.js";
 export interface ActorProgramSource {
     path: string;
     content: string;
@@ -9,8 +10,28 @@ export interface ActivatedActorProgram {
     actorHandle: string;
     views: number;
 }
+export interface RunScriptSources {
+    entryId: string;
+    handle: string;
+    files: readonly ActorProgramSource[];
+    programs: readonly { name: string; files: readonly ActorProgramSource[] }[];
+    sharedPrograms: readonly string[];
+}
+export interface RunScriptStartInput {
+    content: string;
+    embedded: boolean;
+    startedBy: string;
+}
 export interface ActorProgramsService extends ActorProgramExecutor {
     workspaceDirectory(runId: string): Promise<string>;
-    importPackage(context: CommandContext, runId: string, name: string, files: readonly ActorProgramSource[], signal?: AbortSignal, scriptEntryId?: string): Promise<ActivatedActorProgram>;
+    importPackage(context: CommandContext, runId: string, name: string, files: readonly ActorProgramSource[], signal?: AbortSignal): Promise<ActivatedActorProgram>;
+    /** Installs a run script with its bundled programs, or reuses what the same script installed before; a failure leaves the run unchanged. */
+    installScript(context: CommandContext, runId: string, script: RunScriptSources, signal?: AbortSignal): Promise<ActivatedActorProgram>;
+    /** Queues a start input for the installed script so that its program recognizes it as a start; an embedded start also places its main view. */
+    enqueueStart(context: CommandContext, runId: string, handle: string, start: RunScriptStartInput): { count: number };
+    /** Whether a run script installed this TypeScript actor's package in the run. */
+    isScriptActor(runId: string, actorId: string): boolean;
+    /** Which package the actor runs and where it came from; a package changed in the run counts as created in the run. Authorize by this, never by handle. */
+    programOf(runId: string, actorId: string): ActorProgramIdentity | undefined;
 }
 export const actorProgramsToken = serviceToken<ActorProgramsService>("ragents.actor-programs.runtime");

package/apps/server/src/plugin-support/plugin-folder.ts

@@ -1,6 +1,7 @@
 import { statSync } from "node:fs";
 import path from "node:path";
 import type {
+  ActorPackageContribution,
   PluginRegistration,
   RAgentsPlugin,
   SkillContribution,
@@ -8,7 +9,7 @@ import type {
 } from "@ragents/engine";
 import { skillsFromDirectory, type FolderSkills } from "./skills.js";
 import { pluginFolder } from "./plugins-root.js";
-import { runScriptsFromDirectory, type ScriptStartEntry } from "./run-scripts.js";
+import { actorPackagesFromDirectory, runScriptsFromDirectory, type ScriptStartEntry } from "./run-scripts.js";
 import { systemPromptOptionsFromDirectory, type SystemPromptOption } from "./system-prompts.js";
 
 export { pluginFolder };
@@ -37,6 +38,11 @@ export const folderRunScripts = (
   return directory ? runScriptsFromDirectory(directory, pluginId) : [];
 };
 
+export const folderActorPackages = (folder: string): readonly ActorPackageContribution[] => {
+  const directory = assetFolder(folder, "actors");
+  return directory ? actorPackagesFromDirectory(directory) : [];
+};
+
 export const folderSkillPaths = (folder: string): readonly string[] => folderSkills(folder, path.basename(folder)).paths;
 
 export const folderSystemPrompts = (folder: string): readonly SystemPromptOption[] => {
@@ -48,6 +54,7 @@ export const withFolderAssets = (plugin: RAgentsPlugin): RAgentsPlugin => ({
   manifest: plugin.manifest,
   register: (host) => {
     const explicitEntries: StartEntryContribution[] = [];
+    const explicitPackages: ActorPackageContribution[] = [];
     const explicitSkills: SkillContribution[] = [];
     const observed: PluginRegistration = {
       ...host,
@@ -55,6 +62,10 @@ export const withFolderAssets = (plugin: RAgentsPlugin): RAgentsPlugin => ({
         explicitEntries.push(...contributions);
         host.startEntries(...contributions);
       },
+      actorPackages: (...contributions) => {
+        explicitPackages.push(...contributions);
+        host.actorPackages(...contributions);
+      },
       skills: (...contributions) => {
         explicitSkills.push(...contributions);
         host.skills(...contributions);
@@ -69,6 +80,8 @@ export const withFolderAssets = (plugin: RAgentsPlugin): RAgentsPlugin => ({
       ...folderRunScripts(folder, plugin.manifest.id),
     ].filter((entry) => !explicitEntries.some((explicit) => explicit.id === entry.id));
     if (entries.length > 0) host.startEntries(...entries);
+    const packages = folderActorPackages(folder).filter((entry) => !explicitPackages.some((explicit) => explicit.name === entry.name));
+    if (packages.length > 0) host.actorPackages(...packages);
 
     const skillPaths = skills.paths;
     if (skillPaths.length === 0) return;

package/apps/server/src/plugin-support/run-scripts.ts

@@ -1,12 +1,12 @@
 import { readdirSync, readFileSync, statSync } from "node:fs";
 import path from "node:path";
-import type { ActorProgramFile, JsonValue, StartEntryContribution } from "@ragents/engine";
+import type { ActorPackageContribution, ActorProgramFile, JsonValue, StartEntryContribution } from "@ragents/engine";
 import { flag, frontMatterOf, numberOf, tagsOf } from "./front-matter.js";
 
 export type ScriptStartEntry = Extract<StartEntryContribution, { action: "script" }>;
 
 const PACKAGE_NAME = /^[a-z0-9][a-z0-9-]*$/;
-const RUN_FIELDS = ["title", "description", "order", "guide", "tags", "coordinator", "category", "fixed-start-options"];
+const RUN_FIELDS = ["title", "description", "order", "guide", "tags", "coordinator", "embeddable", "shared-programs", "category", "fixed-start-options"];
 
 const requiredFile = (directory: string, name: string): string => {
   const file = path.join(directory, name);
@@ -14,6 +14,16 @@ const requiredFile = (directory: string, name: string): string => {
   return file;
 };
 
+/** The header line shared-programs names shared actor packages of the profile, separated by commas. */
+const sharedProgramsOf = (file: string, value: string | undefined): readonly string[] | undefined => {
+  if (value === undefined) return undefined;
+  const names = value.split(",").map((name) => name.trim());
+  if (names.some((name) => !PACKAGE_NAME.test(name)) || new Set(names).size !== names.length) {
+    throw new Error(`${file}: shared-programs must name each shared actor package once, separated by commas`);
+  }
+  return names;
+};
+
 /** The header line fixed-start-options is a JSON object on one line: start option id to fixed value. */
 const fixedStartOptionsOf = (file: string, value: string | undefined): Readonly<Record<string, JsonValue>> | undefined => {
   if (value === undefined) return undefined;
@@ -60,6 +70,7 @@ const runScriptFrom = (directory: string, name: string, id: string): ScriptStart
   const category = fields.get("category");
   if (category !== undefined && !category.trim()) throw new Error(`${runFile}: category is empty`);
   const fixedStartOptions = fixedStartOptionsOf(runFile, fields.get("fixed-start-options"));
+  const sharedPrograms = sharedProgramsOf(runFile, fields.get("shared-programs"));
   const programsDirectory = path.join(directory, "actors");
   const programsStats = statSync(programsDirectory, {throwIfNoEntry: false});
   if (programsStats && !programsStats.isDirectory()) throw new Error(`${programsDirectory} must be a directory`);
@@ -80,6 +91,8 @@ const runScriptFrom = (directory: string, name: string, id: string): ScriptStart
     script: {
       handle: name,
       coordinator: flag(runFile, "coordinator", fields.get("coordinator"), true),
+      embeddable: flag(runFile, "embeddable", fields.get("embeddable")),
+      ...(sharedPrograms !== undefined ? { sharedPrograms } : {}),
       files: filesOf(directory),
       programs,
     },
@@ -98,6 +111,18 @@ export const runScriptsFromDirectory = (directory: string, idPrefix: string): re
   return packages.map((name) => runScriptFrom(path.join(resolved, name), name, `${idPrefix}.${name}`));
 };
 
+/** Every folder is one shared actor package, named after the folder. */
+export const actorPackagesFromDirectory = (directory: string): readonly ActorPackageContribution[] => {
+  const resolved = path.resolve(directory);
+  const entries = readdirSync(resolved, {withFileTypes: true}).sort((left, right) => left.name.localeCompare(right.name));
+  const stray = entries.filter((entry) => !entry.isDirectory()).map((entry) => entry.name);
+  if (stray.length > 0) throw new Error(`${resolved} contains files instead of actor package folders: ${stray.join(", ")}`);
+  return entries.map((entry) => {
+    if (!PACKAGE_NAME.test(entry.name)) throw new Error(`${resolved}: the folder name ${entry.name} is not a package name (lowercase letters, digits, hyphen)`);
+    return {name: entry.name, files: filesOf(path.join(resolved, entry.name))};
+  });
+};
+
 export const runScriptFromDirectory = (directory: string): ScriptStartEntry => {
   if (!path.isAbsolute(directory)) throw new Error("The run script package needs an absolute server file path");
   const resolved = path.resolve(directory);

package/apps/server/src/profile/compose.ts

@@ -6,6 +6,7 @@ import { aliasCompletionModel, aliasCompletionModelToken } from "../plugin-suppo
 import { withFolderAssets } from "../plugin-support/plugin-folder.js";
 import type { PluginModule } from "../plugin-support/plugin-module.js";
 import { runManagementToken } from "../ragents/global-chat.js";
+import { registerRunScriptFunctions } from "../ragents/run-script-tools.js";
 import { registerTypeScriptFunctions } from "../ragents/typescript-tools.js";
 import {
   executorContributionsToken,
@@ -84,6 +85,7 @@ export const composeProfile = (options: ProfileComposition, bridges: HostBridges
     }));
   }
   registerTypeScriptFunctions(host);
+  registerRunScriptFunctions(host);
   host.seal();
   return host;
 };