agent-accelerator 0.5.5 → 0.5.7

package/src/utils/session.ts

@@ -1,7 +1,5 @@
 import { clampCacheKey } from "./cache.ts";
 import type { ThinkingLevel } from "../types/core.ts";
-import type { MidSessionMode } from "../types/agent.ts";
-import type { AgentConfig } from "../types/agent.ts";
 import type { ModelSpec } from "../types/model.ts";
 import type { ModelProviderInstance } from "../providers/registry.ts";
 import type { ContentPart } from "../types/message.ts";
@@ -83,6 +81,7 @@ export function nowMs(): number {
   return Date.now();
 }
 
+// 32 random lowercase hex characters; in: newRunId/newTurnId, out: a string.
 function random32Hex(): string {
   try {
     const c = (globalThis as any)?.crypto;
@@ -111,14 +110,7 @@ export function newTurnId(): string {
   return random32Hex();
 }
 
-/**
- * Single canonical prompt preview (Q-49): merges the former
- * `previewPrompt` (agent.ts) / `steerPreview` (loop.ts) duplicates.
- * Bounded to 500 chars, display-only. Other modules own their copies;
- * new code should import this one.
- *
- * @example `previewPrompt("hello")`
- */
+/** Bounded (500 chars), display-only preview of a prompt, used in `queued`/`steer_injected` events, turn lists and `interrupted()`. */
 export function previewPrompt(prompt: string | ContentPart[]): string {
   if (typeof prompt === "string") return prompt.slice(0, 500);
   try {
@@ -141,6 +133,7 @@ export interface ParsedModelRef {
   thinking?: ThinkingLevel;
 }
 
+// Splits `provider/model` on the first slash (bare ids default to openrouter); in: parseModelRef, out: provider and model id.
 function splitModelString(raw: string): { provider: string; modelId: string } {
   const trimmed = raw.trim();
   const slash = trimmed.indexOf("/");
@@ -153,12 +146,14 @@ function splitModelString(raw: string): { provider: string; modelId: string } {
   };
 }
 
+// Type guard for a `{ model: string }` helper result; in: parseModelRef, out: a boolean.
 function isModelProviderInstance(v: unknown): v is ModelProviderInstance {
   if (!v || typeof v !== "object" || Array.isArray(v)) return false;
   const r = v as Record<string, unknown>;
   return typeof r["model"] === "string" && (r["model"] as string).length > 0;
 }
 
+// Type guard for a catalog spec (`provider` and `id` strings); in: parseModelRef, out: a boolean.
 function isModelSpec(v: unknown): v is ModelSpec {
   if (!v || typeof v !== "object" || Array.isArray(v)) return false;
   const r = v as Record<string, unknown>;
@@ -192,154 +187,3 @@ export function parseModelRef(input: string | ModelSpec | ModelProviderInstance)
   }
   throw new ConfigError("parseModelRef: expected string | ModelSpec | ModelProviderInstance.");
 }
-
-/** Validated, readonly agent configuration returned by {@link resolveAgentConfig} (Q-32). */
-export interface ResolvedAgentConfig {
-  readonly model: NonNullable<AgentConfig["model"]>;
-  readonly thinkingLevel?: ThinkingLevel;
-  readonly maxTurns: number;
-  readonly midSession: { readonly mode: MidSessionMode; readonly maxQueued: number };
-  readonly toolNames: readonly string[];
-}
-
-const VALID_THINKING_LEVELS: readonly ThinkingLevel[] = [
-  "none",
-  "dynamic",
-  "minimal",
-  "low",
-  "medium",
-  "high",
-  "xhigh",
-  "max",
-];
-
-const VALID_MIDSESSION_MODES: readonly MidSessionMode[] = ["steer", "queue", "auto"];
-
-/** Local name normalization mirroring `normalizeToolName` (no import cycle, Q-32). */
-function normalizeConfigToolName(name: string): string {
-  return name
-    .trim()
-    .replace(/^(?:functions?|tools?)\./i, "")
-    .replace(/([a-z0-9])([A-Z])/g, "$1_$2")
-    .replace(/[\s-]+/g, "_")
-    .toLowerCase();
-}
-
-/**
- * Single config resolution (Q-32). Validates `model`, `thinkingLevel`,
- * `maxTurns`, `midSession`, and tool-name collisions, collecting EVERY issue
- * and throwing one `ConfigError` listing all of them. Not wired into `Agent`
- * (other owner) — call it from setup paths that want fail-fast validation.
- *
- * @example `const cfg = resolveAgentConfig({ model, maxTurns: 10 });`
- */
-export function resolveAgentConfig(config: AgentConfig): Readonly<ResolvedAgentConfig> {
-  const issues: string[] = [];
-  const cfg = (config ?? {}) as AgentConfig;
-
-  let model: NonNullable<AgentConfig["model"]> | undefined;
-  const rawModel = cfg.model;
-  if (typeof rawModel === "string") {
-    if (rawModel.trim()) model = rawModel;
-    else issues.push("model: must be a non-empty string | ModelSpec | ModelProviderInstance.");
-  } else if (rawModel && typeof rawModel === "object") {
-    model = rawModel as NonNullable<AgentConfig["model"]>;
-  } else {
-    issues.push("model: is required (string | ModelSpec | ModelProviderInstance).");
-  }
-
-  let thinkingLevel: ThinkingLevel | undefined;
-  if (cfg.thinkingLevel !== undefined) {
-    if ((VALID_THINKING_LEVELS as readonly string[]).includes(cfg.thinkingLevel)) {
-      thinkingLevel = cfg.thinkingLevel;
-    } else {
-      issues.push(
-        `thinkingLevel: invalid '${cfg.thinkingLevel}'. Expected one of: ${VALID_THINKING_LEVELS.join(", ")}.`
-      );
-    }
-  }
-
-  let maxTurns = Infinity;
-  if (cfg.maxTurns !== undefined) {
-    const m = cfg.maxTurns;
-    if (m === 0) {
-      maxTurns = Infinity;
-    } else if (m === Infinity) {
-      maxTurns = Infinity;
-    } else if (typeof m === "number" && Number.isFinite(m) && m >= 1) {
-      maxTurns = Math.floor(m);
-    } else {
-      issues.push(`maxTurns: must be finite >= 1 or Infinity (0/omitted means unlimited). Received: ${String(m)}.`);
-    }
-  }
-
-  let mode: MidSessionMode = "auto";
-  if (cfg.midSession?.mode !== undefined) {
-    if ((VALID_MIDSESSION_MODES as readonly string[]).includes(cfg.midSession.mode as string)) {
-      mode = cfg.midSession.mode as MidSessionMode;
-    } else {
-      issues.push(
-        `midSession.mode: invalid '${String(cfg.midSession.mode)}'. Expected one of: ${VALID_MIDSESSION_MODES.join(", ")}.`
-      );
-    }
-  }
-  let maxQueued = 20;
-  if (cfg.midSession?.maxQueued !== undefined) {
-    const q = cfg.midSession.maxQueued;
-    if (typeof q === "number" && Number.isFinite(q) && Math.floor(q) === q && q >= 0) {
-      maxQueued = q;
-    } else {
-      issues.push(`midSession.maxQueued: must be an integer >= 0. Received: ${String(q)}.`);
-    }
-  }
-
-  const toolNames: string[] = [];
-  const tools = cfg.tools;
-  if (tools !== undefined) {
-    const entries: Array<[string, string]> = [];
-    if (Array.isArray(tools)) {
-      for (const def of tools) {
-        const declared = (def as { name?: unknown })?.name;
-        if (typeof declared === "string" && declared.trim()) {
-          toolNames.push(declared);
-          entries.push([declared, declared]);
-        } else {
-          issues.push("tools: array entries must declare a non-empty `name`.");
-        }
-      }
-    } else if (tools && typeof tools === "object") {
-      for (const [key, def] of Object.entries(tools)) {
-        toolNames.push(key);
-        const declared = (def as { name?: unknown })?.name;
-        entries.push([key, typeof declared === "string" && declared ? declared : key]);
-      }
-    } else {
-      issues.push("tools: must be a record or array of ToolDefinitions.");
-    }
-    const seen = new Map<string, string>();
-    for (const [key, declared] of entries) {
-      for (const candidate of new Set([key, declared])) {
-        const normalized = normalizeConfigToolName(String(candidate));
-        const prev = seen.get(normalized);
-        if (prev !== undefined && prev !== key) {
-          issues.push(
-            `tools: name collision: '${prev}' and '${key}' both normalize to '${normalized}'. Rename one tool.`
-          );
-        } else if (prev === undefined) {
-          seen.set(normalized, key);
-        }
-      }
-    }
-  }
-
-  if (issues.length > 0) {
-    throw new ConfigError(`Invalid Agent config (${issues.length} issue${issues.length === 1 ? "" : "s"}): ${issues.join(" ")}`);
-  }
-  return {
-    model: model as NonNullable<AgentConfig["model"]>,
-    ...(thinkingLevel !== undefined ? { thinkingLevel } : {}),
-    maxTurns,
-    midSession: { mode, maxQueued },
-    toolNames,
-  };
-}