Skip to content

The open-source agent harness - the runtime layer that turns an LLM into a working agent.

12.6 KB
Raw Blame
import type { AgentRuntimeConfig, AgentSpec } from './types.js';

/** @deprecated Migrated into chat/agent keys on first read. */
export const DRAFT_SPEC_PREFERENCES_STORAGE_KEY = 'tfy-aui-draft-spec-preferences';
export const CHAT_DRAFT_SPEC_PREFERENCES_STORAGE_KEY = 'tfy-aui-chat-draft-spec-preferences';
export const AGENT_DRAFT_SPEC_PREFERENCES_STORAGE_KEY = 'tfy-aui-agent-draft-spec-preferences';

export type DraftPreferenceKind = 'chat' | 'agent';

type StoredDraftSpecPreferences = {
  version: 1;
  spec: AgentSpec;
};

function isObject(value: unknown): value is object {
  return typeof value === 'object' && value !== null;
}

function isMountList(value: unknown): boolean {
  return Array.isArray(value) && value.every(isObject);
}

function isAgentSpec(value: unknown): value is AgentSpec {
  if (!isObject(value)) return false;
  const model = Reflect.get(value, 'model');
  if (!isObject(model) || typeof Reflect.get(model, 'name') !== 'string') return false;

  const params = Reflect.get(model, 'params');
  if (params !== undefined && !isObject(params)) return false;

  const skills = Reflect.get(value, 'skills');
  if (skills !== undefined && !isMountList(skills)) return false;

  const mcpServers = Reflect.get(value, 'mcpServers');
  if (mcpServers !== undefined && !isMountList(mcpServers)) return false;

  const config = Reflect.get(value, 'config');
  return config === undefined || isObject(config);
}

function isStoredDraftSpecPreferences(value: unknown): value is StoredDraftSpecPreferences {
  return isObject(value) && Reflect.get(value, 'version') === 1 && isAgentSpec(Reflect.get(value, 'spec'));
}

function storageKeyForKind(kind: DraftPreferenceKind): string {
  return kind === 'chat' ? CHAT_DRAFT_SPEC_PREFERENCES_STORAGE_KEY : AGENT_DRAFT_SPEC_PREFERENCES_STORAGE_KEY;
}

function readSandboxEnabled(spec: AgentSpec): boolean | undefined {
  if (spec.config === undefined) return undefined;
  // `sandbox` is persisted on draft config but is not part of AgentRuntimeConfig.
  const sandbox = Reflect.get(spec.config, 'sandbox');
  if (!isObject(sandbox)) return undefined;
  const enabled = Reflect.get(sandbox, 'enabled');
  return typeof enabled === 'boolean' ? enabled : undefined;
}

function readTrimmedString(value: object, key: string): string {
  const raw = Reflect.get(value, key);
  return typeof raw === 'string' ? raw.trim() : '';
}

type SandboxConfig = NonNullable<AgentRuntimeConfig['sandbox']>;

/** Display name. A leftover wire `environment_name` counts when the client field is empty. */
export function readSandboxEnvironmentName(sandbox: object | undefined): string {
  if (!isObject(sandbox)) return 'default';
  const camelName = readTrimmedString(sandbox, 'environmentName');
  if (camelName.length > 0) return camelName;
  const snakeName = readTrimmedString(sandbox, 'environment_name');
  return snakeName.length > 0 ? snakeName : 'default';
}

/** Set the client field and drop a leftover wire key so passthrough serialization cannot send it. */
export function sandboxWithEnvironmentName(
  sandbox: SandboxConfig | undefined,
  environmentName: string | undefined,
): SandboxConfig {
  const next: SandboxConfig = { ...sandbox, environmentName };
  Reflect.deleteProperty(next, 'environment_name');
  return next;
}

/**
 * Client field wins. Copy a leftover wire `environment_name` only when the client
 * field is empty, then drop the wire key.
 */
function normalizeSandboxEnvironmentName(spec: AgentSpec): AgentSpec {
  const sandbox = spec.config?.sandbox;
  if (sandbox === undefined || !Reflect.has(sandbox, 'environment_name')) return spec;

  const camelName = readTrimmedString(sandbox, 'environmentName');
  const snakeName = readTrimmedString(sandbox, 'environment_name');
  const nextSandbox: SandboxConfig = { ...sandbox };
  Reflect.deleteProperty(nextSandbox, 'environment_name');
  if (camelName.length === 0 && snakeName.length > 0) {
    nextSandbox.environmentName = snakeName;
  }
  return {
    ...spec,
    config: {
      ...spec.config,
      sandbox: nextSandbox,
    },
  };
}

