@gajae-code/agent-core 0.1.1

package/CHANGELOG.md

@@ -0,0 +1,482 @@
+# Changelog
+
+## [Unreleased]
+
+## [0.1.1] - 2026-05-28
+
+### Added
+
+- Added `Agent.forceAbort()` so hosts can recover from provider/tool aborts that ignore cooperative cancellation without clearing conversation history.
+
+## [15.3.0] - 2026-05-25
+### Fixed
+
+- Fixed `transformContext` receiving the loop config object as the `signal` argument instead of the actual `AbortSignal`, so hooks that check `signal.aborted` or call `signal.addEventListener` now work correctly under abort/timeout conditions
+- Fixed `appendOnlyContext` not being re-evaluated after `setModel()` — the mode was decided once at session construction based on the initial model's provider, so switching from/to DeepSeek (or changing `provider.appendOnlyContext`) mid-session produced incorrect mode behavior
+
+## [15.2.3] - 2026-05-22
+### Added
+
+- Added `onBeforeYield` hook support so user code can run right before the agent loop checks for follow-up messages
+
+## [15.1.3] - 2026-05-17
+### Added
+
+- Added optional `telemetry` support to `generateSummary`, `generateHandoff`, `generateBranchSummary`, and `compact` options so compaction, handoff, and branch summary one-shot LLM calls can emit OpenTelemetry chat telemetry when enabled
+- Added shared oneshot telemetry instrumentation for compaction, handoff, and branch summary calls, tagging spans with `pi.gen_ai.oneshot.kind` values such as `compaction_summary`, `compaction_short_summary`, `compaction_turn_prefix`, `handoff`, and `branch_summary`
+
+## [15.1.2] - 2026-05-15
+### Added
+
+- Added `responseHeaders` to `ChatUsageEvent` and `ManualChatTelemetryOptions` so telemetry hooks receive captured lowercase upstream response headers for each chat span
+- Added automatic gateway/proxy detection from response headers (`litellm`, `helicone`, `portkey`, `openrouter`) and stamped `pi.gen_ai.gateway.*` span attributes for detected routing metadata
+- Added exported `detectGatewayFromHeaders` API for header-based gateway detection
+
+## [15.1.0] - 2026-05-15
+### Breaking Changes
+
+- Removed the `@gajae-code/agent-core/compaction/handoff` exports from the package surface, including `extractHandoffDocument`, `createHandoffContext`, and `createHandoffFileName`
+- Removed legacy telemetry constants from the public enum surface (including `AGGREGATE_ATTR`, `GenAIAttr.System`, and old `gen_ai.*` extension keys such as `gen_ai.request.service_tier`/cost/tool status/handoff fields) and replaced them with `OpenAIAttr`, `PiGenAIAttr`, and `PiGenAIAggregateAttr`
+
+### Added
+
+- Added `generateHandoff(messages, model, apiKey, options)` to `@gajae-code/agent-core/compaction` to generate a handoff document by calling the model directly, using live system/tool context and optional metadata
+- Added generation filtering so the returned handoff document now includes only text content blocks from the model output
+- Added support for defining `AgentTool` schemas with Zod, with legacy TypeBox schemas still supported when generating tool schemas for model calls
+- Added `OpenAIAttr`, `PiGenAIAttr`, and `PiGenAIAggregateAttr` exports so consumers can reference the new `openai.*` and `pi.gen_ai.*` telemetry attribute keys directly
+- Added `onChatUsage` to `AgentTelemetryConfig`, an always-fired hook receiving a `ChatUsageEvent` for every chat step that produced usage. The event carries the chat `span`, `agent`, `conversationId`, `stepNumber`, `model`, `provider`, `serviceTier`, `usage`, optional `cost`, and resolved dynamic `attributes` — independent of whether a `costEstimator` is configured.
+- Added `agentLoopDetailed(...)` and `agentLoopContinueDetailed(...)` helpers that return the same event stream plus a `detailed()` result with run `telemetry` and `coverage`
+- Added `onRunEnd` to `AgentTelemetryConfig` to receive `AgentRunSummary` and `AgentRunCoverage` at the end of each invocation
+- Added run-level telemetry and coverage types/helpers (for example `AgentRunSummary`, `AgentRunCoverage`, `aggregateAgentRunSummaries`, and `aggregateAgentRunCoverage`) to package exports
+- Added generic telemetry extension hooks for dynamic span attributes, provider/agent-name normalization, per-step cost deltas, warning callbacks, bounded summary content capture, and manual chat telemetry for non-loop model calls.
+- Added opt-in OpenTelemetry instrumentation on the agent loop. Pass `telemetry: {}` (or a richer `AgentTelemetryConfig`) on `AgentLoopConfig` / `AgentOptions` / `createAgentSession({ telemetry })` to emit GenAI-semantic-convention spans plus `pi.gen_ai.*` extension attributes:
+- `invoke_agent {agent.name}` wraps each `agentLoop` invocation with `gen_ai.operation.name=invoke_agent`, agent identity, conversation id, and `pi.gen_ai.agent.step.count`.
+- `chat {model}` per provider call, parented under `invoke_agent`, with OTEL request/response/usage attributes (`gen_ai.request.{model,stream,temperature,top_p,top_k,max_tokens,presence_penalty,stop_sequences}`, `gen_ai.response.{model,id,finish_reasons,time_to_first_chunk}`, `gen_ai.usage.{input_tokens,output_tokens,cache_read.input_tokens,cache_creation.input_tokens,reasoning.output_tokens}`) and project extensions for reasoning effort, tool choice, available tools, usage totals, and cost.
+- `execute_tool {tool.name}` per tool call, parented under `invoke_agent`, with `gen_ai.tool.{name,call.id,description,type}` plus the active context so user/MCP/provider spans created inside `tool.execute()` attach as children.
+- One-shot `handoff` span available via the public `recordHandoff(...)` helper for agent-to-agent transitions.
+- Added `AgentTelemetryConfig` hooks (`onSpanStart`, `onSpanEnd`, `costEstimator`), `agent` identity, `attributes` envelope merged onto every span, `captureMessageContent` toggle (defaults to the `OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT` env var) emitting OTEL-shaped `gen_ai.input.messages` / `gen_ai.output.messages` / `gen_ai.system_instructions` / `gen_ai.tool.call.arguments` / `gen_ai.tool.call.result`, and tracer/tracerName override surfaces.
+- Added `Agent#setTelemetry(config)` so consumers can swap or disable instrumentation between invocations.
+- Added `@opentelemetry/api` as a runtime dependency; SDK setup (exporters, samplers, processors) remains the host's responsibility per standard OTEL conventions. When no SDK is registered, helpers fall through to no-op spans with zero overhead.
+- Added compaction APIs under `@gajae-code/agent-core/compaction`, including context compaction, branch summarization, handoff prompt/context helpers, pruning, token budgeting, prompt templates, and OpenAI `/responses/compact` helpers.
+
+### Changed
+
+- Changed handoff document generation to force `toolChoice: "none"` when calling the model so tool invocation is disabled during generation
+- Changed `chat` spans to emit normalized provider identifiers in `gen_ai.provider.name` via OTEL-style values (for example `google` to `gcp.gemini`) instead of the legacy `gen_ai.system` label
+- Changed service-tier telemetry to emit `openai.request.service_tier`/`openai.response.service_tier` only when supported by provider via `shouldSendServiceTier`, rather than always using `gen_ai.request.service_tier`
+- Changed captured message payloads so full capture now records OTEL-structured message parts with `pi.gen_ai.request.messages`, `pi.gen_ai.system_instructions`, and `gen_ai.output.messages` including assistant `finish_reason`
+- Changed the `agent_end` event payload to include optional `telemetry` and `coverage` fields when telemetry is enabled, while keeping the legacy payload shape when disabled
+- Changed `invoke_agent` spans to include aggregate `pi.gen_ai.agent.*` attributes for chat/tool counts, latency, usage, cost, errors, and tool coverage
+
+### Fixed
+
+- Fixed intent-field injection for tool schemas defined with Zod by converting them to wire schema before mutation
+- Fixed token accounting in `ChatUsageEvent` and usage summaries so `inputTokens` and `totalTokens` now include cached read/write input tokens
+- Fixed `execute_tool` span attributes so `pi.gen_ai.tool.status` and `error.type` now reflect run-level tool outcomes (`ok`, `error`, `skipped`, `blocked`, `timeout`, `aborted`) instead of mapping all non-ok cases the same way
+- Fixed `onRunEnd` callbacks to be safe and idempotent by invoking them once per run and swallowing thrown callback errors so they cannot fail or duplicate successful runs
+- Fixed run telemetry to count interrupted, blocked, or otherwise skipped tool calls so run coverage and tool counters now include those paths
+- Fixed chat failure handling so failed chat steps are still represented in run summaries when provider streaming throws before yielding an assistant message
+- Fixed double-counting of interrupted tool calls in run summaries: the `runTool` early-return on a queued steering interrupt now defers to the post-batch tail sweep so each call is recorded exactly once
+- Fixed `coverage.toolsInvoked` and run-summary tool counters under-reporting tool calls embedded in an aborted/errored assistant message — those calls now record a collector orphan with status `aborted` or `error`
+- Fixed `AgentRunSummary.usage.inputTokens` so it now includes `cache_read` and `cache_write` input tokens, matching `ChatUsageEvent.inputTokens`
+- Fixed span lifecycle hooks (`onSpanStart`, `onSpanEnd`) so a thrown user callback is caught and surfaced via `onTelemetryWarning` (`on_span_start_failed` / `on_span_end_failed`) instead of leaking and aborting the surrounding span
+- Fixed unbounded recursion in summary content capture when a captured value contains a cyclic or deeply nested array — array recursion now respects the same depth cap as plain-object recursion and replaces back-references with `"[Circular]"`
+
+## [15.0.1] - 2026-05-14
+### Breaking Changes
+
+- Raised the minimum required Bun version from >=1.3.7 to >=1.3.14
+
+## [14.9.5] - 2026-05-12
+
+### Added
+
+- Added an `isError?: boolean` field on `AgentToolResult` so tools can flag a non-throwing failure (e.g. an aggregator that catches per-entry errors). `coerceToolResult` preserves the flag and the agent loop surfaces it as a tool error on the wire.
+
+## [14.9.3] - 2026-05-10
+### Added
+
+- Added `onHarmonyLeak` option on `Agent`/loop config to receive GPT-5 Harmony leak audit callbacks
+- Added harmony-leak detection and audit exports to the package index for programmatic leak detection and recovery hooks
+
+### Changed
+
+- Changed OpenAI code provider model runs to detect GPT-5 Harmony protocol leakage during streaming and automatically retry or recover tool calls instead of sending contaminated arguments downstream
+
+### Security
+
+- Hardened tool-call handling against leaked `to=functions.*` protocol tails by truncating or retrying before execution
+- Hardened failure handling so repeated GPT-5 Harmony leak mitigation is retried only up to two times before escalating to an explicit error
+
+## [14.9.0] - 2026-05-10
+### Added
+
+- Added `Agent#metadata` field forwarded to every API request; callers can set arbitrary provider metadata (e.g. `metadata.user_id`) once and have it applied to all subsequent stream calls without modifying per-call options
+- Added `Agent#setMetadataResolver(fn)` for installing a function that resolves request metadata at call time. The `metadata` getter dispatches through the resolver on every read (including the snapshot taken per `prompt()`), so callers reflect mutable external state (e.g. live OAuth account UUID after a token refresh) without manual re-syncs. Plain `agent.metadata = …` continues to set a static value and clears any installed resolver.
+
+### Added
+
+- Added an `onSseEvent` agent option and loop config forwarding path for raw provider SSE diagnostics.
+
+## [14.7.6] - 2026-05-07
+
+### Added
+
+- Added `hideThinkingSummary` option/getter/setter on `Agent` and `AgentLoopConfig`. Forwarded to the underlying stream call so providers can omit reasoning/thinking summaries on demand.
+## [14.7.2] - 2026-05-06
+### Added
+
+- Added `loadMode` option to `AgentTool` to mark built-in tools as `essential` for initial loading or `discoverable` for search activation
+- Added optional `summary` field to `AgentTool` definitions for one-line text used in tool discovery indexes
+
+## [14.7.0] - 2026-05-04
+### Breaking Changes
+
+- Changed `Agent` API types so `systemPrompt` is now a list of prompt strings, requiring callers to pass and update system prompts via string arrays
+
+### Changed
+
+- Removed automatic project-context injection into each model call from loop logic
+
+### Removed
+
+- Removed the `projectPrompt` field from agent state/context and the `setProjectPrompt` mutator
+
+## [14.6.2] - 2026-05-03
+
+### Fixed
+
+- Fixed unhandled promise rejection when `getApiKey` or any other async error occurs during `streamAssistantResponse`: agent loop IIFEs now catch and route errors through `EventStream.fail()`, which terminates the `for await` loop and lets `Agent#runLoop`'s catch block create a proper error assistant message instead of crashing
+
+## [14.6.0] - 2026-05-02
+### Fixed
+
+- Fixed request cancellation before provider events by emitting an aborted assistant message and ending the stream with `stopReason: "aborted"`
+
+## [14.5.10] - 2026-04-30
+
+### Added
+
+- Added an `onResponse` stream option for observing provider response metadata after response headers arrive.
+
+## [14.2.0] - 2026-04-23
+
+### Changed
+
+- Changed tool dispatch to match model-returned tool calls by either internal tool name or custom wire name, enabling custom OpenAI tool names such as `apply_patch`.
+
+## [14.0.1] - 2026-04-08
+### Added
+
+- Added `onAssistantMessageEvent` callback option to inspect assistant streaming events before they are emitted, enabling abort decisions before buffered events continue flowing
+- Added `setAssistantMessageEventInterceptor()` method to dynamically set or update the assistant message event interceptor
+
+## [13.13.0] - 2026-03-18
+
+### Added
+
+- Added `startup.checkUpdate` setting, set to `true` by default, can be disabled to skip the update check on agent initialization
+
+## [13.12.7] - 2026-03-16
+
+### Added
+
+- Added overload for `prompt()` method accepting a string input with optional options parameter
+
+### Fixed
+
+- Fixed stale forced toolChoice being passed to provider after tools are refreshed mid-turn
+
+## [13.9.16] - 2026-03-10
+### Added
+
+- Added `onPayload` option to `AgentOptions` to inspect or replace provider payloads before they are sent
+
+## [13.9.3] - 2026-03-07
+
+### Added
+
+- Exported `ThinkingLevel` selector constants and types for configuring agent reasoning behavior
+- Added `inherit` thinking level option to defer reasoning configuration to higher-level selectors
+- Added `serviceTier` option to configure service tier for agent requests
+
+### Changed
+
+- Changed `thinkingLevel` from required string to optional `Effort` type, allowing undefined state
+- Updated `setThinkingLevel()` method to accept `Effort | undefined` instead of `ThinkingLevel` string
+
+## [13.4.0] - 2026-03-01
+### Added
+
+- Added `getToolChoice` option to dynamically override tool choice per LLM call
+
+## [13.3.8] - 2026-02-28
+### Changed
+
+- Changed intent field name from `agent__intent` to `_i` in tool schemas
+
+### Fixed
+
+- Fixed synthetic tool result text formatting so aborted/error tool results no longer emit `Tool execution was aborted.: Request was aborted` style punctuation.
+## [13.3.7] - 2026-02-27
+### Added
+
+- Added `lenientArgValidation` option to tools to allow graceful handling of argument validation errors by passing raw arguments to execute() instead of returning an error to the LLM
+
+## [13.3.1] - 2026-02-26
+### Added
+
+- Added `topP`, `topK`, `minP`, `presencePenalty`, and `repetitionPenalty` options to `AgentOptions` for fine-grained sampling control
+- Added getter and setter properties for sampling parameters on the `Agent` class to allow runtime configuration
+
+## [13.1.0] - 2026-02-23
+
+### Changed
+
+- Removed per-tool `agent__intent` field description from injected schema to reduce token usage; intent format is now documented once in the system prompt instead of repeated in every tool definition
+## [12.19.0] - 2026-02-22
+### Changed
+
+- Updated tool result messages to include error details when tool execution fails
+
+## [12.14.0] - 2026-02-19
+
+### Added
+
+- Added `intentTracing` option to enable intent goal extraction from tool calls, allowing models to specify high-level goals via a required `_intent` field that is automatically injected into tool schemas and stripped from arguments before execution
+
+## [12.11.0] - 2026-02-19
+
+### Added
+
+- Exported `AgentBusyError` exception class for handling concurrent agent operations
+
+### Changed
+
+- Agent now throws `AgentBusyError` instead of generic `Error` when attempting concurrent operations
+
+## [12.8.0] - 2026-02-16
+
+### Added
+
+- Added `transformToolCallArguments` option to `AgentOptions` and `AgentLoopConfig` for transforming tool call arguments before execution (e.g. secret deobfuscation)
+
+## [12.2.0] - 2026-02-13
+
+### Added
+
+- Added `providerSessionState` option to share provider state map for session-scoped transport and session caches
+- Added `preferWebsockets` option to hint that websocket transport should be preferred when supported by the provider implementation
+
+## [11.10.0] - 2026-02-10
+
+### Added
+
+- Added `temperature` option to `AgentOptions` to control LLM sampling temperature
+- Added `temperature` getter and setter to `Agent` class for runtime configuration
+
+## [11.6.0] - 2026-02-07
+
+### Added
+
+- Added `hasQueuedMessages()` method to check for pending steering/follow-up messages
+- Resume queued steering and follow-up messages from `continue()` after auto-compaction
+
+### Changed
+
+- Extracted `dequeueSteeringMessages()` and `dequeueFollowUpMessages()` from inline config callbacks
+- Added `skipInitialSteeringPoll` option to `_runLoop()` for correct queue resume ordering
+
+## [11.3.0] - 2026-02-06
+
+### Added
+
+- Added `maxRetryDelayMs` option to AgentOptions to cap server-requested retry delays, allowing higher-level retry logic to handle long waits with user visibility
+
+### Changed
+
+- Updated ThinkingLevel documentation to include support for gpt-5.3 and gpt-5.3-openai-code models with 'xhigh' thinking level
+
+## [11.2.0] - 2026-02-05
+
+### Fixed
+
+- Fixed handling of aborted requests to properly throw abort errors when stream terminates without a terminal event
+
+## [10.5.0] - 2026-02-04
+
+### Added
+
+- Added `concurrency` option to `AgentTool` to control tool scheduling: "shared" (default, runs in parallel) or "exclusive" (runs alone)
+- Implemented parallel execution of shared tools within a single agent turn for improved performance
+
+### Changed
+
+- Refactored tool execution to support concurrent scheduling with proper interrupt handling and steering message checks
+
+## [9.2.2] - 2026-01-31
+
+### Added
+
+- Added toolChoice option to AgentPromptOptions for controlling tool selection
+
+## [8.2.0] - 2026-01-24
+
+### Changed
+
+- Updated TypeScript configuration for better publish-time configuration handling with tsconfig.publish.json
+
+## [8.0.0] - 2026-01-23
+
+### Added
+
+- Added `nonAbortable` option to tools to ignore abort signals during execution
+
+## [6.8.0] - 2026-01-20
+
+### Changed
+
+- Updated proxy stream processing to use utility function for reading lines
+
+## [6.2.0] - 2026-01-19
+
+### Added
+
+- Enhanced getToolContext to receive tool call batch information including batchId, index, total count, and tool call details
+
+## [5.6.7] - 2026-01-18
+
+### Fixed
+
+- Added proper tool result messages for tool calls that are aborted or error out
+- Ensured tool_use/tool_result pairing is maintained when tool execution fails
+
+## [4.6.0] - 2026-01-12
+
+### Changed
+
+- Modified assistant message handling to split messages around tool results for improved readability when using Cursor tools
+
+### Fixed
+
+- Fixed tool result ordering in Cursor mode by buffering results and emitting them at the correct position within assistant messages
+
+## [4.3.0] - 2026-01-11
+
+### Added
+
+- Added `cursorExecHandlers` and `cursorOnToolResult` options for local tool execution with cursor-based streaming
+- Added `emitExternalEvent` method to allow external event injection into the agent state
+
+## [4.0.0] - 2026-01-10
+
+### Added
+
+- Added `popLastSteer()` and `popLastFollowUp()` methods to remove and return the last queued message (LIFO) for dequeue operations
+- `thinkingBudgets` option on `Agent` and `AgentOptions` to customize token budgets per thinking level
+- `sessionId` option on `Agent` to forward session identifiers to LLM providers for session-based caching
+
+### Fixed
+
+- `minimal` thinking level now maps to `minimal` reasoning effort instead of being treated as `low`
+
+## [3.33.0] - 2026-01-08
+
+### Fixed
+
+- Ensured aborted assistant responses always include an error message for callers.
+- Filtered thinking blocks from Cerebras request context to keep multi-turn prompts compatible.
+
+## [3.21.0] - 2026-01-06
+
+### Changed
+
+- Switched from local `@gajae-code/ai` to upstream `@gajae-code/ai` package
+
+### Added
+
+- Added `sessionId` option for provider caching (e.g., OpenAI code provider session-based prompt caching)
+- Added `sessionId` getter/setter on Agent class for runtime session switching
+
+## [3.20.0] - 2026-01-06
+
+### Breaking Changes
+
+- Replaced `queueMessage`/`queueMode` with steering + follow-up queues: use `steer`, `setSteeringMode`, and `getSteeringMode` for mid-run interruptions, and `followUp`, `setFollowUpMode`, and `getFollowUpMode` for post-turn messages
+- Agent loop callbacks now use `getSteeringMessages` and `getFollowUpMessages` instead of `getQueuedMessages`
+
+### Added
+
+- Added follow-up message queue support so new user messages can continue a run after the agent would otherwise stop
+- Added `RenderResultOptions.spinnerFrame` for animated tool-result rendering
+
+### Changed
+
+- `prompt()` and `continue()` now throw when the agent is already streaming; use steering or follow-up queues instead
+
+## [3.4.1337] - 2026-01-03
+
+### Added
+
+- Added `popMessage()` method to Agent class for removing and retrieving the last message
+- Added abort signal checks during response streaming for faster interruption handling
+
+### Fixed
+
+- Fixed abort handling to properly return aborted message state when stream is interrupted mid-response
+
+## [1.341.0] - 2026-01-03
+
+### Added
+
+- Added `interruptMode` option to control when queued messages interrupt tool execution.
+- Implemented "immediate" mode (default) to check queue after each tool and interrupt remaining tools.
+- Implemented "wait" mode to defer queue processing until the entire turn completes.
+- Added getter and setter methods for `interruptMode` on Agent class.
+
+## [1.337.1] - 2026-01-02
+
+### Changed
+
+- Forked to @gajae-code scope with unified versioning across all packages
+
+## [1.337.0] - 2026-01-02
+
+Initial release under @gajae-code scope. See previous releases at [badlogic/pi-mono](https://github.com/badlogic/pi-mono).
+
+## [0.31.0] - 2026-01-02
+
+### Breaking Changes
+
+- **Transport abstraction removed**: `ProviderTransport`, `AppTransport`, and `AgentTransport` interface have been removed. Use the `streamFn` option directly for custom streaming implementations.
+
+- **Agent options renamed**:
+  - `transport` → removed (use `streamFn` instead)
+  - `messageTransformer` → `convertToLlm`
+  - `preprocessor` → `transformContext`
+
+- **`AppMessage` renamed to `AgentMessage`**: All references to `AppMessage` have been renamed to `AgentMessage` for consistency.
+
+- **`CustomMessages` renamed to `CustomAgentMessages`**: The declaration merging interface has been renamed.
+
+- **`UserMessageWithAttachments` and `Attachment` types removed**: Attachment handling is now the responsibility of the `convertToLlm` function.
+
+- **Agent loop moved from `@gajae-code/ai`**: The `agentLoop`, `agentLoopContinue`, and related types have moved to this package. Import from `@gajae-code/pi-agent` instead.
+
+### Added
+
+- `streamFn` option on `Agent` for custom stream implementations. Default uses `streamSimple` from pi-ai.
+
+- `streamProxy()` utility function for browser apps that need to proxy LLM calls through a backend server. Replaces the removed `AppTransport`.
+
+- `getApiKey` option for dynamic API key resolution (useful for expiring OAuth tokens like GitHub Copilot).
+
+- `agentLoop()` and `agentLoopContinue()` low-level functions for running the agent loop without the `Agent` class wrapper.
+
+- New exported types: `AgentLoopConfig`, `AgentContext`, `AgentTool`, `AgentToolResult`, `AgentToolUpdateCallback`, `StreamFn`.
+
+### Changed
+
+- `Agent` constructor now has all options optional (empty options use defaults).
+
+- `queueMessage()` is now synchronous (no longer returns a Promise).