@orkestrel/agent 0.0.4 → 0.0.6

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

@@ -378,6 +378,13 @@ export declare type AgentEventMap = {
     readonly error: readonly [error: unknown];
     /** The run was cancelled (external signal / timeout / budget / `abort()`) — the cancel reason. */
     readonly abort: readonly [reason: unknown];
+    /**
+     * The loop exhausted its `limit` while still holding unresolved tool intent (the model
+     * requested tools on the very last allowed turn) — the turn count reached. Distinct from
+     * `abort`: exhaustion is NOT a cancel (no external signal / timeout / budget tripped), so
+     * this fires INSTEAD of `abort`, still followed by `finish` carrying the partial result.
+     */
+    readonly exhaust: readonly [turns: number];
     /**
      * AUTOMATIC compaction's summarizer THREW — a NON-FATAL warn channel (the run continues; see
      * {@link AgentOptions.window}). When the loop's between-turns / pre-first-turn auto-compaction
@@ -735,9 +742,17 @@ export declare interface AgentRegistryOptions {
  * `partial` is `true` when the turn was committed early from a cancel — an external
  * `signal` abort, the turn's own `abort()`, a `timeout` deadline, or an exhausted
  * `budget` — in which case `content` is whatever had accumulated when the cancel
- * landed. It is `false` for a turn that ran to a natural finish. `usage` is present
- * only when at least one provider call reported usage. `thinking` is present only
- * when a provider call surfaced reasoning it separated from the answer
+ * landed. `partial` is ALSO `true` when the loop exhausted its `limit` while still
+ * holding unresolved tool intent (the model requested tools on the very last allowed
+ * turn) — a distinct, non-cancel cause covered by {@link RunOutcome.exhausted} (see
+ * the `exhaust` {@link AgentEventMap} event). It is `false` for a turn that ran to a
+ * natural finish (including a `limit: 0` run, which never enters the loop). `usage` is
+ * present only when at least one provider call reported usage — an aborted run's `usage`
+ * INCLUDES the cancelled turn's tokens when the provider reports partial usage on the
+ * abort (folded in exactly like a completed turn's); a provider that cannot observe
+ * usage mid-stream (e.g. a daemon whose final counts never arrive before the cancel)
+ * reports none for that turn, and none is fabricated. `thinking` is present
+ * only when a provider call surfaced reasoning it separated from the answer
  * ({@link ProviderResult.thinking}, joined across the run's calls) — display/audit
  * metadata that never re-enters the conversation.
  */
@@ -802,6 +817,34 @@ export declare interface AgentRunOptions {
      * behaviour), so a caller that passes no options runs exactly as before.
      */
     readonly think?: boolean;
+    /**
+     * Constrain the response to this JSON-Schema shape, forwarded to the provider's `stream`
+     * as {@link ProviderStreamOptions.schema} — a per-run structured-output request. Omitted ⇒
+     * no constraint (the loop is byte-for-byte the prior behaviour).
+     */
+    readonly schema?: Readonly<Record<string, unknown>>;
+    /**
+     * Overrides {@link AgentOptions.limit} for THIS run only — the max tool-iteration turns
+     * before the loop stops. Omitted ⇒ the agent's constructed `limit` applies.
+     */
+    readonly limit?: number;
+    /**
+     * Overrides {@link AgentOptions.timeout} for THIS run only — a wall-clock deadline (ms)
+     * whose abort commits a partial result. Omitted ⇒ the agent's constructed `timeout` applies.
+     */
+    readonly timeout?: number;
+    /**
+     * Overrides {@link AgentOptions.budget} for THIS run only — a token cost bound whose abort
+     * commits a partial result; `start()`ed for this run exactly as the constructed budget is.
+     * Omitted ⇒ the agent's constructed `budget` applies.
+     */
+    readonly budget?: BudgetInterface<TokenUsage>;
+    /**
+     * An additional per-run external cancel, COMPOSED with {@link AgentOptions.signal} (both
+     * fold into the run's bound abort via `AbortSignal.any` — neither is dropped). Omitted ⇒
+     * only the agent's constructed `signal` (if any) applies.
+     */
+    readonly signal?: AbortSignal;
 }
 
 /**
@@ -3791,13 +3834,18 @@ export declare interface ProviderResult {
  * `think` OVERRIDES the provider's constructed reasoning preference for THIS call: `true`
  * asks the backend to separate reasoning natively (a thinking model returns it on its
  * `message.thinking` channel, surfaced as `'thinking'` {@link ProviderDelta}s + the final
- * {@link ProviderResult.thinking}); `false` suppresses it. Omitted ⇒ the provider's own
- * default applies (the constructor value), so the contract stays backward-safe — a caller
+ * {@link ProviderResult.thinking}); `false` suppresses it. `schema`, when given, asks the
+ * backend to constrain its response to the given JSON-Schema shape (the same open
+ * JSON-Schema record {@link ToolDefinition.parameters} already carries) — a structured-output
+ * request for THIS call only. Both omitted ⇒ the provider's own defaults apply (the
+ * constructor value / no schema constraint), so the contract stays backward-safe — a caller
  * that passes no options behaves exactly as before.
  */
 export declare interface ProviderStreamOptions {
     /** Override the provider's reasoning preference for this call; omitted ⇒ the provider default. */
     readonly think?: boolean;
+    /** Constrain the response to this JSON-Schema shape (the same open record {@link ToolDefinition.parameters} uses); omitted ⇒ no constraint. */
+    readonly schema?: Readonly<Record<string, unknown>>;
 }
 
 /**
@@ -3891,16 +3939,19 @@ export declare interface ReplaceResult {
  * the loop: `content` accumulates the streamed assistant text, `thinking` the
  * reasoning the provider calls separated from it ({@link ProviderResult.thinking},
  * joined across calls — `undefined` until one surfaces it), `usage` the summed
- * {@link TokenUsage} (present only when a provider call reported it), and `partial`
- * flips `true` when a cancel commits the run early. It is the INTERNAL precursor to
- * the settled `AgentResult` — the loop reads it back to assemble the public result —
- * not a caller-facing shape.
+ * {@link TokenUsage} (present only when a provider call reported it), `partial`
+ * flips `true` when a cancel commits the run early OR when the loop exhausts its
+ * `limit` with unresolved tool intent, and `exhausted` flips `true` in that second
+ * case specifically (a distinct, non-cancel cause the {@link AgentEventMap} `exhaust`
+ * event observes). It is the INTERNAL precursor to the settled `AgentResult` — the
+ * loop reads it back to assemble the public result — not a caller-facing shape.
  */
 export declare interface RunOutcome {
     content: string;
     thinking: string | undefined;
     usage: TokenUsage | undefined;
     partial: boolean;
+    exhausted: boolean;
 }
 
 /**

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

@@ -378,6 +378,13 @@ export declare type AgentEventMap = {
     readonly error: readonly [error: unknown];
     /** The run was cancelled (external signal / timeout / budget / `abort()`) — the cancel reason. */
     readonly abort: readonly [reason: unknown];
