@ai-agent-forge/agent-forge 0.85.0

package/dist/core/agent-session-loop.js

@@ -0,0 +1,155 @@
+/**
+ * Default main-loop wiring for AgentSession.
+ *
+ * Extracted from `agent-session.ts`. The two host installers operate on the
+ * internal session facade ({@link AgentSessionInternals}); `AgentSession` keeps
+ * same-name delegates so the constructor and `_buildRuntime` call sites,
+ * dynamic dispatch, and test spies keep working unchanged. Method-to-method
+ * calls that have a facade member go through the session parameter (not direct
+ * imports) to preserve that dispatch — including
+ * `session._compactBeforeNextAssistantResponse`, whose delegate stays on the
+ * class and forwards to `agent-session-compaction.ts`.
+ *
+ * The agent's construction-time context transform is captured once as the
+ * transform chain head, while `beforeToolCall`/`afterToolCall`/
+ * `transformContext`/`prepareNextTurn` read the capability runtime's hook
+ * chains at execution time, so a runtime rebuild swaps in the new runtime
+ * without reinstalling the wiring.
+ */
+import { detachedSessionSnapshot } from "./agent-session-internal.js";
+import { dispatchToolGateBlockedLifecycle } from "./agent-session-lifecycle.js";
+/**
+ * Wire the default main loop onto the Agent instance.
+ *
+ * The five hook positions are composed from the runtime's loop-hook chains.
+ * Chains are read at execution time, so a runtime rebuild swaps in the new
+ * runtime without reinstalling the wiring. The agent's construction-time
+ * context transform stays as the transform chain head (host wiring, not a
+ * plugin capability); the default links come from the bootstrap agent-loop
+ * plugin and third-party links chain after them in registration order.
+ *
+ * `shouldStopAfterTurn` follows the same shape: the default repeated-tool-call
+ * stop guard is a chain link registered by the bootstrap agent-loop plugin
+ * (see {@link createRepeatedToolCallStopPolicy} in bootstrap-agent-loop.ts),
+ * and this wiring only consumes the chain under OR semantics.
+ */
+export function wireDefaultLoop(session) {
+    // Captured once, matching the previous overwrite semantics: hooks are
+    // installed a single time and read live session state at execution time.
+    const previousPrepareNextTurnWithContext = session.agent.prepareNextTurnWithContext ??
+        (session.agent.prepareNextTurn
+            ? async (_turn, signal) => await session.agent.prepareNextTurn?.(signal)
+            : undefined);
+    session._initialPrepareNextTurn = previousPrepareNextTurnWithContext;
+    const previousTransform = session.agent.transformContext;
+    const transformHead = previousTransform
+        ? async (messages, signal) => await previousTransform(messages, signal)
+        : undefined;
+    session.agent.beforeToolCall = async ({ toolCall, args }, signal) => {
+        const chain = session._capabilityRuntime?.getLoopHookChain("beforeToolCall") ?? [];
+        let currentArgs = args;
+        let replaced = false;
+        for (const link of chain) {
+            const result = await link({ toolCallId: toolCall.id, toolName: toolCall.name, args: currentArgs, signal });
+            if (!result)
+                continue;
+            if (result.block) {
+                // 先派发观察事实再短路：模型可见行为不变（block 短路为 isError
+                // tool result 携带 reason，D-062 既有语义）。空白 reason 与校验器
+                // 的 trim 非空判定同谓词归一为缺席——空串派发会被校验器拒绝且
+                // 失败仅落宿主日志，拦截观察事实就静默丢了。
+                const reason = typeof result.reason === "string" && result.reason.trim() !== "" ? result.reason : undefined;
+                await dispatchToolGateBlockedLifecycle(session, toolCall.id, toolCall.name, reason);
+                return result;
+            }
+            if ("args" in result) {
+                currentArgs = result.args;
+                replaced = true;
+            }
+        }
+        return replaced ? { args: currentArgs } : undefined;
+    };
+    session.agent.afterToolCall = async ({ toolCall, args, result, isError }, signal) => {
+        const chain = session._capabilityRuntime?.getLoopHookChain("afterToolCall") ?? [];
+        let current = result;
+        let override;
+        for (const link of chain) {
+            const linkResult = await link({
+                toolCallId: toolCall.id,
+                toolName: toolCall.name,
+                args,
+                result: current,
+                isError,
+                signal,
+            });
+            if (linkResult === undefined)
+                continue;
+            current = linkResult;
+            override = linkResult;
+        }
+        return override;
+    };
+    session.agent.transformContext = async (messages, signal) => {
+        let current = messages;
+        if (transformHead) {
+            const transformed = await transformHead(current, signal);
+            if (transformed !== undefined)
+                current = transformed;
+        }
+        const chain = session._capabilityRuntime?.getLoopHookChain("transformContext") ?? [];
+        for (const link of chain) {
+            const transformed = await link(current, signal);
+            if (transformed !== undefined)
+                current = transformed;
+        }
+        return current;
+    };
+    session.agent.prepareNextTurnWithContext = async (turn, signal) => {
+        const chain = session._capabilityRuntime?.getLoopHookChain("prepareNextTurn") ?? [];
+        let current = turn;
+        for (const link of chain) {
+            const revised = await link(current, signal);
+            if (revised !== undefined)
+                current = revised;
+        }
+        return current;
+    };
+    // 回合后停机链（第五条）：构造期 hook 仍是链头（先投一票，true 即停），
+    // 之后消费 capability runtime 的 "shouldStopAfterTurn" 链，任一链路返回
+    // true 即停。默认护栏由 bootstrap agent-loop 插件经 registerLoopHook 注册，
+    // disabledBootstrapPlugins 跳过该插件时链为空——此时行为与从前等价
+    // （无链即返回构造期 head 的结果或 false，等价 no-op）。
+    const previousShouldStopAfterTurn = session.agent.shouldStopAfterTurn;
+    session.agent.shouldStopAfterTurn = async (context, signal) => {
+        if (previousShouldStopAfterTurn && (await previousShouldStopAfterTurn(context, signal)))
+            return true;
+        const chain = session._capabilityRuntime?.getLoopHookChain("shouldStopAfterTurn") ?? [];
+        for (const link of chain) {
+            if (await link(context, signal))
+                return true;
+        }
+        return false;
+    };
+}
+/** Session-bound host state the default loop links read at execution time. */
+export function createLoopWiring(session) {
+    return {
+        getSessionId: () => session.sessionId,
+        getRevision: () => detachedSessionSnapshot(session.sessionManager.getRevision()),
+        getTurnCorrelationId: () => session._turnCorrelationId,
+        observeError: (error, source, event) => {
+            session._observeLifecycleDeliveryError(error, source, event);
+        },
+        getImageAutoResize: () => session.settingsManager.getImageAutoResize(),
+        compactBeforeNextAssistantResponse: (context, signal) => session._compactBeforeNextAssistantResponse(context, signal),
+        getTurnRefresh: () => ({
+            systemPrompt: session._systemPromptOverride ?? session._baseSystemPrompt,
+            tools: session.agent.state.tools.slice(),
+            model: session.agent.state.model,
+            thinkingLevel: session.agent.state.thinkingLevel,
+        }),
+        getInitialPrepareNextTurn: () => session._initialPrepareNextTurn,
+        getContextStrategyName: () => session._contextStrategyName,
+    };
+}
+//# sourceMappingURL=agent-session-loop.js.map

