@schlenkr/ragents 0.1.13 → 0.1.15

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

@@ -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/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;
 };

package/apps/server/src/provider.ts

@@ -4,7 +4,7 @@ import { existsSync, statSync } from "node:fs";
 import { chmod, mkdir, open, readFile, readdir, realpath, rename, rm } from "node:fs/promises";
 import path from "node:path";
 import type { ChatSessionLike, ChatSessionProvider, RunListScope, SessionInfo } from "./chat-handler.js";
-import { DomainError, isRunId, unrestrictedAccess, type AccessContext, type HttpRouteContribution, type Journal, type JournalLoadFailure, type MethodContribution, type PluginHost, type ServiceToken, type SessionStartedContext } from "@ragents/engine";
+import { canStartEntry, createAccessContext, DomainError, isRunId, unrestrictedAccess, type AccessContext, type HttpRouteContribution, type Journal, type JournalLoadFailure, type MethodContribution, type PluginHost, type ServiceToken, type SessionStartedContext } from "@ragents/engine";
 import { WORKSPACE_EXECUTOR_VERSION } from "@ragents/workspace-executor";
 import { assertRunRights, assertRunWorkspaceAccess, runIdInPath, runListScope, runReachable, type GlobalRunPolicy, type RunAccessPolicy } from "./api/rights.js";
 import { configuredAnonymousUser, configuredUsers } from "./config-file.js";
@@ -42,7 +42,7 @@ import { RunChatSession } from "./ragents/session.js";
 import { globalChatToken, globalRunPolicyOf, type GlobalChatPolicy, type ManagedRunStart, type RunManagement } from "./ragents/global-chat.js";
 import { workspaceRuntimeToken, type SessionWorkspace, type WorkspaceTransfer } from "./ragents/workspace-runtime.js";
 import { settingsResponse, skillDetailResponse, type SettingsResponse, type SettingsSkillDetail } from "./settings.js";
-import { createTitleCompactor } from "./title-compactor.js";
+import { createTitleCompactor, MAX_TITLE_CHARS } from "./title-compactor.js";
 import { ModelRuntime } from "@ragents/agent";
 import { TitleSettingsStore } from "./title-settings.js";
 import { sandboxServicesToken } from "./plugin-support/workspace-sandbox-host.js";
@@ -59,6 +59,8 @@ type ListedSession = SessionInfo & {
   running: boolean;
   /** Whether the caller reaches the run's workspace; otherwise UIs hide what needs it. */
   workspaceAccessible: boolean;
+  /** Display name of the user who created the run; missing for a run created without sign-in. */
+  ownerLabel?: string;
   metadata?: Readonly<Record<string, unknown>>;
   metadataUnavailable?: Readonly<Record<string, string>>;
 };
@@ -246,9 +248,9 @@ export class RunSessionProvider implements ChatSessionProvider {
       scriptEntryFor: (entryId) => globalPolicy ? undefined : this.plugins.startEntries.scriptPackage(entryId),
       startEntryFor: (entryId) => globalPolicy ? undefined : this.plugins.startEntries.entry(entryId),
       actorPrograms: {
-        runInput: (...args) => this.plugins.service(actorProgramsToken).runInput(...args),
-        workspaceDirectory: (runId) => this.plugins.service(actorProgramsToken).workspaceDirectory(runId),
-        importPackage: (...args) => this.plugins.service(actorProgramsToken).importPackage(...args),
+        installScript: (...args) => this.plugins.service(actorProgramsToken).installScript(...args),
+        enqueueStart: (...args) => this.plugins.service(actorProgramsToken).enqueueStart(...args),
+        isScriptActor: (runId, actorId) => this.plugins.optionalService(actorProgramsToken)?.isScriptActor(runId, actorId) ?? false,
       },
     });
     this.sessions.set(id, session);
