@schlenkr/ragents 0.1.13 → 0.1.15

package/bundles/ragents.actor-programs/server/index.js

@@ -5,6 +5,7 @@ const require = __ragentsCreateRequire(import.meta.url);
 import path3 from "node:path";
 import { runtimeProviderToken as runtimeProviderToken2, runGuardToken } from "@ragents/host/ragents/host-services.js";
 import { askServiceToken } from "@ragents/plugins/ragents.ask/server/contract";
+import { surfacePlacementToken } from "@ragents/plugins/ragents.orchestration/server/contract";
 
 // server/agent-tools.ts
 import { ToolRegistry } from "@ragents/engine";
@@ -324,8 +325,9 @@ import { randomUUID } from "node:crypto";
 import { lstat, mkdir, readdir, readFile, realpath as realpath2, rm, writeFile } from "node:fs/promises";
 import { lstatSync, readFileSync, renameSync } from "node:fs";
 import path from "node:path";
+import { isDeepStrictEqual } from "node:util";
 import { Value } from "typebox/value";
-import { actorByHandle, actorDescriptionMaxLength, agentTools, assertJsonValue as assertJsonValue2, canonicalHash, defineRunFunction, defineToolAvailability, emptyUsage, handleKey, runCapabilityContractHash as runCapabilityContractHash2, scriptInputOf, schemaComplaints } from "@ragents/engine";
+import { actorByHandle, actorDescriptionMaxLength, agentTools, assertJsonValue as assertJsonValue2, canonicalHash, defineRunFunction, defineToolAvailability, emptyUsage, handleKey, inheritedGrants, runCapabilityContractHash as runCapabilityContractHash2, scriptInputOf, schemaComplaints } from "@ragents/engine";
 import { ACTOR_PROGRAMS_STATE_ID, ACTOR_INVOCATIONS_STATE_ID, ACTOR_SCRIPT_STATE_ID, ACTOR_STATE_ID, resolveActorView } from "@ragents/host/plugin-support/actor-programs/contract.js";
 
 // server/limits.ts
@@ -360,6 +362,42 @@ var jsonValue = (value, label) => {
   return value;
 };
 
