Skip to content

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

7.9 KB
Raw Blame
'use client';

import type { AssistantClient } from '@assistant-ui/store';
import { useAui } from '@assistant-ui/store';
import { useCallback, useSyncExternalStore } from 'react';
import type { McpAuthRequiredEvent } from './server/index.js';

import type { PendingApproval, PendingToolResponse } from './collectPending.js';
import type { AgentSpecUpdate } from './draft/agentSpec.js';
import type { AgentSpec } from './server/types.js';
import type { RespondToToolApprovalOptions } from './toolApproval.js';
import type { RespondToToolResponseOptions } from './toolResponse.js';

export type { PendingApproval, PendingToolResponse };

export interface TrueForgeDraftRuntimeExtras {
  agentSpec: AgentSpec | null;
  draftSessionId: string | undefined;
  isSpecLoading: boolean;
  isSpecSyncing: boolean;
  specError: unknown;
  updateAgentSpec: (update: AgentSpecUpdate) => void;
  flushAgentSpec: () => Promise<void>;
  adoptAgentSpec: (request: { agentSpec: AgentSpec; updatedAt?: string }) => void;
}

export interface TrueForgeRuntimeExtras {
  pendingApprovals: PendingApproval[];
  pendingToolResponses: PendingToolResponse[];
  pendingMcpAuth: { mcpServers: McpAuthRequiredEvent['mcpServers'] } | null;
  resumeUnavailable: boolean;
  sandboxId: string | undefined;
  respondToToolApproval: (response: RespondToToolApprovalOptions) => void;
  respondToToolResponse: (response: RespondToToolResponseOptions) => void;
  resumeMcpAuth: () => Promise<void>;
  downloadSandboxFile: (req: { turnId: string; path: string }) => Promise<Blob>;
  cancel: () => Promise<void>;
  resetFromTurn: (turnId: string) => Promise<void>;
  reload: () => void;
  hasOlderHistory: boolean;
  isLoadingOlderHistory: boolean;
  loadOlderHistory: () => Promise<void>;
  draft: TrueForgeDraftRuntimeExtras | null;
}

const extrasBrandSymbol = Symbol('useTrueForgeAgentRuntime extras');

const isTrueForgeExtras = (extras: unknown): extras is TrueForgeRuntimeExtras =>
  typeof extras === 'object' && extras !== null && extrasBrandSymbol in extras;

const extrasBrand = {
  provide: (value: TrueForgeRuntimeExtras): TrueForgeRuntimeExtras => {
    Object.defineProperty(value, extrasBrandSymbol, {
      value: true,
      enumerable: false,
      configurable: true,
    });
    return value;
  },
  is: isTrueForgeExtras,
  tryGet: (extras: unknown): TrueForgeRuntimeExtras | undefined => (isTrueForgeExtras(extras) ? extras : undefined),
};

export const EMPTY_DRAFT_EXTRAS: TrueForgeDraftRuntimeExtras = {
  agentSpec: null,
  draftSessionId: undefined,
  isSpecLoading: false,
  isSpecSyncing: false,
  specError: null,
  updateAgentSpec: () => {
    throw new Error('Draft agent extras are only available in draft mode.');
  },
  flushAgentSpec: () => Promise.reject(new Error('Draft agent extras are only available in draft mode.')),
  adoptAgentSpec: () => {
    throw new Error('Draft agent extras are only available in draft mode.');
  },
};

type SubscribeFn = (onStoreChange: () => void) => () => void;

function isThreadAccessor(value: unknown): value is (this: object) => unknown {
  return typeof value === 'function';
}

function isGetState(value: unknown): value is (this: object) => unknown {
  return typeof value === 'function';
}

function isSubscribe(value: unknown): value is (this: object, onStoreChange: () => void) => unknown {
  return typeof value === 'function';
}

/**
 * Walk `Object.create(parent)` AUI clients. Stops before leaving the chain.
 * Callers must try/catch RootAssistantClient proxy gets (it throws on any
 * missing accessor such as `subscribe` / `thread`).
 */
function walkAssistantClientAncestors(client: AssistantClient, visit: (current: object) => 'continue' | 'stop'): void {
  let current: object | null = client;
  const seen = new Set<object>();
  while (!seen.has(current)) {
    seen.add(current);
    if (visit(current) === 'stop') {
      return;
    }
    const parent = Reflect.getPrototypeOf(current);
    if (parent == null || parent === Object.prototype) {
      return;
    }
    current = parent;
  }
}

