@powerhousedao/reactor-browser 6.2.2-dev.8 → 6.2.2-dev.81

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

@@ -0,0 +1,369 @@
+import { PhAiToolAnnotations, PhAiToolDescriptor } from "@powerhousedao/shared/document-model";
+import { ISyncManager } from "@powerhousedao/reactor";
+import * as react_jsx_runtime0 from "react/jsx-runtime";
+import { LanguageModel, ModelMessage } from "ai";
+
+//#region src/ai/types.d.ts
+/**
+ * Browser-side AI chat over the reactor.
+ *
+ * The chat agent is tool-agnostic: consumers (e.g. Connect) pass a lazy
+ * provider of {@link AiToolDescriptor}s. The descriptors mirror the
+ * provider-agnostic tool core in `@powerhousedao/reactor-mcp/tools`, so the
+ * same tool definitions drive both the MCP server and the in-browser chat.
+ */
+/** User-configured LLM connection settings, persisted in localStorage. */
+interface AiSettings {
+  /** Master on/off for the in-browser assistant. Off by default. */
+  enabled: boolean;
+  /** OpenAI-compatible base URL, e.g. `https://api.openai.com/v1` */
+  baseUrl: string;
+  /** API key. Sent only to the configured endpoint, never to Powerhouse. */
+  apiKey: string;
+  /** Model id the endpoint serves, e.g. `gpt-4o-mini`. */
+  model: string;
+  /**
+   * When false (default), write tools render an approval card and pause the
+   * agent loop until the user approves or rejects the action.
+   */
+  autoApproveWrites: boolean;
+}
+/** MCP-compatible annotation hints; structural, no MCP SDK dependency. */
+type AiToolAnnotations = PhAiToolAnnotations;
+/**
+ * Provider-agnostic tool descriptor accepted by the chat agent.
+ *
+ * Structurally compatible with the MCP tool records produced by
+ * `createReactorMcpProvider`: the callback parameter is `never` so any
+ * per-tool-args function type is assignable, and the result is `unknown`
+ * because the envelope shape (MCP `CallToolResult`) is unwrapped at the
+ * adapter boundary.
+ */
+type AiToolDescriptor = PhAiToolDescriptor;
+/** Tool descriptors the app resolves when the user sends a message. */
+type AiToolsProvider = () => Promise<AiToolDescriptor[]>;
+/** Tool names whose execution mutates the reactor and requires approval. */
+declare const WRITE_TOOLS: ReadonlySet<string>;
+/**
+ * Whether executing the tool mutates state and requires user approval:
+ * the built-in write tools, or any tool flagged destructive in its
+ * annotations (covers package-provided tools outside the built-in set).
+ */
+declare function isWriteTool(name: string, annotations?: AiToolAnnotations): boolean;
+type ToolCallState = "awaiting-approval" | "executing" | "done" | "error" | "rejected";
+/** One rendered unit inside a chat message. */
+type ChatPart = {
+  type: "text";
+  text: string;
+} | {
+  type: "tool";
+  toolCallId: string;
+  name: string;
+  args: unknown;
+  state: ToolCallState;
+  result?: unknown;
+  error?: string;
+};
+interface ChatMessage {
+  id: string;
+  role: "user" | "assistant";
+  parts: ChatPart[];
+}
+/** A write tool call the user must approve or reject. */
+interface PendingApproval {
+  toolCallId: string;
+  name: string;
+  args: unknown;
+}
+/** Context snapshot injected into the agent system prompt. */
+interface ChatContext {
+  driveId?: string;
+  driveName?: string;
+  nodeId?: string;
+  nodeName?: string;
+  nodeKind?: "file" | "folder";
+  documentType?: string;
+  documentName?: string;
+  documentId?: string;
+  switchboardUrl?: string;
+  switchboardGraphqlUrl?: string;
+}
+/** Events the agent emits while running a turn. */
+type AgentEvent = {
+  type: "text-delta";
+  delta: string;
+} | {
+  type: "tool-start";
+  toolCallId: string;
+  name: string;
+  args: unknown;
+} | {
+  type: "approval-request";
+  toolCallId: string;
+  name: string;
+  args: unknown;
+} | {
+  type: "approval-resolved";
+  toolCallId: string;
+  approved: boolean;
+} | {
+  type: "tool-result";
+  toolCallId: string;
+  name: string;
+  state: "done" | "error" | "rejected";
+  result?: unknown;
+  error?: string;
+}
+/**
+ * Token accounting for the turn: the input tokens of the model's last
+ * step (i.e. the size of the context it was reasoning over).
+ */
+| {
+  type: "usage";
+  inputTokens: number;
+} | {
+  type: "finish";
+} | {
+  type: "error";
+  error: string;
+};
+//#endregion
+//#region src/ai/agent.d.ts
+/** Hard cap on model round-trips per user message (each tool step counts). */
+declare const MAX_AGENT_STEPS = 10;
+/**
+ * Hard cap on the characters of one tool result fed back to the model.
+ *
+ * Large results (whole document states, catalog listings, schema
+ * summaries) accumulate across steps because every step resends the whole
+ * conversation; without a budget a few broad queries exhaust the model's
+ * context and stall the turn. Over-budget results are truncated with a
+ * marker so the model re-queries more narrowly.
+ */
+declare const MAX_TOOL_RESULT_CHARS = 12000;
+/**
+ * Number of the most recent turns whose tool results are kept in full in
+ * the committed history. Tool results are re-derivable (the store is the
+ * source of truth), so results older than that window are replaced with
+ * one-line stubs: this is what keeps a long conversation from exhausting
+ * the model's context.
+ */
+declare const FULL_RESULT_TURNS = 2;
+/** Tool results smaller than this are cheap to keep and are never stubbed. */
+declare const STUB_MIN_CHARS = 500;
+/**
+ * Replaces tool results older than the last {@link FULL_RESULT_TURNS}
+ * turns with one-line stubs naming the tool and its arguments. User and
+ * assistant messages are never touched, and tool calls keep their input,
+ * so the model can re-query any stubbed result with the same arguments.
+ * Idempotent: stubs are below {@link STUB_MIN_CHARS} and pass through.
+ */
+declare function stubStaleToolResults(history: ModelMessage[]): ModelMessage[];
+declare function createReactorChatModel(settings: AiSettings): LanguageModel;
+/**
+ * Unwraps the MCP `CallToolResult` envelope produced by the reactor tool
+ * core into a plain value for the AI SDK. Throws for error results so the
+ * SDK surfaces them as tool errors in the next model step.
+ */
+declare function unwrapToolResult(raw: unknown): unknown;
+/** Builds the system prompt, grounding the agent in the current selection. */
+declare function buildSystemPrompt(context: ChatContext): string;
+interface ReactorChatAgentOptions {
+  settings: AiSettings;
+  tools: AiToolDescriptor[];
+  context: ChatContext;
+  onEvent: (event: AgentEvent) => void;
+  signal?: AbortSignal;
+  /** Test seam: override the model (e.g. a mock language model). */
+  model?: LanguageModel;
+  /** Prior conversation to continue (see {@link ReactorChatAgent.getHistory}). */
+  history?: ModelMessage[];
+}
+/**
+ * Runs one tool-loop conversation turn against an OpenAI-compatible model.
+ *
+ * The agent keeps the model message history across turns. Write tools are
+ * gated by the AI SDK's tool approval: when auto-approval is off, the
+ * pending user decision is bridged through {@link approve}/{@link reject}.
+ */
+declare class ReactorChatAgent {
+  private readonly options;
+  private history;
+  private approvals;
+  constructor(options: ReactorChatAgentOptions);
+  /** The model history after the last completed turn, for the next agent. */
+  getHistory(): ModelMessage[];
+  /** Clears the conversation history (a fresh chat). */
+  reset(): void;
+  /** Approves a pending write tool call, resuming the agent loop. */
+  approve(toolCallId: string): void;
+  /** Rejects a pending write tool call; the rejection is fed to the model. */
+  reject(toolCallId: string): void;
+  private resolveApproval;
+  private cancelPendingApprovals;
+  /** Runs one user turn: appends the message, streams the model, commits history. */
+  send(text: string): Promise<void>;
+  /**
+   * Removes tool calls that were never executed (step cap or abort):
+   * OpenAI-compatible APIs reject a tool call without its tool result.
+   */
+  private dropUnresolvedToolCalls;
+  private handleStreamPart;
+}
+//#endregion
+//#region src/ai/components/approval-card.d.ts
+/**
+ * In-chat approval card for a write tool call. Approving or rejecting
+ * resolves the pending approval inside the agent loop.
+ */
+declare function ApprovalCard({
+  approval,
+  onApprove,
+  onReject
+}: {
+  approval: PendingApproval;
+  onApprove: (toolCallId: string) => void;
+  onReject: (toolCallId: string) => void;
+}): react_jsx_runtime0.JSX.Element;
+//#endregion
+//#region src/ai/use-reactor-chat.d.ts
+interface UseReactorChatResult {
+  messages: ChatMessage[];
+  isStreaming: boolean;
+  pendingApprovals: PendingApproval[];
+  error: string | null;
+  settings: AiSettings;
+  configured: boolean;
+  send: (text: string) => void;
+  stop: () => void;
+  approve: (toolCallId: string) => void;
+  reject: (toolCallId: string) => void;
+  clear: () => void;
+}
+/**
+ * Drives one in-browser chat conversation against the reactor tools.
+ *
+ * `toolsProvider` lazily resolves the tool descriptors (e.g. from
+ * `createReactorMcpProvider` bound to `window.ph.reactorClient`) when the
+ * user sends a message, so the reactor does not need to be ready at render
+ * time.
+ */
+declare function useReactorChat(toolsProvider?: AiToolsProvider): UseReactorChatResult;
+//#endregion
+//#region src/ai/components/chat-window.d.ts
+/** The chat window panel, anchored above the FAB in the bottom-right. */
+declare function ChatWindow({
+  chat,
+  onClose
+}: {
+  chat: UseReactorChatResult;
+  onClose: () => void;
+}): react_jsx_runtime0.JSX.Element;
+//#endregion
+//#region src/ai/components/reactor-chat-fab.d.ts
+/**
+ * Bottom-right floating action button that opens the reactor AI chat window.
+ *
+ * `getTools` lazily resolves the reactor tool descriptors (from
+ * `createReactorMcpProvider` bound to the browser reactor client) when the
+ * user sends a message.
+ */
+declare function ReactorChatFab({
+  getTools
+}: {
+  getTools?: AiToolsProvider;
+}): react_jsx_runtime0.JSX.Element | null;
+//#endregion
+//#region src/ai/context.d.ts
+/**
+ * Snapshot of the current selection in the drive explorer, used to make the
+ * chat context-aware: "create a budget here" targets the selected drive,
+ * "summarize this document" targets the selected document.
+ */
+declare function useChatContext(): ChatContext;
+//#endregion
+//#region src/ai/settings-store.d.ts
+declare const DEFAULT_AI_SETTINGS: AiSettings;
+type Listener = () => void;
+/** Returns the current settings (stable snapshot for useSyncExternalStore). */
+declare function getAiSettings(): AiSettings;
+/** Merges a partial update, persists, and notifies subscribers. */
+declare function updateAiSettings(patch: Partial<AiSettings>): AiSettings;
+/** Clears all stored settings. */
+declare function clearAiSettings(): void;
+/** Subscribes to settings changes. Returns the unsubscribe function. */
+declare function subscribeAiSettings(listener: Listener): () => void;
+/** True when the endpoint, key and model are all configured. */
+declare function isAiConfigured(settings: AiSettings): boolean;
+//#endregion
+//#region src/ai/switchboard.d.ts
+/**
+ * The switchboard serving a remote drive: the base URL the browser talks to
+ * and its GraphQL supergraph endpoint.
+ */
+interface DriveSwitchboard {
+  /** Switchboard base URL (e.g. `http://localhost:4001`). */
+  switchboardUrl: string;
+  /** GraphQL supergraph endpoint (`<base>/graphql`). */
+  graphqlUrl: string;
+}
+/**
+ * Reads the tab-side sync manager from the browser global. Returns
+ * `undefined` in non-browser environments or before the reactor client
+ * module is initialized.
+ */
+declare function getBrowserSyncManager(): ISyncManager | undefined;
+/**
+ * Resolves the switchboard that serves a drive, if any.
+ *
+ * Every remote drive stores its switchboard's exact GraphQL channel
+ * endpoint in its sync remote — `channelConfig = { type: "gql",
+ * parameters: { url: "<origin>/graphql/r" } }` — and the switchboard base
+ * is that URL minus the `/graphql/r` suffix. Deriving it per drive (rather
+ * than from a global setting) is what keeps multi-switchboard deployments
+ * correct. Drives that are not synced to a remote switchboard (local
+ * drives, other channel types, unexpected shapes) return `undefined`.
+ */
+declare function resolveDriveSwitchboard(driveId: string | undefined, syncManager?: ISyncManager): DriveSwitchboard | undefined;
+/**
+ * Introspection over the switchboard supergraph's root query and mutation
+ * fields. Types are requested with three levels of `ofType` nesting so
+ * that common shapes like `[X!]!` (LIST(NON_NULL(LIST(X)))) render fully.
+ */
+declare const SWITCHBOARD_INTROSPECTION_QUERY: string;
+/** One root query or mutation field, reduced to a prompt-friendly line. */
+type SchemaFieldSummary = {
+  name: string;
+  description?: string;
+  args: string;
+  returns: string;
+};
+/**
+ * Reduces a GraphQL `__schema` introspection payload (the `data.__schema`
+ * object) to a compact summary of its root query and mutation fields.
+ * Accepts `unknown` because the payload arrives over the wire.
+ */
+declare function summarizeIntrospectionSchema(schema: unknown): {
+  queries: SchemaFieldSummary[];
+  mutations: SchemaFieldSummary[];
+  truncated: boolean;
+};
+declare const SWITCHBOARD_SCHEMA_TOOL_NAME = "getSwitchboardSchema";
+/** Test seams for {@link createSwitchboardSchemaTool}. */
+interface SwitchboardToolDeps {
+  getSyncManager?: () => ISyncManager | undefined;
+  getSelectedDriveId?: () => string | undefined;
+  tokenProvider?: () => Promise<string | undefined>;
+  fetchImpl?: typeof fetch;
+  timeoutMs?: number;
+}
+/**
+ * Creates the read-only `getSwitchboardSchema` tool: it introspects the
+ * GraphQL supergraph of the switchboard serving a drive and returns a
+ * summary of its root queries and mutations. It reads the schema only and
+ * never modifies data.
+ */
+declare function createSwitchboardSchemaTool(deps?: SwitchboardToolDeps): AiToolDescriptor;
+//#endregion
+export { AgentEvent, AiSettings, AiToolAnnotations, AiToolDescriptor, AiToolsProvider, ApprovalCard, ChatContext, ChatMessage, ChatPart, ChatWindow, DEFAULT_AI_SETTINGS, DriveSwitchboard, FULL_RESULT_TURNS, MAX_AGENT_STEPS, MAX_TOOL_RESULT_CHARS, PendingApproval, ReactorChatAgent, ReactorChatAgentOptions, ReactorChatFab, STUB_MIN_CHARS, SWITCHBOARD_INTROSPECTION_QUERY, SWITCHBOARD_SCHEMA_TOOL_NAME, SchemaFieldSummary, SwitchboardToolDeps, ToolCallState, UseReactorChatResult, WRITE_TOOLS, buildSystemPrompt, clearAiSettings, createReactorChatModel, createSwitchboardSchemaTool, getAiSettings, getBrowserSyncManager, isAiConfigured, isWriteTool, resolveDriveSwitchboard, stubStaleToolResults, subscribeAiSettings, summarizeIntrospectionSchema, unwrapToolResult, updateAiSettings, useChatContext, useReactorChat };
+//# sourceMappingURL=index.d.ts.map

package/dist/src/ai/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","names":[],"sources":["../../../src/ai/types.ts","../../../src/ai/agent.ts","../../../src/ai/components/approval-card.tsx","../../../src/ai/use-reactor-chat.ts","../../../src/ai/components/chat-window.tsx","../../../src/ai/components/reactor-chat-fab.tsx","../../../src/ai/context.ts","../../../src/ai/settings-store.ts","../../../src/ai/switchboard.ts"],"mappings":"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"}