package/dist/core/agent-session-loop.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-session-loop.js","sourceRoot":"","sources":["../../src/core/agent-session-loop.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Default main-loop wiring for AgentSession.\n *\n * Extracted from `agent-session.ts`. The two host installers operate on the\n * internal session facade ({@link AgentSessionInternals}); `AgentSession` keeps\n * same-name delegates so the constructor and `_buildRuntime` call sites,\n * dynamic dispatch, and test spies keep working unchanged. Method-to-method\n * calls that have a facade member go through the session parameter (not direct\n * imports) to preserve that dispatch — including\n * `session._compactBeforeNextAssistantResponse`, whose delegate stays on the\n * class and forwards to `agent-session-compaction.ts`.\n *\n * The agent's construction-time context transform is captured once as the\n * transform chain head, while `beforeToolCall`/`afterToolCall`/\n * `transformContext`/`prepareNextTurn` read the capability runtime's hook\n * chains at execution time, so a runtime rebuild swaps in the new runtime\n * without reinstalling the wiring.\n */\n\nimport type {\n\tAfterToolCallResult,\n\tAgentLoopTurnUpdate,\n\tAgentMessage,\n\tPrepareNextTurnContext,\n} from \"@agent-forge/agent-core\";\nimport type { AgentSessionInternals } from \"./agent-session-internal.ts\";\nimport { detachedSessionSnapshot } from \"./agent-session-internal.ts\";\nimport { dispatchToolGateBlockedLifecycle } from \"./agent-session-lifecycle.ts\";\nimport type { AgentLoopTransformContextHookV1, AgentLoopWiringV1 } from \"./extensions/index.ts\";\n\n/**\n * Wire the default main loop onto the Agent instance.\n *\n * The five hook positions are composed from the runtime's loop-hook chains.\n * Chains are read at execution time, so a runtime rebuild swaps in the new\n * runtime without reinstalling the wiring. The agent's construction-time\n * context transform stays as the transform chain head (host wiring, not a\n * plugin capability); the default links come from the bootstrap agent-loop\n * plugin and third-party links chain after them in registration order.\n *\n * `shouldStopAfterTurn` follows the same shape: the default repeated-tool-call\n * stop guard is a chain link registered by the bootstrap agent-loop plugin\n * (see {@link createRepeatedToolCallStopPolicy} in bootstrap-agent-loop.ts),\n * and this wiring only consumes the chain under OR semantics.\n */\nexport function wireDefaultLoop(session: AgentSessionInternals): void {\n\t// Captured once, matching the previous overwrite semantics: hooks are\n\t// installed a single time and read live session state at execution time.\n\tconst previousPrepareNextTurnWithContext =\n\t\tsession.agent.prepareNextTurnWithContext ??\n\t\t(session.agent.prepareNextTurn\n\t\t\t? async (_turn: PrepareNextTurnContext, signal?: AbortSignal) => await session.agent.prepareNextTurn?.(signal)\n\t\t\t: undefined);\n\tsession._initialPrepareNextTurn = previousPrepareNextTurnWithContext;\n\n\tconst previousTransform = session.agent.transformContext;\n\tconst transformHead: AgentLoopTransformContextHookV1 | undefined = previousTransform\n\t\t? async (messages, signal) => await previousTransform(messages as AgentMessage[], signal)\n\t\t: undefined;\n\n\tsession.agent.beforeToolCall = async ({ toolCall, args }, signal) => {\n\t\tconst chain = session._capabilityRuntime?.getLoopHookChain(\"beforeToolCall\") ?? [];\n\t\tlet currentArgs: unknown = args;\n\t\tlet replaced = false;\n\t\tfor (const link of chain) {\n\t\t\tconst result = await link({ toolCallId: toolCall.id, toolName: toolCall.name, args: currentArgs, signal });\n\t\t\tif (!result) continue;\n\t\t\tif (result.block) {\n\t\t\t\t// 先派发观察事实再短路：模型可见行为不变（block 短路为 isError\n\t\t\t\t// tool result 携带 reason，D-062 既有语义）。空白 reason 与校验器\n\t\t\t\t// 的 trim 非空判定同谓词归一为缺席——空串派发会被校验器拒绝且\n\t\t\t\t// 失败仅落宿主日志，拦截观察事实就静默丢了。\n\t\t\t\tconst reason = typeof result.reason === \"string\" && result.reason.trim() !== \"\" ? result.reason : undefined;\n\t\t\t\tawait dispatchToolGateBlockedLifecycle(session, toolCall.id, toolCall.name, reason);\n\t\t\t\treturn result;\n\t\t\t}\n\t\t\tif (\"args\" in result) {\n\t\t\t\tcurrentArgs = result.args;\n\t\t\t\treplaced = true;\n\t\t\t}\n\t\t}\n\t\treturn replaced ? { args: currentArgs } : undefined;\n\t};\n\n\tsession.agent.afterToolCall = async ({ toolCall, args, result, isError }, signal) => {\n\t\tconst chain = session._capabilityRuntime?.getLoopHookChain(\"afterToolCall\") ?? [];\n\t\tlet current: unknown = result;\n\t\tlet override: unknown;\n\t\tfor (const link of chain) {\n\t\t\tconst linkResult = await link({\n\t\t\t\ttoolCallId: toolCall.id,\n\t\t\t\ttoolName: toolCall.name,\n\t\t\t\targs,\n\t\t\t\tresult: current,\n\t\t\t\tisError,\n\t\t\t\tsignal,\n\t\t\t});\n\t\t\tif (linkResult === undefined) continue;\n\t\t\tcurrent = linkResult;\n\t\t\toverride = linkResult;\n\t\t}\n\t\treturn override as AfterToolCallResult | undefined;\n\t};\n\n\tsession.agent.transformContext = async (messages: AgentMessage[], signal?: AbortSignal) => {\n\t\tlet current: readonly AgentMessage[] = messages;\n\t\tif (transformHead) {\n\t\t\tconst transformed = await transformHead(current, signal);\n\t\t\tif (transformed !== undefined) current = transformed as readonly AgentMessage[];\n\t\t}\n\t\tconst chain = session._capabilityRuntime?.getLoopHookChain(\"transformContext\") ?? [];\n\t\tfor (const link of chain) {\n\t\t\tconst transformed = await link(current, signal);\n\t\t\tif (transformed !== undefined) current = transformed as readonly AgentMessage[];\n\t\t}\n\t\treturn current as AgentMessage[];\n\t};\n\n\tsession.agent.prepareNextTurnWithContext = async (turn, signal) => {\n\t\tconst chain = session._capabilityRuntime?.getLoopHookChain(\"prepareNextTurn\") ?? [];\n\t\tlet current: unknown = turn;\n\t\tfor (const link of chain) {\n\t\t\tconst revised = await link(current, signal);\n\t\t\tif (revised !== undefined) current = revised;\n\t\t}\n\t\treturn current as AgentLoopTurnUpdate;\n\t};\n\n\t// 回合后停机链（第五条）：构造期 hook 仍是链头（先投一票，true 即停），\n\t// 之后消费 capability runtime 的 \"shouldStopAfterTurn\" 链，任一链路返回\n\t// true 即停。默认护栏由 bootstrap agent-loop 插件经 registerLoopHook 注册，\n\t// disabledBootstrapPlugins 跳过该插件时链为空——此时行为与从前等价\n\t// （无链即返回构造期 head 的结果或 false，等价 no-op）。\n\tconst previousShouldStopAfterTurn = session.agent.shouldStopAfterTurn;\n\tsession.agent.shouldStopAfterTurn = async (context, signal) => {\n\t\tif (previousShouldStopAfterTurn && (await previousShouldStopAfterTurn(context, signal))) return true;\n\t\tconst chain = session._capabilityRuntime?.getLoopHookChain(\"shouldStopAfterTurn\") ?? [];\n\t\tfor (const link of chain) {\n\t\t\tif (await link(context, signal)) return true;\n\t\t}\n\t\treturn false;\n\t};\n}\n\n/** Session-bound host state the default loop links read at execution time. */\nexport function createLoopWiring(session: AgentSessionInternals): AgentLoopWiringV1 {\n\treturn {\n\t\tgetSessionId: () => session.sessionId,\n\t\tgetRevision: () => detachedSessionSnapshot(session.sessionManager.getRevision()),\n\t\tgetTurnCorrelationId: () => session._turnCorrelationId,\n\t\tobserveError: (error, source, event) => {\n\t\t\tsession._observeLifecycleDeliveryError(error, source, event);\n\t\t},\n\t\tgetImageAutoResize: () => session.settingsManager.getImageAutoResize(),\n\t\tcompactBeforeNextAssistantResponse: (context, signal) =>\n\t\t\tsession._compactBeforeNextAssistantResponse(context, signal),\n\t\tgetTurnRefresh: () => ({\n\t\t\tsystemPrompt: session._systemPromptOverride ?? session._baseSystemPrompt,\n\t\t\ttools: session.agent.state.tools.slice(),\n\t\t\tmodel: session.agent.state.model,\n\t\t\tthinkingLevel: session.agent.state.thinkingLevel,\n\t\t}),\n\t\tgetInitialPrepareNextTurn: () => session._initialPrepareNextTurn,\n\t\tgetContextStrategyName: () => session._contextStrategyName,\n\t};\n}\n"]}

