@framers/agentos 0.11.6 → 0.12.0

package/dist/cognition/emergent/EmergentCapabilityEngine.js

@@ -13,6 +13,7 @@
  * After registration the engine tracks usage and auto-promotes tools that
  * meet the configured `EmergentConfig.promotionThreshold` criteria.
  */
+import { GMI_INSTANCE_ID_PREFIX } from './types.js';
 import { parsePersistedSource, parseRowSchemas, parseStoredRequest, requestFromImplementation, sessionFromSource, requestFromSource, sourceFromImplementation, stateSetterFromColumn, toolFromRow, } from './persisted-source.js';
 import { normalizeAllowlist, toSandboxApis } from './capabilities.js';
 // ============================================================================
@@ -24,6 +25,35 @@ import { normalizeAllowlist, toSandboxApis } from './capabilities.js';
 /** The configuration key behind a reason, named in the start-up line. */
 const REASON_CONFIG_KEYS = {
     source_not_persisted: 'emergent.persistSandboxSource',
+    sandbox_tools_off: 'emergent.allowSandboxTools',
+    compose_needs_gate: 'a StepGate (deps.stepGate, or the ComposableToolBuilder)',
+    step_not_chainable: 'emergent.compose.sideEffectingTools',
+    side_effects_undeclared: "the step tool's hasSideEffects",
+    step_cycle: "the composition's steps (a step reaches the composition itself)",
+};
+/**
+ * The library's suspensions of a composition that a change in what is
+ * registered can lift: the composition is checked again when a tool one of
+ * its steps names is registered (`onHostToolRegistered`).
+ */
+const STEP_SUSPENSION_REASONS = new Set([
+    'compose_needs_gate',
+    'step_missing',
+    'step_not_chainable',
+    'side_effects_undeclared',
+    'step_replaced',
+    'step_cycle',
+]);
+/** Step refusals a composed call can meet at run time, and the suspension each leads to. */
+const RUN_REFUSAL_REASONS = {
+    step_missing: 'step_missing',
+    step_not_chainable: 'step_replaced',
+    side_effects_undeclared: 'step_replaced',
+    compose_needs_gate: 'compose_needs_gate',
+    step_cycle: 'step_cycle',
+    // The step's tool was replaced between its check and its run: nothing ran,
+    // and the composition waits for a re-check.
+    step_replaced: 'step_replaced',
 };
 // ============================================================================
 // ENGINE
@@ -86,6 +116,12 @@ export class EmergentCapabilityEngine {
         this.onToolForged = deps.onToolForged;
         this.onToolPromoted = deps.onToolPromoted;
         this.onToolRemoved = deps.onToolRemoved;
+        if (deps.stepGate) {
+            this.composableBuilder.bind({ gate: deps.stepGate });
+        }
+        this.composableBuilder.bind({
+            sideEffectingTools: this.config.compose?.sideEffectingTools ?? [],
+        });
     }
     // --------------------------------------------------------------------------
     // PUBLIC: forge
