@cotal-ai/manager 0.106.1 → 0.107.0

package/dist/manager.js

@@ -376,6 +376,12 @@ export class Manager {
     /** See {@link ManagerOptions.installedExtensions}. */
     installedExtensions;
     executionState;
+    /** One backend per kind a seat has asked for, beside {@link runtime}. The manager's own runtime
+     *  stays the default and is never replaced by a later seat's choice. */
+    runtimes = new Map();
+    /** Hosted pooled control, recorded so a later seat cannot add a custodial runtime the constructor
+     *  already refused for the manager's own. */
+    pooled;
     /** Internal test seam. Production leaves this undefined and uses the scoped delivery-admin evictor. */
     staticLifecycleEvict;
     preserveStopTimeoutMs;
@@ -715,6 +721,7 @@ export class Manager {
         if (opts.secretStore)
             this.secretStoreIdentity = injectedSecretStoreIdentity(opts.secretStore);
         this.installedExtensions = opts.installedExtensions ?? false;
+        this.pooled = opts.pooled === true;
         this.executionState = opts.execution === "none" ? { kind: "none" } : { kind: "runtime" };
         if (!this.remoteAuthority) {
             const local = loadManagerInstanceIdentity(this.workspaceRoot, this.space);
@@ -772,6 +779,30 @@ export class Manager {
             throw new EpEnvelopeError("unimplemented", this.executionRefusal());
         return this.runtime;
     }
+    /** The backend one seat launches, restarts, and is reaped through. An omitted or blank choice is
+     *  this manager's own runtime. A named one is created once, cached by its resolved kind, and reused
+     *  for every later seat of that kind. The manager's own runtime is never replaced. An unknown or
+     *  unreachable runtime throws, and pooled control refuses a custodial one by the same rule the
+     *  constructor applied to the manager's own. */
+    runtimeFor(kind) {
+        if (this.executionState.kind === "none")
+            throw new EpEnvelopeError("unimplemented", this.executionRefusal());
+        const asked = kind?.trim();
+        if (!asked)
+            return this.runtime;
+        if (asked === "auto")
+            throw new Error(`runtime "auto" chooses the manager's runtime, not one seat; omit runtime to use ${this.runtime.kind}`);
+        if (asked === this.runtime.kind)
+            return this.runtime;
+        const cached = this.runtimes.get(asked);
+        if (cached)
+            return cached;
+        const runtime = createRuntime(asked, `cotal-${this.space}`);
+        if (this.pooled && isCustodialRuntime(runtime))
+            throw new Error(`pooled control refuses custodial runtime "${runtime.kind}" before starting agents`);
+        this.runtimes.set(runtime.kind, runtime);
+        return runtime;
+    }
     /** What a default process stop does with this manager's seats. `release` drops manager-local
      *  custody and leaves every seat running. `stop` means this runtime keeps its PTYs inside the
      *  manager process, so those seats close with it: the stop stops and deprovisions them, and still
@@ -4546,10 +4577,11 @@ export class Manager {
                     .reduce((max, p) => Math.max(max, p.ts), 0) + 1;
                 // Same ordering as the spawn path: the replacement seat's reference is recorded on the
                 // still-active slot before its processes exist, so a crash here never strands it.
-                const custody = this.reserveCustody();
+                const runtime = this.runtimeFor(a.launch.runtime);
+                const custody = this.reserveCustody(runtime);
                 if (custody)
                     await this.recordSlotCustody(a, custody);
-                const handle = await this.spawnCustodied(a.name, spec, a.launch.cwd, custody);
+                const handle = await this.spawnCustodied(runtime, a.name, spec, a.launch.cwd, custody);
                 replacement = handle;
                 restart.sessionStatePath = spec.sessionStatePath ?? restart.sessionStatePath;
                 if (continueSession !== undefined) {
@@ -4727,6 +4759,8 @@ export class Manager {
         // scalar/array (the CLI never does). Core doesn't interpret the keys; the connector validates them.
         if (args.launchOptions !== undefined && (typeof args.launchOptions !== "object" || args.launchOptions === null || Array.isArray(args.launchOptions)))
             return Promise.resolve({ ok: false, error: "launchOptions: expected a key:value mapping" });
+        if (args.runtime !== undefined && (typeof args.runtime !== "string" || !args.runtime.trim()))
+            return Promise.resolve({ ok: false, error: "runtime: expected a non-empty runtime name" });
         let supervise;
         if (args.supervise !== undefined) {
             const raw = args.supervise;
@@ -4815,6 +4849,7 @@ export class Manager {
             allowPublish,
             shareTools,
             ...(supervise !== undefined ? { supervise } : {}),
+            ...(typeof args.runtime === "string" ? { runtime: args.runtime.trim() } : {}),
             route,
         }, caller, hooks, authenticatedCaller);
     }
@@ -5234,6 +5269,13 @@ export class Manager {
         // Before the first await, so the grant, the launch, the retained form and the restart slot all read
         // the lists and the restart policy as admitted.
         opts = ownLists(opts);
+        let runtime;
+        try {
+            runtime = this.runtimeFor(opts.runtime);
+        }
+        catch (e) {
+            return { ok: false, error: rejectionText(e) };
+        }
         if (opts.resolved)
             opts.resolved = ownLists(opts.resolved);
         if (opts.supervise)
@@ -5312,8 +5354,8 @@ export class Manager {
         // exit, so a name cannot be respawned in place. User-mode seats have no static slot that
         // keeps the incarnation owned across a process death, so the same refusal applies there.
         if (opts.supervise !== undefined) {
-            if (this.requiredRuntime.kind !== "pty")
-                return { ok: false, error: `supervise is a restart policy this host cannot enforce: runtime "${this.requiredRuntime.kind}" cannot respawn a name in place` };
+            if (runtime.kind !== "pty")
+                return { ok: false, error: `supervise is a restart policy this host cannot enforce: runtime "${runtime.kind}" cannot respawn a name in place` };
             if (this.userMode)
                 return { ok: false, error: "supervise is a restart policy this host cannot enforce: a user-mode seat has no static slot to keep the incarnation owned across a process death" };
         }
@@ -5330,8 +5372,8 @@ export class Manager {
         }
         // A delegated seat starts outside this host from values alone, so a choice only this host can
         // honour is refused here, before enrollment, and named rather than dropped.
-        if (this.requiredRuntime.spawnDelegated) {
-            const delegatedBy = `runtime "${this.requiredRuntime.kind}" starts seats outside this host`;
+        if (runtime.spawnDelegated) {
+            const delegatedBy = `runtime "${runtime.kind}" starts seats outside this host`;
             if (!this.remoteAuthority?.enrollManagedAgent)
                 return { ok: false, error: `${delegatedBy}, which needs a host that enrolls managed agents (remoteAuthority.enrollManagedAgent); a delegated seat has no local grant path` };
             try {
@@ -5508,9 +5550,9 @@ export class Manager {
             }
         }
         // The child takes launch options as `--opt k=v`, so only string values can cross to it.
-        const unportable = this.requiredRuntime.spawnDelegated ? Object.keys(launchOptions ?? {}).filter((k) => typeof launchOptions[k] !== "string") : [];
+        const unportable = runtime.spawnDelegated ? Object.keys(launchOptions ?? {}).filter((k) => typeof launchOptions[k] !== "string") : [];
         if (unportable.length)
-            return { ok: false, error: `runtime "${this.requiredRuntime.kind}" starts seats outside this host, so it cannot pass non-string launch options (${unportable.join(", ")})` };
+            return { ok: false, error: `runtime "${runtime.kind}" starts seats outside this host, so it cannot pass non-string launch options (${unportable.join(", ")})` };
         // The AG-UI event plane is on unless the launch explicitly opted out. Refused HERE, before
         // anything is minted: a connector that cannot
         // emit must fail before provisioning rather than after, exactly as an unsupported `resume` does.
@@ -5599,7 +5641,7 @@ export class Manager {
             // launch. Minting it inside `runtime.spawn` (as it used to be) put the processes on disk
             // before anything recorded how to address them, so a crash in that window left a live seat
             // outside every manager and the successor retired the slot over it.
-            const custody = this.reserveCustody();
+            const custody = this.reserveCustody(runtime);
             // ACCEPT SEAM (spawn-as-action): the incarnation identity is minted and NOTHING has
             // been provisioned yet — the action serve path binds the goal + replies the acceptance HERE. A
             // throw (bind conflict / duplicate goalId) aborts the spawn before provisioning: the catch below
@@ -5820,12 +5862,12 @@ export class Manager {
             // manager path is produced for it, only the handoff its runtime writes into the child.
             let spec;
             let handle;
-            if (this.requiredRuntime.spawnDelegated) {
+            if (runtime.spawnDelegated) {
                 const handoff = this.composeManagedHandoff(enrolled.material, enrolled.actorToken);
                 if (this.delegatedLaunched.has(lifecycleUid))
-                    throw new Error(`lifecycle ${lifecycleUid} was already handed to runtime "${this.requiredRuntime.kind}"; a lifecycle is handed off at most once`);
+                    throw new Error(`lifecycle ${lifecycleUid} was already handed to runtime "${runtime.kind}"; a lifecycle is handed off at most once`);
                 this.delegatedLaunched.add(lifecycleUid);
-                handle = this.requiredRuntime.spawnDelegated({ agent, persona: readFileSync(configPath, "utf8"), managerInstanceId: this.managerInstanceId, role, model, variant, prompt, launchOptions: launchOptions, events }, handoff);
+                handle = runtime.spawnDelegated({ agent, persona: readFileSync(configPath, "utf8"), managerInstanceId: this.managerInstanceId, role, model, variant, prompt, launchOptions: launchOptions, events }, handoff);
             }
             else {
                 if (carried) {
@@ -5837,7 +5879,7 @@ export class Manager {
                 if (carried)
                     this.transcripts.consume(opts.resumeClaim, opts.resume);
                 spec.env = { ...spec.env, COTAL_MANAGER_INSTANCE: this.managerInstanceId };
-                handle = await this.spawnCustodied(name, spec, cwd, custody);
+                handle = await this.spawnCustodied(runtime, name, spec, cwd, custody);
             }
             hooks?.onLaunched?.(); // The "launched" progress edge (process spawned, pre-presence)
             const managed = {
@@ -5860,6 +5902,7 @@ export class Manager {
                 control: spec?.control,
                 ...(spec ? {} : { handedOff: true }),
                 launch: {
+                    runtime: runtime.kind,
                     source: opts.resolved
                         ? {
                             kind: "manifest",
@@ -6027,7 +6070,7 @@ export class Manager {
             // "no role", so dropping the key preserves the reply (surfaced by readiness:live).
             // A host that granted other channels than this spawn asked for: the receipt carries both.
             const acl = enrolled ? enrolledAcl({ allowSubscribe, allowPublish }, enrolled.material) : undefined;
-            const okData = { name, agent, id: managed.id, mode: handle.kind, streamsTerminal: this.streamsTerminal, lifecycleUid, ...(role !== undefined ? { role } : {}), ...(opts.eventsNotice !== undefined ? { eventsNotice: opts.eventsNotice } : {}), ...(acl ? { acl } : {}), ...(readiness.operator !== undefined ? { waitingFor: readiness.operator } : {}) };
+            const okData = { name, agent, id: managed.id, mode: handle.kind, streamsTerminal: runtime.streamsTerminal, lifecycleUid, ...(role !== undefined ? { role } : {}), ...(opts.eventsNotice !== undefined ? { eventsNotice: opts.eventsNotice } : {}), ...(acl ? { acl } : {}), ...(readiness.operator !== undefined ? { waitingFor: readiness.operator } : {}) };
             await hooks?.onOutcome?.({ kind: "succeeded", data: okData });
             return { ok: true, data: okData };
         }
@@ -6371,7 +6414,8 @@ export class Manager {
     async orphanedResumeSeat(entry, principal, liveRoster) {
         if (!this.auth || this.userMode || entry.identity.mode !== "static")
             return undefined;
-        if (typeof this.requiredRuntime.reap !== "function")
+        const runtime = this.runtimeFor(entry.launch.runtime);
+        if (typeof runtime.reap !== "function")
             return undefined;
         if (liveRoster.some((p) => p.card.id === principal && p.lifecycleUid !== entry.identity.lifecycleUid))
             return undefined;
@@ -6380,14 +6424,14 @@ export class Manager {
             return undefined;
         if (ownedBySibling(slot, this.managerInstanceId))
             return undefined;
-        return slot.runtime?.kind === this.requiredRuntime.kind ? slot.runtime : undefined;
+        return slot.runtime?.kind === runtime.kind ? slot.runtime : undefined;
     }
     /** Reap a seat {@link orphanedResumeSeat} found, then wait for its principal to leave presence so
      *  the relaunch's readiness cannot match the dead seat's row. Returns the refusal when the reap
      *  proves nothing or the principal stays live, which means another process holds it. */
     async reapOrphanedResumeSeat(principal, reference) {
         try {
-            const evidence = await requireRuntimeReap(this.requiredRuntime, reference);
+            const evidence = await requireRuntimeReap(this.runtimeFor(reference.kind), reference);
             console.error(`resume: reaped orphaned seat ${reference.kind}:${reference.id} of retained principal "${principal}" (${evidence.detail})`);
         }
         catch (e) {
@@ -6413,8 +6457,8 @@ export class Manager {
         try {
             if (entry.space !== this.space)
                 return { ok: false, error: `retained agent ${entry.name} belongs to space "${entry.space}", not "${this.space}"` };
-            if (entry.launch.runtime !== this.requiredRuntime.kind)
-                return { ok: false, error: `retained agent ${entry.name} requires runtime "${entry.launch.runtime}", current manager uses "${this.requiredRuntime.kind}"` };
+            if (entry.launch.runtime !== this.runtimeFor(entry.launch.runtime).kind)
+                return { ok: false, error: `retained agent ${entry.name} requires runtime "${entry.launch.runtime}", which this manager cannot resolve` };
             const nameErr = this.nameError(entry.name);
             if (nameErr)
                 return { ok: false, error: nameErr };
@@ -6586,11 +6630,12 @@ export class Manager {
             if (!Number.isSafeInteger(readinessTimeoutMs) || readinessTimeoutMs <= 0)
                 return { ok: false, error: `connector ${connector.name} declares invalid readinessTimeoutMs ${JSON.stringify(connector.readinessTimeoutMs)}; expected a positive safe integer` };
             const resumeId = entry.identity.mode === "user" ? principalKey(entry.identity.owner, entry.identity.actor).key : entry.identity.id;
-            const custody = this.reserveCustody();
+            const runtime = this.runtimeFor(entry.launch.runtime);
+            const custody = this.reserveCustody(runtime);
             if (custody)
                 await this.recordSlotCustody({ name: entry.name, id: resumeId, lifecycleUid: entry.identity.lifecycleUid }, custody);
             prepared.spawned = true;
-            const handle = await this.spawnCustodied(entry.name, prepared.spec, entry.launch.cwd, custody);
+            const handle = await this.spawnCustodied(runtime, entry.name, prepared.spec, entry.launch.cwd, custody);
             const managed = {
                 name: entry.name,
                 role: entry.role,
@@ -6615,6 +6660,7 @@ export class Manager {
                 handle,
                 control: prepared.spec.control,
                 launch: {
+                    runtime: entry.launch.runtime,
                     source: entry.launch.source,
                     cwd: entry.launch.cwd,
                     model: entry.launch.model,
@@ -9220,14 +9266,14 @@ export class Manager {
     /** Mint the custody reference for a seat this manager is about to spawn, BEFORE the processes
      *  exist. Absent for a runtime with no durable custody (there is nothing a successor could reap
      *  by reference), which is the only case that still spawns unreserved. */
-    reserveCustody() {
-        return isCustodialRuntime(this.requiredRuntime) ? this.requiredRuntime.reserve() : undefined;
+    reserveCustody(runtime) {
+        return isCustodialRuntime(runtime) ? runtime.reserve() : undefined;
     }
     /** Spawn under a reserved reference and prove the runtime honoured it. A runtime that minted its
      *  own id instead would leave every durable record addressing a seat that does not exist, so the
      *  mismatch tears the new seat down and throws rather than returning an unaddressable handle. */
-    async spawnCustodied(name, spec, cwd, reserved) {
-        const handle = this.requiredRuntime.spawn(name, spec, cwd, reserved);
+    async spawnCustodied(runtime, name, spec, cwd, reserved) {
+        const handle = runtime.spawn(name, spec, cwd, reserved);
         if (reserved === undefined)
             return handle;
         const got = handle.reference;
@@ -9249,7 +9295,7 @@ export class Manager {
         }
         else {
             try {
-                const evidence = await requireRuntimeReap(this.requiredRuntime, got);
+                const evidence = await requireRuntimeReap(runtime, got);
                 disposal = `the spawned seat was reaped (${evidence.detail})`;
             }
             catch (e) {
@@ -9263,7 +9309,7 @@ export class Manager {
                         : `the spawned seat could NOT be reaped: ${rejectionText(e)}`;
             }
         }
-        throw new Error(`runtime "${this.requiredRuntime.kind}" reserved custody ${reserved.kind}:${reserved.id} for "${name}" but spawned ` +
+        throw new Error(`runtime "${runtime.kind}" reserved custody ${reserved.kind}:${reserved.id} for "${name}" but spawned ` +
             `${got ? `${got.kind}:${got.id}` : "a handle with no reference"}; the recorded reference would address no seat, so ${disposal}`);
     }
     /** Persist what a successor needs to take this seat back if this process ends without stopping
@@ -9276,7 +9322,8 @@ export class Manager {
         if (!this.auth || this.userMode)
             return;
         const policy = a.restart?.policy;
-        const adoptable = a.handle.reference !== undefined && typeof this.requiredRuntime.adopt === "function";
+        const runtime = this.runtimeFor(a.handle.kind);
+        const adoptable = a.handle.reference !== undefined && typeof runtime.adopt === "function";
         if (!policy && !adoptable)
             return;
         const agent = this.resumeEntryOf(a);
@@ -9325,8 +9372,8 @@ export class Manager {
             return undefined;
         if (record.instanceId !== this.managerInstanceId || record.agent.space !== this.space)
             return undefined;
-        if (record.agent.launch.runtime !== this.requiredRuntime.kind) {
-            console.error(`! ${row.alias}: its seat ran on runtime "${record.agent.launch.runtime}" and this manager uses "${this.requiredRuntime.kind}"; the lifecycle is retired, not restarted`);
+        if (record.agent.launch.runtime !== row.runtime?.kind) {
+            console.error(`! ${row.alias}: its seat ran on runtime "${record.agent.launch.runtime}" and its slot names "${row.runtime?.kind ?? "none"}"; the lifecycle is retired, not restarted`);
             return undefined;
         }
         return record;
@@ -9341,7 +9388,7 @@ export class Manager {
             return "its record is not a static identity";
         if (row.runtime === undefined)
             return "its slot names no seat";
-        const runtime = this.requiredRuntime;
+        const runtime = this.runtimeFor(row.runtime.kind);
         if (typeof runtime.adopt !== "function")
             return `runtime "${runtime.kind}" cannot adopt a seat`;
         // The credential is the manager's own lifecycle-keyed file, and its seed renews it.
@@ -9383,6 +9430,7 @@ export class Manager {
             // The runtime names an adopted handle by what it holds; the record names the seat.
             handle: { ...adopted, name: entry.name },
             launch: {
+                runtime: entry.launch.runtime,
                 source: entry.launch.source,
                 cwd: entry.launch.cwd,
                 model: entry.launch.model,
@@ -9425,7 +9473,7 @@ export class Manager {
         // names is reaped first. A runtime that cannot prove it gone refuses, and the terminal retires it.
         if (row.runtime !== undefined) {
             try {
-                const evidence = await requireRuntimeReap(this.requiredRuntime, row.runtime);
+                const evidence = await requireRuntimeReap(this.runtimeFor(row.runtime.kind), row.runtime);
                 console.error(`${row.alias}: the seat its previous manager left ${evidence.detail}`);
             }
             catch (error) {
@@ -9470,7 +9518,8 @@ export class Manager {
         // An unproven reap throws from here rather than printing, so it propagates into
         // driveStaticRetirement's catch, which records the failure and HOLDS the name. That is the whole
         // point of refusing: the alias must not be freed while a seat nobody proved gone may still run.
-        const evidence = await requireRuntimeReap(this.requiredRuntime, a.runtime);
+        const runtime = this.runtimeFor(a.runtime.kind);
+        const evidence = await requireRuntimeReap(runtime, a.runtime);
         console.error(`static retirement ${a.name}: orphan seat process ${evidence.detail}`);
     }
     /** The static F1 terminal for one departed incarnation (Unit B): delegates the gate/head CAS
@@ -10667,7 +10716,7 @@ export class Manager {
             // carried through verbatim, and the namespaced detail lets a caller act on the one fact
             // without reading the wording. This is the same answer `input` gives a runtime that cannot
             // write, for the same reason.
-            if (!this.streamsTerminal)
+            if (!this.runtimeFor(a.handle.kind).streamsTerminal)
                 throw new EpEnvelopeError("unimplemented", `the ${a.handle.kind} runtime streams no terminal, so agent "${a.name}" has none to attach: ${rejectionText(e)}`, [{ kind: RUNTIME_NO_TERMINAL_DETAIL, runtime: a.handle.kind }], "not-executed");
             throw new EpEnvelopeError("failed-precondition", rejectionText(e), undefined, "not-executed");
         }