package/dist/core/agent-session-model.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Model selection and thinking-level resolution for AgentSession.
+ *
+ * Extracted from `agent-session.ts`. Every function here operates on the
+ * internal session facade ({@link AgentSessionInternals}); `AgentSession`
+ * keeps same-name delegates so call sites, dynamic dispatch, and test spies
+ * keep working unchanged. Method-to-method calls that have a facade member go
+ * through the session parameter (not direct function calls) to preserve that
+ * dispatch. `setModel` and `cycleModel` stay parallel implementations: each
+ * keeps its own apply/persist/thinking/model_select sequence and never calls
+ * the other.
+ */
+import type { ThinkingLevel } from "@agent-forge/agent-core";
+import type { Api, Model } from "@agent-forge/ai/compat";
+import type { ModelCycleResult, ModelMutationOptions } from "./agent-session.ts";
+import type { AgentSessionInternals } from "./agent-session-internal.ts";
+import type { ModelFactsViewV1 } from "./extensions/public-api.ts";
+export declare function emitModelSelect(session: AgentSessionInternals, nextModel: Model<Api>, previousModel: Model<Api> | undefined, source: "set" | "cycle" | "restore"): Promise<void>;
+/**
+ * Set model directly.
+ * Validates that auth is configured and saves to the session transcript.
+ * Persists to global defaults only when options.persist is true.
+ * @throws Error if no auth is configured for the model
+ */
+export declare function setModel(session: AgentSessionInternals, model: Model<Api>, options?: ModelMutationOptions): Promise<void>;
+export declare function addPersistedDefaultToNonEmptyScope(session: AgentSessionInternals, model: Model<Api>): void;
+/**
+ * Cycle to next/previous model.
+ * Uses scoped models (from --models flag) if available, otherwise all available models.
+ * @param direction - "forward" (default) or "backward"
+ * @returns The new model info, or undefined if only one model available
+ */
+export declare function cycleModel(session: AgentSessionInternals, direction?: "forward" | "backward", options?: ModelMutationOptions): Promise<ModelCycleResult | undefined>;
+export declare function cycleScopedModel(session: AgentSessionInternals, direction: "forward" | "backward", options: ModelMutationOptions): Promise<ModelCycleResult | undefined>;
+export declare function cycleAvailableModel(session: AgentSessionInternals, direction: "forward" | "backward", options: ModelMutationOptions): Promise<ModelCycleResult | undefined>;
+/** Scoped models for cycling (from --models flag). */
+export declare function getScopedModels(session: AgentSessionInternals): ReadonlyArray<{
+    model: Model<Api>;
+    thinkingLevel?: ThinkingLevel;
+}>;
+/** Project provider-agnostic facts off a Model without exposing api/headers/cost internals. */
+export declare function modelFactsView(model: Model<Api>): ModelFactsViewV1;
+/** Update scoped models for cycling. */
+export declare function setScopedModels(session: AgentSessionInternals, scopedModels: Array<{
+    model: Model<Api>;
+    thinkingLevel?: ThinkingLevel;
+}>): void;
+export declare function getThinkingLevelForModelSwitch(session: AgentSessionInternals, targetModel?: Model<Api>, explicitLevel?: ThinkingLevel): ThinkingLevel;
+//# sourceMappingURL=agent-session-model.d.ts.map

