@orkestrel/agent 0.0.22 → 0.0.24

package/dist/src/core/index.d.cts

@@ -486,6 +486,14 @@ export declare type AgentEventMap = {
  * - **Bounded.** Each turn arms a single cancel folded from the external `signal`, the
  *   `timeout` deadline, and the `budget` signal (through `AbortSignal.any`); any of them —
  *   or `abort()` — stops the loop and settles the result `partial: true`.
+ *   Tool handlers receive that run's signal through their `ToolContext`. An agent abort,
+ *   stream abort, external signal, or deadline can reach a running handler. The budget is
+ *   charged during provider streaming and between turns, before tool dispatch; exhaustion
+ *   ends the run without dispatching, never inside a handler. An abort before dispatch
+ *   appends neither the assistant call turn nor tool messages and emits no tool chunk;
+ *   streamed content remains in the partial result. Cancellation after entry is cooperative:
+ *   the loop awaits a running handler even when it ignores the signal.
+ *   The agent supplies no caller identity.
  * - **Paced + capped.** The `scheduler` (when given) yields between turns; tool
  *   iteration is capped at `limit` so the loop always terminates.
  * - **Two observation surfaces.** Pull: the {@link AgentChunk} stream (`stream().events`)
@@ -3826,7 +3834,7 @@ export declare type MessageRole = 'system' | 'user' | 'assistant' | 'tool';
  *
  * @remarks
  * The wire is strictly narrower than Message: non-JSON call arguments are refused,
- * and caller context is refused by the guard or dropped by the parser.
+ * and execution context stays local. The guard refuses extra members; the parser drops them.
  */
 export declare const messageShape: ObjectShape<    {
 id: StringShape;
@@ -4056,7 +4064,8 @@ readonly [k: string]: JSONValue;
  *
  * @remarks
  * The wire is strictly narrower than ProviderRequest: non-JSON arguments, parameters,
- * or schema members are refused, and caller context is refused or dropped.
+ * or schema members are refused. Execution context stays local; the guard refuses
+ * extra members, and the parser drops them.
  */
 export declare const providerRequestShape: ObjectShape<    {
 messages: ArrayShape<ObjectShape<    {
@@ -4130,7 +4139,7 @@ total: number;
  *
  * @remarks
  * The wire is strictly narrower than ProviderResult: non-JSON call arguments are
- * refused, and caller context is refused or dropped.
+ * refused. Execution context stays local; the guard refuses extra members, and the parser drops them.
  */
 export declare const providerResultShape: ObjectShape<    {
 content: StringShape;
@@ -4284,7 +4293,8 @@ message: string;
  *
  * @remarks
  * The wire is strictly narrower than RelayFrame through its result and partial
- * fields: non-JSON arguments are refused, and caller context is refused or dropped.
+ * fields: non-JSON arguments are refused. Execution context stays local; the guard
+ * refuses extra members, and the parser drops them.
  */
 export declare const relayFrameShape: UnionShape<readonly [ObjectShape<    {
 channel: LiteralShape<readonly ["content", "thinking"]>;
@@ -4353,7 +4363,8 @@ export declare interface RelayOptions {
  * Carries provider calls over an authenticated NDJSON relay endpoint.
  *
  * @remarks
- * The `ToolCall.caller` member never crosses the hop. The wire body is an owned snapshot of
+ * Tool execution context stays local; calls carry only `id`, `name`, and `arguments`.
+ * The wire body is an owned snapshot of
  * the projection read through property descriptors, so a serializer reachable only through a
  * `get` trap or a prototype is never consulted; an own function-valued property such as a
  * `toJSON` method is a value outside JSON and is refused before fetching, with the clone's
@@ -4398,7 +4409,7 @@ export declare class RelayProvider extends AgentProvider {
      * value carries is ignored rather than consulted and cannot reach the wire.
      *
      * @param request - The domain conversation and call configuration
-     * @returns The validated wire request with caller context omitted
+     * @returns The validated wire request
      * @throws {ProviderError} Thrown when the snapshot cannot be taken — a hostile read or a
      * value outside JSON — carrying that failure as its `cause`, and when the snapshot the
      * projection produced is not a valid wire request
@@ -5065,8 +5076,8 @@ export declare interface ThinkSplitterInterface {
  *
  * @remarks
  * The wire is strictly narrower than the domain: non-JSON arguments are refused.
- * ToolCall.caller is not in this shape and never crosses a wire. The guard refuses
- * that extra member; the contract parser drops it.
+ * Calls carry only id, name, and arguments; execution context stays local.
+ * The guard refuses every extra member; the contract parser drops extra members.
  */
 export declare const toolCallShape: ObjectShape<    {
 id: StringShape;

package/dist/src/core/index.d.ts

@@ -486,6 +486,14 @@ export declare type AgentEventMap = {
  * - **Bounded.** Each turn arms a single cancel folded from the external `signal`, the
  *   `timeout` deadline, and the `budget` signal (through `AbortSignal.any`); any of them —
  *   or `abort()` — stops the loop and settles the result `partial: true`.
+ *   Tool handlers receive that run's signal through their `ToolContext`. An agent abort,
+ *   stream abort, external signal, or deadline can reach a running handler. The budget is
+ *   charged during provider streaming and between turns, before tool dispatch; exhaustion
+ *   ends the run without dispatching, never inside a handler. An abort before dispatch
+ *   appends neither the assistant call turn nor tool messages and emits no tool chunk;
+ *   streamed content remains in the partial result. Cancellation after entry is cooperative:
+ *   the loop awaits a running handler even when it ignores the signal.
+ *   The agent supplies no caller identity.
  * - **Paced + capped.** The `scheduler` (when given) yields between turns; tool
  *   iteration is capped at `limit` so the loop always terminates.
  * - **Two observation surfaces.** Pull: the {@link AgentChunk} stream (`stream().events`)
@@ -3826,7 +3834,7 @@ export declare type MessageRole = 'system' | 'user' | 'assistant' | 'tool';
  *
  * @remarks
  * The wire is strictly narrower than Message: non-JSON call arguments are refused,
- * and caller context is refused by the guard or dropped by the parser.
+ * and execution context stays local. The guard refuses extra members; the parser drops them.
  */
 export declare const messageShape: ObjectShape<    {
 id: StringShape;
@@ -4056,7 +4064,8 @@ readonly [k: string]: JSONValue;
  *
  * @remarks
  * The wire is strictly narrower than ProviderRequest: non-JSON arguments, parameters,
- * or schema members are refused, and caller context is refused or dropped.
+ * or schema members are refused. Execution context stays local; the guard refuses
+ * extra members, and the parser drops them.
  */
 export declare const providerRequestShape: ObjectShape<    {
 messages: ArrayShape<ObjectShape<    {
@@ -4130,7 +4139,7 @@ total: number;
  *
  * @remarks
  * The wire is strictly narrower than ProviderResult: non-JSON call arguments are
- * refused, and caller context is refused or dropped.
+ * refused. Execution context stays local; the guard refuses extra members, and the parser drops them.
  */
 export declare const providerResultShape: ObjectShape<    {
 content: StringShape;
@@ -4284,7 +4293,8 @@ message: string;
  *
  * @remarks
  * The wire is strictly narrower than RelayFrame through its result and partial
- * fields: non-JSON arguments are refused, and caller context is refused or dropped.
+ * fields: non-JSON arguments are refused. Execution context stays local; the guard
+ * refuses extra members, and the parser drops them.
  */
 export declare const relayFrameShape: UnionShape<readonly [ObjectShape<    {
 channel: LiteralShape<readonly ["content", "thinking"]>;
@@ -4353,7 +4363,8 @@ export declare interface RelayOptions {
  * Carries provider calls over an authenticated NDJSON relay endpoint.
  *
  * @remarks
- * The `ToolCall.caller` member never crosses the hop. The wire body is an owned snapshot of
+ * Tool execution context stays local; calls carry only `id`, `name`, and `arguments`.
+ * The wire body is an owned snapshot of
  * the projection read through property descriptors, so a serializer reachable only through a
  * `get` trap or a prototype is never consulted; an own function-valued property such as a
  * `toJSON` method is a value outside JSON and is refused before fetching, with the clone's
@@ -4398,7 +4409,7 @@ export declare class RelayProvider extends AgentProvider {
      * value carries is ignored rather than consulted and cannot reach the wire.
      *
      * @param request - The domain conversation and call configuration
-     * @returns The validated wire request with caller context omitted
+     * @returns The validated wire request
      * @throws {ProviderError} Thrown when the snapshot cannot be taken — a hostile read or a
      * value outside JSON — carrying that failure as its `cause`, and when the snapshot the
      * projection produced is not a valid wire request
@@ -5065,8 +5076,8 @@ export declare interface ThinkSplitterInterface {
  *
  * @remarks
  * The wire is strictly narrower than the domain: non-JSON arguments are refused.
- * ToolCall.caller is not in this shape and never crosses a wire. The guard refuses
- * that extra member; the contract parser drops it.
+ * Calls carry only id, name, and arguments; execution context stays local.
+ * The guard refuses every extra member; the contract parser drops extra members.
  */
 export declare const toolCallShape: ObjectShape<    {
 id: StringShape;

package/dist/src/core/index.js

@@ -1,4 +1,4 @@
-import { arrayOf, arrayShape, attempt, booleanShape, cloneJSONValue, createContract, isArray, isBoolean, isFiniteNumber, isObject, isRecord, isString, jsonShape, literalShape, numberShape, objectShape, optionalShape, parseJSONAs, parseJSONValue, rawShape, recordShape, stringShape, unionShape } from "@orkestrel/contract";
+import { arrayOf, arrayShape, attempt, booleanShape, cloneJSONValue, createContract, isArray, isBoolean, isFiniteNumber, isInstance, isObject, isRecord, isString, jsonShape, literalShape, numberShape, objectShape, optionalShape, parseJSONAs, parseJSONValue, rawShape, recordShape, stringShape, unionShape } from "@orkestrel/contract";
 import { createDatabase, createMemoryDriver } from "@orkestrel/database";
 import { createQueue } from "@orkestrel/queue";
 import { createRunner, errorToMessage } from "@orkestrel/workflow";
@@ -187,7 +187,7 @@ var ProviderAbortError = class extends Error {
 * ```
 */
 function isProviderAbortError(value) {
-	return value instanceof ProviderAbortError;
+	return isInstance(value, ProviderAbortError);
 }
 /**
 * Reports an {@link AgentInterface} run that ended {@link AgentResult.partial} under a
@@ -234,7 +234,7 @@ var AgentJobError = class extends Error {
 * ```
 */
 function isAgentJobError(value) {
-	return value instanceof AgentJobError;
+	return isInstance(value, AgentJobError);
 }
 /**
 * Reports a conversation with no {@link ConversationSummaryHandler} to fold its messages with,
@@ -278,7 +278,7 @@ var ConversationError = class extends Error {
 * ```
 */
 function isConversationError(value) {
-	return value instanceof ConversationError;
+	return isInstance(value, ConversationError);
 }
 /**
 * Reports a concurrent run that would corrupt shared per-agent accounting, or a rehydration
@@ -324,7 +324,7 @@ var AgentError = class extends Error {
 * ```
 */
 function isAgentError(value) {
-	return value instanceof AgentError;
+	return isInstance(value, AgentError);
 }
 /**
 * Reports a coded provider failure with its HTTP status and underlying cause when available.
@@ -358,7 +358,7 @@ var ProviderError = class extends Error {
 * ```
 */
 function isProviderError(value) {
-	return value instanceof ProviderError;
+	return isInstance(value, ProviderError);
 }
 //#endregion
 //#region src/core/shapers.ts
@@ -367,8 +367,8 @@ function isProviderError(value) {
 *
 * @remarks
 * The wire is strictly narrower than the domain: non-JSON arguments are refused.
-* ToolCall.caller is not in this shape and never crosses a wire. The guard refuses
-* that extra member; the contract parser drops it.
+* Calls carry only id, name, and arguments; execution context stays local.
+* The guard refuses every extra member; the contract parser drops extra members.
 */
 var toolCallShape = objectShape({
 	id: stringShape(),
@@ -380,7 +380,7 @@ var toolCallShape = objectShape({
 *
 * @remarks
 * The wire is strictly narrower than Message: non-JSON call arguments are refused,
-* and caller context is refused by the guard or dropped by the parser.
+* and execution context stays local. The guard refuses extra members; the parser drops them.
 */
 var messageShape = objectShape({
 	id: stringShape(),
@@ -399,7 +399,8 @@ var messageShape = objectShape({
 *
 * @remarks
 * The wire is strictly narrower than ProviderRequest: non-JSON arguments, parameters,
-* or schema members are refused, and caller context is refused or dropped.
+* or schema members are refused. Execution context stays local; the guard refuses
+* extra members, and the parser drops them.
 */
 var providerRequestShape = objectShape({
 	messages: arrayShape(messageShape),
@@ -418,7 +419,7 @@ var providerRequestShape = objectShape({
 *
 * @remarks
 * The wire is strictly narrower than ProviderResult: non-JSON call arguments are
-* refused, and caller context is refused or dropped.
+* refused. Execution context stays local; the guard refuses extra members, and the parser drops them.
 */
 var providerResultShape = objectShape({
 	content: stringShape(),
@@ -435,7 +436,8 @@ var providerResultShape = objectShape({
 *
 * @remarks
 * The wire is strictly narrower than RelayFrame through its result and partial
-* fields: non-JSON arguments are refused, and caller context is refused or dropped.
+* fields: non-JSON arguments are refused. Execution context stays local; the guard
+* refuses extra members, and the parser drops them.
 */
 var relayFrameShape = unionShape(objectShape({
 	channel: literalShape(["content", "thinking"]),
@@ -723,7 +725,7 @@ function renderFencedFile(path, language, content) {
 * @returns The floored count, or `0` when the value is non-finite or non-positive
 */
 function sanitizeToken(value) {
-	return Number.isFinite(value) && value > 0 ? Math.floor(value) : 0;
+	return isFiniteNumber(value) && value > 0 ? Math.floor(value) : 0;
 }
 /**
 * Sanitizes a {@link TokenUsage} into safe, non-negative integers — the guard an agent's
@@ -2162,13 +2164,19 @@ var Agent = class {
 				};
 			}
 			if (result.tools !== void 0 && result.tools.length > 0) {
+				const authorization = this.#authorize(result.tools);
+				if (abort.signal.aborted) {
+					partial = true;
+					broke = true;
+					break;
+				}
 				const assistant = this.#context.messages.add({
 					role: "assistant",
 					content: result.content,
 					calls: result.tools
 				});
 				messages.push(assistant);
-				const results = await this.#authorize(tools, result.tools);
+				const results = await this.#dispatch(tools, result.tools, abort.signal, authorization);
 				for (let index = 0; index < result.tools.length; index += 1) {
 					const call = result.tools[index];
 					const outcomeResult = results[index];
@@ -2228,8 +2236,8 @@ var Agent = class {
 		messages.splice(0, messages.length, ...this.#context.build(this.#provider.format));
 		return false;
 	}
-	async #authorize(tools, calls) {
-		if (this.#authority === void 0) return tools.execute(calls);
+	#authorize(calls) {
+		if (this.#authority === void 0) return void 0;
 		const authority = this.#authority;
 		const allowed = [];
 		const denials = /* @__PURE__ */ new Map();
@@ -2249,7 +2257,15 @@ var Agent = class {
 				this.#emitter.emit("deny", call, decision.reason);
 			}
 		}
-		const executed = allowed.length > 0 ? await tools.execute(allowed) : [];
+		return {
+			allowed,
+			denials
+		};
+	}
+	async #dispatch(tools, calls, signal, authorization) {
+		if (authorization === void 0) return tools.execute(calls, { signal });
+		const { allowed, denials } = authorization;
+		const executed = allowed.length > 0 ? await tools.execute(allowed, { signal }) : [];
 		const byId = new Map(denials);
 		for (const result of executed) byId.set(result.id, result);
 		return calls.map((call) => byId.get(call.id) ?? denyCall(call, void 0));
@@ -2933,7 +2949,8 @@ var AgentProvider = class {
 * Carries provider calls over an authenticated NDJSON relay endpoint.
 *
 * @remarks
-* The `ToolCall.caller` member never crosses the hop. The wire body is an owned snapshot of
+* Tool execution context stays local; calls carry only `id`, `name`, and `arguments`.
+* The wire body is an owned snapshot of
 * the projection read through property descriptors, so a serializer reachable only through a
 * `get` trap or a prototype is never consulted; an own function-valued property such as a
 * `toJSON` method is a value outside JSON and is refused before fetching, with the clone's
@@ -2992,7 +3009,7 @@ var RelayProvider = class extends AgentProvider {
 	* value carries is ignored rather than consulted and cannot reach the wire.
 	*
 	* @param request - The domain conversation and call configuration
-	* @returns The validated wire request with caller context omitted
+	* @returns The validated wire request
 	* @throws {ProviderError} Thrown when the snapshot cannot be taken — a hostile read or a
 	* value outside JSON — carrying that failure as its `cause`, and when the snapshot the
 	* projection produced is not a valid wire request
@@ -3130,7 +3147,7 @@ var RelayStream = class {
 			if (step.done) this.#finish(controller);
 		} catch (error) {
 			if (this.#settled) return;
-			const frame = error instanceof ProviderAbortError ? {
+			const frame = isProviderAbortError(error) ? {
 				channel: "abort",
 				partial: error.partial
 			} : {