@gajae-code/agent-core 0.12.5 → 0.12.7

package/CHANGELOG.md

@@ -2,7 +2,14 @@
 
 ## [Unreleased]
 
+## [0.12.7] - 2026-07-31
+
+## [0.12.6] - 2026-07-31
+
 ## [0.12.5] - 2026-07-30
+### Fixed
+
+- Proxy streams now fail closed when a `toolcall_end` event references missing or non-tool-call content instead of silently dropping the protocol violation and accepting a later terminal event.
 
 ## [0.12.4] - 2026-07-30
 

package/dist/types/agent-loop.d.ts

@@ -3,6 +3,7 @@
  * Transforms to Message[] only at the LLM call boundary.
  */
 import { type Context, EventStream } from "@gajae-code/ai";
+import type { AttemptScope } from "./attempt-scope";
 import { type AgentRunCoverage, type AgentRunSummary } from "./run-collector";
 import type { AgentContext, AgentEvent, AgentLoopConfig, AgentMessage, StreamFn } from "./types";
 /** Sentinel returned by the abort race in `streamAssistantResponse`. */
@@ -17,7 +18,7 @@ export declare const MANAGED_ATTEMPT_MAX_STAGED_BYTES: number;
  * Start an agent loop with a new prompt message.
  * The prompt is added to the context and events are emitted for it.
  */
-export declare function agentLoop(prompts: AgentMessage[], context: AgentContext, config: AgentLoopConfig, signal?: AbortSignal, streamFn?: StreamFn, emitManagedAgentStart?: boolean): EventStream<AgentEvent, AgentMessage[]>;
+export declare function agentLoop(prompts: AgentMessage[], context: AgentContext, config: AgentLoopConfig, signal?: AbortSignal, streamFn?: StreamFn, emitAgentStart?: boolean, initialScope?: AttemptScope): EventStream<AgentEvent, AgentMessage[]>;
 /**
  * Continue an agent loop from the current context without adding a new message.
  * Used for retries - context already has user message or tool results.
@@ -26,7 +27,7 @@ export declare function agentLoop(prompts: AgentMessage[], context: AgentContext
  * via `convertToLlm`. If it doesn't, the LLM provider will reject the request.
  * This cannot be validated here since `convertToLlm` is only called once per turn.
  */
-export declare function agentLoopContinue(context: AgentContext, config: AgentLoopConfig, signal?: AbortSignal, streamFn?: StreamFn, emitManagedAgentStart?: boolean): EventStream<AgentEvent, AgentMessage[]>;
+export declare function agentLoopContinue(context: AgentContext, config: AgentLoopConfig, signal?: AbortSignal, streamFn?: StreamFn, emitAgentStart?: boolean, initialScope?: AttemptScope): EventStream<AgentEvent, AgentMessage[]>;
 /**
  * Hard work budget for one degraded snapshot: every visited node AND every
  * enumerated own key is debited against this budget before it is processed

package/dist/types/agent.d.ts

@@ -3,8 +3,9 @@
  */
 import { type AssistantMessage, type AssistantMessageEvent, type CursorExecHandlers, type CursorToolResultHandler, type Effort, type ImageContent, type Message, type Model, type ProviderSessionState, type ServiceTier, type SimpleStreamOptions, type ThinkingBudgets, type ToolChoice } from "@gajae-code/ai";
 import type { AppendOnlyContextManager } from "./append-only-context";
+import type { AttemptScope } from "./attempt-scope";
 import type { HarmonyAuditEvent } from "./harmony-leak";
-import type { AgentEvent, AgentLoopConfig, AgentMessage, AgentState, AgentTool, AgentToolContext, ManagedLogicalRunId, RunResourceLedger, RunTerminalRequest, StreamFn, ToolCallContext } from "./types";
+import type { AgentEvent, AgentLoopConfig, AgentMessage, AgentState, AgentTool, AgentToolContext, ManagedLogicalRunId, RunCancellationDomainBridge, RunResourceLedger, RunTerminalRequest, StreamFn, ToolCallContext } from "./types";
 /**
  * Whether persisted history ends at a point where a new model turn can resume.
  * Assistant-ended histories require an in-memory queued message and are handled
@@ -28,7 +29,7 @@ export interface AgentOptions {
      * Optional transform applied to context before convertToLlm.
      * Use for context pruning, injecting external context, etc.
      */