package/dist/core/agent-session-model.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-session-model.d.ts","sourceRoot":"","sources":["../../src/core/agent-session-model.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AAC7D,OAAO,KAAK,EAAE,GAAG,EAAE,KAAK,EAAE,MAAM,wBAAwB,CAAC;AAEzD,OAAO,KAAK,EAAE,gBAAgB,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AACjF,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,6BAA6B,CAAC;AAGzE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,4BAA4B,CAAC;AAEnE,wBAAsB,eAAe,CACpC,OAAO,EAAE,qBAAqB,EAC9B,SAAS,EAAE,KAAK,CAAC,GAAG,CAAC,EACrB,aAAa,EAAE,KAAK,CAAC,GAAG,CAAC,GAAG,SAAS,EACrC,MAAM,EAAE,KAAK,GAAG,OAAO,GAAG,SAAS,GACjC,OAAO,CAAC,IAAI,CAAC,CAGf;AAED;;;;;GAKG;AACH,wBAAsB,QAAQ,CAC7B,OAAO,EAAE,qBAAqB,EAC9B,KAAK,EAAE,KAAK,CAAC,GAAG,CAAC,EACjB,OAAO,GAAE,oBAAyB,GAChC,OAAO,CAAC,IAAI,CAAC,CAoBf;AAED,wBAAgB,kCAAkC,CAAC,OAAO,EAAE,qBAAqB,EAAE,KAAK,EAAE,KAAK,CAAC,GAAG,CAAC,GAAG,IAAI,CAY1G;AAED;;;;;GAKG;AACH,wBAAsB,UAAU,CAC/B,OAAO,EAAE,qBAAqB,EAC9B,SAAS,GAAE,SAAS,GAAG,UAAsB,EAC7C,OAAO,GAAE,oBAAyB,GAChC,OAAO,CAAC,gBAAgB,GAAG,SAAS,CAAC,CAKvC;AAED,wBAAsB,gBAAgB,CACrC,OAAO,EAAE,qBAAqB,EAC9B,SAAS,EAAE,SAAS,GAAG,UAAU,EACjC,OAAO,EAAE,oBAAoB,GAC3B,OAAO,CAAC,gBAAgB,GAAG,SAAS,CAAC,CAoCvC;AAED,wBAAsB,mBAAmB,CACxC,OAAO,EAAE,qBAAqB,EAC9B,SAAS,EAAE,SAAS,GAAG,UAAU,EACjC,OAAO,EAAE,oBAAoB,GAC3B,OAAO,CAAC,gBAAgB,GAAG,SAAS,CAAC,CA2BvC;AAED,sDAAsD;AACtD,wBAAgB,eAAe,CAC9B,OAAO,EAAE,qBAAqB,GAC5B,aAAa,CAAC;IAAE,KAAK,EAAE,KAAK,CAAC,GAAG,CAAC,CAAC;IAAC,aAAa,CAAC,EAAE,aAAa,CAAA;CAAE,CAAC,CAErE;AAED,+FAA+F;AAC/F,wBAAgB,cAAc,CAAC,KAAK,EAAE,KAAK,CAAC,GAAG,CAAC,GAAG,gBAAgB,CAQlE;AAED,wCAAwC;AACxC,wBAAgB,eAAe,CAC9B,OAAO,EAAE,qBAAqB,EAC9B,YAAY,EAAE,KAAK,CAAC;IAAE,KAAK,EAAE,KAAK,CAAC,GAAG,CAAC,CAAC;IAAC,aAAa,CAAC,EAAE,aAAa,CAAA;CAAE,CAAC,GACvE,IAAI,CAEN;AAED,wBAAgB,8BAA8B,CAC7C,OAAO,EAAE,qBAAqB,EAC9B,WAAW,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,EACxB,aAAa,CAAC,EAAE,aAAa,GAC3B,aAAa,CAYf","sourcesContent":["/**\n * Model selection and thinking-level resolution for AgentSession.\n *\n * Extracted from `agent-session.ts`. Every function here operates on the\n * internal session facade ({@link AgentSessionInternals}); `AgentSession`\n * keeps same-name delegates so call sites, dynamic dispatch, and test spies\n * keep working unchanged. Method-to-method calls that have a facade member go\n * through the session parameter (not direct function calls) to preserve that\n * dispatch. `setModel` and `cycleModel` stay parallel implementations: each\n * keeps its own apply/persist/thinking/model_select sequence and never calls\n * the other.\n */\n\nimport type { ThinkingLevel } from \"@agent-forge/agent-core\";\nimport type { Api, Model } from \"@agent-forge/ai/compat\";\nimport { modelsAreEqual } from \"@agent-forge/ai/compat\";\nimport type { ModelCycleResult, ModelMutationOptions } from \"./agent-session.ts\";\nimport type { AgentSessionInternals } from \"./agent-session-internal.ts\";\nimport { dispatchModelSelectLifecycle } from \"./agent-session-lifecycle.ts\";\nimport { DEFAULT_THINKING_LEVEL } from \"./defaults.ts\";\nimport type { ModelFactsViewV1 } from \"./extensions/public-api.ts\";\n\nexport async function emitModelSelect(\n\tsession: AgentSessionInternals,\n\tnextModel: Model<Api>,\n\tpreviousModel: Model<Api> | undefined,\n\tsource: \"set\" | \"cycle\" | \"restore\",\n): Promise<void> {\n\tif (modelsAreEqual(previousModel, nextModel)) return;\n\tawait dispatchModelSelectLifecycle(session, { provider: nextModel.provider, id: nextModel.id }, source);\n}\n\n/**\n * Set model directly.\n * Validates that auth is configured and saves to the session transcript.\n * Persists to global defaults only when options.persist is true.\n * @throws Error if no auth is configured for the model\n */\nexport async function setModel(\n\tsession: AgentSessionInternals,\n\tmodel: Model<Api>,\n\toptions: ModelMutationOptions = {},\n): Promise<void> {\n\tif (!(await session._modelRuntime.checkAuth(model.provider))) {\n\t\tthrow new Error(`No API key for ${model.provider}/${model.id}`);\n\t}\n\n\tconst previousModel = session.model;\n\tconst thinkingLevel = session._getThinkingLevelForModelSwitch(model);\n\tsession.agent.state.model = model;\n\tsession.sessionManager.appendModelChange(model.provider, model.id);\n\tif (options.persist) {\n\t\tsession.settingsManager.setDefaultModelAndProvider(model.provider, model.id);\n\t\tsession._addPersistedDefaultToNonEmptyScope(model);\n\t}\n\n\t// Apply thinking level for the new model.\n\t// Per-model thinking level overrides take priority over the global default.\n\t// Model persistence does not implicitly rewrite the global thinking default.\n\tsession.setThinkingLevel(thinkingLevel);\n\n\tawait session._emitModelSelect(model, previousModel, \"set\");\n}\n\nexport function addPersistedDefaultToNonEmptyScope(session: AgentSessionInternals, model: Model<Api>): void {\n\tif (session._scopedModels.length === 0) return;\n\tif (session._scopedModels.some((scoped) => modelsAreEqual(scoped.model, model))) return;\n\n\tsession._scopedModels = [...session._scopedModels, { model }];\n\n\tconst enabledModels = session.settingsManager.getEnabledModels();\n\tif (!enabledModels?.length) return;\n\n\tconst modelReference = `${model.provider}/${model.id}`;\n\tif (enabledModels.some((pattern) => pattern.toLowerCase() === modelReference.toLowerCase())) return;\n\tsession.settingsManager.setEnabledModels([...enabledModels, modelReference]);\n}\n\n/**\n * Cycle to next/previous model.\n * Uses scoped models (from --models flag) if available, otherwise all available models.\n * @param direction - \"forward\" (default) or \"backward\"\n * @returns The new model info, or undefined if only one model available\n */\nexport async function cycleModel(\n\tsession: AgentSessionInternals,\n\tdirection: \"forward\" | \"backward\" = \"forward\",\n\toptions: ModelMutationOptions = {},\n): Promise<ModelCycleResult | undefined> {\n\tif (session._scopedModels.length > 0) {\n\t\treturn session._cycleScopedModel(direction, options);\n\t}\n\treturn session._cycleAvailableModel(direction, options);\n}\n\nexport async function cycleScopedModel(\n\tsession: AgentSessionInternals,\n\tdirection: \"forward\" | \"backward\",\n\toptions: ModelMutationOptions,\n): Promise<ModelCycleResult | undefined> {\n\tconst availableIds = new Set(\n\t\tsession._modelRuntime.getAvailableSnapshot().map((model) => `${model.provider}\\0${model.id}`),\n\t);\n\tconst scopedModels = session._scopedModels.filter((scoped) =>\n\t\tavailableIds.has(`${scoped.model.provider}\\0${scoped.model.id}`),\n\t);\n\tif (scopedModels.length <= 1) return undefined;\n\n\tconst currentModel = session.model;\n\tlet currentIndex = scopedModels.findIndex((sm) => modelsAreEqual(sm.model, currentModel));\n\n\tif (currentIndex === -1) currentIndex = 0;\n\tconst len = scopedModels.length;\n\tconst nextIndex = direction === \"forward\" ? (currentIndex + 1) % len : (currentIndex - 1 + len) % len;\n\tconst next = scopedModels[nextIndex];\n\tconst thinkingLevel = session._getThinkingLevelForModelSwitch(next.model, next.thinkingLevel);\n\n\t// Apply model\n\tsession.agent.state.model = next.model;\n\tsession.sessionManager.appendModelChange(next.model.provider, next.model.id);\n\tif (options.persist) {\n\t\tsession.settingsManager.setDefaultModelAndProvider(next.model.provider, next.model.id);\n\t\tsession._addPersistedDefaultToNonEmptyScope(next.model);\n\t}\n\n\t// Apply thinking level for the new model.\n\t// - Explicit scoped model thinking level overrides defaults\n\t// - Per-model thinking level overrides take priority over the global default\n\t// setThinkingLevel clamps to model capabilities.\n\t// Model persistence does not implicitly rewrite the global thinking default.\n\tsession.setThinkingLevel(thinkingLevel);\n\n\tawait session._emitModelSelect(next.model, currentModel, \"cycle\");\n\n\treturn { model: next.model, thinkingLevel: session.thinkingLevel, isScoped: true };\n}\n\nexport async function cycleAvailableModel(\n\tsession: AgentSessionInternals,\n\tdirection: \"forward\" | \"backward\",\n\toptions: ModelMutationOptions,\n): Promise<ModelCycleResult | undefined> {\n\tconst availableModels = session._modelRuntime.getAvailableSnapshot();\n\tif (availableModels.length <= 1) return undefined;\n\n\tconst currentModel = session.model;\n\tlet currentIndex = availableModels.findIndex((m) => modelsAreEqual(m, currentModel));\n\n\tif (currentIndex === -1) currentIndex = 0;\n\tconst len = availableModels.length;\n\tconst nextIndex = direction === \"forward\" ? (currentIndex + 1) % len : (currentIndex - 1 + len) % len;\n\tconst nextModel = availableModels[nextIndex];\n\n\tconst thinkingLevel = session._getThinkingLevelForModelSwitch(nextModel);\n\tsession.agent.state.model = nextModel;\n\tsession.sessionManager.appendModelChange(nextModel.provider, nextModel.id);\n\tif (options.persist) {\n\t\tsession.settingsManager.setDefaultModelAndProvider(nextModel.provider, nextModel.id);\n\t\tsession._addPersistedDefaultToNonEmptyScope(nextModel);\n\t}\n\n\t// Apply thinking level for the new model.\n\t// Model persistence does not implicitly rewrite the global thinking default.\n\tsession.setThinkingLevel(thinkingLevel);\n\n\tawait session._emitModelSelect(nextModel, currentModel, \"cycle\");\n\n\treturn { model: nextModel, thinkingLevel: session.thinkingLevel, isScoped: false };\n}\n\n/** Scoped models for cycling (from --models flag). */\nexport function getScopedModels(\n\tsession: AgentSessionInternals,\n): ReadonlyArray<{ model: Model<Api>; thinkingLevel?: ThinkingLevel }> {\n\treturn session._scopedModels;\n}\n\n/** Project provider-agnostic facts off a Model without exposing api/headers/cost internals. */\nexport function modelFactsView(model: Model<Api>): ModelFactsViewV1 {\n\treturn {\n\t\tprovider: model.provider,\n\t\tid: model.id,\n\t\tcontextWindow: model.contextWindow,\n\t\tmaxTokens: model.maxTokens,\n\t\treasoning: model.reasoning,\n\t};\n}\n\n/** Update scoped models for cycling. */\nexport function setScopedModels(\n\tsession: AgentSessionInternals,\n\tscopedModels: Array<{ model: Model<Api>; thinkingLevel?: ThinkingLevel }>,\n): void {\n\tsession._scopedModels = scopedModels;\n}\n\nexport function getThinkingLevelForModelSwitch(\n\tsession: AgentSessionInternals,\n\ttargetModel?: Model<Api>,\n\texplicitLevel?: ThinkingLevel,\n): ThinkingLevel {\n\tif (explicitLevel !== undefined) {\n\t\treturn explicitLevel;\n\t}\n\t// Per-model default takes priority when switching to a model that has one\n\tif (targetModel) {\n\t\tconst perModel = session.settingsManager.getModelThinkingLevel(targetModel.provider, targetModel.id);\n\t\tif (perModel !== undefined) {\n\t\t\treturn perModel;\n\t\t}\n\t}\n\treturn session.settingsManager.getDefaultThinkingLevel() ?? session.thinkingLevel ?? DEFAULT_THINKING_LEVEL;\n}\n"]}

package/dist/core/agent-session-model.js