@@ -106,7 +142,9 @@ export class EmergentCapabilityEngine {
      * 6. If rejected: return failure with the judge's reasoning.
      *
      * @param request - The forge request describing the desired tool.
-     * @param context - Caller context containing the agent and session IDs.
+     * @param context - The agent and session ids. `caller` is the forging
+     *   call's own context: a composition's test steps run as that caller, so
+     *   they meet the checks the caller's direct calls meet.
      * @returns A {@link ForgeResult} indicating success or failure.
      */
     async forge(request, context) {
@@ -122,34 +160,68 @@ export class EmergentCapabilityEngine {
         if (request.implementation.mode === 'compose') {
             // ---- COMPOSE MODE ----
             source = JSON.stringify(request.implementation);
-            // Build the composable tool so we can execute test cases against it.
-            const composedTool = this.composableBuilder.build(request.name, request.description, request.inputSchema, request.implementation);
-            // Run every declared test case.
-            const mockContext = {
+            // Every step must be chainable before any test case runs.
+            for (const step of request.implementation.steps) {
+                const verdict = this.composableBuilder.check(step.tool);
+                if (!verdict.ok) {
+                    return {
+                        success: false,
+                        error: `${verdict.code}: step "${step.name}" (tool "${step.tool}"): ${verdict.message}`,
+                    };
+                }
+            }
+            // A composition must not reach itself, through any nesting.
+            const cycle = this.compositionCycle(request.name, request.implementation.steps);
+            if (cycle) {
+                return {
+                    success: false,
+                    error: `step_cycle: "${request.name}" reaches itself through ${cycle.join(' -> ')}`,
+                };
+            }
+            // The test steps run as the forging caller, so they meet the checks the
+            // caller's direct calls meet; a host that builds the engine itself and
+            // passes no caller gets a context of its own.
+            const testContext = context.caller ?? {
                 gmiId: context.agentId,
                 personaId: 'emergent-forge',
                 userContext: { userId: 'system' },
                 correlationId: context.sessionId,
             };
             for (const tc of request.testCases) {
+                let result;
                 try {
-                    const result = await composedTool.execute(tc.input, mockContext);
-                    testResults.push({
-                        input: tc.input,
-                        output: result.output,
-                        success: result.success,
-                        error: result.error,
-                    });
+                    result = await this.composableBuilder.runPipeline(request.implementation, tc.input, testContext, { dry: { stepOutputs: tc.stepOutputs ?? {} } });
                 }
                 catch (err) {
-                    const message = err instanceof Error ? err.message : String(err);
                     testResults.push({
                         input: tc.input,
                         output: undefined,
                         success: false,
-                        error: message,
+                        error: err instanceof Error ? err.message : String(err),
                     });
+                    continue;
                 }
+                const details = result.details;
+                if (details?.code === 'dry_run_needs_output') {
+                    return { success: false, error: result.error };
+                }
+                if (details?.code === 'permission_denied' && !context.caller) {
+                    // A step needs a capability the stand-in context does not carry:
+                    // the test says nothing about the tool, so the forge asks for the
+                    // caller instead of recording a failed test.
+                    return {
+                        success: false,
+                        error: 'caller_context_required: a step of this composition needs a capability; ' +
+                            "pass the forging caller's context (forge(request, { ..., caller }))",
+                    };
+                }
+                testResults.push({
+                    input: tc.input,
+                    output: result.output,
+                    success: result.success,
+                    error: result.error,
+                    ...(details?.effects && details.effects.length > 0 ? { effects: details.effects } : {}),
+                });
             }
         }
         else {
@@ -289,7 +361,16 @@ export class EmergentCapabilityEngine {
                         error: error instanceof Error ? error.message : 'Failed to activate forged tool.',
                     };
                 }
-                const settled = await this.settleRegistration(live);
+                let settled;
+                try {
+                    settled = await this.settleRegistration(live);
+                }
+                catch (error) {
+                    return {
+                        success: false,
+                        error: error instanceof Error ? error.message : 'the forged tool could not be registered',
+                    };
+                }
                 if (settled && settled.reason === 'removed') {
                     // Removed while the host was registering it: nothing is registered.
                     return { success: false, error: 'the tool was removed while it was being forged' };
@@ -334,10 +415,21 @@ export class EmergentCapabilityEngine {
         if (!tool) {
             return null;
         }
+        // A tool that no longer fits what is in force is suspended, not promoted.
+        const refusal = this.refusalFor(tool.implementation, tool.name);
+        if (refusal) {
+            await this.suspendAsLibrary(toolId, refusal);
+            return { success: false, error: `${refusal}: the tool no longer fits and was suspended.` };
+        }
         // Only session-tier tools are eligible for auto-promotion.
         if (tool.tier !== 'session') {
             return null;
         }
+        // An owner with the reserved instance-id prefix is never promoted: an
+        // agent-tier row with that owner reads as one an earlier release wrote.
+        if (tool.createdBy.startsWith(GMI_INSTANCE_ID_PREFIX)) {
+            return null;
+        }
         // Check thresholds.
         const { uses, confidence } = this.config.promotionThreshold;
         if (tool.usageStats.totalUses < uses || tool.usageStats.confidenceScore < confidence) {
@@ -440,30 +532,34 @@ export class EmergentCapabilityEngine {
      * @returns what happened, so a host can tell a registered tool from a refused one.
      */
     async syncPersistedTool(tool) {
-        let row = await this.registry.loadRow(tool.id);
-        if (!row && this.registry.hasStorage()) {
+        const existing = await this.registry.loadRow(tool.id);
+        if (!existing && this.registry.hasStorage()) {
             // No stored row yet: the host hydrates from its own store. The row is
             // written as it was before loading went through the stored row, so the
             // tool's uses are recorded and the next load finds it.
             await this.registry.writeToolRow(tool);
-            row = await this.registry.loadRow(tool.id);
-        }
-        if (row) {
-            // With source persistence off the row holds a redacted record; the
-            // implementation the host supplied is what runs then.
-            return this.admitRow(row, { sourceFallback: sourceFromImplementation(tool.implementation) });
         }
-        const stored = await this.registry.readState(tool.id);
-        return this.admit({
-            toolId: tool.id,
-            name: tool.name,
-            source: sourceFromImplementation(tool.implementation),
-            stored,
-            requestStored: stored?.request != null,
-            legacyActive: tool.isActive ?? true,
-            tier: tool.tier,
-            createdBy: tool.createdBy,
-            buildTool: () => tool,
+        // The row is read for the admission after any write above, so the write
+        // is not a change the admission's read missed.
+        return this.withRead(async (readAt) => {
+            const row = await this.registry.loadRow(tool.id);
+            if (row) {
+                // With source persistence off the row holds a redacted record; the
+                // implementation the host supplied is what runs then.
+                return this.admitRow(row, { readAt, sourceFallback: sourceFromImplementation(tool.implementation) });
+            }
+            const stored = await this.registry.readState(tool.id);
+            return this.admit({
+                toolId: tool.id,
+                name: tool.name,
+                source: sourceFromImplementation(tool.implementation),
+                stored,
+                requestStored: stored?.request != null,
+                legacyActive: tool.isActive ?? true,
+                tier: tool.tier,
+                createdBy: tool.createdBy,
+                buildTool: () => tool,
+            }, { readAt });
         });
     }
     /**
@@ -516,17 +612,47 @@ export class EmergentCapabilityEngine {
             throw new Error("selector_required: loadPersistedTools({ tiers: ['session'] }) needs the sessionId whose tools to load; " +
                 "a session's tools are private to it.");
         }
-        const rows = await this.registry.loadRows(tiers, { agentId, sessionId });
         const outcomes = [];
         const failed = [];
-        for (const row of rows) {
+        // One read for the rows and their admissions: a tool that changes in this
+        // process after the rows were read (a removal, a registration) is read
+        // again before it is adopted.
+        await this.withRead(async (readAt) => {
+            // Code tools first: a stored composition may chain a stored code tool.
+            const rows = (await this.registry.loadRows(tiers, { agentId, sessionId })).sort((a, b) => Number(a.implementation_mode === 'compose') - Number(b.implementation_mode === 'compose'));
+            for (const row of rows) {
+                try {
+                    outcomes.push(await this.admitRow(row, { readAt }));
+                }
+                catch (error) {
+                    const message = error instanceof Error ? error.message : String(error);
+                    failed.push({ toolId: row.id, name: row.name, error: message });
+                    console.warn(`[agentos:emergent] stored tool "${row.name}" (${row.id}) did not load: ${message}`);
+                }
+            }
+        });
+        // A composition can chain another composition loaded after it: those
+        // suspended because a step was missing are admitted once more.
+        for (let i = 0; i < outcomes.length; i += 1) {
+            const outcome = outcomes[i];
+            if (outcome.state !== 'suspended' || outcome.reason !== 'step_missing') {
+                continue;
+            }
             try {
-                outcomes.push(await this.admitRow(row));
+                const again = await this.withRead(async (readAt) => {
+                    const row = await this.registry.loadRow(outcome.toolId);
+                    return row ? this.admitRow(row, { readAt }) : undefined;
+                });
+                if (again) {
+                    outcomes[i] = again;
+                }
             }
             catch (error) {
                 const message = error instanceof Error ? error.message : String(error);
-                failed.push({ toolId: row.id, name: row.name, error: message });
-                console.warn(`[agentos:emergent] stored tool "${row.name}" (${row.id}) did not load: ${message}`);
+                outcomes.splice(i, 1);
+                i -= 1;
+                failed.push({ toolId: outcome.toolId, name: outcome.name, error: message });
+                console.warn(`[agentos:emergent] stored tool "${outcome.name}" (${outcome.toolId}) did not load: ${message}`);
             }
         }
         for (const outcome of outcomes) {
@@ -602,26 +728,69 @@ export class EmergentCapabilityEngine {
      * @returns the outcome, or `undefined` when the tool is unknown.
      */
     async reactivateTool(toolId) {
-        const row = await this.registry.loadRow(toolId);
-        if (row) {
-            return this.admitRow(row, { force: true });
+        return this.recheck(toolId, true);
+    }
+    /**
+     * Called by the host when any tool is registered. A composition the library
+     * suspended because a step was missing, refused, replaced or circular is
+     * checked again when a tool one of its steps names arrives, and registered
+     * when it fits. A host's own suspension is left to the host.
+     */
+    async onHostToolRegistered(toolName) {
+        for (const record of this.registry.listStates()) {
+            if (record.state !== 'suspended' ||
+                record.setBy !== 'library' ||
+                !STEP_SUSPENSION_REASONS.has(record.reason ?? '')) {
+                continue;
+            }
+            if (record.request?.kind !== 'compose' || !record.request.steps.some((step) => step.tool === toolName)) {
+                continue;
+            }
+            try {
+                await this.recheck(record.toolId, false);
+            }
+            catch (error) {
+                console.warn(`[agentos:emergent] could not re-check "${record.toolId}" after "${toolName}" was registered:`, error instanceof Error ? error.message : error);
+            }
         }
-        const tool = this.registry.get(toolId);
-        if (!tool) {
-            return undefined;
+    }
+    async recheck(toolId, force) {
+        return this.withRead(async (readAt) => {
+            const row = await this.registry.loadRow(toolId);
+            if (row) {
+                return this.admitRow(row, { force, readAt });
+            }
+            const tool = this.registry.get(toolId);
+            if (!tool) {
+                return undefined;
+            }
+            const held = this.registry.getState(toolId);
+            return this.admit({
+                toolId,
+                name: tool.name,
+                source: sourceFromImplementation(tool.implementation),
+                stored: held,
+                requestStored: held?.request != null,
+                legacyActive: true,
+                tier: tool.tier,
+                createdBy: tool.createdBy,
+                buildTool: () => tool,
+            }, { force, readAt });
+        });
+    }
+    /**
+     * Run a read of stored rows and the admissions that use it. `readAt` is the
+     * point the read started at; an admission adopts only what has not changed
+     * since (see `EmergentToolRegistry.adopt`).
+     */
+    async withRead(read) {
+        const readAt = this.registry.beginRead();
+        try {
+            return await read(readAt);
+        }
+        finally {
+            this.registry.endRead();
         }
-        const held = this.registry.getState(toolId);
-        return this.admit({
-            toolId,
-            name: tool.name,
-            source: sourceFromImplementation(tool.implementation),
-            stored: held,
-            requestStored: held?.request != null,
-            legacyActive: true,
-            tier: tool.tier,
-            createdBy: tool.createdBy,
-            buildTool: () => tool,
-        }, { force: true });
     }
     admitRow(row, options = {}) {
         const stored = row.state
@@ -676,12 +845,17 @@ export class EmergentCapabilityEngine {
         const { toolId, name } = candidate;
         const depth = options.readmitted ?? 0;
         if (depth < 2) {
-            const fresh = await this.registry.loadRow(toolId);
-            if (fresh) {
-                return this.admitRow(fresh, { ...options, readmitted: depth + 1 });
-            }
-            await this.unregisterIfLive(toolId);
-            return { toolId, name, state: 'demoted', reason: 'removed' };
+            // The tool's queued writes and deletes land first, so the row read next
+            // is the one they leave.
+            await this.registry.settled(toolId);
+            return this.withRead(async (readAt) => {
+                const fresh = await this.registry.loadRow(toolId);
+                if (fresh) {
+                    return this.admitRow(fresh, { ...options, readmitted: depth + 1, readAt });
+                }
+                await this.unregisterIfLive(toolId);
+                return { toolId, name, state: 'demoted', reason: 'removed' };
+            });
         }
         // Nothing is written; the tool is held off here until the next load.
         this.holdStored(toolId, {
@@ -697,10 +871,9 @@ export class EmergentCapabilityEngine {
     }
     async admit(candidate, options = {}) {
         const { toolId, name, source, stored, requestStored } = candidate;
-        // The tool's generation as this admission starts: a removal, a
-        // registration or a row write after this point makes what it holds stale,
-        // and the adoption below is refused.
-        const generation = this.registry.generation(toolId);
+        // The point after which a change makes what this admission holds stale:
+        // where its row was read, or, for a caller that did not say, now.
+        const readAt = options.readAt ?? this.registry.generation(toolId);
         let legacyActive = candidate.legacyActive;
         // A row whose last state write did not finish its flag write: finish it
         // first, so the flag reads what the state row says before anything is
@@ -792,11 +965,11 @@ export class EmergentCapabilityEngine {
         //     ever pass the owner check: it loads suspended rather than running
         //     for everyone. Forging the tool again under the persona is the way
         //     back; `reactivateTool` goes through this same path.
-        if (!refusal && candidate.tier === 'agent' && candidate.createdBy.startsWith('gmi-instance-')) {
+        if (!refusal && candidate.tier === 'agent' && candidate.createdBy.startsWith(GMI_INSTANCE_ID_PREFIX)) {
             refusal = 'legacy_owner';
         }
         if (implementation && !refusal) {
-            refusal = this.refusalFor(implementation);
+            refusal = this.refusalFor(implementation, name);
         }
         if (refusal || !implementation) {
             const reason = refusal ?? 'source_unreadable';
@@ -891,11 +1064,22 @@ export class EmergentCapabilityEngine {
             setBy: 'library',
             at: Date.now(),
             request,
-        }, generation);
+        }, readAt);
         if (!adopted) {
-            // Removed, or replaced under its id, in this process while the row was
-            // being admitted: what this admission read is stale.
-            return { toolId, name, state: 'demoted', reason: 'removed' };
+            // The tool changed in this process after its row was read (removed,
+            // replaced under its id, written again), or a removal of it is still
+            // deleting its rows: what this admission holds may be stale. With
+            // storage the row is read again once the tool's queued writes have run;
+            // without, the registry's own record is the answer.
+            if (this.registry.hasStorage()) {
+                return this.readmit(candidate, options);
+            }
+            const current = this.registry.get(toolId);
+            if (!current) {
+                return { toolId, name, state: 'demoted', reason: 'removed' };
+            }
+            const held = this.registry.getState(toolId);
+            return { toolId, name: current.name, state: held?.state ?? 'active', reason: held?.reason ?? null };
         }
         this.indexTool(tool.id, tool.createdBy, this.extractSessionId(tool.source) ?? `persisted:${tool.id}`);
         if (this.onToolForged) {
@@ -922,49 +1106,133 @@ export class EmergentCapabilityEngine {
      * hold that very object. When it does not (the tool was removed, or
      * replaced under its id, while the registration ran), the executor is
      * brought back in line with the registry: the current tool's executable is
-     * registered again when there is one, so whichever registration landed
-     * last, the current tool is what runs under the name; the stale executable
-     * is taken out when there is none. Returns the outcome to report, or
-     * undefined when the registration stands.
+     * registered (the old name's taken out first when the name changed), or
+     * the stale executable is taken out when the registry holds none. The
+     * registry is read again after every registration, so a change during the
+     * settlement is settled too, up to three rounds. A registration that fails,
+     * or a tool still changing after three rounds, leaves no executable under
+     * the name and throws: a tool that cannot be called is reported, never a
+     * stale executable left running. Returns the outcome to report, or
+     * undefined when the first registration stands.
      */
     async settleRegistration(tool) {
-        const current = this.registry.get(tool.id);
-        if (current === tool) {
-            return undefined;
-        }
-        try {
-            if (current && this.onToolForged) {
-                await this.onToolForged(current, this.createExecutableTool(current));
+        let registered = tool;
+        for (let round = 0; round < 3; round += 1) {
+            const current = this.registry.get(tool.id);
+            if (current === registered) {
+                if (round === 0) {
+                    return undefined;
+                }
+                if (!current) {
+                    this.removeIndexedToolEverywhere(tool.id);
+                    return { toolId: tool.id, name: tool.name, state: 'demoted', reason: 'removed' };
+                }
+                const held = this.registry.getState(tool.id);
+                return { toolId: tool.id, name: current.name, state: held?.state ?? 'active', reason: held?.reason ?? null };
             }
-            else if (!current && this.onToolRemoved) {
-                await this.onToolRemoved(tool);
+            try {
+                if (registered && (!current || current.name !== registered.name) && this.onToolRemoved) {
+                    await this.onToolRemoved(registered);
+                }
+                if (current && this.onToolForged) {
+                    await this.onToolForged(current, this.createExecutableTool(current));
+                }
+                registered = current;
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                await this.dropExecutable(registered ?? current ?? tool);
+                if (!this.registry.get(tool.id)) {
+                    this.removeIndexedToolEverywhere(tool.id);
+                }
+                throw new Error(`the executable of "${tool.name}" (${tool.id}) could not be brought in line with the registry: ${message}`);
             }
         }
-        catch (error) {
-            console.warn(`[agentos:emergent] could not settle the executable of "${tool.name}" (${tool.id}):`, error instanceof Error ? error.message : error);
+        await this.dropExecutable(registered ?? tool);
+        throw new Error(`the executable of "${tool.name}" (${tool.id}) could not be settled: the tool kept changing while it was registered`);
+    }
+    /** Take a tool's executable out of the host, best-effort. */
+    async dropExecutable(tool) {
+        if (!this.onToolRemoved) {
+            return;
         }
-        finally {
-            if (!current) {
-                this.removeIndexedToolEverywhere(tool.id);
-            }
+        try {
+            await this.onToolRemoved(tool);
         }
-        if (!current) {
-            return { toolId: tool.id, name: tool.name, state: 'demoted', reason: 'removed' };
+        catch (error) {
+            console.warn(`[agentos:emergent] could not take out the executable of "${tool.name}" (${tool.id}):`, error instanceof Error ? error.message : error);
         }
-        const held = this.registry.getState(tool.id);
-        return { toolId: tool.id, name: current.name, state: held?.state ?? 'active', reason: held?.reason ?? null };
     }
     /**
      * The library's reason for not running an implementation under the
      * configuration in force, or `null`. Later steps add their checks here, so
      * forging, loading and promotion all ask the same question.
      */
-    refusalFor(implementation) {
-        if (implementation.mode === 'sandbox' && implementation.code.trim() === '') {
-            return 'source_not_persisted';
+    refusalFor(implementation, name) {
+        if (implementation.mode === 'sandbox') {
+            if (!this.config.allowSandboxTools) {
+                return 'sandbox_tools_off';
+            }
+            if (implementation.code.trim() === '') {
+                return 'source_not_persisted';
+            }
+            return null;
+        }
+        for (const step of implementation.steps) {
+            const verdict = this.composableBuilder.check(step.tool);
+            if (!verdict.ok) {
+                return verdict.code;
+            }
+        }
+        if (name !== undefined && this.compositionCycle(name, implementation.steps)) {
+            return 'step_cycle';
+        }
+        return null;
+    }
+    /**
+     * The path of step tool names through which a composition named `name`
+     * reaches itself, or a nested composition reaches one already on the path;
+     * null when there is none. Nested compositions are followed through the
+     * tools the gate resolves now.
+     */
+    compositionCycle(name, steps, path = []) {
+        for (const step of steps) {
+            if (step.tool === name || path.includes(step.tool)) {
+                return [...path, step.tool];
+            }
+            const nested = this.nestedSteps(step.tool);
+            if (nested) {
+                const found = this.compositionCycle(name, nested, [...path, step.tool]);
+                if (found) {
+                    return found;
+                }
+            }
         }
         return null;
     }
+    /** The steps of the emergent composition registered as `toolName`, or undefined. */
+    nestedSteps(toolName) {
+        const resolved = this.composableBuilder.resolve(toolName);
+        if (resolved?.emergentMode !== 'compose' || !resolved.id.startsWith('emergent-tool:')) {
+            return undefined;
+        }
+        const implementation = this.registry.get(resolved.id.slice('emergent-tool:'.length))?.implementation;
+        return implementation?.mode === 'compose' ? implementation.steps : undefined;
+    }
+    /**
+     * A suspension the library sets from a run or a promotion check: written as
+     * the library's (so a later load, or a registration of the missing step
+     * tool, re-checks it), held here, and the executable taken out.
+     */
+    async suspendAsLibrary(toolId, reason) {
+        try {
+            await this.registry.setState(toolId, 'suspended', reason, { setBy: 'library' });
+        }
+        catch (error) {
+            console.warn(`[agentos:emergent] could not store the suspension of "${toolId}" (${reason}):`, error instanceof Error ? error.message : error);
+        }
+        await this.unregisterIfLive(toolId);
+    }
     async unregisterIfLive(toolId) {
         const live = this.registry.get(toolId);
         if (live && this.onToolRemoved) {
@@ -1067,6 +1335,7 @@ export class EmergentCapabilityEngine {
                     },
                     executeTool: deps.executeTool,
                     listTools: deps.listTools,
+                    checkStep: (name) => this.composableBuilder.check(name),
                 }));
             }
             catch {
@@ -1116,7 +1385,12 @@ export class EmergentCapabilityEngine {
             inputSchema: tool.inputSchema,
             outputSchema: tool.outputSchema,
             category: 'emergent',
-            hasSideEffects: tool.implementation.mode === 'sandbox',
+            emergentMode: tool.implementation.mode,
+            // A composition has side effects when one of its steps does (or is a
+            // composition itself); each such step is then asked at the step (see
+            // ToolOrchestrator), not at the composed call.
+            hasSideEffects: tool.implementation.mode === 'sandbox' ||
+                this.composableBuilder.hasSideEffectingStep(tool.implementation),
             execute: async (args, context) => {
                 // The registry no longer holds the tool (removed, or its session
                 // cleaned up) while the executable is still registered: refuse, do
@@ -1151,6 +1425,20 @@ export class EmergentCapabilityEngine {
                 const startTime = performance.now();
                 const result = await baseTool.execute(args, context);
                 const executionTimeMs = Math.round(performance.now() - startTime);
+                // A step that can no longer be chained (its tool was removed or
+                // replaced, or the chain reaches itself) suspends the composition
+                // until a fitting tool is registered.
+                const refused = result.details?.code;
+                const suspendFor = !result.success && refused ? RUN_REFUSAL_REASONS[refused] : undefined;
+                if (suspendFor) {
+                    await this.suspendAsLibrary(tool.id, suspendFor);
+                    return {
+                        success: false,
+                        output: result.output,
+                        error: result.error ?? 'A step of this composition can no longer be chained.',
+                        details: result.details,
+                    };
+                }
                 let success = result.success;
                 let error = result.error;
                 // Track whether the output passed schema validation separately from
@@ -1178,6 +1466,7 @@ export class EmergentCapabilityEngine {
                         success: false,
                         output: result.output,
                         error: error ?? 'Emergent tool execution failed.',
+                        ...(result.details ? { details: result.details } : {}),
                     };
             },
         };