@@ -295,6 +297,8 @@ export class RunSessionProvider implements ChatSessionProvider {
     const isCoordinator = (runId: string) => this.plugins.optionalService(globalChatToken)?.isCoordinator(runId) ?? false;
     const listed = engine.journal.runIds().filter((runId) => !isCoordinator(runId)
       && !this.deleteRequested.has(runId) && !this.deleted.has(runId) && visible(runId));
+    const anonymousUser = configuredAnonymousUser();
+    const userLabels = new Map([...configuredUsers() ?? [], ...anonymousUser ? [anonymousUser] : []].map((user) => [user.id, user.label]));
     const described = await Promise.all(listed.map(async (runId): Promise<ListedSession | undefined> => {
       const state = engine.journal.stateOf(runId);
       if (!state) return undefined;
@@ -317,6 +321,7 @@ export class RunSessionProvider implements ChatSessionProvider {
         running: [...state.actors.values()].some((actor) => actor.kind !== "human" && engine.scheduler.isRunning(runId, actor.id))
           || (this.sessions.get(runId)?.running ?? false),
         workspaceAccessible: workspace,
+        ...(state.ownerUserId !== null ? { ownerLabel: userLabels.get(state.ownerUserId) ?? state.ownerUserId } : {}),
         metadata: metadata.values,
         ...(Object.keys(metadata.unavailable).length > 0 ? { metadataUnavailable: metadata.unavailable } : {}),
       };
@@ -358,9 +363,28 @@ export class RunSessionProvider implements ChatSessionProvider {
       },
       stop: (runId) => this.openSession(runId).stop(),
       resetGlobal: (runId) => this.resetGlobalConversation(runId),
+      scripts: (runId) => {
+        const access = this.ownerAccess(runId);
+        return this.openSession(runId).runScripts(this.plugins.startEntries.describe().filter((entry) => canStartEntry(access, entry.id)), access.user?.id ?? null);
+      },
+      startScript: (runId, entryId, input, startedBy) => {
+        const access = this.ownerAccess(runId);
+        if (!canStartEntry(access, entryId)) throw new DomainError("access-denied", `The run script ${entryId} is not enabled for the owner of this run.`, 403);
+        return this.openSession(runId).startAndWait(entryId, input, access.user ? { id: access.user.id, label: access.user.label } : undefined, startedBy);
+      },
     };
   }
 
+  /** The owner's access as a user of this profile; the run's own actors start run scripts with it. */
+  private ownerAccess(runId: string): AccessContext {
+    this.ensureUsable(runId);
+    const users = configuredUsers();
+    const ownerUserId = this.requireEngine().journal.stateOf(runId)?.ownerUserId ?? null;
+    return createAccessContext(ownerUserId === null
+      ? { enabled: users !== undefined, user: users ? null : configuredAnonymousUser() ?? null }
+      : { enabled: true, user: users?.find((user) => user.id === ownerUserId) ?? null });
+  }
+
   private async createManagedRun(start: ManagedRunStart): Promise<string> {
     const local = start.kind === "package" ? runScriptFromDirectory(start.directory) : undefined;
     const id = randomUUID();
@@ -924,5 +948,6 @@ const lockedSession = (failure: JournalLoadFailure, journal: Journal): ListedSes
 const sessionTitle = (text: string | undefined): string | undefined => {
   const lines = text?.split(/\r?\n/).map((line) => line.trim()).filter(Boolean) ?? [];
   if (lines.length === 0) return undefined;
-  return lines[0]?.startsWith("[Test:") && lines[1] ? `${lines[0]} ${lines[1]}` : lines[0];
+  const title = lines[0]?.startsWith("[Test:") && lines[1] ? `${lines[0]} ${lines[1]}` : lines[0] ?? "";
+  return title.length > MAX_TITLE_CHARS ? `${title.slice(0, MAX_TITLE_CHARS - 3)}...` : title;
 };

package/apps/server/src/ragents/chat-projection.ts

@@ -11,6 +11,8 @@ export interface ChatProjectionScope {
   primaryActorId: string;
   ownerId: string;
   labelOf: (actorId: string) => string | undefined;
+  /** The handle of a TypeScript actor a run script installed; the chat shows its runtime output too. */
+  scriptActorHandle?: (actorId: string) => string | undefined;
   turnOf: (turnId: string) => Pick<Turn, "actorId" | "toolCalls">;
   /** Whether this command also interrupted a turn of the actor; its stop then repeats no reason. */
   interruptedByCommand: (commandId: string, actorId: string) => boolean;
@@ -51,6 +53,11 @@ export const chatEventsOf = (event: JournalEvent, scope: ChatProjectionScope, cu
   if (event.type === "turn.interrupted")
     return scope.turnOf(event.payload.turnId).actorId === scope.primaryActorId ? journalChatEventsOf(event, cursor, interruptedIn(scope)) : [];
 
+  if (event.type === "runtime.output.recorded" && event.actorId !== scope.primaryActorId) {
+    const handle = scope.scriptActorHandle?.(event.actorId);
+    return handle ? [{ kind: "system", text: `@${handle}: ${event.payload.text}`, at }] : [];
+  }
+
   if (event.actorId !== scope.primaryActorId) return [];
 
   if (event.type === "plugin.state-replaced" || event.type === "plugin.state-patched") return [{

package/apps/server/src/ragents/global-chat.ts

@@ -1,6 +1,6 @@
 import { serviceToken, type AccessContext, type CatalogModel, type ExecutableActor, type JournalEvent, type JsonValue, type ModelSelection, type Orchestration, type RunView } from "@ragents/engine";
 import type { GlobalRunPolicy } from "../api/rights.js";
-import type { ChatUser, SessionInfo } from "../chat-handler.js";
+import type { ChatUser, RunScriptListing, SessionInfo, StartedScript } from "../chat-handler.js";
 
 export interface GlobalChatPolicy {
   /** A user's coordinator; without sign-in (null) there is exactly one. */
@@ -49,6 +49,10 @@ export interface RunManagement {
   send: (runId: string, message: string, access: AccessContext) => Promise<void>;
   stop: (runId: string) => Promise<void>;
   resetGlobal: (runId: string) => Promise<void>;
+  /** The run scripts the run's owner may start, and whether each can start in the run now. */
+  scripts: (runId: string) => readonly RunScriptListing[];
+  /** Starts a run script in the run as its owner would; startedBy is the actor that receives its result. */
+  startScript: (runId: string, entryId: string, input: JsonValue | null, startedBy: string) => Promise<StartedScript>;
 }
 
 export const globalChatToken = serviceToken<GlobalChatPolicy>("host.global-chat");