+    /**
+     * The loop exhausted its `limit` while still holding unresolved tool intent (the model
+     * requested tools on the very last allowed turn) — the turn count reached. Distinct from
+     * `abort`: exhaustion is NOT a cancel (no external signal / timeout / budget tripped), so
+     * this fires INSTEAD of `abort`, still followed by `finish` carrying the partial result.
+     */
+    readonly exhaust: readonly [turns: number];
     /**
      * AUTOMATIC compaction's summarizer THREW — a NON-FATAL warn channel (the run continues; see
      * {@link AgentOptions.window}). When the loop's between-turns / pre-first-turn auto-compaction
@@ -735,9 +742,17 @@ export declare interface AgentRegistryOptions {
  * `partial` is `true` when the turn was committed early from a cancel — an external
  * `signal` abort, the turn's own `abort()`, a `timeout` deadline, or an exhausted
  * `budget` — in which case `content` is whatever had accumulated when the cancel
- * landed. It is `false` for a turn that ran to a natural finish. `usage` is present
- * only when at least one provider call reported usage. `thinking` is present only
- * when a provider call surfaced reasoning it separated from the answer
+ * landed. `partial` is ALSO `true` when the loop exhausted its `limit` while still
+ * holding unresolved tool intent (the model requested tools on the very last allowed
+ * turn) — a distinct, non-cancel cause covered by {@link RunOutcome.exhausted} (see
+ * the `exhaust` {@link AgentEventMap} event). It is `false` for a turn that ran to a
+ * natural finish (including a `limit: 0` run, which never enters the loop). `usage` is
+ * present only when at least one provider call reported usage — an aborted run's `usage`
+ * INCLUDES the cancelled turn's tokens when the provider reports partial usage on the
+ * abort (folded in exactly like a completed turn's); a provider that cannot observe
+ * usage mid-stream (e.g. a daemon whose final counts never arrive before the cancel)
+ * reports none for that turn, and none is fabricated. `thinking` is present
+ * only when a provider call surfaced reasoning it separated from the answer
  * ({@link ProviderResult.thinking}, joined across the run's calls) — display/audit
  * metadata that never re-enters the conversation.
  */
