@orkestrel/agent 0.0.9 → 0.0.11

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

@@ -100,15 +100,17 @@ export declare type AgentChunk = {
  * The richer turn context the agent loop assembles a provider request from — the optional
  * system prompt, the observable context managers (instructions / workspaces), the
  * {@link ConversationManagerInterface} message source (whose active conversation IS `messages`),
- * the {@link ToolManagerInterface} registry, and a mutable active {@link ScopeInterface}.
+ * the {@link ToolManagerInterface} registry, and an active {@link ScopeInterface} changed through
+ * {@link AgentContextInterface.apply}.
  *
  * @remarks
  * - **Composition.** `system` is the optional system prompt; `instructions` / `tools` /
  *   `workspaces` / `conversations` are the registries passed in `options` (bring your own), or
  *   fresh empty ones when omitted (so `workspaces` is ALWAYS present); `messages` is the ACTIVE
  *   conversation's live tail (ALWAYS defined — see below). `scope` is the active filter —
- *   `undefined` (the default) ⇒ no filtering; settable afterwards. `workspaces` / `conversations`
- *   are likewise SETTABLE (swap the whole registry between runs).
+ *   `undefined` (the default) ⇒ no filtering; change it through `apply(scope)`. The structural
+ *   `workspaces` / `conversations` registries are fixed at construction; switch their active
+ *   members through their own `switch(id)` methods.
  * - **The message source — the conversation registry's ACTIVE conversation.** `conversations` is a
  *   {@link ConversationManagerInterface}; the context ENSURES it always has an active conversation
  *   (at construction it `add`s a default when the manager has none), so the DYNAMIC `messages`
@@ -167,13 +169,11 @@ export declare class AgentContext implements AgentContextInterface {
     get system(): string | undefined;
     get instructions(): InstructionManagerInterface;
     get workspaces(): WorkspaceManagerInterface;
-    set workspaces(value: WorkspaceManagerInterface);
     get messages(): MessageManagerInterface;
     get conversations(): ConversationManagerInterface;
-    set conversations(value: ConversationManagerInterface);
     get tools(): ToolManagerInterface;
     get scope(): ScopeInterface | undefined;
-    set scope(value: ScopeInterface | undefined);
+    apply(scope: ScopeInterface | undefined): void;
     build(format?: ContextFormatInterface): readonly MessageInterface[];
 }
 
@@ -214,8 +214,8 @@ export declare interface AgentContextInterface {
      * construction). It IS the active {@link ConversationInterface} itself (which satisfies
      * {@link MessageManagerInterface} structurally), so appends through `messages` route to the
      * active conversation's tail and `build()` folds its `view()`. Computed dynamically (it follows
-     * a `conversations.switch(id)` or a `conversations` swap), the SAME reference the active
-     * conversation exposes — no duplication.
+     * `conversations.switch(id)`), the SAME reference the active conversation exposes — no
+     * duplication.
      */
     readonly messages: MessageManagerInterface;
     /**
@@ -231,6 +231,18 @@ export declare interface AgentContextInterface {
     readonly tools: ToolManagerInterface;
     /** The active scope applied at `build()` time + the loop's tool-advertise step (`undefined` ⇒ no filtering). */
     readonly scope: ScopeInterface | undefined;
+    /**
+     * Apply the active per-turn scope filter. Passing `undefined` removes filtering.
+     *
+     * @param scope - The scope to apply, or `undefined` to remove the active filter
+     *
+     * @example
+     * ```ts
+     * context.apply(scope)
+     * context.apply(undefined)
+     * ```
+     */
+    apply(scope: ScopeInterface | undefined): void;
     /**
      * The provider input for the next turn: a leading `system` message folding the prompt
      * + the scoped instructions + the ACTIVE workspace's scoped-in TEXT files (rendered as
@@ -295,10 +307,10 @@ export declare interface AgentContextInterface {
  * `instructions` / `workspaces` are optional pre-built managers to reuse (bring your own
  * registry); when one is omitted, the context creates a fresh empty one. `scope` is the
  * initial active filter applied at `build()` time (and at the loop's tool-advertise step); it
- * defaults to `undefined` — no filtering — and is mutable through the context's `scope` setter
- * afterwards. `conversations` is the {@link ConversationManagerInterface} the context's message
- * source flows from: `messages` IS the manager's ACTIVE conversation's live tail and `build()`
- * folds that conversation's `view()` (section summaries + live). When omitted, a fresh
+ * defaults to `undefined` — no filtering — and can be changed through the context's `apply`
+ * method afterwards. `conversations` is the structural {@link ConversationManagerInterface} the
+ * context's message source flows from: `messages` IS the manager's ACTIVE conversation's live tail
+ * and `build()` folds that conversation's `view()` (section summaries + live). When omitted, a fresh
  * {@link ConversationManagerInterface} is created and a default conversation is added (so
  * `messages` is ALWAYS defined). All default to a context with no system prompt, empty registries,
  * no scope, and a fresh conversation registry holding one default conversation.
@@ -313,8 +325,8 @@ export declare interface AgentContextOptions {
      * A pre-built {@link WorkspaceManagerInterface} to reuse; a fresh empty one is created when
      * omitted (so `context.workspaces` is ALWAYS present). `build()` renders the ACTIVE workspace's
      * files by carrier — text files into the system block (fenced), image files attached to the last
-     * user message — and is mutable through the context's `workspaces` setter afterwards. The active
-     * workspace is the SOLE document/image context.
+     * user message. The registry is structural; change its active workspace through
+     * `workspaces.switch(id)`. The active workspace is the SOLE document/image context.
      */
     readonly workspaces?: WorkspaceManagerInterface;
     /** The initial active scope (the build-time filter); `undefined` ⇒ no filtering. */
