@code-yeongyu/senpi-agent-core 2026.9.30 → 2026.10.1-2

package/dist/harness/telemetry.d.ts

@@ -128,6 +128,12 @@ export declare const HARNESS_TELEMETRY_SCHEMA: {
                 readonly kind: "root_or_external";
             };
             readonly startAttributes: {
+                readonly "pi.operation.kind": {
+                    readonly type: "string";
+                    readonly required: true;
+                    readonly values: readonly ["run"];
+                    readonly description: "Run operation kind";
+                };
                 readonly "pi.session.id": {
                     readonly type: "string";
                     readonly required: true;
@@ -151,12 +157,6 @@ export declare const HARNESS_TELEMETRY_SCHEMA: {
                     readonly required: true;
                     readonly description: "Whether this invocation resumes durable work";
                 };
-                readonly "pi.operation.kind": {
-                    readonly type: "string";
-                    readonly required: true;
-                    readonly values: readonly ["run"];
-                    readonly description: "Run operation kind";
-                };
             };
             readonly endAttributes: {
                 readonly "pi.error.code": {
@@ -186,6 +186,12 @@ export declare const HARNESS_TELEMETRY_SCHEMA: {
                 readonly kind: "root_or_external";
             };
             readonly startAttributes: {
+                readonly "pi.operation.kind": {
+                    readonly type: "string";
+                    readonly required: true;
+                    readonly values: readonly ["compaction"];
+                    readonly description: "Compaction operation kind";
+                };
                 readonly "pi.session.id": {
                     readonly type: "string";
                     readonly required: true;
@@ -209,12 +215,6 @@ export declare const HARNESS_TELEMETRY_SCHEMA: {
                     readonly required: true;
                     readonly description: "Whether this invocation resumes durable work";
                 };
-                readonly "pi.operation.kind": {
-                    readonly type: "string";
-                    readonly required: true;
-                    readonly values: readonly ["compaction"];
-                    readonly description: "Compaction operation kind";
-                };
             };
             readonly endAttributes: {
                 readonly "pi.error.code": {
@@ -244,6 +244,12 @@ export declare const HARNESS_TELEMETRY_SCHEMA: {
                 readonly kind: "root_or_external";
             };
             readonly startAttributes: {
+                readonly "pi.operation.kind": {
+                    readonly type: "string";
+                    readonly required: true;
+                    readonly values: readonly ["navigation"];
+                    readonly description: "Navigation operation kind";
+                };
                 readonly "pi.session.id": {
                     readonly type: "string";
                     readonly required: true;
@@ -267,12 +273,6 @@ export declare const HARNESS_TELEMETRY_SCHEMA: {
                     readonly required: true;
                     readonly description: "Whether this invocation resumes durable work";
                 };
-                readonly "pi.operation.kind": {
-                    readonly type: "string";
-                    readonly required: true;
-                    readonly values: readonly ["navigation"];
-                    readonly description: "Navigation operation kind";
-                };
             };
             readonly endAttributes: {
                 readonly "pi.error.code": {
@@ -738,6 +738,12 @@ export declare const AGENT_TELEMETRY_SCHEMAS: readonly [{
                 readonly kind: "root_or_external";
             };
             readonly startAttributes: {
+                readonly "pi.operation.kind": {
+                    readonly type: "string";
+                    readonly required: true;
+                    readonly values: readonly ["run"];
+                    readonly description: "Run operation kind";
+                };
                 readonly "pi.session.id": {
                     readonly type: "string";
                     readonly required: true;
@@ -761,12 +767,6 @@ export declare const AGENT_TELEMETRY_SCHEMAS: readonly [{
                     readonly required: true;
                     readonly description: "Whether this invocation resumes durable work";
                 };
-                readonly "pi.operation.kind": {
-                    readonly type: "string";
-                    readonly required: true;
-                    readonly values: readonly ["run"];
-                    readonly description: "Run operation kind";
-                };
             };
             readonly endAttributes: {
                 readonly "pi.error.code": {
@@ -796,6 +796,12 @@ export declare const AGENT_TELEMETRY_SCHEMAS: readonly [{
                 readonly kind: "root_or_external";
             };
             readonly startAttributes: {
+                readonly "pi.operation.kind": {
+                    readonly type: "string";
+                    readonly required: true;
+                    readonly values: readonly ["compaction"];
+                    readonly description: "Compaction operation kind";
+                };
                 readonly "pi.session.id": {
                     readonly type: "string";
                     readonly required: true;
@@ -819,12 +825,6 @@ export declare const AGENT_TELEMETRY_SCHEMAS: readonly [{
                     readonly required: true;
                     readonly description: "Whether this invocation resumes durable work";
                 };
-                readonly "pi.operation.kind": {
-                    readonly type: "string";
-                    readonly required: true;
-                    readonly values: readonly ["compaction"];
-                    readonly description: "Compaction operation kind";
-                };
             };
             readonly endAttributes: {
                 readonly "pi.error.code": {
@@ -854,6 +854,12 @@ export declare const AGENT_TELEMETRY_SCHEMAS: readonly [{
                 readonly kind: "root_or_external";
             };
             readonly startAttributes: {
+                readonly "pi.operation.kind": {
+                    readonly type: "string";
+                    readonly required: true;
+                    readonly values: readonly ["navigation"];
+                    readonly description: "Navigation operation kind";
+                };
                 readonly "pi.session.id": {
                     readonly type: "string";
                     readonly required: true;
@@ -877,12 +883,6 @@ export declare const AGENT_TELEMETRY_SCHEMAS: readonly [{
                     readonly required: true;
                     readonly description: "Whether this invocation resumes durable work";
                 };
-                readonly "pi.operation.kind": {
-                    readonly type: "string";
-                    readonly required: true;
-                    readonly values: readonly ["navigation"];
-                    readonly description: "Navigation operation kind";
-                };
             };
             readonly endAttributes: {
                 readonly "pi.error.code": {

package/dist/harness/tools/image.js

@@ -4,7 +4,7 @@ export function detectSupportedImageMimeType(buffer) {
         return buffer[3] === 0xf7 ? undefined : "image/jpeg";
     if (startsWith(buffer, PNG_SIGNATURE))
         return isPng(buffer) && !isAnimatedPng(buffer) ? "image/png" : undefined;
-    if (startsWithAscii(buffer, 0, "GIF"))
+    if (startsWithAscii(buffer, 0, "GIF87a") || startsWithAscii(buffer, 0, "GIF89a"))
         return "image/gif";
     if (startsWithAscii(buffer, 0, "RIFF") && startsWithAscii(buffer, 8, "WEBP"))
         return "image/webp";

package/dist/proxy.d.ts

@@ -2,7 +2,7 @@
  * Proxy stream function for apps that route LLM calls through a server.
  * The server manages auth and proxies requests to LLM providers.
  */
-import { type AssistantMessage, type AssistantMessageEvent, type Context, EventStream, type Model, type SimpleStreamOptions, type StopReason, type ToolCall } from "@earendil-works/pi-ai";
+import { type AssistantMessage, type AssistantMessageEvent, EventStream, type Model, type SimpleStreamOptions, type StopReason, type ToolCall, type TranscriptContext } from "@earendil-works/pi-ai";
 declare class ProxyMessageEventStream extends EventStream<AssistantMessageEvent, AssistantMessage> {
     constructor();
 }
@@ -71,6 +71,6 @@ export interface ProxyStreamOptions extends ProxySerializableStreamOptions {
     /** Proxy server URL (e.g., "https://genai.example.com") */
     proxyUrl: string;
 }
-export declare function streamProxy(model: Model<any>, context: Context, options: ProxyStreamOptions): ProxyMessageEventStream;
+export declare function streamProxy(model: Model<any>, context: TranscriptContext, options: ProxyStreamOptions): ProxyMessageEventStream;
 export {};
 //# sourceMappingURL=proxy.d.ts.map

package/dist/types.d.ts

@@ -1,16 +1,20 @@
-import type { Api, AssistantMessage, AssistantMessageEvent, AssistantMessageEventStream, Context, CursorExecHandlers, ImageContent, Message, Model, ProviderDiagnostic, SimpleStreamOptions, TextContent, ThinkingSelection, Tool, ToolResultMessage, Usage } from "@earendil-works/pi-ai";
+import type { Api, AssistantMessage, AssistantMessageEvent, AssistantMessageEventStream, CursorExecHandlers, ImageContent, JsonValue, Message, Model, ProviderDiagnostic, SimpleStreamOptions, TextContent, ThinkingSelection, Tool, ToolResultMessage, TranscriptContext, Usage } from "@earendil-works/pi-ai";
 import type { Static, TSchema } from "typebox";
 /**
  * Stream function used by the agent loop. `Models.streamSimple` satisfies
  * this shape.
  *
+ * The loop passes a normalized transcript: the system prompt and tool
+ * declarations are carried by the transcript's system messages, never by
+ * `context.systemPrompt` or `context.tools`.
+ *
  * Contract:
  * - Must not throw or return a rejected promise for request/model/runtime failures.
  * - Must return an AssistantMessageEventStream.
  * - Failures must be encoded in the returned stream via protocol events and a
  *   final AssistantMessage with stopReason "error" or "aborted" and errorMessage.
  */
-export type StreamFn = (model: Model<Api>, context: Context, options?: SimpleStreamOptions) => AssistantMessageEventStream | Promise<AssistantMessageEventStream>;
+export type StreamFn = (model: Model<Api>, context: TranscriptContext, options?: SimpleStreamOptions) => AssistantMessageEventStream | Promise<AssistantMessageEventStream>;
 /**
  * Configuration for how tool calls from a single assistant message are executed.
  *
@@ -57,13 +61,17 @@ export interface BeforeToolCallResult {
  * - `isError`: if provided, replaces the tool result error flag
  * - `usage`: if provided, replaces the tool result usage
  * - `terminate`: if provided, replaces the early-termination hint
+ * - `structuredContent`: if provided, replaces the structured content. If `content` is provided
+ *   without it, the structured content is dropped, because it may no longer match the content.
+ *   Return it along with `content` to keep it.
  *
- * Omitted fields keep the original executed tool result values.
+ * Other omitted fields keep the original executed tool result values.
  * There is no deep merge for `content`, `details`, or `usage`.
  */
 export interface AfterToolCallResult {
     content?: (TextContent | ImageContent)[];
     details?: unknown;
+    structuredContent?: JsonValue;
     isError?: boolean;
     /** Usage from the final tool execution itself, if available. Not used for main LLM context accounting. */
     usage?: Usage;
@@ -99,21 +107,36 @@ export interface AfterToolCallContext {
     /** Current agent context at the time the tool call is finalized. */
     context: AgentContext;
 }
-/** Context passed to `shouldStopAfterTurn`. */
-export interface ShouldStopAfterTurnContext {
+/** Context passed to completed-turn callbacks. */
+export interface AgentTurnContext {
     /** The assistant message that completed the turn. */
     message: AssistantMessage;
-    /** Tool result messages passed to the preceding `turn_end` event. */
+    /** Tool result messages emitted for the completed turn. */
     toolResults: ToolResultMessage[];
     /** Current agent context after the turn's assistant message and tool results have been appended. */
     context: AgentContext;
     /** Messages that this loop invocation will return if it exits at this point. Prompt runs include the initial prompt messages; continuation runs do not include pre-existing context messages. */
     newMessages: AgentMessage[];
 }
+/** Decision returned by {@link FinishTurn}. Returning undefined preserves normal scheduling. */
+export type AgentTurnDecision = {
+    action: "continue";
+} | {
+    action: "end";
+};
+/**
+ * Called after a completed assistant turn and all of its tool-result messages, but before `turn_end`.
+ * On a normal turn, `{ action: "continue" }` ensures one next provider request. Tool-result, steering, or
+ * follow-up scheduling can satisfy that request and adds no extra request; otherwise the loop continues once
+ * with the current context. Error and aborted responses remain hard exits.
+ */
+export type FinishTurn = (turn: AgentTurnContext, signal?: AbortSignal) => AgentTurnDecision | void | Promise<AgentTurnDecision | undefined> | Promise<void>;
 /** Replacement runtime state used by the agent loop before starting another provider request. */
 export interface AgentLoopTurnUpdate {
     /** Context for the next provider request. */
     context?: AgentContext;
+    /** Messages to append before the next provider request, with normal lifecycle events. */
+    messages?: AgentMessage[];
     /** Model for the next provider request. */
     model?: Model<any>;
     /** Thinking level for the next provider request. */
@@ -123,7 +146,20 @@ export interface AgentLoopTurnUpdate {
     /** Whether the next provider request should abort a server-selected fallback. */
     abortServerSideFallback?: boolean;
 }
-export interface PrepareNextTurnContext extends ShouldStopAfterTurnContext {
+/** Runtime state available immediately before a conversational provider request. */
+export interface PrepareRequestContext {
+    context: AgentContext;
+    model: Model<any>;
+    thinkingLevel: ThinkingLevel;
+}
+/** Replacement runtime state for the provider request being prepared. */
+export type AgentRequestUpdate = Omit<AgentLoopTurnUpdate, "messages">;
+/**
+ * Called immediately before every conversational provider request, including the first.
+ * Pending messages have already been appended and emitted when this callback runs.
+ */
+export type PrepareRequest = (request: PrepareRequestContext, signal?: AbortSignal) => AgentRequestUpdate | void | Promise<AgentRequestUpdate | undefined> | Promise<void>;
+export interface PrepareNextTurnContext extends AgentTurnContext {
 }
 export interface AgentLoopConfig extends SimpleStreamOptions {
     model: Model<any>;
@@ -154,7 +190,7 @@ export interface AgentLoopConfig extends SimpleStreamOptions {
     /**
      * Converts AgentMessage[] to LLM-compatible Message[] before each LLM call.
      *
-     * Each AgentMessage must be converted to a UserMessage, AssistantMessage, or ToolResultMessage
+     * Each AgentMessage must be converted to a SystemMessage, UserMessage, AssistantMessage, or ToolResultMessage
      * that the LLM can understand. AgentMessages that cannot be converted (e.g., UI-only notifications,
      * status messages) should be filtered out.
      *
@@ -209,30 +245,33 @@ export interface AgentLoopConfig extends SimpleStreamOptions {
      */
     getApiKey?: (provider: string) => Promise<string | undefined> | string | undefined;
     /**
-     * Called after each turn fully completes and `turn_end` has been emitted.
-     *
-     * If it returns true, the loop emits `agent_end` and exits before polling steering or follow-up queues,
-     * without starting another LLM call. The current assistant response and any tool executions finish normally.
-     * This callback sees the completed-turn context and runs before `prepareNextTurn`.
-     *
-     * Use this to request a graceful stop after the current turn, e.g. before context gets too full.
-     *
-     * Contract: must not throw or reject. Throwing interrupts the low-level agent loop without producing a normal event sequence.
+     * Called after the assistant message and all tool-result messages have been emitted, immediately before `turn_end`.
+     * `{ action: "end" }` ends the run without polling queues or preparing another request.
+     * On a normal turn, `{ action: "continue" }` ensures one next provider request. Tool-result, steering, or
+     * follow-up scheduling can satisfy that request and adds no extra request; otherwise the loop continues once
+     * with the current context. Returning undefined preserves normal scheduling. Error and aborted responses remain
+     * hard exits.
      */
-    shouldStopAfterTurn?: (context: ShouldStopAfterTurnContext) => boolean | Promise<boolean>;
+    finishTurn?: FinishTurn;
+    /**
+     * Called immediately before every conversational provider request, including the first.
+     * Pending messages have already been appended. The returned context, model, and thinking level
+     * replace the runtime values for this and later requests in the run. This hook does not poll queues.
+     */
+    prepareRequest?: PrepareRequest;
     /**
      * Called after each completed assistant turn, including a normal stop response, before the loop decides whether another provider request starts.
      * A terminating-tool continuation emits its `turn_start` boundary first so queue owners can clear
      * or replace pending input before preparation finishes and the continuation is admitted.
-     * `shouldStopAfterTurn` and an empty terminating tool batch can end the run before preparation.
-     * Return replacement context/model/thinking state to affect the next turn.
+     * `finishTurn` returning `{ action: "end" }` and an empty terminating tool batch can end the run before preparation.
+     * Return replacement context/model/thinking state or messages to append to affect the next turn.
      * Return undefined to keep using the current context/config.
      */
     prepareNextTurn?: (context: PrepareNextTurnContext) => AgentLoopTurnUpdate | undefined | Promise<AgentLoopTurnUpdate | undefined>;
     /**
      * Returns steering messages to inject into the conversation mid-run.
      *
-     * Called after the current assistant turn finishes executing its tool calls, unless `shouldStopAfterTurn` exits first.
+     * Called after the current assistant turn finishes executing its tool calls, unless `finishTurn` ends the run.
      * If messages are returned, they are added to the context before the next LLM call.
      * Tool calls from the current assistant message are not skipped.
      *
@@ -339,7 +378,11 @@ export type AgentMessage = Message | CustomAgentMessages[keyof CustomAgentMessag
  * assigned arrays before storing them.
  */
 export interface AgentState {
-    /** System prompt sent with each model request. */
+    /**
+     * Base system prompt sent with each model request (fork: assignable; the loop folds it into the
+     * leading system message through `normalizeContext()`). Later transcript system messages with
+     * `content` or `sections` still apply on top of it.
+     */
     systemPrompt: string;
     /** Active model used for future turns. */
     model: Model<any>;
@@ -352,12 +395,21 @@ export interface AgentState {
     thinkingSelection?: ThinkingSelection;
     /** First reasoning effort on the branch, used to preserve Responses cache prefixes. */
     reasoningBaseline?: string;
-    /** Available tools. Assigning a new array copies the top-level array. */
+    /**
+     * Executable tools. Assigning a new array copies the top-level array.
+     *
+     * Differences from the tools declared in the transcript are announced to the model
+     * with a system message before the next request.
+     */
     set tools(tools: AgentTool<any>[]);
     get tools(): AgentTool<any>[];
     /** Tool list the provider receives when it differs from `tools`; see {@link AgentContext.declaredTools}. */
     declaredTools?: AgentTool<any>[];
-    /** Conversation transcript. Assigning a new array copies the top-level array. */
+    /**
+     * Conversation transcript. Assigning a new array copies the top-level array.
+     *
+     * System messages in the transcript carry the prompt and tool declarations.
+     */
     set messages(messages: AgentMessage[]);
     get messages(): AgentMessage[];
     /**
@@ -376,25 +428,39 @@ export interface AgentState {
     readonly providerDiagnostic?: ProviderDiagnostic;
 }
 /** Final or partial result produced by a tool. */
-export interface AgentToolResult<T> {
+export interface AgentToolResult<T = JsonValue | undefined> {
     /** Text or image content returned to the model. */
     content: (TextContent | ImageContent)[];
     /** Arbitrary structured details for logs or UI rendering. */
     details: T;
+    /**
+     * Machine-readable result matching the tool's `outputSchema`, for programmatic callers. Not sent
+     * to the model; `content` remains the model-facing result.
+     */
+    structuredContent?: JsonValue;
     /** Usage from the final tool execution itself, if available. Not used for main LLM context accounting. */
     usage?: Usage;
-    /** Names of tools introduced by this result and available from this transcript point onward. */
-    addedToolNames?: string[];
+    /**
+     * Report a failure without throwing. The model sees `content` as an error result, like a thrown
+     * error, but `details` and `structuredContent` are kept for the UI and programmatic callers.
+     */
+    isError?: boolean;
     /**
      * Hint that the agent should stop after the current tool batch.
      * Early termination only happens when every finalized tool result in the batch sets this to true.
      */
     terminate?: boolean;
     /**
-     * Report a failure without throwing: `true` marks this result as a tool error while keeping
-     * `content` and `details` intact for the model and renderers. Omitted or `false` means success.
+     * Names of tools introduced by this result and available from this transcript point onward
+     * (fork lazy-tool activation and tool-search native deferred loading).
      */
-    isError?: boolean;
+    addedToolNames?: string[];
+}
+/** Final outcome of a tool call after hooks ran. */
+export interface AgentToolCallOutcome {
+    toolCall: AgentToolCall;
+    result: AgentToolResult<any>;
+    isError: boolean;
 }
 /**
  * Callback used by tools to stream partial execution updates.
@@ -412,7 +478,15 @@ export interface AgentTool<TParameters extends TSchema = TSchema, TDetails = any
      * Must return an object that matches `TParameters`.
      */
     prepareArguments?: (args: unknown) => Static<TParameters>;
-    /** Execute the tool call. Throw on failure instead of encoding errors in `content`. */
+    /**
+     * JSON Schema of `structuredContent` in successful results. Tools that declare it should always
+     * set `structuredContent`.
+     */
+    outputSchema?: TSchema;
+    /**
+     * Execute the tool call. Throw on failure, or return a result with `isError: true`; do not only
+     * describe the failure in `content`.
+     */
     execute: (toolCallId: string, params: Static<TParameters>, signal?: AbortSignal, onUpdate?: AgentToolUpdateCallback<TDetails>) => Promise<AgentToolResult<TDetails>>;
     /** Recovery policy for an effect whose durable intent exists but whose outcome is unknown. */
     replay?: "never" | "safe";
@@ -427,11 +501,14 @@ export interface AgentTool<TParameters extends TSchema = TSchema, TDetails = any
 }
 /** Context snapshot passed into the low-level agent loop. */
 export interface AgentContext {
-    /** System prompt included with the request. */
-    systemPrompt: string;
+    /**
+     * Fork shorthand for the leading system message; `buildProviderContext` folds it with
+     * `normalizeContext()`. Upstream-built contexts carry the prompt in transcript system messages.
+     */
+    systemPrompt?: string;
     /** Transcript visible to the model. */
     messages: AgentMessage[];
-    /** Tools available for this run. */
+    /** Tools available for execution in this run. */
     tools?: AgentTool<any>[];
     /**
      * Superset of `tools` to declare to the provider, keeping the tool prefix byte-stable while the

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@code-yeongyu/senpi-agent-core",
-	"version": "2026.9.30",
+	"version": "2026.10.1-2",
 	"description": "General-purpose agent with transport abstraction, state management, and attachment support",
 	"type": "module",
 	"main": "./dist/index.js",
@@ -18,6 +18,10 @@
 			"types": "./dist/harness/context.d.ts",
 			"import": "./dist/harness/context.js"
 		},
+		"./experimental/pico3": {
+			"types": "./dist/harness/pico3/index.d.ts",
+			"import": "./dist/harness/pico3/index.js"
+		},
 		"./harness/env/nodejs": {
 			"types": "./dist/harness/env/nodejs.d.ts",
 			"import": "./dist/harness/env/nodejs.js"
@@ -46,7 +50,7 @@
 		"clean": "shx rm -rf dist",
 		"generate-telemetry-docs": "node scripts/generate-telemetry-docs.ts",
 		"check:telemetry-docs": "node scripts/generate-telemetry-docs.ts --check",
-		"build": "tsgo -p tsconfig.build.json",
+		"build": "tsc -p tsconfig.build.json",
 		"bench:session:timing": "vitest bench --config vitest.benchmark.config.ts",
 		"bench:session:memory": "tsx --tsconfig benchmark/tsconfig.json benchmark/session/loaded-footprint.ts",
 		"bench:session:allocations": "tsx --tsconfig benchmark/tsconfig.json benchmark/session/allocation-profile.ts",
@@ -57,9 +61,9 @@
 		"prepublishOnly": "npm run build"
 	},
 	"dependencies": {
-		"@earendil-works/chord": "0.85.1",
-		"@earendil-works/pi-ai": "npm:@code-yeongyu/senpi-ai@2026.9.30",
-		"@earendil-works/pi-telemetry": "npm:@code-yeongyu/senpi-telemetry@2026.9.30",
+		"@earendil-works/chord": "0.99.1",
+		"@earendil-works/pi-ai": "npm:@code-yeongyu/senpi-ai@2026.10.1-2",
+		"@earendil-works/pi-telemetry": "npm:@code-yeongyu/senpi-telemetry@2026.10.1-2",
 		"diff": "9.0.0",
 		"ignore": "7.0.9",
 		"typebox": "1.3.34",