@orkestrel/agent 0.0.27 → 0.0.28

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

@@ -446,7 +446,12 @@ export declare type AgentEventMap = {
     readonly tool: readonly [call: ToolCall, result: ToolResult];
     /** Reports a turn's {@link TokenUsage} — emitted after a usage-bearing provider call. */
     readonly usage: readonly [usage: TokenUsage];
-    /** Reports a call the authority denied — the call + the optional reason (not in the chunk stream). */
+    /**
+     * Reports a call denied by scope or authority, before dispatch.
+     * A turn advertising no tools drops each call with `no tool is advertised in the active scope`.
+     * Otherwise a call excluded by the tool allow-list carries `<tool name> is not in the active scope` and
+     * produces a denial tool result and message. Authority evaluates only admitted calls.
+     */
     readonly deny: readonly [call: ToolCall, reason: string | undefined];
     /** Reports the run settled successfully (a natural finish or a cancel's partial) — the {@link AgentResult}. */
     readonly finish: readonly [result: AgentResult];
@@ -761,7 +766,7 @@ export declare interface AgentJudgeInterface extends JudgeInterface {
  * - `workspaces` — an optional pre-built {@link WorkspaceManagerInterface} forwarded to the
  *   agent's context; a fresh empty one is created when omitted (mirrors {@link AgentContextOptions.workspaces}).
  * - `scope` — an optional initial active {@link ScopeInterface} forwarded to the agent's context
- *   (the build-time filter); `undefined` ⇒ no filtering (mirrors {@link AgentContextOptions.scope}).
+ *   (the context and tool-dispatch filter); `undefined` ⇒ every registered tool is admitted.
  * - `on` — the reserved {@link EmitterHooks} key: initial listeners for the agent's
  *   {@link AgentEventMap}, wired at construction (for example `{ finish: (r) => log(r) }`).
  */
@@ -776,7 +781,16 @@ export declare interface AgentOptions {
     readonly instructions?: InstructionManagerInterface;
     /** Reuses a pre-built workspace registry forwarded to the agent's context; a fresh empty one is created when omitted. */
     readonly workspaces?: WorkspaceManagerInterface;
-    /** Sets the initial active scope forwarded to the agent's context (the build-time filter); `undefined` ⇒ no filtering. */
+    /**
+     * Sets the initial active scope; `undefined` admits every registered tool.
+     * Each turn snapshots the scope's tool allow-list before advertising and checks calls
+     * against that list before applying authority. An absent list also admits unknown names
+     * to authority and the registry, which returns its tool-not-found failure.
+     * A reply to a turn advertising no tools ends the run as its answer, records an assistant
+     * message without calls, and emits a `deny` event for every dropped call without marking it partial.
+     * Other scoped-out calls produce denial tool results and messages, and the loop continues.
+     * Changing the context scope through the `apply` method takes effect on the next turn.
+     */
     readonly scope?: ScopeInterface;
     /** Caps the tool-iteration turns before the loop stops; defaults to `DEFAULT_AGENT_LIMIT`. */
     readonly limit?: number;
@@ -789,11 +803,11 @@ export declare interface AgentOptions {
     /** Carries an external cancel; its abort commits a partial result. */
     readonly signal?: AbortSignal;
     /**
-     * Holds an optional policy gate consulted before each tool call runs — a denied call is
+     * Holds an optional policy gate consulted after scope admits a tool call — a denied call is
      * fed back to the model as a denial {@link ToolResult} (a `tool` chunk + a tool
      * message) rather than executed (no tool run, no budget cost), so the model sees the
-     * denial and can react; an allowed call dispatches normally. Omitted ⇒ every call
-     * dispatches as before.
+     * denial and can react; an allowed call dispatches normally. Omitted ⇒ every admitted call
+     * dispatches through the registry.
      */
     readonly authority?: AuthorityInterface;
     /**
@@ -1138,6 +1152,11 @@ export declare interface AgentResult {
     readonly thinking?: string;
     /** Holds the summed {@link TokenUsage} across the turn's provider calls (present when any reported it). */
     readonly usage?: TokenUsage;
+    /**
+     * Reports cancellation or a turn limit reached with unresolved tool intent.
+     * A reply to a turn advertising no tools is a complete answer (`false`), even if it
+     * contains calls: those calls are dropped and observed through the `deny` event.
+     */
     readonly partial: boolean;
 }
 
@@ -5193,7 +5212,11 @@ export declare class Scope implements ScopeInterface {
 export declare interface ScopeFilter {
     /** Lists the allowed instruction `name`s (`undefined` ⇒ all, `[]` ⇒ none, else only-listed). */
     readonly instructions?: readonly string[];
-    /** Lists the allowed tool `name`s (`undefined` ⇒ all, `[]` ⇒ none, else only-listed). */
+    /**
+     * Lists the allowed tool `name`s (`undefined` ⇒ all, `[]` ⇒ none, else only-listed).
+     * The loop advertises and dispatches only admitted tools, checking scope before authority.
+     * If no definition is advertised, the reply ends the run without dispatching its calls.
+     */
     readonly tools?: readonly string[];
     /**
      * Lists the allowed active-workspace file `path`s (`undefined` ⇒ all, `[]` ⇒ none, else only-listed) —

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

@@ -446,7 +446,12 @@ export declare type AgentEventMap = {
     readonly tool: readonly [call: ToolCall, result: ToolResult];
     /** Reports a turn's {@link TokenUsage} — emitted after a usage-bearing provider call. */
     readonly usage: readonly [usage: TokenUsage];
-    /** Reports a call the authority denied — the call + the optional reason (not in the chunk stream). */
+    /**
+     * Reports a call denied by scope or authority, before dispatch.
+     * A turn advertising no tools drops each call with `no tool is advertised in the active scope`.
+     * Otherwise a call excluded by the tool allow-list carries `<tool name> is not in the active scope` and
+     * produces a denial tool result and message. Authority evaluates only admitted calls.
+     */
     readonly deny: readonly [call: ToolCall, reason: string | undefined];
     /** Reports the run settled successfully (a natural finish or a cancel's partial) — the {@link AgentResult}. */
     readonly finish: readonly [result: AgentResult];
@@ -761,7 +766,7 @@ export declare interface AgentJudgeInterface extends JudgeInterface {
  * - `workspaces` — an optional pre-built {@link WorkspaceManagerInterface} forwarded to the
  *   agent's context; a fresh empty one is created when omitted (mirrors {@link AgentContextOptions.workspaces}).
  * - `scope` — an optional initial active {@link ScopeInterface} forwarded to the agent's context
- *   (the build-time filter); `undefined` ⇒ no filtering (mirrors {@link AgentContextOptions.scope}).
+ *   (the context and tool-dispatch filter); `undefined` ⇒ every registered tool is admitted.
  * - `on` — the reserved {@link EmitterHooks} key: initial listeners for the agent's
  *   {@link AgentEventMap}, wired at construction (for example `{ finish: (r) => log(r) }`).
  */
@@ -776,7 +781,16 @@ export declare interface AgentOptions {
     readonly instructions?: InstructionManagerInterface;
     /** Reuses a pre-built workspace registry forwarded to the agent's context; a fresh empty one is created when omitted. */
     readonly workspaces?: WorkspaceManagerInterface;
-    /** Sets the initial active scope forwarded to the agent's context (the build-time filter); `undefined` ⇒ no filtering. */
+    /**
+     * Sets the initial active scope; `undefined` admits every registered tool.
+     * Each turn snapshots the scope's tool allow-list before advertising and checks calls
+     * against that list before applying authority. An absent list also admits unknown names
+     * to authority and the registry, which returns its tool-not-found failure.
+     * A reply to a turn advertising no tools ends the run as its answer, records an assistant
+     * message without calls, and emits a `deny` event for every dropped call without marking it partial.
+     * Other scoped-out calls produce denial tool results and messages, and the loop continues.
+     * Changing the context scope through the `apply` method takes effect on the next turn.
+     */
     readonly scope?: ScopeInterface;
     /** Caps the tool-iteration turns before the loop stops; defaults to `DEFAULT_AGENT_LIMIT`. */
     readonly limit?: number;
@@ -789,11 +803,11 @@ export declare interface AgentOptions {
     /** Carries an external cancel; its abort commits a partial result. */
     readonly signal?: AbortSignal;
     /**
-     * Holds an optional policy gate consulted before each tool call runs — a denied call is
+     * Holds an optional policy gate consulted after scope admits a tool call — a denied call is
      * fed back to the model as a denial {@link ToolResult} (a `tool` chunk + a tool
      * message) rather than executed (no tool run, no budget cost), so the model sees the
-     * denial and can react; an allowed call dispatches normally. Omitted ⇒ every call
-     * dispatches as before.
+     * denial and can react; an allowed call dispatches normally. Omitted ⇒ every admitted call
+     * dispatches through the registry.
      */
     readonly authority?: AuthorityInterface;
     /**
@@ -1138,6 +1152,11 @@ export declare interface AgentResult {
     readonly thinking?: string;
     /** Holds the summed {@link TokenUsage} across the turn's provider calls (present when any reported it). */
     readonly usage?: TokenUsage;
+    /**
+     * Reports cancellation or a turn limit reached with unresolved tool intent.
+     * A reply to a turn advertising no tools is a complete answer (`false`), even if it
+     * contains calls: those calls are dropped and observed through the `deny` event.
+     */
     readonly partial: boolean;
 }
 
@@ -5193,7 +5212,11 @@ export declare class Scope implements ScopeInterface {
 export declare interface ScopeFilter {
     /** Lists the allowed instruction `name`s (`undefined` ⇒ all, `[]` ⇒ none, else only-listed). */
     readonly instructions?: readonly string[];
-    /** Lists the allowed tool `name`s (`undefined` ⇒ all, `[]` ⇒ none, else only-listed). */
+    /**
+     * Lists the allowed tool `name`s (`undefined` ⇒ all, `[]` ⇒ none, else only-listed).
+     * The loop advertises and dispatches only admitted tools, checking scope before authority.
+     * If no definition is advertised, the reply ends the run without dispatching its calls.
+     */
     readonly tools?: readonly string[];
     /**
      * Lists the allowed active-workspace file `path`s (`undefined` ⇒ all, `[]` ⇒ none, else only-listed) —

package/dist/src/core/index.js

@@ -2447,7 +2447,8 @@ var Agent = class {
 				broke = true;
 				break;
 			}
-			const advertised = filterAllowList(this.#context.scope?.tools, tools.definitions(), (definition) => definition.name);
+			const names = this.#context.scope?.tools?.slice();
+			const advertised = filterAllowList(names, tools.definitions(), (definition) => definition.name);
 			const definitions = advertised.length > 0 ? advertised : void 0;
 			let charged = 0;
 			let turnContent = "";
@@ -2501,8 +2502,10 @@ var Agent = class {
 					usage: resultUsage
 				};
 			}
-			if (result.tools !== void 0 && result.tools.length > 0) {
-				const authorization = this.#authorize(result.tools);
+			if (definitions === void 0) for (const call of result.tools ?? []) this.#emitter.emit("deny", call, "no tool is advertised in the active scope");
+			else if (result.tools !== void 0 && result.tools.length > 0) {
+				const admitted = filterAllowList(names, result.tools, (call) => call.name);
+				const authorization = this.#authorize(result.tools, admitted);
 				if (abort.signal.aborted) {
 					partial = true;
 					broke = true;
@@ -2574,24 +2577,33 @@ var Agent = class {
 		messages.splice(0, messages.length, ...this.#context.build(this.#provider.format));
 		return false;
 	}
-	#authorize(calls) {
-		if (this.#authority === void 0) return void 0;
+	#authorize(calls, admitted) {
 		const authority = this.#authority;
-		const allowed = [];
+		const allowed = /* @__PURE__ */ new Map();
 		const denials = /* @__PURE__ */ new Map();
-		for (const call of calls) {
+		for (const [index, call] of calls.entries()) {
+			if (!admitted.includes(call)) {
+				const reason = `${call.name} is not in the active scope`;
+				denials.set(index, denyCall(call, reason));
+				this.#emitter.emit("deny", call, reason);
+				continue;
+			}
+			if (authority === void 0) {
+				allowed.set(index, call);
+				continue;
+			}
 			let decision;
 			try {
 				decision = authority.evaluate({ call });
 			} catch (error) {
 				const reason = errorToMessage(error);
-				denials.set(call.id, denyCall(call, reason));
+				denials.set(index, denyCall(call, reason));
 				this.#emitter.emit("deny", call, reason);
 				continue;
 			}
-			if (decision.allowed) allowed.push(call);
+			if (decision.allowed) allowed.set(index, call);
 			else {
-				denials.set(call.id, denyCall(call, decision.reason));
+				denials.set(index, denyCall(call, decision.reason));
 				this.#emitter.emit("deny", call, decision.reason);
 			}
 		}
@@ -2601,12 +2613,16 @@ var Agent = class {
 		};
 	}
 	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));
+		const executed = allowed.size > 0 ? await tools.execute([...allowed.values()], { signal }) : [];
+		const results = new Map(denials);
+		let offset = 0;
+		for (const index of allowed.keys()) {
+			const result = executed[offset];
+			if (result !== void 0) results.set(index, result);
+			offset += 1;
+		}
+		return calls.map((call, index) => results.get(index) ?? denyCall(call, void 0));
 	}
 	async *#provide(messages, signal, definitions, think, schema, onDelta) {
 		const options = {};