@code-yeongyu/senpi-agent-core 2026.10.1 → 2026.10.2

package/README.md

@@ -15,6 +15,10 @@ bun add @earendil-works/pi-agent-core
 
 The SQLite session backend and the `node:sqlite` adapter live in a separate package, `@earendil-works/pi-storage-sqlite-node`, so the core package does not pull in runtime builtins or native SQLite dependencies by default. The backend accepts a runtime-specific SQLite factory, allowing other session backends to ship as their own packages in the future.
 
+### Agent harness
+
+This fork keeps the agent harness (`src/harness/**`) in this package, together with its subpath exports (`./node`, `./harness/*`, `./experimental/pico3`) and the SQLite session backend package. Upstream v1.0.0 moved that runtime into `pi-durable`; the fork did not adopt that move, so coding-agent keeps importing the harness from `@earendil-works/pi-agent-core`.
+
 ## Quick Start
 
 ```typescript

package/dist/agent.js

@@ -56,6 +56,11 @@ function createMutableAgentState(initialState) {
         providerDiagnostic: undefined,
     };
 }
+const LLM_ROLES = new Set(["user", "assistant", "toolResult", "system"]);
+/** A queued message with an app-defined role (monitor, task or background-command notices). */
+function isBackgroundNotice(message) {
+    return !LLM_ROLES.has(message.role);
+}
 class PendingMessageQueue {
     constructor(mode) {
         this.messages = [];
@@ -71,11 +76,23 @@ class PendingMessageQueue {
     getClearGeneration() {
         return this.clearGeneration;
     }
+    /**
+     * `one-at-a-time` gives each queued LLM message (user, assistant, tool result, system) its own
+     * drain. Background notices (custom roles, such as monitor or task events) queued back to back
+     * are one batch: a burst of events is answered by one turn instead of one turn per event.
+     */
     peek() {
         if (this.mode === "all")
             return this.messages.slice();
         const first = this.messages[0];
-        return first ? [first] : [];
+        if (!first)
+            return [];
+        if (!isBackgroundNotice(first))
+            return [first];
+        let end = 1;
+        while (end < this.messages.length && isBackgroundNotice(this.messages[end]))
+            end++;
+        return this.messages.slice(0, end);
     }
     drain() {
         const drained = this.peek();

package/dist/harness/compaction/compaction.js

@@ -421,9 +421,22 @@ export async function generateSummaryWithRequest(currentMessages, options, reque
     if (response.stopReason === "error") {
         return err(new CompactionError("summarization_failed", `Summarization failed: ${response.errorMessage || "Unknown error"}`));
     }
+    const unusable = unusableSummary(response, "Summarization");
+    if (unusable !== undefined)
+        return err(new CompactionError("summarization_failed", unusable));
     const textContent = contentTextForSummary(response.content);
     return ok({ text: textContent, usage: response.usage });
 }
+/** Why a settled response cannot replace history: only a clean stop with text and no tool call is a summary. */
+function unusableSummary(response, label) {
+    if (response.stopReason === "length")
+        return `${label} hit the token limit; the summary is incomplete`;
+    if (response.content.some((block) => block.type === "toolCall"))
+        return `${label} attempted to call a tool`;
+    if (contentTextForSummary(response.content).trim().length === 0)
+        return `${label} produced no text`;
+    return undefined;
+}
 /** Prepare session entries for compaction, or return undefined when compaction is not applicable. */
 export function prepareCompaction(pathEntries, settings) {
     if (pathEntries.length === 0 || pathEntries[pathEntries.length - 1].type === "compaction") {
@@ -452,7 +465,7 @@ export function prepareCompaction(pathEntries, settings) {
         compactableEntries = [...virtualRetainedEntries, ...pathEntries.slice(prevCompactionIndex + 1)];
     }
     const boundaryEnd = compactableEntries.length;
-    const tokensBefore = estimateContextTokens(buildContextEntries(pathEntries).flatMap(sessionEntryToContextMessages)).tokens;
+    const tokensBefore = estimateCompactionPathTokens(pathEntries);
     const cutPoint = findCutPoint(compactableEntries, 0, boundaryEnd, settings.keepRecentTokens);
     const historyEnd = cutPoint.isSplitTurn ? cutPoint.turnStartIndex : cutPoint.firstKeptEntryIndex;
     const messagesToSummarize = [];
@@ -492,6 +505,29 @@ export function prepareCompaction(pathEntries, settings) {
         settings,
     });
 }
+/**
+ * Context tokens of a session path. Usage reported before the newest compaction measured the history that
+ * compaction replaced, so only usage reported after it anchors the estimate; until a newer response reports
+ * usage, the summary and retained tail are estimated from their content.
+ */
+function estimateCompactionPathTokens(pathEntries) {
+    const entries = buildContextEntries(pathEntries);
+    let boundary = 0;
+    for (let i = entries.length - 1; i >= 0; i--) {
+        if (entries[i].type === "compaction") {
+            boundary = i + 1;
+            break;
+        }
+    }
+    const since = estimateContextTokens(entries.slice(boundary).flatMap(sessionEntryToContextMessages));
+    if (since.lastUsageIndex !== null)
+        return since.tokens;
+    let tokens = since.tokens;
+    for (const message of dropFailedAssistantTurns(entries.slice(0, boundary).flatMap(sessionEntryToContextMessages))) {
+        tokens += estimateTokens(message);
+    }
+    return tokens;
+}
 const TURN_PREFIX_SUMMARIZATION_PROMPT = `This is the PREFIX of a turn that was too large to keep. The SUFFIX (recent work) is retained.
 
 Summarize the prefix to provide context for the retained suffix:
@@ -567,6 +603,9 @@ async function generateTurnPrefixSummary(messages, model, reserveTokens, thinkin
     if (response.stopReason === "error") {
         return err(new CompactionError("summarization_failed", `Turn prefix summarization failed: ${response.errorMessage || "Unknown error"}`));
     }
+    const unusable = unusableSummary(response, "Turn prefix summarization");
+    if (unusable !== undefined)
+        return err(new CompactionError("summarization_failed", unusable));
     return ok({
         text: contentTextForSummary(response.content),
         usage: response.usage,

package/dist/harness/env/nodejs.js

@@ -700,12 +700,15 @@ export class NodeExecutionEnv {
                     settle(err(callbackError));
                     return;
                 }
-                if (timedOut) {
-                    settle(err(new ExecutionError("timeout", `timeout:${options?.timeout}`)));
-                    return;
-                }
-                if (signal?.aborted) {
-                    settle(err(new ExecutionError("aborted", "aborted")));
+                const interrupted = timedOut
+                    ? new ExecutionError("timeout", `timeout:${options?.timeout}`)
+                    : signal?.aborted
+                        ? new ExecutionError("aborted", "aborted")
+                        : undefined;
+                if (interrupted !== undefined) {
+                    if (spillPath !== undefined)
+                        interrupted.spillPath = spillPath;
+                    settle(err(interrupted));
                     return;
                 }
                 if (spillError) {

package/dist/harness/runtime/drive/structural.js

@@ -833,6 +833,10 @@ export async function recoverStructuralGeneration(lane, drive, effect) {
     }), drive.context);
     return published.kind === "cancel_requested" ? { kind: "continue" } : published.value;
 }
+/** Automatic compaction needs history before its cut; summarizing nothing only spends a provider request. */
+function summarizesHistory(preparation) {
+    return preparation.messagesToSummarize.length > 0 || preparation.turnPrefixMessages.length > 0;
+}
 /** Prepare threshold compaction only when no newer compaction already guards this trigger. */
 export async function prepareCompactionThreshold(lane, drive, checkpoint) {
     const settings = checkpoint.settings.compaction;
@@ -860,7 +864,9 @@ export async function prepareCompactionThreshold(lane, drive, checkpoint) {
     const prepared = prepareCompaction(path.value, settings);
     if (!prepared.ok)
         throw prepared.error;
-    if (prepared.value === undefined || !shouldCompact(prepared.value.tokensBefore, model.contextWindow, settings)) {
+    if (prepared.value === undefined ||
+        !summarizesHistory(prepared.value) ||
+        !shouldCompact(prepared.value.tokensBefore, model.contextWindow, settings)) {
         return { kind: "result", value: undefined };
     }
     return {
@@ -870,7 +876,7 @@ export async function prepareCompactionThreshold(lane, drive, checkpoint) {
 }
 /** Prepare one overflow compaction before the response settlement transaction. */
 export async function prepareOverflowCompaction(lane, drive, generation) {
-    if (generation.generationContext.overflowRecoveryUsed)
+    if (generation.generationContext.overflowRecoveryUsed || !generation.settings.compaction.enabled)
         return undefined;
     const path = await readBoundedEntries(lane, drive, generation);
     if (path.kind === "cancel_requested")
@@ -878,7 +884,7 @@ export async function prepareOverflowCompaction(lane, drive, generation) {
     const prepared = prepareCompaction(path.value, generation.settings.compaction);
     if (!prepared.ok)
         throw prepared.error;
-    if (prepared.value === undefined)
+    if (prepared.value === undefined || !summarizesHistory(prepared.value))
         return undefined;
     return {
         taskId: lane.session.idGenerator.next(),

package/dist/harness/tools/bash.js

@@ -70,7 +70,12 @@ export function createBashTool(options) {
             }, context);
             acceptingUpdates = false;
             let outputText = view?.text ?? "";
-            const capture = result.ok ? { text: outputText, ...result.value } : view;
+            const interruptedSpillPath = result.ok ? undefined : result.error.spillPath;
+            const capture = result.ok
+                ? { text: outputText, ...result.value }
+                : view !== undefined && view.spillPath === undefined && interruptedSpillPath !== undefined
+                    ? { ...view, spillPath: interruptedSpillPath }
+                    : view;
             let details;
             if (capture?.truncation.truncated) {
                 details = { truncation: capture.truncation, fullOutputPath: capture.spillPath };
@@ -87,6 +92,9 @@ export function createBashTool(options) {
                     outputText += `\n\n[Showing lines ${startLine}-${endLine} of ${capture.truncation.totalLines} (${formatSize(DEFAULT_MAX_BYTES)} limit). Full output: ${capture.spillPath}]`;
                 }
             }
+            else if (interruptedSpillPath !== undefined) {
+                outputText += `${outputText ? "\n\n" : ""}[Full output: ${interruptedSpillPath}]`;
+            }
             if (!result.ok) {
                 const status = result.error.code === "timeout"
                     ? `Command timed out after ${timeout} seconds`

package/dist/harness/tools/edit.js

@@ -21,10 +21,11 @@ function isSingleEditInput(value) {
     const edit = value;
     return typeof edit.oldText === "string" && typeof edit.newText === "string";
 }
+/** Works on a copy, so the provider's tool call arguments stay unchanged; arrays are left for validation to reject. */
 function prepareEditArguments(input) {
-    if (!input || typeof input !== "object")
+    if (!input || typeof input !== "object" || Array.isArray(input))
         return input;
-    const args = input;
+    const args = { ...input };
     if (typeof args.edits === "string") {
         try {
             const parsed = JSON.parse(args.edits);

package/dist/harness/tools/file-mutation-queue.js

@@ -10,12 +10,25 @@ function getState(env) {
 }
 async function getMutationQueueKey(env, path, context) {
     const absolutePath = getOrThrow(await env.absolutePath(path, context));
+    return canonicalKeyPath(env, absolutePath, context);
+}
+/**
+ * The canonical path; for a file that does not exist yet, its canonical parent joined with its name, so a write that
+ * creates a file and a later mutation of it share one key even when one of them goes through a symlinked directory.
+ */
+async function canonicalKeyPath(env, absolutePath, context) {
     const canonicalPath = await env.canonicalPath(absolutePath, context);
     if (canonicalPath.ok)
         return canonicalPath.value;
-    if (canonicalPath.error.code === "not_found" || canonicalPath.error.code === "not_supported")
+    if (canonicalPath.error.code === "not_supported")
+        return absolutePath;
+    if (canonicalPath.error.code !== "not_found")
+        throw canonicalPath.error;
+    const parent = getOrThrow(await env.joinPath([absolutePath, ".."], context));
+    if (parent === absolutePath || !absolutePath.startsWith(parent))
         return absolutePath;
-    throw canonicalPath.error;
+    const name = absolutePath.slice(parent.length + (/[/\\]$/.test(parent) ? 0 : 1));
+    return getOrThrow(await env.joinPath([await canonicalKeyPath(env, parent, context), name], context));
 }
 /** Serialize file mutations targeting the same environment and canonical path. */
 export async function withFileMutationQueue(env, path, fn, context) {

package/dist/harness/types.d.ts

@@ -129,6 +129,8 @@ export declare class ExecutionError extends Error {
     readonly cause?: unknown;
     /** Backend-independent error code. */
     code: ExecutionErrorCode;
+    /** Complete output preserved before a timeout or abort interrupted the command, when it spilled. */
+    spillPath?: string;
     constructor(code: ExecutionErrorCode, message: string, cause?: unknown);
 }
 /** Stable compaction error codes returned by compaction helpers. */

package/dist/harness/utils/truncate.js

@@ -149,10 +149,9 @@ export function truncateHead(content, options = {}) {
         outputLinesArr.push(line);
         outputBytesCount += lineBytes;
     }
-    // If we exited due to line limit
-    if (outputLinesArr.length >= maxLines && outputBytesCount <= maxBytes) {
-        truncatedBy = "lines";
-    }
+    // Without a byte break, only omitted lines prove the line limit was reached; otherwise a trailing newline exceeded bytes.
+    if (truncatedBy !== "bytes")
+        truncatedBy = outputLinesArr.length < totalLines ? "lines" : "bytes";
     const outputContent = outputLinesArr.join("\n");
     const finalOutputBytes = utf8ByteLength(outputContent);
     return {

package/dist/types.d.ts

@@ -31,6 +31,8 @@ export type ToolExecutionMode = "sequential" | "parallel";
  *
  * - "all": drain and inject every queued message at that point.
  * - "one-at-a-time": drain and inject only the oldest queued message, leaving the rest queued for later drain points.
+ *   A run of consecutive app-defined notices (any role other than user, assistant, toolResult or system)
+ *   is drained together as that oldest entry, so a burst of background events takes one turn.
  */
 export type QueueMode = "all" | "one-at-a-time";
 /** A single tool call content block emitted by an assistant message. */

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@code-yeongyu/senpi-agent-core",
-	"version": "2026.10.1",
+	"version": "2026.10.2",
 	"description": "General-purpose agent with transport abstraction, state management, and attachment support",
 	"type": "module",
 	"main": "./dist/index.js",
@@ -62,8 +62,8 @@
 	},
 	"dependencies": {
 		"@earendil-works/chord": "0.99.1",
-		"@earendil-works/pi-ai": "npm:@code-yeongyu/senpi-ai@2026.10.1",
-		"@earendil-works/pi-telemetry": "npm:@code-yeongyu/senpi-telemetry@2026.10.1",
+		"@earendil-works/pi-ai": "npm:@code-yeongyu/senpi-ai@2026.10.2",
+		"@earendil-works/pi-telemetry": "npm:@code-yeongyu/senpi-telemetry@2026.10.2",
 		"diff": "9.0.0",
 		"ignore": "7.0.9",
 		"typebox": "1.3.34",