@@ -0,0 +1,155 @@
+/**
+ * Model selection and thinking-level resolution for AgentSession.
+ *
+ * Extracted from `agent-session.ts`. Every function here operates on the
+ * internal session facade ({@link AgentSessionInternals}); `AgentSession`
+ * keeps same-name delegates so call sites, dynamic dispatch, and test spies
+ * keep working unchanged. Method-to-method calls that have a facade member go
+ * through the session parameter (not direct function calls) to preserve that
+ * dispatch. `setModel` and `cycleModel` stay parallel implementations: each
+ * keeps its own apply/persist/thinking/model_select sequence and never calls
+ * the other.
+ */
+import { modelsAreEqual } from "@agent-forge/ai/compat";
+import { dispatchModelSelectLifecycle } from "./agent-session-lifecycle.js";
+import { DEFAULT_THINKING_LEVEL } from "./defaults.js";
+export async function emitModelSelect(session, nextModel, previousModel, source) {
+    if (modelsAreEqual(previousModel, nextModel))
+        return;
+    await dispatchModelSelectLifecycle(session, { provider: nextModel.provider, id: nextModel.id }, source);
+}
+/**
+ * Set model directly.
+ * Validates that auth is configured and saves to the session transcript.
+ * Persists to global defaults only when options.persist is true.
+ * @throws Error if no auth is configured for the model
+ */
+export async function setModel(session, model, options = {}) {
+    if (!(await session._modelRuntime.checkAuth(model.provider))) {
+        throw new Error(`No API key for ${model.provider}/${model.id}`);
+    }
+    const previousModel = session.model;
+    const thinkingLevel = session._getThinkingLevelForModelSwitch(model);
+    session.agent.state.model = model;
+    session.sessionManager.appendModelChange(model.provider, model.id);
+    if (options.persist) {
+        session.settingsManager.setDefaultModelAndProvider(model.provider, model.id);
+        session._addPersistedDefaultToNonEmptyScope(model);
+    }
+    // Apply thinking level for the new model.
+    // Per-model thinking level overrides take priority over the global default.
+    // Model persistence does not implicitly rewrite the global thinking default.
+    session.setThinkingLevel(thinkingLevel);
+    await session._emitModelSelect(model, previousModel, "set");
+}
+export function addPersistedDefaultToNonEmptyScope(session, model) {
+    if (session._scopedModels.length === 0)
+        return;
+    if (session._scopedModels.some((scoped) => modelsAreEqual(scoped.model, model)))
+        return;
+    session._scopedModels = [...session._scopedModels, { model }];
+    const enabledModels = session.settingsManager.getEnabledModels();
+    if (!enabledModels?.length)
+        return;
+    const modelReference = `${model.provider}/${model.id}`;
+    if (enabledModels.some((pattern) => pattern.toLowerCase() === modelReference.toLowerCase()))
+        return;
+    session.settingsManager.setEnabledModels([...enabledModels, modelReference]);
+}
+/**
+ * Cycle to next/previous model.
+ * Uses scoped models (from --models flag) if available, otherwise all available models.
+ * @param direction - "forward" (default) or "backward"
+ * @returns The new model info, or undefined if only one model available
+ */
+export async function cycleModel(session, direction = "forward", options = {}) {
+    if (session._scopedModels.length > 0) {
+        return session._cycleScopedModel(direction, options);
+    }
+    return session._cycleAvailableModel(direction, options);
+}
+export async function cycleScopedModel(session, direction, options) {
+    const availableIds = new Set(session._modelRuntime.getAvailableSnapshot().map((model) => `${model.provider}\0${model.id}`));
+    const scopedModels = session._scopedModels.filter((scoped) => availableIds.has(`${scoped.model.provider}\0${scoped.model.id}`));
+    if (scopedModels.length <= 1)
+        return undefined;
+    const currentModel = session.model;
+    let currentIndex = scopedModels.findIndex((sm) => modelsAreEqual(sm.model, currentModel));
+    if (currentIndex === -1)
+        currentIndex = 0;
+    const len = scopedModels.length;
+    const nextIndex = direction === "forward" ? (currentIndex + 1) % len : (currentIndex - 1 + len) % len;
+    const next = scopedModels[nextIndex];
+    const thinkingLevel = session._getThinkingLevelForModelSwitch(next.model, next.thinkingLevel);
+    // Apply model
+    session.agent.state.model = next.model;
+    session.sessionManager.appendModelChange(next.model.provider, next.model.id);
+    if (options.persist) {
+        session.settingsManager.setDefaultModelAndProvider(next.model.provider, next.model.id);
+        session._addPersistedDefaultToNonEmptyScope(next.model);
+    }
+    // Apply thinking level for the new model.
+    // - Explicit scoped model thinking level overrides defaults
+    // - Per-model thinking level overrides take priority over the global default
+    // setThinkingLevel clamps to model capabilities.
+    // Model persistence does not implicitly rewrite the global thinking default.
+    session.setThinkingLevel(thinkingLevel);
+    await session._emitModelSelect(next.model, currentModel, "cycle");
+    return { model: next.model, thinkingLevel: session.thinkingLevel, isScoped: true };
+}
+export async function cycleAvailableModel(session, direction, options) {
+    const availableModels = session._modelRuntime.getAvailableSnapshot();
+    if (availableModels.length <= 1)
+        return undefined;
+    const currentModel = session.model;
+    let currentIndex = availableModels.findIndex((m) => modelsAreEqual(m, currentModel));
+    if (currentIndex === -1)
+        currentIndex = 0;
+    const len = availableModels.length;
+    const nextIndex = direction === "forward" ? (currentIndex + 1) % len : (currentIndex - 1 + len) % len;
+    const nextModel = availableModels[nextIndex];
+    const thinkingLevel = session._getThinkingLevelForModelSwitch(nextModel);
+    session.agent.state.model = nextModel;
+    session.sessionManager.appendModelChange(nextModel.provider, nextModel.id);
+    if (options.persist) {
+        session.settingsManager.setDefaultModelAndProvider(nextModel.provider, nextModel.id);
+        session._addPersistedDefaultToNonEmptyScope(nextModel);
+    }
+    // Apply thinking level for the new model.
+    // Model persistence does not implicitly rewrite the global thinking default.
+    session.setThinkingLevel(thinkingLevel);
+    await session._emitModelSelect(nextModel, currentModel, "cycle");
+    return { model: nextModel, thinkingLevel: session.thinkingLevel, isScoped: false };
+}
+/** Scoped models for cycling (from --models flag). */
+export function getScopedModels(session) {
+    return session._scopedModels;
+}
+/** Project provider-agnostic facts off a Model without exposing api/headers/cost internals. */
+export function modelFactsView(model) {
+    return {
+        provider: model.provider,
+        id: model.id,
+        contextWindow: model.contextWindow,
+        maxTokens: model.maxTokens,
+        reasoning: model.reasoning,
+    };
+}
+/** Update scoped models for cycling. */
+export function setScopedModels(session, scopedModels) {
+    session._scopedModels = scopedModels;
+}
+export function getThinkingLevelForModelSwitch(session, targetModel, explicitLevel) {
+    if (explicitLevel !== undefined) {
+        return explicitLevel;
+    }
+    // Per-model default takes priority when switching to a model that has one
+    if (targetModel) {
+        const perModel = session.settingsManager.getModelThinkingLevel(targetModel.provider, targetModel.id);
+        if (perModel !== undefined) {
+            return perModel;
+        }
+    }
+    return session.settingsManager.getDefaultThinkingLevel() ?? session.thinkingLevel ?? DEFAULT_THINKING_LEVEL;
+}
+//# sourceMappingURL=agent-session-model.js.map