function readWebSearchEnabled(spec: AgentSpec): boolean | undefined {
  if (spec.config?.webSearch === undefined) return undefined;
  const enabled = spec.config.webSearch.enabled;
  return typeof enabled === 'boolean' ? enabled : undefined;
}

/**
 * New Chat: model (+ reasoning params), skills, MCP, and the web-search toggle.
 * Other runtime config (sandbox, ask-user, …) is not persisted for chat.
 */
export function selectChatDraftSpecPreferences(spec: AgentSpec): AgentSpec {
  const webSearchEnabled = readWebSearchEnabled(spec);
  return {
    model: spec.model,
    ...(spec.skills !== undefined ? { skills: spec.skills } : {}),
    ...(spec.mcpServers !== undefined ? { mcpServers: spec.mcpServers } : {}),
    ...(webSearchEnabled !== undefined ? { config: { webSearch: { enabled: webSearchEnabled } } } : {}),
  };
}

/** New Agent: full composer seed including runtime config (sandbox, ask-user, …). */
export function selectAgentDraftSpecPreferences(spec: AgentSpec): AgentSpec {
  const normalized = normalizeSandboxEnvironmentName(spec);
  return {
    ...selectChatDraftSpecPreferences(normalized),
    ...(normalized.config !== undefined ? { config: normalized.config } : {}),
  };
}

/**
 * Fresh New Agent seed after save/reset: keep model + runtime toggles, drop
 * instructions / initial messages / MCP / skills from the previous build.
 */
export function freshAgentBuilderSeed(spec: AgentSpec): AgentSpec {
  return {
    model: spec.model,
    ...(spec.config !== undefined ? { config: spec.config } : {}),
  };
}

export function selectDraftSpecPreferences(spec: AgentSpec, kind: DraftPreferenceKind): AgentSpec {
  return kind === 'chat' ? selectChatDraftSpecPreferences(spec) : selectAgentDraftSpecPreferences(spec);
}

/** Disable sandbox when unavailable; availability must not override the user's runtime choice. */
export function withCapabilitiesSandbox(spec: AgentSpec, sandboxEnabled: boolean | null | undefined): AgentSpec {
  if (sandboxEnabled !== false || readSandboxEnabled(spec) === false) return spec;
  const config = {
    ...spec.config,
    sandbox: { ...spec.config?.sandbox, enabled: false },
  };
  return {
    ...spec,
    config,
  };
}

/**
 * Align `config.webSearch` with host capability.
 * - unavailable → force false on the live draft (do not persist — see `withoutWebSearchPreference`)
 * - available → fill true only when the key is absent (preserve explicit user toggles)
 */
export function withCapabilitiesWebSearch({
  spec,
  webSearchEnabled,
}: {
  spec: AgentSpec;
  webSearchEnabled: boolean | null | undefined;
  /** Kept for call-site compatibility; chat and agent share the same fill/preserve rules. */
  kind?: DraftPreferenceKind;
}): AgentSpec {
  if (webSearchEnabled == null) return spec;

  if (webSearchEnabled === false) {
    if (readWebSearchEnabled(spec) === false) return spec;
    return {
      ...spec,
      config: {
        ...spec.config,
        webSearch: { ...spec.config?.webSearch, enabled: false },
      },
    };
  }

  // Only default true when the field is missing — chat and agent both keep user toggles.
  if (spec.config?.webSearch !== undefined) return spec;
  return {
    ...spec,
    config: {
      ...spec.config,
      webSearch: { enabled: true },
    },
  };
}

/** Drop webSearch so a capability-forced off is not stored as a user preference. */
export function withoutWebSearchPreference(spec: AgentSpec): AgentSpec {
  if (spec.config?.webSearch === undefined) return spec;
  const { webSearch: _ignored, ...restConfig } = spec.config;
  if (Object.keys(restConfig).length === 0) {
    const { config: _config, ...rest } = spec;
    return rest;
  }
  return { ...spec, config: restConfig };
}

/**
 * When web-search becomes available, a live `enabled: false` may be leftover force-off
 * or a schema default from an inline session created before capabilities loaded.
 * Default-fill on only when that false is not an explicit user/saved choice.
 *
 * New Chat (`kind: 'chat'`) also recovers when capability first becomes known
 * (`null`/`undefined` → true), so a premature createSession does not stick off.
 * Agent drafts keep an explicit off across first capability load.
 */
