@code-yeongyu/senpi 2026.8.1 → 2026.8.3

package/node_modules/@earendil-works/pi-agent-core/dist/harness/agent-harness.js

@@ -129,6 +129,8 @@ function normalizeHookError(error) {
 export class AgentHarness {
     constructor(options) {
         this.phase = "idle";
+        this.activeTasks = new Map();
+        this.isShutdown = false;
         this.pendingSessionWrites = [];
         this.tools = new Map();
         this.steerQueue = [];
@@ -156,6 +158,10 @@ export class AgentHarness {
         this.steeringQueueMode = options.steeringMode ?? "one-at-a-time";
         this.followUpQueueMode = options.followUpMode ?? "one-at-a-time";
     }
+    assertNotShutDown() {
+        if (this.isShutdown)
+            throw new AgentHarnessError("invalid_state", "AgentHarness has been shut down");
+    }
     getHandlers(type) {
         return this.handlers.get(type);
     }
@@ -253,16 +259,43 @@ export class AgentHarness {
             nextTurn: [...this.nextTurnQueue],
         });
     }
-    startRunPromise() {
+    startOperation() {
+        const abortController = new AbortController();
         let finish = () => { };
-        this.runPromise = new Promise((resolve) => {
+        this.activeAbortController = abortController;
+        void this.track("operation", () => new Promise((resolve) => {
             finish = resolve;
-        });
-        return () => {
-            this.runPromise = undefined;
-            finish();
+        }));
+        return {
+            signal: abortController.signal,
+            finish: () => {
+                this.activeAbortController = undefined;
+                finish();
+            },
         };
     }
+    async track(kind, operation) {
+        let settle = () => { };
+        const settled = new Promise((resolve) => {
+            settle = resolve;
+        });
+        this.activeTasks.set(settled, kind);
+        try {
+            return await operation();
+        }
+        finally {
+            this.activeTasks.delete(settled);
+            settle();
+        }
+    }
+    async waitForTasks(kind) {
+        while (true) {
+            const tasks = [...this.activeTasks].flatMap(([task, taskKind]) => kind === undefined || kind === taskKind ? [task] : []);
+            if (tasks.length === 0)
+                return;
+            await Promise.all(tasks);
+        }
+    }
     async resolveToolContext() {
         if (typeof this.toolContext === "function") {
             return await this.toolContext();
@@ -276,6 +309,7 @@ export class AgentHarness {
         };
     }
     async createTurnState() {
+        this.assertNotShutDown();
         const context = await this.session.buildContext();
         const resources = this.getResources();
         const sessionMetadata = await this.session.getMetadata();
@@ -469,7 +503,7 @@ export class AgentHarness {
                 await this.session.appendSessionName(write.name ?? "");
             }
             else if (write.type === "leaf") {
-                await this.session.getStorage().setLeafId(write.targetId);
+                await this.session.moveTo(write.targetId);
             }
             this.pendingSessionWrites.shift();
         }
@@ -512,7 +546,8 @@ export class AgentHarness {
         await this.handleAgentEvent({ type: "agent_end", messages: [failureMessage] }, signal);
         return [failureMessage];
     }
-    async executeTurn(turnState, text, options) {
+    async executeTurn(turnState, text, signal, options) {
+        this.assertNotShutDown();
         let activeTurnState = turnState;
         let messages = [createUserMessage(text, options?.images)];
         if (this.nextTurnQueue.length > 0) {
@@ -533,21 +568,20 @@ export class AgentHarness {
             systemPrompt: turnState.systemPrompt,
             resources: turnState.resources,
         });
+        this.assertNotShutDown();
         if (beforeResult?.messages)
             messages = [...messages, ...beforeResult.messages];
-        const abortController = new AbortController();
         const getTurnState = () => activeTurnState;
         const setTurnState = (nextTurnState) => {
             activeTurnState = nextTurnState;
         };
-        this.runAbortController = abortController;
         const runResultPromise = (async () => {
             try {
-                return await runAgentLoop(messages, this.createContext(turnState, beforeResult?.systemPrompt), this.createLoopConfig(getTurnState, setTurnState), (event) => this.handleAgentEvent(event, abortController.signal), abortController.signal, this.createStreamFn(getTurnState));
+                return await runAgentLoop(messages, this.createContext(turnState, beforeResult?.systemPrompt), this.createLoopConfig(getTurnState, setTurnState), (event) => this.handleAgentEvent(event, signal), signal, this.createStreamFn(getTurnState));
             }
             catch (error) {
                 try {
-                    return await this.emitRunFailure(activeTurnState.model, error, abortController.signal.aborted, abortController.signal);
+                    return await this.emitRunFailure(activeTurnState.model, error, signal.aborted, signal);
                 }
                 catch (failureError) {
                     const cause = new AggregateError([toError(error), toError(failureError)], "Agent run failed and failure reporting failed");
@@ -566,104 +600,110 @@ export class AgentHarness {
             throw new AgentHarnessError("invalid_state", "AgentHarness prompt completed without an assistant message");
         }
         finally {
-            try {
-                await this.flushPendingSessionWrites();
-            }
-            finally {
-                this.runAbortController = undefined;
-            }
+            await this.flushPendingSessionWrites();
         }
     }
     async prompt(text, options) {
+        this.assertNotShutDown();
         if (this.phase !== "idle")
             throw new AgentHarnessError("busy", "AgentHarness is busy");
         this.phase = "turn";
-        const finishRunPromise = this.startRunPromise();
+        const operation = this.startOperation();
         try {
             const turnState = await this.createTurnState();
-            return await this.executeTurn(turnState, text, options);
+            return await this.executeTurn(turnState, text, operation.signal, options);
         }
         catch (error) {
             this.phase = "idle";
             throw normalizeHarnessError(error, "unknown");
         }
         finally {
-            finishRunPromise();
+            operation.finish();
         }
     }
     async skill(name, additionalInstructions) {
+        this.assertNotShutDown();
         if (this.phase !== "idle")
             throw new AgentHarnessError("busy", "AgentHarness is busy");
         this.phase = "turn";
-        const finishRunPromise = this.startRunPromise();
+        const operation = this.startOperation();
         try {
             const turnState = await this.createTurnState();
             const skill = (turnState.resources.skills ?? []).find((candidate) => candidate.name === name);
             if (!skill)
                 throw new AgentHarnessError("invalid_argument", `Unknown skill: ${name}`);
-            return await this.executeTurn(turnState, formatSkillInvocation(skill, additionalInstructions));
+            return await this.executeTurn(turnState, formatSkillInvocation(skill, additionalInstructions), operation.signal);
         }
         catch (error) {
             this.phase = "idle";
             throw normalizeHarnessError(error, "unknown");
         }
         finally {
-            finishRunPromise();
+            operation.finish();
         }
     }
     async promptFromTemplate(name, args = []) {
+        this.assertNotShutDown();
         if (this.phase !== "idle")
             throw new AgentHarnessError("busy", "AgentHarness is busy");
         this.phase = "turn";
-        const finishRunPromise = this.startRunPromise();
+        const operation = this.startOperation();
         try {
             const turnState = await this.createTurnState();
             const template = (turnState.resources.promptTemplates ?? []).find((candidate) => candidate.name === name);
             if (!template)
                 throw new AgentHarnessError("invalid_argument", `Unknown prompt template: ${name}`);
-            return await this.executeTurn(turnState, formatPromptTemplateInvocation(template, args));
+            return await this.executeTurn(turnState, formatPromptTemplateInvocation(template, args), operation.signal);
         }
         catch (error) {
             this.phase = "idle";
             throw normalizeHarnessError(error, "unknown");
         }
         finally {
-            finishRunPromise();
+            operation.finish();
         }
     }
     async steer(text, options) {
+        this.assertNotShutDown();
         if (this.phase === "idle")
             throw new AgentHarnessError("invalid_state", "Cannot steer while idle");
         this.steerQueue.push(createUserMessage(text, options?.images));
         await this.emitQueueUpdate();
     }
     async followUp(text, options) {
+        this.assertNotShutDown();
         if (this.phase === "idle")
             throw new AgentHarnessError("invalid_state", "Cannot follow up while idle");
         this.followUpQueue.push(createUserMessage(text, options?.images));
         await this.emitQueueUpdate();
     }
     async nextTurn(text, options) {
+        this.assertNotShutDown();
         this.nextTurnQueue.push(createUserMessage(text, options?.images));
         await this.emitQueueUpdate();
     }
     async appendMessage(message) {
-        try {
-            if (this.phase === "idle") {
-                await this.session.appendMessage(message);
+        this.assertNotShutDown();
+        return this.track("mutation", async () => {
+            try {
+                if (this.phase === "idle") {
+                    await this.session.appendMessage(message);
+                }
+                else {
+                    this.pendingSessionWrites.push({ type: "message", message });
+                }
             }
-            else {
-                this.pendingSessionWrites.push({ type: "message", message });
+            catch (error) {
+                throw normalizeHarnessError(error, "session");
             }
-        }
-        catch (error) {
-            throw normalizeHarnessError(error, "session");
-        }
+        });
     }
     async compact(customInstructions) {
+        this.assertNotShutDown();
         if (this.phase !== "idle")
             throw new AgentHarnessError("busy", "compact() requires idle harness");
         this.phase = "compaction";
+        const operation = this.startOperation();
         try {
             const model = this.model;
             if (!model)
@@ -680,17 +720,18 @@ export class AgentHarness {
                 preparation,
                 branchEntries,
                 customInstructions,
-                signal: new AbortController().signal,
+                signal: operation.signal,
             });
             if (hookResult?.cancel)
                 throw new AgentHarnessError("compaction", "Compaction cancelled");
             const provided = hookResult?.compaction;
             const compactResult = provided
                 ? { ok: true, value: provided }
-                : await compact(preparation, this.models, model, customInstructions, undefined, this.thinkingLevel, this.retry, this.retryCallbacks("compaction"));
+                : await compact(preparation, this.models, model, customInstructions, operation.signal, this.thinkingLevel, this.retry, this.retryCallbacks("compaction"));
             if (!compactResult.ok)
                 throw compactResult.error;
             const result = compactResult.value;
+            this.assertNotShutDown();
             const entryId = await this.session.appendCompaction(result.summary, result.firstKeptEntryId, result.tokensBefore, result.details, provided !== undefined, result.usage, result.retainedTail);
             const entry = await this.session.getEntry(entryId);
             if (entry?.type === "compaction") {
@@ -703,12 +744,15 @@ export class AgentHarness {
         }
         finally {
             this.phase = "idle";
+            operation.finish();
         }
     }
     async navigateTree(targetId, options) {
+        this.assertNotShutDown();
         if (this.phase !== "idle")
             throw new AgentHarnessError("busy", "navigateTree() requires idle harness");
         this.phase = "branch_summary";
+        const operation = this.startOperation();
         try {
             const oldLeafId = await this.session.getLeafId();
             if (oldLeafId === targetId)
@@ -727,8 +771,11 @@ export class AgentHarness {
                 replaceInstructions: options?.replaceInstructions,
                 label: options?.label,
             };
-            const signal = new AbortController().signal;
-            const hookResult = await this.emitHook({ type: "session_before_tree", preparation, signal });
+            const hookResult = await this.emitHook({
+                type: "session_before_tree",
+                preparation,
+                signal: operation.signal,
+            });
             if (hookResult?.cancel)
                 return { cancelled: true };
             let summaryEntry;
@@ -742,7 +789,7 @@ export class AgentHarness {
                 const branchSummary = await generateBranchSummary(entries, {
                     models: this.models,
                     model,
-                    signal: new AbortController().signal,
+                    signal: operation.signal,
                     customInstructions: hookResult?.customInstructions ?? options?.customInstructions,
                     replaceInstructions: hookResult?.replaceInstructions ?? options?.replaceInstructions,
                     retry: this.retry,
@@ -773,6 +820,7 @@ export class AgentHarness {
             else {
                 newLeafId = targetId;
             }
+            this.assertNotShutDown();
             const summaryId = await this.session.moveTo(newLeafId, summaryText
                 ? {
                     summary: summaryText,
@@ -800,50 +848,61 @@ export class AgentHarness {
         }
         finally {
             this.phase = "idle";
+            operation.finish();
         }
     }
     getModel() {
         return this.model;
     }
     async setModel(model) {
-        try {
-            const previousModel = this.model;
-            if (this.phase === "idle") {
-                await this.session.appendModelChange(model.provider, model.id);
+        this.assertNotShutDown();
+        return this.track("mutation", async () => {
+            try {
+                const previousModel = this.model;
+                if (this.phase === "idle") {
+                    await this.session.appendModelChange(model.provider, model.id);
+                }
+                else {
+                    this.pendingSessionWrites.push({ type: "model_change", provider: model.provider, modelId: model.id });
+                }
+                this.model = model;
+                await this.emitOwn({ type: "model_update", model, previousModel, source: "set" });
             }
-            else {
-                this.pendingSessionWrites.push({ type: "model_change", provider: model.provider, modelId: model.id });
+            catch (error) {
+                throw normalizeHarnessError(error, "session");
             }
-            this.model = model;
-            await this.emitOwn({ type: "model_update", model, previousModel, source: "set" });
-        }
-        catch (error) {
-            throw normalizeHarnessError(error, "session");
-        }
+        });
     }
     getThinkingLevel() {
         return this.thinkingLevel;
     }
     async setThinkingLevel(level) {
-        try {
-            const previousLevel = this.thinkingLevel;
-            if (this.phase === "idle") {
-                await this.session.appendThinkingLevelChange(level);
+        this.assertNotShutDown();
+        return this.track("mutation", async () => {
+            try {
+                const previousLevel = this.thinkingLevel;
+                if (this.phase === "idle") {
+                    await this.session.appendThinkingLevelChange(level);
+                }
+                else {
+                    this.pendingSessionWrites.push({ type: "thinking_level_change", thinkingLevel: level });
+                }
+                this.thinkingLevel = level;
+                await this.emitOwn({ type: "thinking_level_update", level, previousLevel });
             }
-            else {
-                this.pendingSessionWrites.push({ type: "thinking_level_change", thinkingLevel: level });
+            catch (error) {
+                throw normalizeHarnessError(error, "session");
             }
-            this.thinkingLevel = level;
-            await this.emitOwn({ type: "thinking_level_update", level, previousLevel });
-        }
-        catch (error) {
-            throw normalizeHarnessError(error, "session");
-        }
+        });
     }
     getTools() {
         return [...this.tools.values()];
     }
     async setTools(tools, activeToolNames) {
+        this.assertNotShutDown();
+        return this.track("mutation", () => this.applyTools(tools, activeToolNames));
+    }
+    async applyTools(tools, activeToolNames) {
         try {
             this.validateUniqueNames(tools.map((tool) => tool.name), "Duplicate tool name(s)");
             const nextTools = new Map(tools.map((tool) => [tool.name, tool]));
@@ -876,6 +935,10 @@ export class AgentHarness {
         return this.activeToolNames.map((name) => this.tools.get(name));
     }
     async setActiveTools(toolNames) {
+        this.assertNotShutDown();
+        return this.track("mutation", () => this.applyActiveTools(toolNames));
+    }
+    async applyActiveTools(toolNames) {
         try {
             this.validateToolNames(toolNames);
             const previousToolNames = [...this.tools.keys()];
@@ -904,12 +967,14 @@ export class AgentHarness {
         return this.steeringQueueMode;
     }
     async setSteeringMode(mode) {
+        this.assertNotShutDown();
         this.steeringQueueMode = mode;
     }
     getFollowUpMode() {
         return this.followUpQueueMode;
     }
     async setFollowUpMode(mode) {
+        this.assertNotShutDown();
         this.followUpQueueMode = mode;
     }
     getResources() {
@@ -919,6 +984,7 @@ export class AgentHarness {
         };
     }
     async setResources(resources) {
+        this.assertNotShutDown();
         const previousResources = this.getResources();
         this.resources = {
             skills: resources.skills?.slice(),
@@ -930,14 +996,35 @@ export class AgentHarness {
         return cloneStreamOptions(this.streamOptions);
     }
     async setStreamOptions(streamOptions) {
+        this.assertNotShutDown();
         this.streamOptions = cloneStreamOptions(streamOptions);
     }
+    /** Permanently stop this harness instance without deleting its durable session. */
+    requestShutdown() {
+        if (this.isShutdown)
+            return;
+        this.isShutdown = true;
+        this.pendingSessionWrites = [];
+        this.steerQueue = [];
+        this.followUpQueue = [];
+        this.nextTurnQueue = [];
+        this.activeAbortController?.abort();
+        this.shutdownPromise = this.waitForTasks();
+    }
+    /** Waits for work active when shutdown was requested to settle. */
+    waitForShutdown() {
+        if (!this.shutdownPromise) {
+            return Promise.reject(new AgentHarnessError("invalid_state", "Shutdown has not been requested"));
+        }
+        return this.shutdownPromise;
+    }
     async abort() {
+        this.assertNotShutDown();
         const clearedSteer = [...this.steerQueue];
         const clearedFollowUp = [...this.followUpQueue];
         this.steerQueue = [];
         this.followUpQueue = [];
-        this.runAbortController?.abort();
+        this.activeAbortController?.abort();
         const errors = [];
         try {
             await this.emitQueueUpdate();
@@ -964,9 +1051,10 @@ export class AgentHarness {
         return { clearedSteer, clearedFollowUp };
     }
     async waitForIdle() {
-        await this.runPromise;
+        await this.waitForTasks("operation");
     }
     subscribe(listener) {
+        this.assertNotShutDown();
         let handlers = this.handlers.get(SUBSCRIBER_EVENT_TYPE);
         if (!handlers) {
             handlers = new Set();
@@ -976,6 +1064,7 @@ export class AgentHarness {
         return () => handlers.delete(listener);
     }
     on(type, handler) {
+        this.assertNotShutDown();
         let handlers = this.handlers.get(type);
         if (!handlers) {
             handlers = new Set();