package/dist/core/agent-session-model.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-session-model.js","sourceRoot":"","sources":["../../src/core/agent-session-model.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Model selection and thinking-level resolution for AgentSession.\n *\n * Extracted from `agent-session.ts`. Every function here operates on the\n * internal session facade ({@link AgentSessionInternals}); `AgentSession`\n * keeps same-name delegates so call sites, dynamic dispatch, and test spies\n * keep working unchanged. Method-to-method calls that have a facade member go\n * through the session parameter (not direct function calls) to preserve that\n * dispatch. `setModel` and `cycleModel` stay parallel implementations: each\n * keeps its own apply/persist/thinking/model_select sequence and never calls\n * the other.\n */\n\nimport type { ThinkingLevel } from \"@agent-forge/agent-core\";\nimport type { Api, Model } from \"@agent-forge/ai/compat\";\nimport { modelsAreEqual } from \"@agent-forge/ai/compat\";\nimport type { ModelCycleResult, ModelMutationOptions } from \"./agent-session.ts\";\nimport type { AgentSessionInternals } from \"./agent-session-internal.ts\";\nimport { dispatchModelSelectLifecycle } from \"./agent-session-lifecycle.ts\";\nimport { DEFAULT_THINKING_LEVEL } from \"./defaults.ts\";\nimport type { ModelFactsViewV1 } from \"./extensions/public-api.ts\";\n\nexport async function emitModelSelect(\n\tsession: AgentSessionInternals,\n\tnextModel: Model<Api>,\n\tpreviousModel: Model<Api> | undefined,\n\tsource: \"set\" | \"cycle\" | \"restore\",\n): Promise<void> {\n\tif (modelsAreEqual(previousModel, nextModel)) return;\n\tawait dispatchModelSelectLifecycle(session, { provider: nextModel.provider, id: nextModel.id }, source);\n}\n\n/**\n * Set model directly.\n * Validates that auth is configured and saves to the session transcript.\n * Persists to global defaults only when options.persist is true.\n * @throws Error if no auth is configured for the model\n */\nexport async function setModel(\n\tsession: AgentSessionInternals,\n\tmodel: Model<Api>,\n\toptions: ModelMutationOptions = {},\n): Promise<void> {\n\tif (!(await session._modelRuntime.checkAuth(model.provider))) {\n\t\tthrow new Error(`No API key for ${model.provider}/${model.id}`);\n\t}\n\n\tconst previousModel = session.model;\n\tconst thinkingLevel = session._getThinkingLevelForModelSwitch(model);\n\tsession.agent.state.model = model;\n\tsession.sessionManager.appendModelChange(model.provider, model.id);\n\tif (options.persist) {\n\t\tsession.settingsManager.setDefaultModelAndProvider(model.provider, model.id);\n\t\tsession._addPersistedDefaultToNonEmptyScope(model);\n\t}\n\n\t// Apply thinking level for the new model.\n\t// Per-model thinking level overrides take priority over the global default.\n\t// Model persistence does not implicitly rewrite the global thinking default.\n\tsession.setThinkingLevel(thinkingLevel);\n\n\tawait session._emitModelSelect(model, previousModel, \"set\");\n}\n\nexport function addPersistedDefaultToNonEmptyScope(session: AgentSessionInternals, model: Model<Api>): void {\n\tif (session._scopedModels.length === 0) return;\n\tif (session._scopedModels.some((scoped) => modelsAreEqual(scoped.model, model))) return;\n\n\tsession._scopedModels = [...session._scopedModels, { model }];\n\n\tconst enabledModels = session.settingsManager.getEnabledModels();\n\tif (!enabledModels?.length) return;\n\n\tconst modelReference = `${model.provider}/${model.id}`;\n\tif (enabledModels.some((pattern) => pattern.toLowerCase() === modelReference.toLowerCase())) return;\n\tsession.settingsManager.setEnabledModels([...enabledModels, modelReference]);\n}\n\n/**\n * Cycle to next/previous model.\n * Uses scoped models (from --models flag) if available, otherwise all available models.\n * @param direction - \"forward\" (default) or \"backward\"\n * @returns The new model info, or undefined if only one model available\n */\nexport async function cycleModel(\n\tsession: AgentSessionInternals,\n\tdirection: \"forward\" | \"backward\" = \"forward\",\n\toptions: ModelMutationOptions = {},\n): Promise<ModelCycleResult | undefined> {\n\tif (session._scopedModels.length > 0) {\n\t\treturn session._cycleScopedModel(direction, options);\n\t}\n\treturn session._cycleAvailableModel(direction, options);\n}\n\nexport async function cycleScopedModel(\n\tsession: AgentSessionInternals,\n\tdirection: \"forward\" | \"backward\",\n\toptions: ModelMutationOptions,\n): Promise<ModelCycleResult | undefined> {\n\tconst availableIds = new Set(\n\t\tsession._modelRuntime.getAvailableSnapshot().map((model) => `${model.provider}\\0${model.id}`),\n\t);\n\tconst scopedModels = session._scopedModels.filter((scoped) =>\n\t\tavailableIds.has(`${scoped.model.provider}\\0${scoped.model.id}`),\n\t);\n\tif (scopedModels.length <= 1) return undefined;\n\n\tconst currentModel = session.model;\n\tlet currentIndex = scopedModels.findIndex((sm) => modelsAreEqual(sm.model, currentModel));\n\n\tif (currentIndex === -1) currentIndex = 0;\n\tconst len = scopedModels.length;\n\tconst nextIndex = direction === \"forward\" ? (currentIndex + 1) % len : (currentIndex - 1 + len) % len;\n\tconst next = scopedModels[nextIndex];\n\tconst thinkingLevel = session._getThinkingLevelForModelSwitch(next.model, next.thinkingLevel);\n\n\t// Apply model\n\tsession.agent.state.model = next.model;\n\tsession.sessionManager.appendModelChange(next.model.provider, next.model.id);\n\tif (options.persist) {\n\t\tsession.settingsManager.setDefaultModelAndProvider(next.model.provider, next.model.id);\n\t\tsession._addPersistedDefaultToNonEmptyScope(next.model);\n\t}\n\n\t// Apply thinking level for the new model.\n\t// - Explicit scoped model thinking level overrides defaults\n\t// - Per-model thinking level overrides take priority over the global default\n\t// setThinkingLevel clamps to model capabilities.\n\t// Model persistence does not implicitly rewrite the global thinking default.\n\tsession.setThinkingLevel(thinkingLevel);\n\n\tawait session._emitModelSelect(next.model, currentModel, \"cycle\");\n\n\treturn { model: next.model, thinkingLevel: session.thinkingLevel, isScoped: true };\n}\n\nexport async function cycleAvailableModel(\n\tsession: AgentSessionInternals,\n\tdirection: \"forward\" | \"backward\",\n\toptions: ModelMutationOptions,\n): Promise<ModelCycleResult | undefined> {\n\tconst availableModels = session._modelRuntime.getAvailableSnapshot();\n\tif (availableModels.length <= 1) return undefined;\n\n\tconst currentModel = session.model;\n\tlet currentIndex = availableModels.findIndex((m) => modelsAreEqual(m, currentModel));\n\n\tif (currentIndex === -1) currentIndex = 0;\n\tconst len = availableModels.length;\n\tconst nextIndex = direction === \"forward\" ? (currentIndex + 1) % len : (currentIndex - 1 + len) % len;\n\tconst nextModel = availableModels[nextIndex];\n\n\tconst thinkingLevel = session._getThinkingLevelForModelSwitch(nextModel);\n\tsession.agent.state.model = nextModel;\n\tsession.sessionManager.appendModelChange(nextModel.provider, nextModel.id);\n\tif (options.persist) {\n\t\tsession.settingsManager.setDefaultModelAndProvider(nextModel.provider, nextModel.id);\n\t\tsession._addPersistedDefaultToNonEmptyScope(nextModel);\n\t}\n\n\t// Apply thinking level for the new model.\n\t// Model persistence does not implicitly rewrite the global thinking default.\n\tsession.setThinkingLevel(thinkingLevel);\n\n\tawait session._emitModelSelect(nextModel, currentModel, \"cycle\");\n\n\treturn { model: nextModel, thinkingLevel: session.thinkingLevel, isScoped: false };\n}\n\n/** Scoped models for cycling (from --models flag). */\nexport function getScopedModels(\n\tsession: AgentSessionInternals,\n): ReadonlyArray<{ model: Model<Api>; thinkingLevel?: ThinkingLevel }> {\n\treturn session._scopedModels;\n}\n\n/** Project provider-agnostic facts off a Model without exposing api/headers/cost internals. */\nexport function modelFactsView(model: Model<Api>): ModelFactsViewV1 {\n\treturn {\n\t\tprovider: model.provider,\n\t\tid: model.id,\n\t\tcontextWindow: model.contextWindow,\n\t\tmaxTokens: model.maxTokens,\n\t\treasoning: model.reasoning,\n\t};\n}\n\n/** Update scoped models for cycling. */\nexport function setScopedModels(\n\tsession: AgentSessionInternals,\n\tscopedModels: Array<{ model: Model<Api>; thinkingLevel?: ThinkingLevel }>,\n): void {\n\tsession._scopedModels = scopedModels;\n}\n\nexport function getThinkingLevelForModelSwitch(\n\tsession: AgentSessionInternals,\n\ttargetModel?: Model<Api>,\n\texplicitLevel?: ThinkingLevel,\n): ThinkingLevel {\n\tif (explicitLevel !== undefined) {\n\t\treturn explicitLevel;\n\t}\n\t// Per-model default takes priority when switching to a model that has one\n\tif (targetModel) {\n\t\tconst perModel = session.settingsManager.getModelThinkingLevel(targetModel.provider, targetModel.id);\n\t\tif (perModel !== undefined) {\n\t\t\treturn perModel;\n\t\t}\n\t}\n\treturn session.settingsManager.getDefaultThinkingLevel() ?? session.thinkingLevel ?? DEFAULT_THINKING_LEVEL;\n}\n"]}

