@code-yeongyu/senpi-agent-core 2026.8.1 → 2026.8.3

package/dist/harness/agent-harness.d.ts

@@ -5,8 +5,10 @@ export declare class AgentHarness<TContext extends object | undefined = undefine
     private session;
     readonly models: Models;
     private phase;
-    private runAbortController?;
-    private runPromise?;
+    private activeAbortController?;
+    private readonly activeTasks;
+    private shutdownPromise?;
+    private isShutdown;
     private pendingSessionWrites;
     private model;
     private thinkingLevel;
@@ -24,6 +26,7 @@ export declare class AgentHarness<TContext extends object | undefined = undefine
     private nextTurnQueue;
     private handlers;
     constructor(options: AgentHarnessOptions<TContext, TSkill, TPromptTemplate, TTool>);
+    private assertNotShutDown;
     private getHandlers;
     private emitOwn;
     private emitAny;
@@ -32,7 +35,9 @@ export declare class AgentHarness<TContext extends object | undefined = undefine
     private emitBeforeProviderRequest;
     private emitBeforeProviderPayload;
     private emitQueueUpdate;
-    private startRunPromise;
+    private startOperation;
+    private track;
+    private waitForTasks;
     private resolveToolContext;
     private bindToolContext;
     private createTurnState;
@@ -74,8 +79,10 @@ export declare class AgentHarness<TContext extends object | undefined = undefine
     setThinkingLevel(level: ThinkingLevel): Promise<void>;
     getTools(): TTool[];
     setTools(tools: TTool[], activeToolNames?: string[]): Promise<void>;
+    private applyTools;
     getActiveTools(): TTool[];
     setActiveTools(toolNames: string[]): Promise<void>;
+    private applyActiveTools;
     getSteeringMode(): QueueMode;
     setSteeringMode(mode: QueueMode): Promise<void>;
     getFollowUpMode(): QueueMode;
@@ -84,6 +91,10 @@ export declare class AgentHarness<TContext extends object | undefined = undefine
     setResources(resources: AgentHarnessResources<TSkill, TPromptTemplate>): Promise<void>;
     getStreamOptions(): AgentHarnessStreamOptions;
     setStreamOptions(streamOptions: AgentHarnessStreamOptions): Promise<void>;
+    /** Permanently stop this harness instance without deleting its durable session. */
+    requestShutdown(): void;
+    /** Waits for work active when shutdown was requested to settle. */
+    waitForShutdown(): Promise<void>;
     abort(): Promise<AbortResult>;
     waitForIdle(): Promise<void>;
     subscribe(listener: (event: AgentHarnessEvent<TSkill, TPromptTemplate>, signal?: AbortSignal) => Promise<void> | void): () => void;

package/dist/harness/agent-harness.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"agent-harness.d.ts","sourceRoot":"","sources":["../../src/harness/agent-harness.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"agent-harness.d.ts","sourceRoot":"","sources":["../../src/harness/agent-harness.ts"],"names":[],"mappings":"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"}

package/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();