export function recoverWebSearchAfterCapabilityAvailable({
  spec,
  previousWebSearchEnabled,
  webSearchEnabled,
  explicitOff = false,
  kind,
}: {
  spec: AgentSpec;
  previousWebSearchEnabled: boolean | null | undefined;
  webSearchEnabled: boolean | null | undefined;
  /** Saved or previously persisted off — not a capability-forced value. */
  explicitOff?: boolean;
  kind?: DraftPreferenceKind;
}): AgentSpec {
  if (explicitOff) return spec;
  if (webSearchEnabled !== true) return spec;
  if (readWebSearchEnabled(spec) !== false) return spec;

  const capabilityReturned = previousWebSearchEnabled === false;
  const capabilityBecameKnown = previousWebSearchEnabled == null && kind === 'chat';
  if (!capabilityReturned && !capabilityBecameKnown) return spec;

  return withCapabilitiesWebSearch({
    spec: withoutWebSearchPreference(spec),
    webSearchEnabled: true,
    kind,
  });
}

function withWebSearchEnabled(spec: AgentSpec, enabled: boolean): AgentSpec {
  if (readWebSearchEnabled(spec) === enabled) return spec;
  return {
    ...spec,
    config: {
      ...spec.config,
      webSearch: { ...spec.config?.webSearch, enabled },
    },
  };
}

export function persistedWebSearchEnabled(kind: DraftPreferenceKind): boolean | undefined {
  const stored = readDraftSpecPreferences(kind);
  return stored == null ? undefined : readWebSearchEnabled(stored);
}

/**
 * Remember a user web-search choice. Capability-forced off, or any value seen before capabilities
 * settle (a schema default, not a choice), is omitted unless a choice was already stored; a stored off
 * is not rewritten to on when search returns.
 */
export function webSearchPreferenceToStore({
  spec,
  webSearchEnabled,
  previousWebSearchEnabled,
  capabilitiesPending = false,
  kind,
}: {
  spec: AgentSpec;
  webSearchEnabled: boolean | null | undefined;
  previousWebSearchEnabled: boolean | null | undefined;
  capabilitiesPending?: boolean;
  kind: DraftPreferenceKind;
}): AgentSpec {
  const persistedEnabled = persistedWebSearchEnabled(kind);
  if (webSearchEnabled === false || capabilitiesPending) {
    const stripped = withoutWebSearchPreference(spec);
    return persistedEnabled === undefined ? stripped : withWebSearchEnabled(stripped, persistedEnabled);
  }
  return recoverWebSearchAfterCapabilityAvailable({
    spec,
    previousWebSearchEnabled,
    webSearchEnabled,
    explicitOff: persistedEnabled === false,
    kind,
  });
}

function readStoredSpec(key: string): AgentSpec | null {
  if (typeof window === 'undefined') return null;
  try {
    const stored: unknown = JSON.parse(window.localStorage.getItem(key) ?? 'null');
    return isStoredDraftSpecPreferences(stored) ? stored.spec : null;
  } catch {
    return null;
  }
}

function writeStoredSpec(key: string, spec: AgentSpec): boolean {
  if (typeof window === 'undefined') return false;
  try {
    const stored: StoredDraftSpecPreferences = { version: 1, spec };
    window.localStorage.setItem(key, JSON.stringify(stored));
    return true;
  } catch {
    // Storage can be unavailable or full; in-memory carry-over still works.
    return false;
  }
}

/** One-shot split of the pre-split shared key into chat + agent stores. */
function migrateLegacyDraftPreferences(): void {
  if (typeof window === 'undefined') return;
  const legacy = readStoredSpec(DRAFT_SPEC_PREFERENCES_STORAGE_KEY);
  if (legacy == null) return;

  const chatReady =
    readStoredSpec(CHAT_DRAFT_SPEC_PREFERENCES_STORAGE_KEY) != null ||
    writeStoredSpec(CHAT_DRAFT_SPEC_PREFERENCES_STORAGE_KEY, selectChatDraftSpecPreferences(legacy));
  const agentReady =
    readStoredSpec(AGENT_DRAFT_SPEC_PREFERENCES_STORAGE_KEY) != null ||
    writeStoredSpec(AGENT_DRAFT_SPEC_PREFERENCES_STORAGE_KEY, selectAgentDraftSpecPreferences(legacy));

  // Keep the legacy key if either destination write failed so a later read can retry.
  if (!chatReady || !agentReady) return;

  try {
    window.localStorage.removeItem(DRAFT_SPEC_PREFERENCES_STORAGE_KEY);
  } catch {
    // Ignore quota / private-mode failures; next read still prefers kind keys.
  }
}

export function readDraftSpecPreferences(kind: DraftPreferenceKind): AgentSpec | null {
  migrateLegacyDraftPreferences();
  const stored = readStoredSpec(storageKeyForKind(kind));
  return stored == null ? null : selectDraftSpecPreferences(normalizeSandboxEnvironmentName(stored), kind);
}

export function writeDraftSpecPreferences(kind: DraftPreferenceKind, spec: AgentSpec): void {
  writeStoredSpec(storageKeyForKind(kind), selectDraftSpecPreferences(spec, kind));
}