package/dist/core/agent-session-paths.d.ts

@@ -0,0 +1,3 @@
+/** 子代理会话目录（不存在时创建）。 */
+export declare function agentSessionsDir(agentDir: string): string;
+//# sourceMappingURL=agent-session-paths.d.ts.map

package/dist/core/agent-session-paths.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-session-paths.d.ts","sourceRoot":"","sources":["../../src/core/agent-session-paths.ts"],"names":[],"mappings":"AASA,uDAAuB;AACvB,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAIzD","sourcesContent":["/**\n * 子代理会话落盘路径（D-060 §3）：与 root 会话同构的 JSONL，但放在\n * `<agentDir>/sessions/_agents/`——不进用户的会话列表，仍可按 sessionId 精确回读。\n */\nimport { mkdirSync } from \"node:fs\";\nimport { join } from \"node:path\";\n\nconst AGENT_SESSIONS_DIR_NAME = \"_agents\";\n\n/** 子代理会话目录（不存在时创建）。 */\nexport function agentSessionsDir(agentDir: string): string {\n\tconst dir = join(agentDir, \"sessions\", AGENT_SESSIONS_DIR_NAME);\n\tmkdirSync(dir, { recursive: true });\n\treturn dir;\n}\n"]}

package/dist/core/agent-session-paths.js

@@ -0,0 +1,14 @@
+/**
+ * 子代理会话落盘路径（D-060 §3）：与 root 会话同构的 JSONL，但放在
+ * `<agentDir>/sessions/_agents/`——不进用户的会话列表，仍可按 sessionId 精确回读。
+ */
+import { mkdirSync } from "node:fs";
+import { join } from "node:path";
+const AGENT_SESSIONS_DIR_NAME = "_agents";
+/** 子代理会话目录（不存在时创建）。 */
+export function agentSessionsDir(agentDir) {
+    const dir = join(agentDir, "sessions", AGENT_SESSIONS_DIR_NAME);
+    mkdirSync(dir, { recursive: true });
+    return dir;
+}
+//# sourceMappingURL=agent-session-paths.js.map

package/dist/core/agent-session-paths.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-session-paths.js","sourceRoot":"","sources":["../../src/core/agent-session-paths.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AACpC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAEjC,MAAM,uBAAuB,GAAG,SAAS,CAAC;AAE1C,uDAAuB;AACvB,MAAM,UAAU,gBAAgB,CAAC,QAAgB,EAAU;IAC1D,MAAM,GAAG,GAAG,IAAI,CAAC,QAAQ,EAAE,UAAU,EAAE,uBAAuB,CAAC,CAAC;IAChE,SAAS,CAAC,GAAG,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IACpC,OAAO,GAAG,CAAC;AAAA,CACX","sourcesContent":["/**\n * 子代理会话落盘路径（D-060 §3）：与 root 会话同构的 JSONL，但放在\n * `<agentDir>/sessions/_agents/`——不进用户的会话列表，仍可按 sessionId 精确回读。\n */\nimport { mkdirSync } from \"node:fs\";\nimport { join } from \"node:path\";\n\nconst AGENT_SESSIONS_DIR_NAME = \"_agents\";\n\n/** 子代理会话目录（不存在时创建）。 */\nexport function agentSessionsDir(agentDir: string): string {\n\tconst dir = join(agentDir, \"sessions\", AGENT_SESSIONS_DIR_NAME);\n\tmkdirSync(dir, { recursive: true });\n\treturn dir;\n}\n"]}

package/dist/core/agent-session-projection.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Read-only session projections for AgentSession: fork selector entries,
+ * session stats, context usage, and export entry points.
+ *
+ * Extracted from `agent-session.ts`. Every function here operates on the
+ * internal session facade ({@link AgentSessionInternals}); `AgentSession`
+ * keeps same-name delegates so call sites, dynamic dispatch, and test spies
+ * keep working unchanged. Method-to-method calls that have a facade member go
+ * through the session parameter (not direct function calls) to preserve that
+ * dispatch — `getSessionStats` reads context usage through
+ * `session.getContextUsage()` and `exportToHtml` resolves tool definitions
+ * through `session.getToolDefinition()`.
+ */
+import type { SessionStats } from "./agent-session.ts";
+import type { AgentSessionInternals } from "./agent-session-internal.ts";
+import type { ContextUsage } from "./extensions/public-api.ts";
+/**
+ * Get all user messages from session for fork selector.
+ */
+export declare function getUserMessagesForForking(session: AgentSessionInternals): Array<{
+    entryId: string;
+    text: string;
+}>;
+/**
+ * Get session statistics. Aggregates over ALL session entries (including
+ * history that was compacted away), so token/cost totals reflect what was
+ * actually billed across the session.
+ */
+export declare function getSessionStats(session: AgentSessionInternals): SessionStats;
+export declare function getContextUsage(session: AgentSessionInternals): ContextUsage | undefined;
+/**
+ * Export session to HTML.
+ * @param outputPath Optional output path (defaults to session directory)
+ * @param options Optional export presentation settings
+ * @returns Path to exported file
+ */
+export declare function exportToHtml(session: AgentSessionInternals, outputPath?: string, options?: {
+    themeName?: string;
+}): Promise<string>;
+/**
+ * Export the current session branch to a JSONL file.
+ * Writes the session header followed by all entries on the current branch path.
+ * @param outputPath Target file path. If omitted, generates a timestamped file in cwd.
+ * @returns The resolved output file path.
+ */
+export declare function exportToJsonl(session: AgentSessionInternals, outputPath?: string): string;
+/**
+ * Get text content of last assistant message.
+ * Useful for /copy command.
+ * @returns Text content, or undefined if no assistant message exists
+ */
+export declare function getLastAssistantText(session: AgentSessionInternals): string | undefined;
+//# sourceMappingURL=agent-session-projection.d.ts.map