+// server/script-state.ts
+var MAX_OPEN_STARTS = 50;
+var MAX_RESULT_CHARACTERS = 32e3;
+var MAX_SUMMARY_LENGTH = 1e3;
+var SHOWN_RESULT_CHARACTERS = 4e3;
+var isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+var isOrigin = (value) => isRecord(value) && (value.kind === "script" && typeof value.entryId === "string" || value.kind === "shared" && typeof value.pluginId === "string");
+var scriptStateOf = (value) => {
+  if (!isRecord(value) || value.version !== 2 || !isRecord(value.packages) || !Array.isArray(value.deliveries))
+    return { version: 2, packages: {}, deliveries: [] };
+  const packages = Object.entries(value.packages).filter(([, entry]) => isRecord(entry) && isOrigin(entry.origin) && typeof entry.identity === "string");
+  return { ...value, packages: Object.fromEntries(packages) };
+};
+var finishesOf = (value) => {
+  if (value === void 0 || value === null) return [];
+  if (!isRecord(value) || !Array.isArray(value.finishes)) throw new Error("The program returned an invalid finish list.");
+  return value.finishes.map((entry) => {
+    if (!isRecord(entry) || !Number.isInteger(entry.start) || entry.start < 1) throw new Error("finish needs the count of an open start.");
+    const result = entry.result ?? null;
+    if (JSON.stringify(result).length > MAX_RESULT_CHARACTERS) throw new Error(`The result of finish is larger than ${MAX_RESULT_CHARACTERS} characters as JSON.`);
+    if (entry.summary !== void 0 && (typeof entry.summary !== "string" || entry.summary.length > MAX_SUMMARY_LENGTH)) {
+      throw new Error(`The summary of finish must be a text of at most ${MAX_SUMMARY_LENGTH} characters.`);
+    }
+    return { start: entry.start, result, ...typeof entry.summary === "string" ? { summary: entry.summary } : {} };
+  });
+};
+var agentResultText = (handle, finish) => {
+  const headline = `Run script @${handle} finished start ${finish.start}${finish.summary ? `: ${finish.summary}` : "."}`;
+  if (finish.result === null) return headline;
+  const json = JSON.stringify(finish.result);
+  const shown = json.length > SHOWN_RESULT_CHARACTERS ? `${json.slice(0, SHOWN_RESULT_CHARACTERS)}... (shortened, ${json.length} characters)` : json;
+  return `${headline}
+Result: ${shown}`;
+};
+var scriptResultContent = (handle, finish) => JSON.stringify({ handle, count: finish.start, result: finish.result, ...finish.summary !== void 0 ? { summary: finish.summary } : {} });
+
 // server/capability-resolver.ts
 import {
   runCapabilityBindingHash,
@@ -421,7 +459,7 @@ var agentCapabilityBinding = (actor, tools, capabilityIds, blockedNames) => {
 
 // server/runtime.ts
 import { compileClientProject, installClientSdk } from "@ragents/host/plugin-support/actor-programs/client-compiler.js";
-import { compileAppBackend, installServerSdk, prepareAppProject, prepareAppWorkspace, projectSourceFiles, readAppPackage, typecheckServerProject } from "@ragents/host/plugin-support/actor-programs/app-project.js";
+import { compileAppBackend, installServerSdk, packageIdentity, prepareAppProject, prepareAppWorkspace, projectSourceFiles, readAppPackage, typecheckServerProject } from "@ragents/host/plugin-support/actor-programs/app-project.js";
 import { syncWorkspaceOwnership } from "@ragents/host/plugin-support/workspace-ownership.js";
 import { runManagedProcess, sandboxedLaunch } from "@ragents/workspace-executor";
 
@@ -1023,6 +1061,13 @@ var commitPackage = (staged, directory, name2) => {
     throw error;
   }
 };
+var sameSources = async (directory, files) => packageIdentity(await projectSourceFiles(directory)) === packageIdentity(files);
+var sameOrigin = (left, right) => left.kind === "script" ? right.kind === "script" && left.entryId === right.entryId : right.kind === "shared" && left.pluginId === right.pluginId;
+var originText = (origin) => !origin ? "that no run script installed" : origin.kind === "script" ? `from the run script ${origin.entryId}` : `shared by ${origin.pluginId}`;
+var foreignShared = (name2, pluginId, record2) => {
+  const holder = !record2 ? "that the host did not install" : sameOrigin(record2.origin, { kind: "shared", pluginId }) ? "that was changed in the run" : originText(record2.origin);
+  return new Error(`${name2} is the shared actor package of ${pluginId}, but this run has a package ${name2} ${holder}; the host neither uses nor replaces it. Remove or rename that package.`);
+};
 var descriptor = (tool) => ({ id: tool.name, label: tool.label, description: tool.description, schema: tool.schema, resultSchema: tool.resultSchema });
 var ActorProgramRuntime = class {
   #options;
@@ -1033,6 +1078,9 @@ var ActorProgramRuntime = class {
   #staged = /* @__PURE__ */ new Set();
   #removing = /* @__PURE__ */ new Set();
   #knownRuns = /* @__PURE__ */ new Set();
+  #recovered = /* @__PURE__ */ new Set();
+  #packageLocks = /* @__PURE__ */ new Map();
+  #identities = /* @__PURE__ */ new Map();
   #epochs = /* @__PURE__ */ new Map();
   #stopping = /* @__PURE__ */ new Set();
   #shuttingDown = false;
@@ -1088,8 +1136,41 @@ var ActorProgramRuntime = class {
   #writeProgram(context, runId, actorId, program) {
     this.runtime().replacePluginState(this.operatorContext(runId), runId, { pluginId: ACTOR_PROGRAMS_STATE_ID, scope: { kind: "actor", actorId }, state: jsonValue({ version: 1, program }, "Actor program") });
   }
+  /** Which run script installed which package, and the inputs the host queued for programs to recognize. */
   #script(runId) {
-    return this.view(runId).pluginStates.find((entry) => entry.pluginId === ACTOR_SCRIPT_STATE_ID && entry.scope.kind === "run")?.state;
+    return scriptStateOf(this.view(runId).pluginStates.find((entry) => entry.pluginId === ACTOR_SCRIPT_STATE_ID && entry.scope.kind === "run")?.state);
+  }
+  /** Keeps only deliveries whose input is still queued or being processed, and `keep`, whose input follows right after this write. */
+  #writeScript(runId, state, keep) {
+    const live = this.#liveCommands(runId, new Set(state.deliveries.map((delivery) => delivery.actorId)));
+    const deliveries = state.deliveries.filter((delivery) => delivery.commandId === keep || live.has(delivery.commandId));
+    this.runtime().replacePluginState(this.operatorContext(runId, "script"), runId, { pluginId: ACTOR_SCRIPT_STATE_ID, scope: { kind: "run" }, state: jsonValue({ ...state, deliveries }, "Run script state") });
+  }
+  /** The commands that queued inputs of these actors which are pending or belong to a running turn. */
+  #liveCommands(runId, actorIds) {
+    const view = this.view(runId);
+    const running = new Set(view.turns.filter((turn) => turn.status === "running").map((turn) => turn.id));
+    const sequences = new Set(view.inputs.filter((input) => actorIds.has(input.actorId) && (input.lifecycle.kind === "pending" || input.lifecycle.kind === "claimed" && running.has(input.lifecycle.turnId))).map((input) => input.sequence));
+    const commands = /* @__PURE__ */ new Set();
+    if (sequences.size === 0)
+      return commands;
+    const oldest = Math.min(...sequences);
+    for (const event of this.runtime().recentEvents(runId)) {
+      if (event.sequence < oldest)
+        break;
+      if (sequences.has(event.sequence))
+        commands.add(event.commandId);
+    }
+    return commands;
+  }
+  #commandOf(runId, sequence) {
+    for (const event of this.runtime().recentEvents(runId)) {
+      if (event.sequence === sequence)
+        return event.commandId;
+      if (event.sequence < sequence)
+        return void 0;
+    }
+    return void 0;
   }
   async #writeSources(directory, files) {
     for (const source of files) {
@@ -1100,10 +1181,31 @@ var ActorProgramRuntime = class {
       await writeFile(file, source.content, { flag: "wx" });
     }
   }