@@ -326,9 +338,8 @@ export declare interface AgentContextOptions {
      * conversation's LIVE tail — is ALWAYS defined. `build()` folds the active conversation's
      * `view()` (the per-section summaries + the live tail) as its AUTHORITATIVE message inclusion —
      * the scope does NOT filter the conversation (it owns inclusion via compaction; scope filters
-     * only instructions / tools / workspace files). A SETTABLE mutable
-     * property afterwards (the context's `conversations` setter — swap the whole registry between
-     * runs), and the active conversation is switchable through the manager's `switch(id)`.
+     * only instructions / tools / workspace files). The registry is structural; change its active
+     * conversation through the manager's `switch(id)`.
      */
     readonly conversations?: ConversationManagerInterface;
 }
@@ -2001,8 +2012,8 @@ export declare function createAgent(provider: ProviderInterface, options?: Agent
  * @remarks
  * `system` is the optional system prompt; `tools` / `instructions` / `workspaces` are pre-built
  * managers to reuse (empty ones are created when omitted, so `context.workspaces` is ALWAYS
- * present); `scope` is the initial active filter (`undefined` ⇒ no filtering, mutable afterwards
- * via `context.scope`). The `messages` store is always fresh. `build()` folds the scoped
+ * present); `scope` is the initial active filter (`undefined` ⇒ no filtering, changeable afterwards
+ * via `context.apply(...)`). The `messages` store is always fresh. `build()` folds the scoped
  * instructions — PLUS the ACTIVE workspace's scope-filtered text files (fenced) — into ONE leading
  * `system` message and appends the scoped conversation (attaching the active workspace's
  * scope-filtered image files' `data` to the last user message), built fresh each call; the active
@@ -3933,7 +3944,7 @@ export declare interface ProviderInterface {
      * built-in framing, beaten by a manager-options or per-item override). Omitted ⇒ the
      * provider is framing-agnostic and the managers' built-in defaults apply unchanged.
      */
-    readonly format?: ContextFormatInterface;
+    readonly format?: ContextFormatInterface | undefined;
     /**
      * Generate one complete turn — resolves the assembled {@link ProviderResult}.
      *

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

@@ -100,15 +100,17 @@ export declare type AgentChunk = {
  * The richer turn context the agent loop assembles a provider request from — the optional
  * system prompt, the observable context managers (instructions / workspaces), the
  * {@link ConversationManagerInterface} message source (whose active conversation IS `messages`),
- * the {@link ToolManagerInterface} registry, and a mutable active {@link ScopeInterface}.
+ * the {@link ToolManagerInterface} registry, and an active {@link ScopeInterface} changed through
+ * {@link AgentContextInterface.apply}.
  *
  * @remarks
  * - **Composition.** `system` is the optional system prompt; `instructions` / `tools` /
  *   `workspaces` / `conversations` are the registries passed in `options` (bring your own), or
  *   fresh empty ones when omitted (so `workspaces` is ALWAYS present); `messages` is the ACTIVE
  *   conversation's live tail (ALWAYS defined — see below). `scope` is the active filter —
- *   `undefined` (the default) ⇒ no filtering; settable afterwards. `workspaces` / `conversations`
- *   are likewise SETTABLE (swap the whole registry between runs).
+ *   `undefined` (the default) ⇒ no filtering; change it through `apply(scope)`. The structural
+ *   `workspaces` / `conversations` registries are fixed at construction; switch their active
+ *   members through their own `switch(id)` methods.
  * - **The message source — the conversation registry's ACTIVE conversation.** `conversations` is a
  *   {@link ConversationManagerInterface}; the context ENSURES it always has an active conversation
  *   (at construction it `add`s a default when the manager has none), so the DYNAMIC `messages`
@@ -167,13 +169,11 @@ export declare class AgentContext implements AgentContextInterface {
     get system(): string | undefined;
     get instructions(): InstructionManagerInterface;
     get workspaces(): WorkspaceManagerInterface;
-    set workspaces(value: WorkspaceManagerInterface);
     get messages(): MessageManagerInterface;
     get conversations(): ConversationManagerInterface;
-    set conversations(value: ConversationManagerInterface);
     get tools(): ToolManagerInterface;
     get scope(): ScopeInterface | undefined;
-    set scope(value: ScopeInterface | undefined);
+    apply(scope: ScopeInterface | undefined): void;
     build(format?: ContextFormatInterface): readonly MessageInterface[];
 }
 
@@ -214,8 +214,8 @@ export declare interface AgentContextInterface {
      * construction). It IS the active {@link ConversationInterface} itself (which satisfies
      * {@link MessageManagerInterface} structurally), so appends through `messages` route to the
      * active conversation's tail and `build()` folds its `view()`. Computed dynamically (it follows
-     * a `conversations.switch(id)` or a `conversations` swap), the SAME reference the active
-     * conversation exposes — no duplication.
+     * `conversations.switch(id)`), the SAME reference the active conversation exposes — no
+     * duplication.
      */
     readonly messages: MessageManagerInterface;
     /**
@@ -231,6 +231,18 @@ export declare interface AgentContextInterface {
     readonly tools: ToolManagerInterface;
     /** The active scope applied at `build()` time + the loop's tool-advertise step (`undefined` ⇒ no filtering). */
     readonly scope: ScopeInterface | undefined;
+    /**
+     * Apply the active per-turn scope filter. Passing `undefined` removes filtering.
+     *
+     * @param scope - The scope to apply, or `undefined` to remove the active filter
+     *
+     * @example
+     * ```ts
+     * context.apply(scope)
+     * context.apply(undefined)
+     * ```
+     */
+    apply(scope: ScopeInterface | undefined): void;
     /**
      * The provider input for the next turn: a leading `system` message folding the prompt
      * + the scoped instructions + the ACTIVE workspace's scoped-in TEXT files (rendered as
@@ -295,10 +307,10 @@ export declare interface AgentContextInterface {
  * `instructions` / `workspaces` are optional pre-built managers to reuse (bring your own
  * registry); when one is omitted, the context creates a fresh empty one. `scope` is the
  * initial active filter applied at `build()` time (and at the loop's tool-advertise step); it
- * defaults to `undefined` — no filtering — and is mutable through the context's `scope` setter
- * afterwards. `conversations` is the {@link ConversationManagerInterface} the context's message
- * source flows from: `messages` IS the manager's ACTIVE conversation's live tail and `build()`
- * folds that conversation's `view()` (section summaries + live). When omitted, a fresh
+ * defaults to `undefined` — no filtering — and can be changed through the context's `apply`
+ * method afterwards. `conversations` is the structural {@link ConversationManagerInterface} the
+ * context's message source flows from: `messages` IS the manager's ACTIVE conversation's live tail
+ * and `build()` folds that conversation's `view()` (section summaries + live). When omitted, a fresh
  * {@link ConversationManagerInterface} is created and a default conversation is added (so
  * `messages` is ALWAYS defined). All default to a context with no system prompt, empty registries,
  * no scope, and a fresh conversation registry holding one default conversation.
@@ -313,8 +325,8 @@ export declare interface AgentContextOptions {
      * A pre-built {@link WorkspaceManagerInterface} to reuse; a fresh empty one is created when
      * omitted (so `context.workspaces` is ALWAYS present). `build()` renders the ACTIVE workspace's
      * files by carrier — text files into the system block (fenced), image files attached to the last
-     * user message — and is mutable through the context's `workspaces` setter afterwards. The active
-     * workspace is the SOLE document/image context.
+     * user message. The registry is structural; change its active workspace through
+     * `workspaces.switch(id)`. The active workspace is the SOLE document/image context.
      */
     readonly workspaces?: WorkspaceManagerInterface;
     /** The initial active scope (the build-time filter); `undefined` ⇒ no filtering. */
@@ -326,9 +338,8 @@ export declare interface AgentContextOptions {
      * conversation's LIVE tail — is ALWAYS defined. `build()` folds the active conversation's
      * `view()` (the per-section summaries + the live tail) as its AUTHORITATIVE message inclusion —
      * the scope does NOT filter the conversation (it owns inclusion via compaction; scope filters
-     * only instructions / tools / workspace files). A SETTABLE mutable
-     * property afterwards (the context's `conversations` setter — swap the whole registry between
-     * runs), and the active conversation is switchable through the manager's `switch(id)`.
+     * only instructions / tools / workspace files). The registry is structural; change its active
+     * conversation through the manager's `switch(id)`.
      */
     readonly conversations?: ConversationManagerInterface;
 }