/**
 * `PartPrimitive.Messages` wraps sub-agent threads in `ReadonlyThreadProvider`,
 * which shadows `thread` (and therefore `thread.extras`) with a readonly client
 * that has no TrueForge extras. Nested AUI clients are `Object.create(parent)`,
 * so walk the prototype chain to reach the root runtime extras.
 */
export function tryGetTrueForgeExtras(client: AssistantClient): TrueForgeRuntimeExtras | undefined {
  let found: TrueForgeRuntimeExtras | undefined;
  walkAssistantClientAncestors(client, current => {
    try {
      const thread: unknown = Reflect.get(current, 'thread');
      if (isThreadAccessor(thread)) {
        const threadClient: unknown = Reflect.apply(thread, current, []);
        if (threadClient == null || typeof threadClient !== 'object') {
          return 'continue';
        }
        const getState: unknown = Reflect.get(threadClient, 'getState');
        if (!isGetState(getState)) {
          return 'continue';
        }
        const state: unknown = Reflect.apply(getState, threadClient, []);
        const extras = extrasBrand.tryGet(
          state != null && typeof state === 'object' ? Reflect.get(state, 'extras') : undefined,
        );
        if (extras != null) {
          found = extras;
          return 'stop';
        }
      }
    } catch {
      // Nested/readonly clients may lack thread; RootAssistantClient proxy
      // throws on missing scope accessors ("thread" / "subscribe").
    }
    return 'continue';
  });
  return found;
}

export function getTrueForgeExtras(client: AssistantClient): TrueForgeRuntimeExtras {
  const extras = tryGetTrueForgeExtras(client);
  if (extras == null) {
    throw new Error('The current thread is not backed by the useTrueForgeAgentRuntime runtime.');
  }
  return extras;
}

function subscribeClientChain(client: AssistantClient): SubscribeFn {
  return onStoreChange => {
    const unsubs: (() => void)[] = [];
    walkAssistantClientAncestors(client, current => {
      try {
        const subscribe: unknown = Reflect.get(current, 'subscribe');
        if (isSubscribe(subscribe)) {
          const unsubscribe: unknown = Reflect.apply(subscribe, current, [onStoreChange]);
          if (typeof unsubscribe === 'function') {
            unsubs.push(() => {
              Reflect.apply(unsubscribe, undefined, []);
            });
          }
        }
        return 'continue';
      } catch {
        // RootAssistantClient proxy — no further usable ancestors.
        return 'stop';
      }
    });
    return () => {
      for (const unsub of unsubs) {
        unsub();
      }
    };
  };
}

/**
 * Resolves TrueForge extras from the nearest ancestor runtime, including
 * inside nested readonly sub-agent renderers (`PartPrimitive.Messages`).
 */
export function useTrueForgeRuntimeExtras(): TrueForgeRuntimeExtras | undefined {
  const aui = useAui();
  const subscribe = useCallback(subscribeClientChain(aui), [aui]);
  const getSnapshot = useCallback(() => tryGetTrueForgeExtras(aui), [aui]);
  return useSyncExternalStore(subscribe, getSnapshot, getSnapshot);
}

function useTrueForgeExtrasApi(): TrueForgeRuntimeExtras;
function useTrueForgeExtrasApi<S>(select: (extras: TrueForgeRuntimeExtras) => S, fallback?: S): S;
function useTrueForgeExtrasApi<S>(select?: (extras: TrueForgeRuntimeExtras) => S, fallback?: S): unknown {
  const extras = useTrueForgeRuntimeExtras();
  const hasFallback = arguments.length >= 2;
  if (extras == null) {
    if (hasFallback) {
      return fallback;
    }
    throw new Error('The current thread is not backed by the useTrueForgeAgentRuntime runtime.');
  }
  return select != null ? select(extras) : extras;
}

/**
 * Brand + provide/tryGet from assistant-ui; get/use walk ancestor AUI clients so
 * nested readonly sub-agent threads still resolve root TrueForge extras.
 */
export const trueForgeExtras = {
  provide: extrasBrand.provide,
  is: extrasBrand.is,
  tryGet: extrasBrand.tryGet,
  get: getTrueForgeExtras,
  use: useTrueForgeExtrasApi,
};