-  async #refresh(runId, program, signal) {
-    const script = this.#script(runId);
-    const files = script ? this.#options.scriptSources(script.entryId, program.name) : void 0;
-    if (files) {
+  #originSources(name2, origin) {
+    if (origin.kind === "script")
+      return this.#options.scriptSources(origin.entryId, name2);
+    const shared = this.#options.sharedPackage(name2);
+    return shared?.pluginId === origin.pluginId ? shared.files : void 0;
+  }
+  /** The identity of the sources the program was built from; a build never changes, so it is read once. */
+  #identityOf(program) {
+    const known = this.#identities.get(program.directory);
+    if (known !== void 0)
+      return known;
+    const identity = packageIdentity(JSON.parse(readFileSync(path.join(program.directory, "sources.json"), "utf8")));
+    this.#identities.set(program.directory, identity);
+    return identity;
+  }
+  /** A package still built from what its origin installed reloads from the origin's current sources; one changed in the run keeps its own. */
+  #refresh(runId, program, signal) {
+    return this.#withPackages(runId, [program.name], () => this.#reload(runId, program, signal));
+  }
+  async #reload(runId, program, signal) {
+    const record2 = this.#script(runId).packages[program.name];
+    const files = record2 && this.#identityOf(program) === record2.identity ? this.#originSources(program.name, record2.origin) : void 0;
+    if (record2 && files) {
+      const state = this.#script(runId);
+      this.#writeScript(runId, { ...state, packages: { ...state.packages, [program.name]: { ...state.packages[program.name], identity: packageIdentity(files) } } });
       const directory = path.join(await this.workspaceDirectory(runId), program.name);
       for (const entry of await readdir(directory))
         if (entry !== "node_modules")
@@ -1140,6 +1242,30 @@ var ActorProgramRuntime = class {
       throw new Error(`The capability contract of ${program.name} still differs after the reactivation.`);
     return refreshed;
   }
+  async #acquire(key) {
+    const previous = this.#packageLocks.get(key) ?? Promise.resolve();
+    const released = Promise.withResolvers();
+    const held = previous.then(() => released.promise);
+    this.#packageLocks.set(key, held);
+    await previous;
+    return () => {
+      released.resolve();
+      if (this.#packageLocks.get(key) === held)
+        this.#packageLocks.delete(key);
+    };
+  }
+  /** One exclusion per run and package name for creating, activating, installing and ensuring; callers wait instead of failing. */
+  async #withPackages(runId, names, work) {
+    const releases = [];
+    try {
+      for (const name2 of [...new Set(names)].sort())
+        releases.push(await this.#acquire(`${runId}\0${name2}`));
+      return await work();
+    } finally {
+      for (const release of releases.reverse())
+        release();
+    }
+  }
   async workspaceDirectory(runId) {
     this.#knownRuns.add(runId);
     return prepareAppWorkspace(path.join(this.#options.directoryFor(runId), "actor-workspace"));
@@ -1175,7 +1301,10 @@ var ActorProgramRuntime = class {
       await rm(staged, { recursive: true, force: true });
     }
   }
-  async scaffold(runId, name2, templateId) {
+  scaffold(runId, name2, templateId) {
+    return this.#withPackages(runId, [name2], () => this.#scaffold(runId, name2, templateId));
+  }
+  async #scaffold(runId, name2, templateId) {
     const sources = Object.entries(templateFiles(templateById(templateId), name2)).map(([file, content]) => ({ path: file, content }));
     const { built: files } = await this.#create(runId, name2, async (directory) => {
       await this.#writeSources(directory, sources);
@@ -1187,19 +1316,284 @@ var ActorProgramRuntime = class {
     });
     return { name: name2, directory: `@actors/${name2}`, files };
   }
-  async importPackage(context, runId, name2, files, signal, scriptEntryId) {
+  importPackage(context, runId, name2, files, signal) {
+    return this.#withPackages(runId, [name2], () => this.#import(context, runId, name2, files, signal));
+  }
+  async #import(context, runId, name2, files, signal) {
     const { directory } = await this.#create(runId, name2, (staged) => this.#writeSources(staged, files));
     try {
-      if (scriptEntryId)
-        this.runtime().replacePluginState(this.operatorContext(runId), runId, { pluginId: ACTOR_SCRIPT_STATE_ID, scope: { kind: "run" }, state: { version: 1, entryId: scriptEntryId } });
-      await this.activate(context, runId, name2, signal);
-      const program = this.programs(runId).find((entry) => entry.name === name2);
-      return { name: name2, actorId: program.actorId, actorHandle: program.actorHandle, views: program.views.length };
+      await this.#activate(context, runId, name2, true, signal);
+      return this.#activated(runId, name2);
     } catch (error) {
       await rm(directory, { recursive: true, force: true });
       throw error;
     }
   }
+  #activated(runId, name2) {
+    const program = this.#program(runId, name2);
+    return { name: name2, actorId: program.actorId, actorHandle: program.actorHandle, views: program.views.length };
+  }
+  installScript(context, runId, script, signal) {
+    return this.#withPackages(runId, [script.handle, ...script.programs.map((program) => program.name), ...script.sharedPrograms], () => this.#install(context, runId, script, signal));
+  }
+  async #install(context, runId, script, signal) {
+    const root = await this.workspaceDirectory(runId);
+    const before = this.#script(runId).packages;
+    const own = { kind: "script", entryId: script.entryId };
+    const programs = [
+      ...script.programs.map((program) => ({ ...program, origin: own })),
+      ...script.sharedPrograms.map((name2) => {
+        const shared = this.#options.sharedPackage(name2);
+        if (!shared)
+          throw new Error(`The run script ${script.entryId} needs the shared actor package ${name2}, which no plugin of this profile provides.`);
+        return { name: name2, files: shared.files, origin: { kind: "shared", pluginId: shared.pluginId } };
+      })
+    ];
+    const present = await this.#presentPrograms(root, script.entryId, programs, before);
+    const reuse = this.#reusesScript(runId, root, script, before);
+    const missing = programs.filter((program) => !present.has(program.name));
+    const claims = this.#claim(runId, [...missing, ...reuse ? [] : [{ name: script.handle, files: script.files, origin: own }]]);
+    const copied = [];
+    try {
+      for (const program of missing) {
+        signal?.throwIfAborted();
+        await this.#create(runId, program.name, (staged) => this.#writeSources(staged, program.files));
+        copied.push(program.name);
+      }
+      return reuse ? await this.#restartScript(context, runId, script.handle, signal) : await this.#import(context, runId, script.handle, script.files, signal);
+    } catch (error) {
+      for (const name2 of copied)
+        await rm(path.join(root, name2), { recursive: true, force: true });
+      try {
+        this.#release(runId, claims);
+      } catch (release) {
+        throw new Error(`${errorText(error)} The ownership record could not be removed again (${errorText(release)}); it names no package and the next start replaces it.`);
+      }
+      throw error;
+    }
+  }
+  /** Ownership is recorded before anything is created, so no package the host installs exists without its origin. */
+  #claim(runId, packages) {
+    const state = this.#script(runId);
+    const claims = packages.map((entry) => {
+      const previous = state.packages[entry.name];
+      return { name: entry.name, previous, claimed: { origin: entry.origin, identity: packageIdentity(entry.files), count: previous && sameOrigin(previous.origin, entry.origin) ? previous.count : 0, open: [] } };
+    });
+    if (claims.length > 0)
+      this.#writeScript(runId, { ...state, packages: { ...state.packages, ...Object.fromEntries(claims.map((claim) => [claim.name, claim.claimed])) } });
+    return claims;
+  }
+  /** Compare and swap: a record someone changed since the claim stays as it is. */
+  #release(runId, claims) {
+    const state = this.#script(runId);
+    const released = claims.filter((claim) => isDeepStrictEqual(state.packages[claim.name], claim.claimed));
+    if (released.length === 0)
+      return;
+    const names = new Set(released.map((claim) => claim.name));
+    const kept = Object.entries(state.packages).filter(([name2]) => !names.has(name2));
+    const restored = released.flatMap((claim) => claim.previous ? [[claim.name, claim.previous]] : []);
+    this.#writeScript(runId, { ...state, packages: Object.fromEntries([...kept, ...restored]) });
+  }
+  /** Whether the host installed this shared package from this plugin and nobody changed it since. */
+  #hostShared(record2, pluginId, identity) {
+    return record2 !== void 0 && sameOrigin(record2.origin, { kind: "shared", pluginId }) && record2.identity === identity;
+  }
+  /** The names already in the run that the start keeps; a different package, or one under a shared name the host did not install, is an error before anything is copied. */
+  async #presentPrograms(root, entryId, programs, packages) {
+    const present = await Promise.all(programs.map(async (program) => {
+      const directory = path.join(root, program.name);
+      if (!occupied(directory))
+        return false;
+      if (program.origin.kind === "shared") {
+        if (this.#hostShared(packages[program.name], program.origin.pluginId, packageIdentity(await projectSourceFiles(directory))))
+          return true;
+        throw foreignShared(program.name, program.origin.pluginId, packages[program.name]);
+      }
+      if (await sameSources(directory, program.files))
+        return true;
+      throw new Error(`The run script ${entryId} bundles the program ${program.name}, but this run already has a different package ${program.name} ${originText(packages[program.name]?.origin)}.`);
+    }));
+    return new Set(programs.filter((_, index) => present[index]).map((program) => program.name));
+  }
+  /** A recorded origin without actor and folder is left over from a failed start, whichever template it names, and counts as not installed. */
+  #reusesScript(runId, root, script, packages) {
+    const holder = this.view(runId).actors.find((actor) => actor.handle === script.handle);
+    const exists = occupied(path.join(root, script.handle));
+    if (!holder && !exists)
+      return false;
+    const origin = packages[script.handle]?.origin;
+    if (origin !== void 0 && !sameOrigin(origin, { kind: "script", entryId: script.entryId }))
+      throw new Error(`The package ${script.handle} in this run ${origin.kind === "script" ? `comes from the run script ${origin.entryId}` : `is the shared package of ${origin.pluginId}`}, not from the run script ${script.entryId}.`);
+    if (origin !== void 0 && exists && (!holder || holder.kind === "script"))
+      return true;
+    throw new Error(holder ? `Handle @${script.handle} already belongs to ${holder.displayName} in this run, not to the run script ${script.entryId}.` : `The package ${script.handle} already exists in this run and was not installed by the run script ${script.entryId}.`);
+  }
+  async #restartScript(context, runId, handle, signal) {
+    const view = this.view(runId);
+    const holder = view.actors.find((actor) => actor.handle === handle);
+    const state = holder && view.pluginStates.find((entry) => entry.pluginId === ACTOR_PROGRAMS_STATE_ID && entry.scope.kind === "actor" && entry.scope.actorId === holder.id)?.state;
+    if (!holder || !state?.program)
+      await this.#activate(context, runId, handle, true, signal);
+    else if (holder.kind !== "human" && holder.lifecycle.kind === "stopped")
+      this.runtime().restartActor(context, runId, holder.id, "Run script started again");
+    return this.#activated(runId, handle);
+  }
+  enqueueStart(context, runId, handle, start) {
+    const program = this.#program(runId, handle);
+    const recorded = this.#script(runId).packages[handle];
+    if (!recorded)
+      throw new Error(`The package ${handle} was not installed by a run script.`);
+    const view = program.views[0];
+    if (start.embedded && view)
+      this.#options.placeView(this.operatorContext(runId, "place"), runId, `app:${view.id}`);
+    const state = this.#script(runId);
+    const record2 = state.packages[handle];
+    const count = record2.count + 1;
+    const delivery = { commandId: context.commandId, actorId: program.actorId, kind: "start", name: handle, count, embedded: start.embedded, startedBy: start.startedBy };
+    this.#writeScript(runId, { ...state, packages: { ...state.packages, [handle]: { ...record2, count } }, deliveries: [...state.deliveries, delivery] }, context.commandId);
+    try {
+      this.runtime().enqueueInput(context, runId, { actorId: program.actorId, content: start.content });
+    } catch (error) {
+      const current = this.#script(runId);
+      this.#writeScript(runId, {
+        ...current,
+        packages: { ...current.packages, [handle]: { ...current.packages[handle], count: record2.count } },
+        deliveries: current.deliveries.filter((entry) => entry.commandId !== context.commandId)
+      });
+      throw error;
+    }
+    return { count };
+  }
+  /** A start or result the host queued for this actor, recognized by the command that queued the input; it is consumed here. */
+  #recognize(runId, actorId, input) {
+    const state = this.#script(runId);
+    if (!state.deliveries.some((delivery2) => delivery2.actorId === actorId))
+      return void 0;
+    const commandId = this.#commandOf(runId, input.sequence);
+    const delivery = state.deliveries.find((entry) => entry.commandId === commandId && entry.actorId === actorId);
+    if (!delivery)
+      return void 0;
+    const deliveries = state.deliveries.filter((entry) => entry !== delivery);
+    if (delivery.kind === "result") {
+      this.#writeScript(runId, { ...state, deliveries });
+      return { result: JSON.parse(input.content) };
+    }
+    const record2 = state.packages[delivery.name];
+    const packages = record2 ? { ...state.packages, [delivery.name]: { ...record2, open: [...record2.open, { count: delivery.count, startedBy: delivery.startedBy }].slice(-MAX_OPEN_STARTS) } } : state.packages;
+    this.#writeScript(runId, { ...state, packages, deliveries });
+    const { input: value, options } = JSON.parse(input.content);
+    return { start: { input: value, options, embedded: delivery.embedded, startedBy: delivery.startedBy, count: delivery.count } };
+  }
+  /** Checked before the state commits: every finish ends a different open start of this package. */
+  #finishesOf(runId, program, value) {
+    const finishes = finishesOf(value);
+    const open = new Set(this.#script(runId).packages[program.name]?.open.map((entry) => entry.count) ?? []);
+    for (const [index, finish] of finishes.entries()) {
+      if (!open.has(finish.start) || finishes.findIndex((other) => other.start === finish.start) !== index)
+        throw new Error(`finish: start ${finish.start} of @${program.actorHandle} is not open; it was finished already, never reached the program, or is older than the last ${MAX_OPEN_STARTS} open starts.`);
+    }
+    return finishes;
+  }
+  #deliverResults(request, program, finishes) {
+    if (finishes.length === 0)
+      return;
+    const state = this.#script(request.runId);
+    const record2 = state.packages[program.name];
+    const finished = new Set(finishes.map((finish) => finish.start));
+    const starters = new Map(record2.open.map((entry) => [entry.count, entry.startedBy]));
+    this.#writeScript(request.runId, { ...state, packages: { ...state.packages, [program.name]: { ...record2, open: record2.open.filter((entry) => !finished.has(entry.count)) } } });
+    for (const finish of finishes)
+      this.#deliverResult(request, program, finish, starters.get(finish.start));
+  }
+  /** The owner reads the summary in the chat, an LLM gets a short message, a TypeScript actor a result it recognizes. */
+  #deliverResult(request, program, finish, startedBy) {
+    const starter = this.view(request.runId).actors.find((actor) => actor.id === startedBy);
+    if (!starter || starter.kind === "human") {
+      request.emit({ kind: "runtime", text: finish.summary ?? `Start ${finish.start} finished.` });
+      return;
+    }
+    const commandId = `run-script-result:${request.turnId}:${program.name}:${finish.start}`;
+    try {
+      if (starter.kind === "script") {
+        const state = this.#script(request.runId);
+        this.#writeScript(request.runId, { ...state, deliveries: [...state.deliveries, { commandId, actorId: starter.id, kind: "result" }] }, commandId);
+      }
+      this.runtime().enqueueInput({ actorId: this.ownerId(request.runId), commandId }, request.runId, {
+        actorId: starter.id,
+        presentation: "background",
+        content: starter.kind === "agent" ? agentResultText(program.actorHandle, finish) : scriptResultContent(program.actorHandle, finish)
+      });
+    } catch (error) {
+      request.emit({ kind: "runtime", text: `The result of start ${finish.start} did not reach @${starter.handle}: ${errorText(error)}` });
+    }
+  }
+  isScriptActor(runId, actorId) {
+    return this.runtime().select(runId, (state) => {
+      const actor = state.actors.get(actorId);
+      if (!actor || actor.kind !== "script")
+        return false;
+      const script = [...state.pluginStates.values()].find((entry) => entry.pluginId === ACTOR_SCRIPT_STATE_ID && entry.scope.kind === "run");
+      return Object.hasOwn(scriptStateOf(script?.state).packages, actor.handle);
+    });
+  }
+  programOf(runId, actorId) {
+    const program = this.programs(runId).find((entry) => entry.actorId === actorId);
+    if (!program)
+      return void 0;
+    const record2 = this.#script(runId).packages[program.name];
+    const origin = record2 && this.#identityOf(program) === record2.identity ? record2.origin : { kind: "run", installedBy: program.installedBy };
+    return { name: program.name, actorId, revision: program.revision, origin };
+  }
+  /** Makes a package active once, whatever state it is in; under a shared name only the package the host installed from that plugin, unchanged. */
+  ensure(context, runId, name2, signal) {
+    this.#assertName(name2);
+    return this.#withPackages(runId, [name2], () => this.#ensure(context, runId, name2, signal));
+  }
+  async #ensure(context, runId, name2, signal) {
+    const outcome = (status) => {
+      const program = this.#program(runId, name2);
+      return { actorId: program.actorId, handle: program.actorHandle, status };
+    };
+    const shared = this.#options.sharedPackage(name2);
+    const record2 = this.#script(runId).packages[name2];
+    const assertShared = (identity) => {
+      if (shared && !this.#hostShared(record2, shared.pluginId, identity()))
+        throw foreignShared(name2, shared.pluginId, record2);
+    };
+    const active = this.programs(runId).find((program) => program.name === name2);
+    if (active) {
+      assertShared(() => this.#identityOf(active));
+      return outcome("active");
+    }
+    const view = this.view(runId);
+    const stopped = view.pluginStates.flatMap((entry) => {
+      const program = entry.pluginId === ACTOR_PROGRAMS_STATE_ID && entry.scope.kind === "actor" ? entry.state.program : null;
+      const actor = program?.name === name2 ? view.actors.find((candidate) => candidate.id === program.actorId) : void 0;
+      return program && actor && actor.kind !== "human" && actor.lifecycle.kind === "stopped" ? [{ program, actor }] : [];
+    })[0];
+    if (stopped) {
+      assertShared(() => this.#identityOf(stopped.program));
+      this.runtime().restartActor(context, runId, stopped.actor.id, "Actor program ensured");
+      return outcome("restarted");
+    }
+    const root = await this.workspaceDirectory(runId);
+    if (occupied(path.join(root, name2))) {
+      const identity = packageIdentity(await projectSourceFiles(path.join(root, name2)));
+      assertShared(() => identity);
+      await this.#activate(context, runId, name2, true, signal);
+      return outcome("activated");
+    }
+    if (!shared)
+      throw new Error(`The package ${name2} is neither in this run nor a shared actor package of this profile.`);
+    const claims = this.#claim(runId, [{ name: name2, files: shared.files, origin: { kind: "shared", pluginId: shared.pluginId } }]);
+    try {
+      await this.#import(context, runId, name2, shared.files, signal);
+    } catch (error) {
+      this.#release(runId, claims);
+      throw error;
+    }
+    return outcome("installed");
+  }
   async check(runId, name2, callerId, signal, reference) {
     this.#assertName(name2);
     const directory = path.join(await this.workspaceDirectory(runId), name2);
@@ -1219,7 +1613,7 @@ var ActorProgramRuntime = class {
       handle: name2,
       displayName: pkg.title,
       kind: "script",
-      grants: caller.grants.filter((grant) => grant.delegable),
+      grants: inheritedGrants(caller),
       createdAt: (/* @__PURE__ */ new Date()).toISOString(),
       createdBy: callerId,
       description: actorDescriptionOf(pkg.description) ?? null,
@@ -1330,7 +1724,7 @@ var ActorProgramRuntime = class {
     return { directory, files, definition, clients, frameStyles, createActor: !owner, ...backend ? { backendJavaScript: backend.javaScript } : {} };
   }
   activate(context, runId, name2, signal, reference) {
-    return this.#activate(context, runId, name2, true, signal, reference);
+    return this.#withPackages(runId, [name2], () => this.#activate(context, runId, name2, true, signal, reference));
   }
   async #activate(context, runId, name2, idle, signal, reference) {
     const key = `${runId}\0${name2}`;
@@ -1431,7 +1825,7 @@ var ActorProgramRuntime = class {
         } else if (holder)
           throw new Error(`Handle @${name2} already belongs to the ${holder.kind !== "human" && holder.lifecycle.kind === "stopped" ? "stopped" : "active"} actor ${holder.displayName}; only a stopped TypeScript actor is restarted on activation. Choose another package name.`);
         else
-          this.runtime().createScriptActor(context, runId, { handle: name2, displayName: definition.title, description: actorDescriptionOf(definition.description), grants: caller.grants.filter((grant) => grant.delegable), toolNames: null });
+          this.runtime().createScriptActor(context, runId, { handle: name2, displayName: definition.title, description: actorDescriptionOf(definition.description), grants: inheritedGrants(caller), toolNames: null });
         const actor = this.resolveActor(runId, context.actorId, `@${name2}`);
         definition.actorId = actor.id;
         definition.actorHandle = actor.handle;
@@ -1458,9 +1852,13 @@ var ActorProgramRuntime = class {
     return this.programs(runId).map((program) => ({ name: program.name, actor: `@${program.actorHandle}`, functions: program.functions.map((fn) => fn.id), views: program.views.map((view) => ({ name: view.key, title: view.title, visible: view.visible })) }));
   }
   async remove(context, runId, name2) {
-    const program = this.#program(runId, name2);
+    const packageName = this.#program(runId, name2).name;
+    return this.#withPackages(runId, [packageName], () => this.#remove(context, runId, packageName, name2));
+  }
+  async #remove(context, runId, packageName, name2) {
+    const program = this.#program(runId, packageName);
     this.#assertIdle(runId, program.actorId);
-    if (this.#installing.has(`${runId}\0${name2}`))
+    if (this.#installing.has(`${runId}\0${packageName}`))
       throw new Error("The package is being activated.");
     const actor = this.actor(runId, program.actorId);
     const key = `${runId}\0${program.actorId}`;
@@ -1638,8 +2036,11 @@ ${view.styles}`, platformVersion: 2, clientJavaScript: readFileSync(path.join(pr
       await this.#serial(request.runId, request.agentId, signal, async () => {
         const { program, descriptors } = await this.#bound(request.runId, request.agentId, void 0, signal, inputOf, descriptorsFor);
         const binding = { id: request.turnId, kind: "input", principal: { id: request.agentId, kind: "script" }, descriptorsFor, call: (name2, input, index) => request.invoke(`${request.turnId}:capability:${index}`, name2, input) };
-        const result = await this.#backend(request.runId, program, { kind: "input", input: scriptInputOf(request.input) }, binding, descriptors, signal);
+        const recognized = this.#recognize(request.runId, request.agentId, request.input);
+        const result = await this.#backend(request.runId, program, { kind: "input", input: scriptInputOf(request.input), ...recognized }, binding, descriptors, signal);
+        const finishes = this.#finishesOf(request.runId, program, result.result);
         this.#commitState(request.runId, request.agentId, result.state, result.initial);
+        this.#deliverResults(request, program, finishes);
         for (const text of result.logs)
           request.emit({ kind: "runtime", text });
       });
@@ -1782,12 +2183,14 @@ Input: ${JSON.stringify(input).slice(0, 500)}`, options: ["Run", "Cancel"], mult
   waitForRunSettlement(runId) {
     return Promise.allSettled([...this.#active.values()].filter((entry) => entry.runId === runId).map((entry) => entry.completed).concat([...this.#queues].filter(([key]) => key.startsWith(`${runId}\0`)).map(([, queue]) => queue))).then(() => void 0);
   }
+  /** Once per run and server process: calls a previous process left open are cancelled, calls of this process keep running. */
   async prepareSession(runId) {
     this.#knownRuns.add(runId);
-    if (!this.runtime().listRuns().some((run) => run.id === runId))
+    if (this.#recovered.has(runId) || !this.runtime().listRuns().some((run) => run.id === runId))
       return;
+    this.#recovered.add(runId);
     for (const invocation of this.#invocations(runId).invocations)
-      if (invocation.status === "queued" || invocation.status === "running")
+      if ((invocation.status === "queued" || invocation.status === "running") && !this.#active.has(invocation.id))
         this.#replaceInvocation(runId, { ...invocation, status: "cancelled", error: "The server was stopped during the call.", finishedAt: (/* @__PURE__ */ new Date()).toISOString() });
   }
   async stopSession(runId, _signal) {
@@ -1798,6 +2201,10 @@ Input: ${JSON.stringify(input).slice(0, 500)}`, options: ["Run", "Cancel"], mult
   }
   async deleteSession(runId) {
     await this.stopRun(runId);
+    this.#recovered.delete(runId);
+    for (const directory of this.#identities.keys())
+      if (directory.startsWith(`${this.#options.directoryFor(runId)}${path.sep}`))
+        this.#identities.delete(directory);
     await rm(this.#options.directoryFor(runId), { recursive: true, force: true });
   }
   async shutdown() {
@@ -1816,7 +2223,8 @@ var metadata = [
   { name: "actor_program_list", label: "List Actor Programs", description: "List active actor packages, functions and views." },
   { name: "actor_program_remove", label: "Remove Actor Program", description: "Detach functions and views and stop the backend.", longDescription: "A TypeScript actor is stopped; an LLM actor retains its agent behavior." },
   { name: "actor_view_set_visibility", label: "Show or hide Actor View", description: "Set surface visibility by package-name/view-key or @handle/view-key.", longDescription: "Use names you chose; the server resolves the view ID. A unique view title also works." },
-  { name: "actor_program_diagnostics", label: "Actor Program Diagnostics", description: "Read the last project diagnostics.", longDescription: "Changed errors are automatically supplied before the next model request." }
+  { name: "actor_program_diagnostics", label: "Actor Program Diagnostics", description: "Read the last project diagnostics.", longDescription: "Changed errors are automatically supplied before the next model request." },
+  { name: "actor_program_ensure", label: "Ensure Actor Program", description: "Make a package active once: return it when active, restart its stopped actor, activate it when installed, or install a shared package of the profile.", longDescription: "Safe to call on every start: an active package is returned unchanged and not rebuilt. status names what happened. actor_program_activate instead rebuilds and reactivates." }
 ];
 var actorProgramManagementToolNames = metadata.map((entry) => entry.name);
 var actorProgramToolsAvailable = defineToolAvailability2({ availability: "conditional", availabilityDetail: "For executable actors with agent.spawn and plugin.state.write." }, (actor) => actor.kind !== "human" && holdsUsable(actor, "agent.spawn") && holdsUsable(actor, "plugin.state.write"));
@@ -1827,7 +2235,8 @@ var managementTools = (runtime, diagnostics) => [
   defineRunFunction2({ ...metadata[2], schema: Type.Object({}, { additionalProperties: false }), resultSchema: Type.Array(Type.Object({ name: Type.String(), actor: Type.String(), functions: Type.Array(Type.String()), views: Type.Array(Type.Object({ name: Type.String(), title: Type.String(), visible: Type.Boolean() })) })), available: actorProgramToolsAvailable, executionMode: "sequential", run: (scope) => runtime.list(scope.caller.runId) }),
   defineRunFunction2({ ...metadata[3], schema: Type.Object({ name }, { additionalProperties: false }), resultSchema: Type.Object({ removed: Type.String() }, { additionalProperties: false }), available: actorProgramToolsAvailable, executionMode: "sequential", run: (scope, id, input) => runtime.remove(scope.context(id), scope.caller.runId, input.name) }),
   defineRunFunction2({ ...metadata[4], schema: Type.Object({ view: Type.String({ minLength: 1, description: "package-name/view-key or @handle/view-key of an activated view, without the surface entity prefix app:. No generated IDs needed." }), visible: Type.Boolean() }, { additionalProperties: false }), resultSchema: Type.Object({ view: Type.String(), visible: Type.Boolean() }, { additionalProperties: false }), available: actorProgramToolsAvailable, executionMode: "sequential", run: (scope, id, input) => runtime.setVisibility(scope.context(id), scope.caller.runId, input.view, input.visible) }),
-  defineRunFunction2({ ...metadata[5], schema: Type.Object({ name: Type.Optional(name) }, { additionalProperties: false }), resultSchema: Type.String(), available: actorProgramToolsAvailable, executionMode: "sequential", run: (scope, _id, input) => diagnostics.latest(scope.caller.runId, scope.caller.actorId, input.name) })
+  defineRunFunction2({ ...metadata[5], schema: Type.Object({ name: Type.Optional(name) }, { additionalProperties: false }), resultSchema: Type.String(), available: actorProgramToolsAvailable, executionMode: "sequential", run: (scope, _id, input) => diagnostics.latest(scope.caller.runId, scope.caller.actorId, input.name) }),
+  defineRunFunction2({ ...metadata[6], schema: Type.Object({ name }, { additionalProperties: false }), resultSchema: Type.Object({ actorId: Type.String(), handle: Type.String(), status: Type.Union([Type.Literal("active"), Type.Literal("restarted"), Type.Literal("activated"), Type.Literal("installed")]) }, { additionalProperties: false }), available: actorProgramToolsAvailable, executionMode: "sequential", run: (scope, id, input) => runtime.ensure(scope.context(id), scope.caller.runId, input.name, scope.signal) })
 ];
 var createActorProgramToolContributors = (runtime, diagnostics) => [
   { name: "ragents.actor-programs.management", descriptors: metadata.map((item) => toolDescriptorFrom(item, actorProgramToolsAvailable)), tools: () => managementTools(runtime, diagnostics) },
@@ -2060,6 +2469,10 @@ var actorProgramsPlugin = (pluginHost) => ({
       scriptSources: (entryId, name2) => {
         const script = pluginHost.startEntries.scriptPackage(entryId);
         return !script ? void 0 : script.handle === name2 ? script.files : script.programs.find((program) => program.name === name2)?.files;
+      },
+      sharedPackage: (name2) => pluginHost.actorPackages.get(name2),
+      placeView: (context, runId, entity) => {
+        host.service(surfacePlacementToken).place(context, runId, { entity });
       }
     });
     host.provide(actorProgramsToken, runtime);