@@ -2001,8 +2012,8 @@ export declare function createAgent(provider: ProviderInterface, options?: Agent
  * @remarks
  * `system` is the optional system prompt; `tools` / `instructions` / `workspaces` are pre-built
  * managers to reuse (empty ones are created when omitted, so `context.workspaces` is ALWAYS
- * present); `scope` is the initial active filter (`undefined` ⇒ no filtering, mutable afterwards
- * via `context.scope`). The `messages` store is always fresh. `build()` folds the scoped
+ * present); `scope` is the initial active filter (`undefined` ⇒ no filtering, changeable afterwards
+ * via `context.apply(...)`). The `messages` store is always fresh. `build()` folds the scoped
  * instructions — PLUS the ACTIVE workspace's scope-filtered text files (fenced) — into ONE leading
  * `system` message and appends the scoped conversation (attaching the active workspace's
  * scope-filtered image files' `data` to the last user message), built fresh each call; the active
@@ -3933,7 +3944,7 @@ export declare interface ProviderInterface {
      * built-in framing, beaten by a manager-options or per-item override). Omitted ⇒ the
      * provider is framing-agnostic and the managers' built-in defaults apply unchanged.
      */
-    readonly format?: ContextFormatInterface;
+    readonly format?: ContextFormatInterface | undefined;
     /**
      * Generate one complete turn — resolves the assembled {@link ProviderResult}.
      *

package/dist/src/core/index.js

@@ -2121,15 +2121,17 @@ var WorkspaceManager = class {
 * The richer turn context the agent loop assembles a provider request from — the optional
 * system prompt, the observable context managers (instructions / workspaces), the
 * {@link ConversationManagerInterface} message source (whose active conversation IS `messages`),
-* the {@link ToolManagerInterface} registry, and a mutable active {@link ScopeInterface}.
+* the {@link ToolManagerInterface} registry, and an active {@link ScopeInterface} changed through
+* {@link AgentContextInterface.apply}.
 *
 * @remarks
 * - **Composition.** `system` is the optional system prompt; `instructions` / `tools` /
 *   `workspaces` / `conversations` are the registries passed in `options` (bring your own), or
 *   fresh empty ones when omitted (so `workspaces` is ALWAYS present); `messages` is the ACTIVE
 *   conversation's live tail (ALWAYS defined — see below). `scope` is the active filter —
-*   `undefined` (the default) ⇒ no filtering; settable afterwards. `workspaces` / `conversations`
-*   are likewise SETTABLE (swap the whole registry between runs).
+*   `undefined` (the default) ⇒ no filtering; change it through `apply(scope)`. The structural
+*   `workspaces` / `conversations` registries are fixed at construction; switch their active
+*   members through their own `switch(id)` methods.
 * - **The message source — the conversation registry's ACTIVE conversation.** `conversations` is a
 *   {@link ConversationManagerInterface}; the context ENSURES it always has an active conversation
 *   (at construction it `add`s a default when the manager has none), so the DYNAMIC `messages`
@@ -2207,27 +2209,20 @@ var AgentContext = class {
 	get workspaces() {
 		return this.#workspaces;
 	}
-	set workspaces(value) {
-		this.#workspaces = value;
-	}
 	get messages() {
 		return this.#conversations.active ?? this.#ensure();
 	}
 	get conversations() {
 		return this.#conversations;
 	}
-	set conversations(value) {
-		this.#conversations = value;
-		if (this.#conversations.active === void 0) this.#conversations.add();
-	}
 	get tools() {
 		return this.#tools;
 	}
 	get scope() {
 		return this.#scope;
 	}
-	set scope(value) {
-		this.#scope = value;
+	apply(scope) {
+		this.#scope = scope;
 	}
 	build(format) {
 		const scope = this.#scope;
@@ -3790,8 +3785,8 @@ function createScopeManager(options) {
 * @remarks
 * `system` is the optional system prompt; `tools` / `instructions` / `workspaces` are pre-built
 * managers to reuse (empty ones are created when omitted, so `context.workspaces` is ALWAYS
-* present); `scope` is the initial active filter (`undefined` ⇒ no filtering, mutable afterwards
-* via `context.scope`). The `messages` store is always fresh. `build()` folds the scoped
+* present); `scope` is the initial active filter (`undefined` ⇒ no filtering, changeable afterwards
+* via `context.apply(...)`). The `messages` store is always fresh. `build()` folds the scoped
 * instructions — PLUS the ACTIVE workspace's scope-filtered text files (fenced) — into ONE leading
 * `system` message and appends the scoped conversation (attaching the active workspace's
 * scope-filtered image files' `data` to the last user message), built fresh each call; the active