package/dist/core/agent-session-projection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-session-projection.d.ts","sourceRoot":"","sources":["../../src/core/agent-session-projection.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAKH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AACvD,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,6BAA6B,CAAC;AAIzE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,4BAA4B,CAAC;AAK/D;;GAEG;AACH,wBAAgB,yBAAyB,CAAC,OAAO,EAAE,qBAAqB,GAAG,KAAK,CAAC;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC,CAelH;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,qBAAqB,GAAG,YAAY,CAkD5E;AAED,wBAAgB,eAAe,CAAC,OAAO,EAAE,qBAAqB,GAAG,YAAY,GAAG,SAAS,CA4CxF;AAED;;;;;GAKG;AACH,wBAAsB,YAAY,CACjC,OAAO,EAAE,qBAAqB,EAC9B,UAAU,CAAC,EAAE,MAAM,EACnB,OAAO,GAAE;IAAE,SAAS,CAAC,EAAE,MAAM,CAAA;CAAO,GAClC,OAAO,CAAC,MAAM,CAAC,CAiBjB;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,qBAAqB,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,MAAM,CAEzF;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,qBAAqB,GAAG,MAAM,GAAG,SAAS,CAsBvF","sourcesContent":["/**\n * Read-only session projections for AgentSession: fork selector entries,\n * session stats, context usage, and export entry points.\n *\n * Extracted from `agent-session.ts`. Every function here operates on the\n * internal session facade ({@link AgentSessionInternals}); `AgentSession`\n * keeps same-name delegates so call sites, dynamic dispatch, and test spies\n * keep working unchanged. Method-to-method calls that have a facade member go\n * through the session parameter (not direct function calls) to preserve that\n * dispatch — `getSessionStats` reads context usage through\n * `session.getContextUsage()` and `exportToHtml` resolves tool definitions\n * through `session.getToolDefinition()`.\n */\n\nimport { contentText } from \"@agent-forge/ai\";\nimport type { AssistantMessage } from \"@agent-forge/ai/compat\";\nimport { getThemeByName, theme } from \"../modes/interactive/theme/theme.ts\";\nimport type { SessionStats } from \"./agent-session.ts\";\nimport type { AgentSessionInternals } from \"./agent-session-internal.ts\";\nimport { calculateContextTokens, estimateContextTokens } from \"./compaction/index.ts\";\nimport { exportSessionToHtml, type ToolHtmlRenderer } from \"./export-html/index.ts\";\nimport { createToolHtmlRenderer } from \"./export-html/tool-renderer.ts\";\nimport type { ContextUsage } from \"./extensions/public-api.ts\";\nimport { exportSessionToJsonl } from \"./session-export.ts\";\nimport { getLatestCompactionEntry } from \"./session-manager.ts\";\nimport { addUsageToTotals, createUsageTotals } from \"./usage-totals.ts\";\n\n/**\n * Get all user messages from session for fork selector.\n */\nexport function getUserMessagesForForking(session: AgentSessionInternals): Array<{ entryId: string; text: string }> {\n\tconst entries = session.sessionManager.getEntries();\n\tconst result: Array<{ entryId: string; text: string }> = [];\n\n\tfor (const entry of entries) {\n\t\tif (entry.type !== \"message\") continue;\n\t\tif (entry.message.role !== \"user\") continue;\n\n\t\tconst text = contentText(entry.message.content, \"\");\n\t\tif (text) {\n\t\t\tresult.push({ entryId: entry.id, text });\n\t\t}\n\t}\n\n\treturn result;\n}\n\n/**\n * Get session statistics. Aggregates over ALL session entries (including\n * history that was compacted away), so token/cost totals reflect what was\n * actually billed across the session.\n */\nexport function getSessionStats(session: AgentSessionInternals): SessionStats {\n\tlet userMessages = 0;\n\tlet assistantMessages = 0;\n\tlet toolResults = 0;\n\tlet totalMessages = 0;\n\tlet toolCalls = 0;\n\tconst usageTotals = createUsageTotals();\n\n\tfor (const entry of session.sessionManager.getEntries()) {\n\t\tif ((entry.type === \"branch_summary\" || entry.type === \"compaction\") && entry.usage) {\n\t\t\taddUsageToTotals(usageTotals, entry.usage);\n\t\t}\n\t\tif (entry.type !== \"message\") continue;\n\t\ttotalMessages++;\n\t\tconst message = entry.message;\n\t\tif (message.role === \"user\") {\n\t\t\tuserMessages++;\n\t\t} else if (message.role === \"toolResult\") {\n\t\t\ttoolResults++;\n\t\t\tif (message.usage) {\n\t\t\t\taddUsageToTotals(usageTotals, message.usage);\n\t\t\t}\n\t\t} else if (message.role === \"assistant\") {\n\t\t\tassistantMessages++;\n\t\t\tconst assistantMsg = message as AssistantMessage;\n\t\t\tif (Array.isArray(assistantMsg.content)) {\n\t\t\t\ttoolCalls += assistantMsg.content.filter((c) => c.type === \"toolCall\").length;\n\t\t\t}\n\t\t\taddUsageToTotals(usageTotals, assistantMsg.usage);\n\t\t}\n\t}\n\n\treturn {\n\t\tsessionFile: session.sessionFile,\n\t\tsessionId: session.sessionId,\n\t\tuserMessages,\n\t\tassistantMessages,\n\t\ttoolCalls,\n\t\ttoolResults,\n\t\ttotalMessages,\n\t\ttokens: {\n\t\t\tinput: usageTotals.input,\n\t\t\toutput: usageTotals.output,\n\t\t\tcacheRead: usageTotals.cacheRead,\n\t\t\tcacheWrite: usageTotals.cacheWrite,\n\t\t\ttotal: usageTotals.input + usageTotals.output + usageTotals.cacheRead + usageTotals.cacheWrite,\n\t\t},\n\t\tcost: usageTotals.cost,\n\t\tcontextUsage: session.getContextUsage(),\n\t};\n}\n\nexport function getContextUsage(session: AgentSessionInternals): ContextUsage | undefined {\n\tconst model = session.model;\n\tif (!model) return undefined;\n\n\tconst contextWindow = model.contextWindow ?? 0;\n\tif (contextWindow <= 0) return undefined;\n\n\t// After compaction, the last assistant usage reflects pre-compaction context size.\n\t// We can only trust usage from an assistant that responded after the latest compaction.\n\t// If no such assistant exists, context token count is unknown until the next LLM response.\n\tconst branchEntries = session.sessionManager.getBranch();\n\tconst latestCompaction = getLatestCompactionEntry(branchEntries);\n\n\tif (latestCompaction) {\n\t\t// Check if there's a valid assistant usage after the compaction boundary\n\t\tconst compactionIndex = branchEntries.lastIndexOf(latestCompaction);\n\t\tlet hasPostCompactionUsage = false;\n\t\tfor (let i = branchEntries.length - 1; i > compactionIndex; i--) {\n\t\t\tconst entry = branchEntries[i];\n\t\t\tif (entry.type === \"message\" && entry.message.role === \"assistant\") {\n\t\t\t\tconst assistant = entry.message;\n\t\t\t\tif (assistant.stopReason !== \"aborted\" && assistant.stopReason !== \"error\") {\n\t\t\t\t\tconst contextTokens = calculateContextTokens(assistant.usage);\n\t\t\t\t\tif (contextTokens > 0) {\n\t\t\t\t\t\thasPostCompactionUsage = true;\n\t\t\t\t\t\tbreak;\n\t\t\t\t\t}\n\t\t\t\t}\n\t\t\t}\n\t\t}\n\n\t\tif (!hasPostCompactionUsage) {\n\t\t\treturn { tokens: null, contextWindow, percent: null };\n\t\t}\n\t}\n\n\tconst estimate = estimateContextTokens(session.messages);\n\tconst percent = (estimate.tokens / contextWindow) * 100;\n\n\treturn {\n\t\ttokens: estimate.tokens,\n\t\tcontextWindow,\n\t\tpercent,\n\t};\n}\n\n/**\n * Export session to HTML.\n * @param outputPath Optional output path (defaults to session directory)\n * @param options Optional export presentation settings\n * @returns Path to exported file\n */\nexport async function exportToHtml(\n\tsession: AgentSessionInternals,\n\toutputPath?: string,\n\toptions: { themeName?: string } = {},\n): Promise<string> {\n\tconst themeName = [options.themeName, session.settingsManager.getTheme()].find(\n\t\t(candidate) => candidate !== undefined && getThemeByName(candidate) !== undefined,\n\t);\n\n\t// Create tool renderer if we have an extension runner (for custom tool HTML rendering)\n\tconst toolRenderer: ToolHtmlRenderer = createToolHtmlRenderer({\n\t\tgetToolDefinition: (name) => session.getToolDefinition(name),\n\t\ttheme,\n\t\tcwd: session.sessionManager.getCwd(),\n\t});\n\n\treturn await exportSessionToHtml(session.sessionManager, session.agent.state, {\n\t\toutputPath,\n\t\tthemeName,\n\t\ttoolRenderer,\n\t});\n}\n\n/**\n * Export the current session branch to a JSONL file.\n * Writes the session header followed by all entries on the current branch path.\n * @param outputPath Target file path. If omitted, generates a timestamped file in cwd.\n * @returns The resolved output file path.\n */\nexport function exportToJsonl(session: AgentSessionInternals, outputPath?: string): string {\n\treturn exportSessionToJsonl(session.sessionManager, outputPath);\n}\n\n/**\n * Get text content of last assistant message.\n * Useful for /copy command.\n * @returns Text content, or undefined if no assistant message exists\n */\nexport function getLastAssistantText(session: AgentSessionInternals): string | undefined {\n\tconst lastAssistant = session.messages\n\t\t.slice()\n\t\t.reverse()\n\t\t.find((m) => {\n\t\t\tif (m.role !== \"assistant\") return false;\n\t\t\tconst msg = m as AssistantMessage;\n\t\t\t// Skip aborted messages with no content\n\t\t\tif (msg.stopReason === \"aborted\" && msg.content.length === 0) return false;\n\t\t\treturn true;\n\t\t});\n\n\tif (!lastAssistant) return undefined;\n\n\tlet text = \"\";\n\tfor (const content of (lastAssistant as AssistantMessage).content) {\n\t\tif (content.type === \"text\") {\n\t\t\ttext += content.text;\n\t\t}\n\t}\n\n\treturn text.trim() || undefined;\n}\n"]}