-    transformContext?: (messages: AgentMessage[], signal?: AbortSignal) => Promise<AgentMessage[]>;
+    transformContext?: (messages: AgentMessage[], signal?: AbortSignal, scope?: AttemptScope) => Promise<AgentMessage[]>;
     /**
      * Steering mode: "all" = send all steering messages at once, "one-at-a-time" = one per turn
      */
@@ -177,8 +178,11 @@ export interface AgentPromptOptions {
     toolChoice?: ToolChoice;
     /** Disable transport replay; fallback accounting is owned by the caller. */
     fallbackManaged?: boolean;
+    /** Continue a cooperative maintenance checkpoint under its existing logical run and cancellation domain. */
+    maintenanceContinuation?: boolean;
     /** Called synchronously after this invocation claims the agent run, before asynchronous provider work. */
-    onRunAccepted?: () => void;
+    /** Receives the immutable run handle as the first callback argument. */
+    onRunAccepted?: (...args: any[]) => void;
     /** Called once immediately before every managed upstream request. */
     nextFallbackAttempt?: AgentLoopConfig["nextFallbackAttempt"];
     /** Called after a managed upstream request is accepted and committed. */
@@ -194,6 +198,14 @@ export declare class Agent {
     #private;
     get intentTracing(): boolean;
     readonly resourceLedger: RunResourceLedger;
+    bindRunCancellationDomainBridge(bridge: RunCancellationDomainBridge, agentSessionClaimKey?: object): void;
+    /** Mint a side-attempt scope and its authority unregister function. */
+    mintSideAttemptScope(): {
+        scope: AttemptScope;
+        dispose: () => void;
+    };
+    /** Return the Agent-owned attempt scope authority for session record injection. */
+    getAttemptScopeAuthority(): import("./attempt-scope").AttemptScopeAuthority;
     streamFn: StreamFn;
     getApiKey?: (provider: string) => Promise<string | undefined> | string | undefined;
     getAuthCredentialType?: (provider: string) => "api_key" | "oauth" | undefined;
@@ -416,7 +428,7 @@ export declare class Agent {
      * did not drain. The abandoned provider/tool stream may still settle later, so
      * #runLoop guards every state mutation with a run id.
      */
-    forceAbort(reason?: string): boolean;
+    forceAbort(reason?: string, logicalRunId?: ManagedLogicalRunId | number): boolean;
     waitForIdle(): Promise<void>;
     /** The active per-attempt run identifier. */
     get activeRunId(): number | undefined;

package/dist/types/attempt-scope.d.ts

@@ -0,0 +1,84 @@
+/**
+ * Per-attempt scope identity for request-scoped execution attribution.
+ *
+ * An AttemptScope is an immutable, frozen value allocated before every
+ * observable lifecycle emission for a single provider/agent attempt.
+ * It carries a stable `attemptId`, a monotonic `generation` (per-lineage),
+ * and a `lineage` discriminator that distinguishes the main attempt from
+ * concurrent side attempts (IRC background, ephemeral/btw turns).
+ *
+ * The `attemptId` + `generation` + `lineage` form the comparable identity.
+ * AttemptScope is structurally assignable to AttemptScopeRef in
+ * `packages/ai` so it can be carried through `SimpleStreamOptions` and
+ * provider hook signatures without a reverse dependency.
+ */
+export type AttemptLineage = "main" | `side:${string}`;
+export interface AttemptScope {
+    readonly attemptId: string;
+    readonly generation: number;
+    readonly lineage: AttemptLineage;
+}
+export declare function attemptScopesEqual(a: AttemptScope, b: AttemptScope): boolean;
+/**
+ * Per-lineage currentness authority. Main and side attempts have separate
+ * instances so a side attempt never invalidates the main scope, and
+ * `forceAbort` advances only the main lineage.
+ */
+export interface LineageCurrentness {
+    readonly lineage: AttemptLineage;
+    /** True iff no successor scope with a greater generation was allocated in this lineage. */
+    isCurrent(scope: AttemptScope): boolean;
+    /** Allocate the next generation for the given attempt identity in this lineage. */
+    advance(attemptId: string): number;
+    /** Allocate the next generation in this lineage. */
+    /** Current generation value for this lineage. */
+    readonly current: number;
+}
+export declare function createLineageCurrentness(lineage: AttemptLineage): LineageCurrentness;
+/**
+ * Agent-owned authority over all attempt lineages. Owns the main lineage;
+ * side lineages are registered/removed with bounded lifecycle.
+ *
+ * This is the SINGLE source of currentness truth injected into
+ * AttemptRecordStore (packages/coding-agent). Every store operation
+ * calls `authority.isCurrent(scope)` and fails closed when the authority
+ * is missing or the scope is superseded.
+ */
+export interface AttemptScopeAuthority {
+    /** Register a side-lineage authority. Returns an unregister function. */
+    registerSide(lineage: AttemptLineage, auth: LineageCurrentness): () => void;
+    /** True iff the scope's lineage is known and its generation is current. */
+    isCurrent(scope: AttemptScope): boolean;
+    /** Advance the main lineage (called by forceAbort). Returns the new generation. */
+    advanceMain(): number;
+    /** Mint the next main-lineage scope. */
+    mintMain(): AttemptScope;
+    /**
+     * Atomically register a fresh side lineage, mint a side scope, and return
+     * both the scope and a dispose function. The authority knows the lineage
+     * BEFORE the scope is returned, so `isCurrent` succeeds immediately.
+     */
+    mintSide(): {
+        scope: AttemptScope;
+        dispose: () => void;
+    };
+}
+export interface AttemptMinter {
+    mint(lineage: AttemptLineage): AttemptScope;
+}
+export declare function createAttemptMinter(): AttemptMinter;
+/**
+ * Create the Agent-owned authority. Owns the main lineage and a bounded
+ * (LRU-capped) map of side lineages. Only RETIRED side authorities are
+ * eligible for LRU eviction; a live side attempt is never silently
+ * invalidated by a newer side registration.
+ */
+export declare function createAttemptScopeAuthority(): AttemptScopeAuthority;
+/**
+ * Immutable per-run attempt handle, carried through terminal/finalizer paths.
+ * Keyed by logicalRunId in the Agent's `#runHandles` map.
+ */
+export interface AttemptRunHandle {
+    readonly logicalRunId: number | import("./types.js").ManagedLogicalRunId;
+    readonly scope: AttemptScope;
+}

package/dist/types/types.d.ts

@@ -1,5 +1,6 @@
 import type { AssistantMessage, AssistantMessageEvent, AssistantMessageEventStream, Effort, ImageContent, Message, Model, SimpleStreamOptions, Static, streamSimple, TextContent, Tool, ToolChoice, ToolResultMessage, TransportFailureFacts, TSchema } from "@gajae-code/ai";
 import type { AppendOnlyContextManager } from "./append-only-context";
+import type { AttemptMinter, AttemptRunHandle, AttemptScope } from "./attempt-scope";
 import type { HarmonyAuditEvent } from "./harmony-leak";
 import type { AgentRunCoverage, AgentRunSummary } from "./run-collector";
 import type { AgentTelemetryConfig } from "./telemetry";
@@ -15,15 +16,94 @@ export interface RunResourceEntry {
     label: string;
     registeredAt: number;
 }
+export type RunSettlementReason = "unknown_run" | "run_not_sealed" | "resources_pending" | "quarantined";
 export type RunSettlementProof = {
     status: "settled";
 } | {
     status: "unfenced";
+    reason: RunSettlementReason;
     pending: RunResourceEntry[];
 };
+export interface RunCancellationDomain {
+    readonly resourceRunId: string;
+    readonly signal: AbortSignal;
+}
+export interface RunCancellationDomainBridge {
+    open(resourceRunId: string): {
+        ok: true;
+        domain: RunCancellationDomain;
+        created: boolean;
+    } | {
+        ok: false;
+        reason: "duplicate_identity" | "quarantined";
+    };
+    lookup(resourceRunId: string): RunCancellationDomain | undefined;
+    abort(resourceRunId: string, reason?: unknown): {
+        ok: true;
+        newlyAborted: boolean;
+    } | {
+        ok: false;
+        reason: "unknown_run" | "quarantined";
+    };
+    release(resourceRunId: string, disposition: "settled" | "quarantined"): void;
+}
+export type ReserveProducerResult = {
+    ok: true;
+    lease: RunResourceProducerLease;
+} | {
+    ok: false;
+    reason: "unknown_run" | "sealed" | "quarantined" | "domain_mismatch";
+};
+export type ClaimProducerResult = {
+    ok: true;
+    lease: RunResourceProducerLease;
+} | {
+    ok: false;
+    reason: "already_claimed" | "handle_mismatch" | "domain_mismatch" | "closed" | "quarantined";
+};
+export type ForkProducerResult = {
+    ok: true;
+    lease: RunResourceProducerLease;
+} | {
+    ok: false;
+    reason: "parent_closed" | "quarantined" | "domain_mismatch";
+};
+export interface RunResourceProducerLease {
+    readonly resourceRunId: string;
+    readonly domain: RunCancellationDomain;
+    readonly signal: AbortSignal;
+    track(kind: RunResourceKind, label: string, settled: PromiseLike<unknown>): boolean;
+    fork(expectedDomain: RunCancellationDomain, kind: RunResourceKind, label: string): ForkProducerResult;
+    closeDiscovery(): void;
+}
+export interface AgentTerminalOwnerContext {
+    readonly resourceRunId: string;
+    readonly domain: RunCancellationDomain;
+}
+export declare function setAgentTerminalOwnerContext(event: object, context: AgentTerminalOwnerContext): void;
+export declare function getAgentTerminalOwnerContext(event: object): AgentTerminalOwnerContext | undefined;
+export interface StandaloneRunOwnership {
+    readonly resourceRunId: string;
+    readonly domain: RunCancellationDomain;
+    claimContinuation(): {
+        ok: true;
+        ownership: StandaloneRunOwnership;
+    } | {
+        ok: false;
+        reason: "already_claimed" | "terminal" | "quarantined";
+    };
+    abandon(reason: "cancelled" | "error"): void;
+}
 export interface RunResourceLedger {
+    /** Bind the bridge once, before any logical run may be opened. */
+    bindCancellationDomainBridge(bridge: RunCancellationDomainBridge): void;
+    /** Bind the unforgeable AgentSession claim key once, before terminal publication. */
+    bindAgentSessionClaimKey(key: object): void;
     /** Reserve a run handle before publishing its `agent_start` event. */
-    open(resourceRunId: string): void;
+    open(resourceRunId: string): RunCancellationDomain | undefined;
+    lookupDomain(resourceRunId: string): RunCancellationDomain | undefined;
+    reserveProducer(resourceRunId: string, expectedDomain: RunCancellationDomain | undefined, kind: RunResourceKind, label: string): ReserveProducerResult;
+    claimProducer(resourceRunId: string, expectedDomain: RunCancellationDomain | undefined, ownerKey: object): ClaimProducerResult;
     track(resourceRunId: string, kind: RunResourceKind, label: string, settled: PromiseLike<unknown>): void;
     pending(resourceRunId: string): RunResourceEntry[];
     /** Seal a run after terminal event publication; only sealed empty runs settle. */
@@ -54,6 +134,10 @@ export interface ManagedAttemptContinuationOwnership {
     /** Stable managed logical-run id; use for all terminal completion requests. */
     readonly logicalRunId: ManagedLogicalRunId;
     readonly generation: number;
+    readonly domain: RunCancellationDomain;
+    readonly lease: RunResourceProducerLease;
+    /** Immutable per-attempt handle used by terminalizers and continuations. */
+    readonly handle: AttemptRunHandle;
     isCurrent(): boolean;
 }
 /** Runs after a discarded attempt is idle, only while its ownership token remains current. */
@@ -77,12 +161,15 @@ export type ManagedAttemptOutcome = {
         /** Exact provider transport facts, including retry headers, for fallback policy. */
         transportFailure?: TransportFailureFacts;
     };
+    scope?: AttemptScope;
 } | {
     type: "context_overflow_discarded";
     message: AssistantMessage;
+    scope?: AttemptScope;
 } | {
     type: "run_terminal";
     reason: "cancelled" | "error" | "exhausted";
+    scope?: AttemptScope;
 };
 export type ManagedAttemptOutcomeHandler = (outcome: ManagedAttemptOutcome) => ManagedAttemptDecision | Promise<ManagedAttemptDecision>;
 /**
@@ -108,6 +195,10 @@ export interface AgentLoopConfig extends SimpleStreamOptions {
     onManagedAttemptAccepted?: () => void | Promise<void>;
     /** Receives a managed invocation outcome without publishing provisional lifecycle events. */
     onManagedAttemptOutcome?: ManagedAttemptOutcomeHandler;
+    /** Per-attempt scope allocator for direct loop callers. */
+    attemptMinter?: AttemptMinter;
+    /** Scope allocated by the owning Agent for the first attempt in this loop. */
+    initialScope?: AttemptScope;
     /**
      * When to interrupt tool execution for steering messages.
      * - "immediate" = check after each tool call (default)
@@ -175,7 +266,7 @@ export interface AgentLoopConfig extends SimpleStreamOptions {
      * }
      * ```
      */
-    transformContext?: (messages: AgentMessage[], signal?: AbortSignal) => Promise<AgentMessage[]>;
+    transformContext?: (messages: AgentMessage[], signal?: AbortSignal, scope?: AttemptScope) => Promise<AgentMessage[]>;
     /**
      * Resolves an API key dynamically for each LLM call.
      *
@@ -336,6 +427,12 @@ export interface AgentLoopConfig extends SimpleStreamOptions {
     resourceLedger?: RunResourceLedger;
     /** Stable resource ownership identifier for this prompt run. */
     resourceRunId?: string;
+    /** Immutable logical cancellation domain bound by the resource ledger. */
+    resourceCancellationDomain?: RunCancellationDomain;
+    /** Agent passes caller ownership; direct loop callers retain loop-owned sealing. */
+    resourceSealOwner?: "caller" | "loop";
+    /** Opaque ownership required to resume a standalone maintenance lifecycle. */
+    standaloneRunOwnership?: StandaloneRunOwnership;
 }
 /**
  * Batch/sequencing metadata for the tool call currently being processed.
@@ -465,6 +562,8 @@ export interface RenderResultOptions {
  * Apps can extend via declaration merging.
  */
 export interface AgentToolContext {
+    /** Per-attempt scope used to attribute tool lifecycle and extension delivery. */
+    attemptScope?: AttemptScope;
 }
 export type AgentToolExecFn<TParameters extends TSchema = TSchema, TDetails = any, TTheme = unknown> = (this: AgentTool<TParameters, TDetails, TTheme>, toolCallId: string, params: Static<TParameters>, signal?: AbortSignal, onUpdate?: AgentToolUpdateCallback<TDetails, TParameters>, context?: AgentToolContext) => Promise<AgentToolResult<TDetails, TParameters>>;
 export interface AgentTool<TParameters extends TSchema = TSchema, TDetails = any, TTheme = unknown> extends Tool<TParameters> {
@@ -513,6 +612,7 @@ export interface AgentContext {
  */
 export type AgentEvent = {
     type: "agent_start";
+    scope?: AttemptScope;
 } | {
     type: "agent_end";
     messages: AgentMessage[];
@@ -523,38 +623,47 @@ export type AgentEvent = {
     /** Present iff `AgentTelemetryConfig` was supplied on this run. */
     telemetry?: AgentRunSummary;
     coverage?: AgentRunCoverage;
+    scope?: AttemptScope;
 } | {
     type: "turn_start";
+    scope?: AttemptScope;
 } | {
     type: "turn_end";
     message: AgentMessage;
     toolResults: ToolResultMessage[];
+    scope?: AttemptScope;
 } | {
     type: "message_start";
     message: AgentMessage;
+    scope?: AttemptScope;
 } | {
     type: "message_update";
     message: AgentMessage;
     assistantMessageEvent: AssistantMessageEvent;
+    scope?: AttemptScope;
 } | {
     type: "message_end";
     message: AgentMessage;
+    scope?: AttemptScope;
 } | {
     type: "tool_execution_start";
     toolCallId: string;
     toolName: string;
     args: any;
     intent?: string;
+    scope?: AttemptScope;
 } | {
     type: "tool_execution_update";
     toolCallId: string;
     toolName: string;
     args: any;
     partialResult: any;
+    scope?: AttemptScope;
 } | {
     type: "tool_execution_end";
     toolCallId: string;
     toolName: string;
     result: any;
     isError?: boolean;
+    scope?: AttemptScope;
 };

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@gajae-code/agent-core",
-	"version": "0.12.5",
+	"version": "0.12.7",
 	"description": "General-purpose agent with transport abstraction, state management, and attachment support",
 	"homepage": "https://gajae-code.com",
 	"author": "Yeachan-Heo and Gajae Code Contributors",
@@ -32,9 +32,9 @@
 		"fmt": "biome format --write ."
 	},
 	"dependencies": {
-		"@gajae-code/ai": "0.12.5",
-		"@gajae-code/natives": "0.12.5",
-		"@gajae-code/utils": "0.12.5",
+		"@gajae-code/ai": "0.12.7",
+		"@gajae-code/natives": "0.12.7",
+		"@gajae-code/utils": "0.12.7",
 		"@opentelemetry/api": "^1.9.0"
 	},
 	"devDependencies": {