@@ -802,6 +817,34 @@ export declare interface AgentRunOptions {
      * behaviour), so a caller that passes no options runs exactly as before.
      */
     readonly think?: boolean;
+    /**
+     * Constrain the response to this JSON-Schema shape, forwarded to the provider's `stream`
+     * as {@link ProviderStreamOptions.schema} — a per-run structured-output request. Omitted ⇒
+     * no constraint (the loop is byte-for-byte the prior behaviour).
+     */
+    readonly schema?: Readonly<Record<string, unknown>>;
+    /**
+     * Overrides {@link AgentOptions.limit} for THIS run only — the max tool-iteration turns
+     * before the loop stops. Omitted ⇒ the agent's constructed `limit` applies.
+     */
+    readonly limit?: number;
+    /**
+     * Overrides {@link AgentOptions.timeout} for THIS run only — a wall-clock deadline (ms)
+     * whose abort commits a partial result. Omitted ⇒ the agent's constructed `timeout` applies.
+     */
+    readonly timeout?: number;
+    /**
+     * Overrides {@link AgentOptions.budget} for THIS run only — a token cost bound whose abort
+     * commits a partial result; `start()`ed for this run exactly as the constructed budget is.
+     * Omitted ⇒ the agent's constructed `budget` applies.
+     */
+    readonly budget?: BudgetInterface<TokenUsage>;
+    /**
+     * An additional per-run external cancel, COMPOSED with {@link AgentOptions.signal} (both
+     * fold into the run's bound abort via `AbortSignal.any` — neither is dropped). Omitted ⇒
+     * only the agent's constructed `signal` (if any) applies.
+     */
+    readonly signal?: AbortSignal;
 }
 
 /**
@@ -3791,13 +3834,18 @@ export declare interface ProviderResult {
  * `think` OVERRIDES the provider's constructed reasoning preference for THIS call: `true`
  * asks the backend to separate reasoning natively (a thinking model returns it on its
  * `message.thinking` channel, surfaced as `'thinking'` {@link ProviderDelta}s + the final
- * {@link ProviderResult.thinking}); `false` suppresses it. Omitted ⇒ the provider's own
- * default applies (the constructor value), so the contract stays backward-safe — a caller
+ * {@link ProviderResult.thinking}); `false` suppresses it. `schema`, when given, asks the
+ * backend to constrain its response to the given JSON-Schema shape (the same open
+ * JSON-Schema record {@link ToolDefinition.parameters} already carries) — a structured-output
+ * request for THIS call only. Both omitted ⇒ the provider's own defaults apply (the
+ * constructor value / no schema constraint), so the contract stays backward-safe — a caller
  * that passes no options behaves exactly as before.
  */
 export declare interface ProviderStreamOptions {
     /** Override the provider's reasoning preference for this call; omitted ⇒ the provider default. */
     readonly think?: boolean;
+    /** Constrain the response to this JSON-Schema shape (the same open record {@link ToolDefinition.parameters} uses); omitted ⇒ no constraint. */
+    readonly schema?: Readonly<Record<string, unknown>>;
 }
 
 /**
@@ -3891,16 +3939,19 @@ export declare interface ReplaceResult {
  * the loop: `content` accumulates the streamed assistant text, `thinking` the
  * reasoning the provider calls separated from it ({@link ProviderResult.thinking},
  * joined across calls — `undefined` until one surfaces it), `usage` the summed
- * {@link TokenUsage} (present only when a provider call reported it), and `partial`
- * flips `true` when a cancel commits the run early. It is the INTERNAL precursor to
- * the settled `AgentResult` — the loop reads it back to assemble the public result —
- * not a caller-facing shape.
+ * {@link TokenUsage} (present only when a provider call reported it), `partial`
+ * flips `true` when a cancel commits the run early OR when the loop exhausts its
+ * `limit` with unresolved tool intent, and `exhausted` flips `true` in that second
+ * case specifically (a distinct, non-cancel cause the {@link AgentEventMap} `exhaust`
+ * event observes). It is the INTERNAL precursor to the settled `AgentResult` — the
+ * loop reads it back to assemble the public result — not a caller-facing shape.
  */
 export declare interface RunOutcome {
     content: string;
     thinking: string | undefined;
     usage: TokenUsage | undefined;
     partial: boolean;
+    exhausted: boolean;
 }
 
 /**

package/dist/src/core/index.js

@@ -2271,10 +2271,13 @@ var Agent = class {
 		return this.stream(options).result;
 	}
 	stream(options) {
-		const timeout = this.#timeoutMs === void 0 ? void 0 : createTimeout({ ms: this.#timeoutMs });
+		const timeoutMs = options?.timeout ?? this.#timeoutMs;
+		const timeout = timeoutMs === void 0 ? void 0 : createTimeout({ ms: timeoutMs });
 		timeout?.start();
-		this.#budget?.start();
-		const abort = createAbort({ signal: this.#parents(timeout) });
+		const budget = options?.budget ?? this.#budget;
+		budget?.start();
+		const limit = options?.limit ?? this.#limit;
+		const abort = createAbort({ signal: this.#parents(timeout, budget, options?.signal) });
 		this.#runs.add(abort);
 		this.#status = "running";
 		this.#emitter.emit("start", this.id);
@@ -2282,11 +2285,12 @@ var Agent = class {
 			content: "",
 			thinking: void 0,
 			usage: void 0,
-			partial: false
+			partial: false,
+			exhausted: false
 		};
 		const channel = new Channel();
 		const settled = createDeferred();
-		this.#pump(abort, outcome, timeout, channel, settled, options?.think);
+		this.#pump(abort, outcome, timeout, channel, settled, options?.think, options?.schema, limit, budget);
 		settled.promise.catch(() => {});
 		return {
 			events: this.#events(channel, abort),
@@ -2299,10 +2303,10 @@ var Agent = class {
 	abort(reason) {
 		for (const abort of [...this.#runs]) abort.abort(reason);
 	}
-	async #pump(abort, outcome, timeout, channel, settled, think) {
+	async #pump(abort, outcome, timeout, channel, settled, think, schema, limit, budget) {
 		let failure;
 		try {
-			for await (const chunk of this.#run(abort, outcome, think)) channel.push(chunk);
+			for await (const chunk of this.#run(abort, outcome, think, schema, limit, budget)) channel.push(chunk);
 		} catch (error) {
 			failure = { error };
 		} finally {
@@ -2313,7 +2317,8 @@ var Agent = class {
 				channel.close();
 				const result = this.#result(outcome);
 				settled.resolve(result);
-				if (outcome.partial) this.#emitter.emit("abort", abort.signal.reason);
+				if (outcome.exhausted) this.#emitter.emit("exhaust", limit);
+				else if (outcome.partial) this.#emitter.emit("abort", abort.signal.reason);
 				this.#emitter.emit("finish", result);
 			} else {
 				this.#status = "error";
@@ -2330,51 +2335,83 @@ var Agent = class {
 			abort.abort();
 		}
 	}
-	async *#run(abort, outcome, think) {
+	async *#run(abort, outcome, think, schema, limit, budget) {
 		const messages = [...this.#context.build(this.#provider.format)];
 		const tools = this.#context.tools;
 		let content = "";
 		let thinking;
 		let usage;
+		let pending = false;
+		let broke = false;
 		const compaction = { futile: false };
 		const compacting = this.#window !== void 0 && this.#context.conversations.active?.summarizable === true;
 		if (compacting) {
 			this.#window?.clear();
 			if (!abort.signal.aborted) await this.#trim(messages, compaction, false);
 		}
-		for (let turn = 0; turn < this.#limit; turn += 1) {
+		for (let turn = 0; turn < limit; turn += 1) {
 			this.#emitter.emit("turn", turn);
 			if (turn > 0) try {
 				await this.#scheduler?.yield({ signal: abort.signal });
 			} catch (error) {
 				if (abort.signal.aborted) {
 					outcome.partial = true;
+					broke = true;
 					break;
 				}
 				throw error;
 			}
 			if (abort.signal.aborted) {
 				outcome.partial = true;
+				broke = true;
 				break;
 			}
 			const advertised = filterAllowList(this.#context.scope?.tools, tools.definitions(), (definition) => definition.name);
 			const definitions = advertised.length > 0 ? advertised : void 0;
+			let charged = 0;
+			let turnContent = "";
 			let result;
 			try {
-				result = yield* this.#provide(messages, abort.signal, definitions, think, (delta) => {
+				result = yield* this.#provide(messages, abort.signal, definitions, think, schema, (delta) => {
 					content += delta;
+					turnContent += delta;
+					const est = estimateTokens(turnContent);
+					if (est > charged) {
+						budget?.consume({
+							prompt: 0,
+							completion: est - charged,
+							total: est - charged
+						});
+						charged = est;
+					}
 				});
 			} catch (error) {
 				if (abort.signal.aborted) {
-					if (isProviderAbortError(error) && error.partial.thinking !== void 0) thinking = this.#thought(thinking, error.partial.thinking);
+					if (isProviderAbortError(error)) {
+						if (error.partial.thinking !== void 0) thinking = this.#thought(thinking, error.partial.thinking);
+						if (error.partial.usage !== void 0) {
+							const abortUsage = error.partial.usage;
+							budget?.consume({
+								prompt: abortUsage.prompt,
+								completion: Math.max(0, abortUsage.completion - charged),
+								total: Math.max(0, abortUsage.total - charged)
+							});
+							usage = this.#sum(usage, abortUsage);
+						}
+					}
 					outcome.partial = true;
+					broke = true;
 					break;
 				}
 				throw error;
 			}
 			if (result.thinking !== void 0 && result.thinking.length > 0) thinking = this.#thought(thinking, result.thinking);
 			if (result.usage !== void 0) {
-				this.#budget?.consume(result.usage);
+				budget?.consume({
+					prompt: result.usage.prompt,
+					completion: Math.max(0, result.usage.completion - charged),
+					total: Math.max(0, result.usage.total - charged)
+				});
 				usage = this.#sum(usage, result.usage);
 				this.#emitter.emit("usage", result.usage);
 				yield {
@@ -2407,6 +2444,7 @@ var Agent = class {
 					messages.push(toolMessage);
 				}
 				if (compacting) await this.#trim(messages, compaction, true);
+				pending = true;
 				continue;
 			}
 			messages.push(this.#context.messages.add({
@@ -2414,8 +2452,14 @@ var Agent = class {
 				content: result.content
 			}));
 			content = result.content;
+			pending = false;
+			broke = true;
 			break;
 		}
+		if (!broke && pending) {
+			outcome.partial = true;
+			outcome.exhausted = !abort.signal.aborted;
+		}
 		outcome.content = content;
 		outcome.thinking = thinking;
 		outcome.usage = usage;
@@ -2475,8 +2519,11 @@ var Agent = class {
 	#reason(error) {
 		return error instanceof Error ? error.message : String(error);
 	}
-	async *#provide(messages, signal, definitions, think, onDelta) {
-		const generator = this.#provider.stream(messages, signal, definitions, think === void 0 ? void 0 : { think });
+	async *#provide(messages, signal, definitions, think, schema, onDelta) {
+		const options = {};
+		if (think !== void 0) options.think = think;
+		if (schema !== void 0) options.schema = schema;
+		const generator = this.#provider.stream(messages, signal, definitions, Object.keys(options).length > 0 ? options : void 0);
 		let next = await generator.next();
 		while (!next.done) {
 			const delta = next.value;
@@ -2494,11 +2541,12 @@ var Agent = class {
 		}
 		return next.value;
 	}
-	#parents(timeout) {
+	#parents(timeout, budget, signal) {
 		const signals = [];
 		if (this.#signal !== void 0) signals.push(this.#signal);
+		if (signal !== void 0) signals.push(signal);
 		if (timeout !== void 0) signals.push(timeout.signal);
-		if (this.#budget !== void 0) signals.push(this.#budget.signal);
+		if (budget !== void 0) signals.push(budget.signal);
 		if (signals.length === 0) return void 0;
 		if (signals.length === 1) return signals[0];
 		return AbortSignal.any(signals);