Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

19.6 KB
Raw Blame
import type { AttachmentPart } from '@inkeep/open-knowledge-core/acp/thread-protocol';
import {
  type AssembleHandoffPromptInput,
  assembleHandoffPrompt,
  type ComposeSelection,
  type CreateScenario,
  composeAskPrompt,
  composeCreatePrompt,
  composeEmptySpacePrompt,
  composeFilePrompt,
  composeFolderPrompt,
  composeSelectionPrompt,
  composeSkillPrompt,
  composeTerminalBareLaunchPrompt,
  composeThreadBareLaunchPrompt,
  type DocContext,
  type HandoffOutcome,
  type HandoffPayload,
  type HandoffScope,
  type HandoffTarget,
  type InstallState,
  OK_TERMINAL_SURFACE_PREAMBLE,
  OK_THREAD_SURFACE_PREAMBLE,
  type PromptTransport,
  type TargetData,
  TERMINAL_CLIS,
  type TerminalCli,
  withSkillPointer,
} from '@inkeep/open-knowledge-core/handoff';
import type { SkillScope } from '@inkeep/open-knowledge-core/schemas/api';
import { t } from '@lingui/core/macro';
import { toast as sonnerToast } from 'sonner';
import { useConfigContext } from '@/lib/config-context';
import {
  type EnsureCoworkSkillOutcome,
  ensureCoworkSkillInstalledWithDefaults,
  reinstallCoworkSkill,
} from '@/lib/handoff/cowork-skill-install';
import { dispatchHandoff as defaultDispatchHandoff } from '@/lib/handoff/dispatch';
import { openExternal as defaultOpenExternal } from '@/lib/handoff/open-external';
import { KNOWN_TARGETS } from '@/lib/handoff/targets';
import {
  recordHandoff as defaultRecordHandoff,
  type HandoffHost,
  type HandoffStatsLine,
} from '@/lib/handoff/telemetry';
import { docNameToRelativePath, joinWorkspacePath, type Workspace } from '@/lib/workspace-paths';
import { useExternalHandoffGate } from './ExternalHandoffGate';
import { requestAgentThreadLaunch } from './thread-launch-events';
import '@/lib/desktop-bridge-types';

interface SelectionContext {
  readonly relativePath: string;
  readonly instruction: string;
  readonly selectionMarkdown: string;
}

interface AskContext {
  readonly relativePath: string;
  readonly instruction: string;
}

type ComposeContext =
  | {
      readonly scope: 'doc';
      readonly docRelativePath: string;
      readonly selection?: ComposeSelection;
      readonly instruction: string;
      readonly mentions: readonly string[];
    }
  | {
      readonly scope: 'folder';
      readonly folderRelativePath: string;
      readonly instruction: string;
      readonly mentions: readonly string[];
    }
  | {
      readonly scope: 'project';
      readonly instruction: string;
      readonly mentions: readonly string[];
    };

export interface HandoffDispatchInput {
  readonly docContext: DocContext | null;
  readonly folderRelativePath?: string;
  readonly selection?: SelectionContext;
  readonly skill?: { readonly name: string; readonly scope: SkillScope };
  readonly ask?: AskContext;
  readonly compose?: ComposeContext;
  readonly createDescription?: string;
  readonly createScenario?: CreateScenario;
  readonly createMentions?: readonly string[];
  readonly instruction?: string;
  readonly attachments?: readonly AttachmentPart[];
  readonly projectDir: string;
  readonly docPath: string;
}

export function buildHandoffInput(args: {
  readonly docName: string | null;
  readonly workspace: Workspace | null;
}): HandoffDispatchInput | null {
  if (!args.docName || !args.workspace) return null;
  const relativePath = docNameToRelativePath(args.docName);
  const { contentDir, pathSeparator } = args.workspace;
  return {
    docContext: { relativePath },
    projectDir: contentDir,
    docPath: joinWorkspacePath(contentDir, relativePath, pathSeparator),
  };
}

export function buildProjectScopedHandoffInput(args: {
  readonly workspace: Workspace | null;
}): HandoffDispatchInput | null {
  if (!args.workspace?.contentDir) return null;
  return {
    docContext: null,
    projectDir: args.workspace.contentDir,
    docPath: '',
  };
}

export function buildCreateHandoffInput(args: {
  readonly workspace: Workspace | null;
  readonly description: string;
  readonly scenario: CreateScenario;
  readonly mentions: readonly string[];
  readonly attachments?: readonly AttachmentPart[];
}): HandoffDispatchInput | null {
  if (!args.workspace?.contentDir) return null;
  return {
    docContext: null,
    createDescription: args.description,
    createScenario: args.scenario,
    createMentions: args.mentions,
    ...(args.attachments !== undefined && args.attachments.length > 0
      ? { attachments: args.attachments }
      : {}),
    projectDir: args.workspace.contentDir,
    docPath: '',
  };
}

export function openInstallUrl(target: TargetData): Promise<void> {
  return defaultOpenExternal(target.installUrl).then(() => undefined);
}

export function buildFolderHandoffInput(args: {
  readonly folderRelativePath: string;
  readonly workspace: Workspace | null;
}): HandoffDispatchInput | null {
  if (!args.workspace?.contentDir) return null;
  if (!args.folderRelativePath) return null;
  return {
    docContext: null,
    folderRelativePath: args.folderRelativePath,
    projectDir: args.workspace.contentDir,
    docPath: '',
  };
}

export function buildSelectionHandoffInput(args: {
  readonly docName: string | null;
  readonly workspace: Workspace | null;
  readonly instruction: string;
  readonly selectionMarkdown: string;
}): HandoffDispatchInput | null {
  if (!args.docName || !args.workspace) return null;
  if (!args.selectionMarkdown) return null;
  const relativePath = docNameToRelativePath(args.docName);
  const { contentDir, pathSeparator } = args.workspace;
  return {
    docContext: null,
    selection: {
      relativePath,
      instruction: args.instruction,
      selectionMarkdown: args.selectionMarkdown,
    },
    projectDir: contentDir,
    docPath: joinWorkspacePath(contentDir, relativePath, pathSeparator),
  };
}

export function buildSkillHandoffInput(args: {
  readonly skillName: string;
  readonly scope: SkillScope;
  readonly workspace: Workspace | null;
}): HandoffDispatchInput | null {
  if (!args.workspace?.contentDir || !args.skillName) return null;
  return {
    docContext: null,
    skill: { name: args.skillName, scope: args.scope },
    projectDir: args.workspace.contentDir,
    docPath: '',
  };
}

export function buildAskHandoffInput(args: {
  readonly docName: string | null;
  readonly workspace: Workspace | null;
  readonly instruction: string;
}): HandoffDispatchInput | null {
  if (!args.docName || !args.workspace) return null;
  const relativePath = docNameToRelativePath(args.docName);
  const { contentDir, pathSeparator } = args.workspace;
  return {
    docContext: null,
    ask: {
      relativePath,
      instruction: args.instruction,
    },
    projectDir: contentDir,
    docPath: joinWorkspacePath(contentDir, relativePath, pathSeparator),
  };
}

export function buildComposerHandoffInput(args: {
  readonly docName: string | null;
  readonly docRelativePath?: string;
  readonly folderRelativePath?: string;
  readonly workspace: Workspace | null;
  readonly instruction: string;
  readonly mentions: readonly string[];
  readonly selection?: ComposeSelection;
  readonly attachments?: readonly AttachmentPart[];
}): HandoffDispatchInput | null {
  if (!args.workspace?.contentDir) return null;
  const { contentDir, pathSeparator } = args.workspace;
  const attachmentsField =
    args.attachments !== undefined && args.attachments.length > 0
      ? { attachments: args.attachments }
      : {};
  if (args.docName) {
    const relativePath = args.docRelativePath ?? docNameToRelativePath(args.docName);
    const base = {
      scope: 'doc' as const,
      docRelativePath: relativePath,
      instruction: args.instruction,
      mentions: args.mentions,
    };
    const compose: ComposeContext =
      args.selection !== undefined ? { ...base, selection: args.selection } : base;
    return {
      docContext: null,
      compose,
      ...attachmentsField,
      projectDir: contentDir,
      docPath: joinWorkspacePath(contentDir, relativePath, pathSeparator),
    };
  }
  if (args.folderRelativePath) {
    return {
      docContext: null,
      compose: {
        scope: 'folder',
        folderRelativePath: args.folderRelativePath,
        instruction: args.instruction,
        mentions: args.mentions,
      },
      ...attachmentsField,
      projectDir: contentDir,
      docPath: '',
    };
  }
  return {
    docContext: null,
    compose: {
      scope: 'project',
      instruction: args.instruction,
      mentions: args.mentions,
    },
    ...attachmentsField,
    projectDir: contentDir,
    docPath: '',
  };
}

export function buildSelectionOrDocHandoffInput(args: {
  readonly docName: string | null;
  readonly workspace: Workspace | null;
  readonly instruction: string;
  readonly selectionMarkdown: string;
}): HandoffDispatchInput | null {
  return buildSelectionHandoffInput(args) ?? buildHandoffInput(args);
}

export interface ToastAction {
  readonly label: string;
  readonly onClick: () => void;
}

export interface ToastSurface {
  success(message: string): void;
  error(message: string, options?: { action?: ToastAction }): void;
}

export interface HandoffDispatchDeps {
  readonly dispatchHandoff: (payload: HandoffPayload) => Promise<HandoffOutcome>;
  readonly recordHandoff: (line: HandoffStatsLine) => Promise<void>;
  readonly toast: ToastSurface;
  readonly now: () => Date;
  readonly isElectronHost: () => boolean;
  readonly getDisplayName: (target: HandoffTarget) => string;
  readonly ensureCoworkSkillInstalled: () => Promise<EnsureCoworkSkillOutcome>;
  readonly autoOpen: boolean;
}

export const MAX_DISPATCH_ATTEMPTS = 3;

export function successToastMessage(displayName: string): string {
  return `Opened in ${displayName}.`;
}

export function errorToastMessage(displayName: string, attempt = 1): string {
  if (attempt >= MAX_DISPATCH_ATTEMPTS) {
    return t`Couldn't reach ${displayName} — please try again later.`;
  }
  if (attempt === MAX_DISPATCH_ATTEMPTS - 1) {
    return t`Still couldn't reach ${displayName} — try one more time?`;
  }
  return t`Couldn't reach ${displayName} — try again?`;
}

export function retryActionLabel(attempt: number): string | null {
  if (attempt >= MAX_DISPATCH_ATTEMPTS) return null;
  return attempt === MAX_DISPATCH_ATTEMPTS - 1 ? t`Try one more time` : t`Try again`;
}

function buildStatsLine(
  target: HandoffTarget,
  outcome: HandoffOutcome,
  host: HandoffHost,
  ts: string,
  scope: HandoffScope | undefined,
): HandoffStatsLine {
  const scopeField = scope === undefined ? {} : { scope };
  if (outcome.ok) {
    return { target, host, outcome: 'ok', ts, ...scopeField };
  }
  return { target, host, outcome: 'error', ts, reason: outcome.reason, ...scopeField };
}

function composeContextToAssembleInput(
  compose: ComposeContext,
  target: HandoffTarget,
  autoOpen: boolean,
  transport: PromptTransport,
): AssembleHandoffPromptInput {
  if (compose.scope === 'doc') {
    const base = {
      scope: 'doc' as const,
      docRelativePath: compose.docRelativePath,
      instruction: compose.instruction,
      mentions: compose.mentions,
      target,
      autoOpen,
      transport,
    };
    return compose.selection !== undefined ? { ...base, selection: compose.selection } : base;
  }
  if (compose.scope === 'folder') {
    return {
      scope: 'folder',
      folderRelativePath: compose.folderRelativePath,
      instruction: compose.instruction,
      mentions: compose.mentions,
      target,
      autoOpen,
      transport,
    };
  }
  return {
    scope: 'project',
    instruction: compose.instruction,
    mentions: compose.mentions,
    target,
    autoOpen,
    transport,
  };
}

export function selectScopedPrompt(
  input: HandoffDispatchInput,
  target: HandoffTarget,
  autoOpen: boolean,
  transport: PromptTransport,
): string {
  if (input.compose) {
    return assembleHandoffPrompt(
      composeContextToAssembleInput(input.compose, target, autoOpen, transport),
    );
  }
  if (input.selection) {
    return composeSelectionPrompt({ ...input.selection, target, transport });
  }
  if (input.skill) {
    return composeSkillPrompt(input.skill.name, input.skill.scope, autoOpen);
  }
  if (input.ask) {
    return composeAskPrompt(
      input.ask.relativePath,
      input.ask.instruction,
      autoOpen,
      target,
      transport,
    );
  }
  const directive =
    input.docContext !== null
      ? composeFilePrompt(input.docContext.relativePath, autoOpen, input.instruction, transport)
      : input.folderRelativePath
        ? composeFolderPrompt(input.folderRelativePath, autoOpen, input.instruction, transport)
        : input.createDescription !== undefined
          ? composeCreatePrompt(
              input.createDescription,
              autoOpen,
              input.createScenario ?? 'new-project',
              input.createMentions ?? [],
              transport,
            )
          : composeEmptySpacePrompt(autoOpen, input.instruction, transport);
  return withSkillPointer(directive);
}

export function composeTerminalLaunchPrompt(input: HandoffDispatchInput, cli: TerminalCli): string {
  const hasInstruction = typeof input.instruction === 'string' && input.instruction.trim() !== '';
  if (
    input.compose !== undefined ||
    input.createDescription !== undefined ||
    input.skill !== undefined ||
    hasInstruction
  ) {
    return `${OK_TERMINAL_SURFACE_PREAMBLE} ${selectScopedPrompt(input, TERMINAL_CLIS[cli].handoffTarget, false, 'terminal')}`;
  }
  return composeTerminalBareLaunchPrompt(input.docContext?.relativePath ?? null);
}

function composeThreadLaunchPrompt(input: HandoffDispatchInput): string {
  const hasInstruction = typeof input.instruction === 'string' && input.instruction.trim() !== '';
  if (
    input.compose !== undefined ||
    input.createDescription !== undefined ||
    input.skill !== undefined ||
    hasInstruction
  ) {
    return `${OK_THREAD_SURFACE_PREAMBLE} ${selectScopedPrompt(input, 'claude-code', false, 'terminal')}`;
  }
  return composeThreadBareLaunchPrompt(input.docContext?.relativePath ?? null);
}

function docNameFromInput(input: HandoffDispatchInput): string | null {
  const rel = input.docContext?.relativePath;
  if (typeof rel !== 'string' || rel === '') return null;
  return rel.replace(/\.(md|mdx)$/, '');
}

export function threadTitleHintFromInput(input: HandoffDispatchInput): string | null {
  const candidates = [
    input.compose?.instruction,
    input.selection?.instruction,
    input.ask?.instruction,
    input.createDescription,
    input.instruction,
  ];
  for (const candidate of candidates) {
    if (typeof candidate === 'string' && candidate.trim() !== '') return candidate;
  }
  return null;
}

export function startAgentThreadForInput(
  input: HandoffDispatchInput,
  opts?: {
    agent?: { source: 'registry' | 'custom'; id: string };
  },
): void {
  requestAgentThreadLaunch({
    agentSource: opts?.agent?.source ?? 'registry',
    agentId: opts?.agent?.id ?? '',
    prompt: composeThreadLaunchPrompt(input),
    docName: docNameFromInput(input),
    titleHint: threadTitleHintFromInput(input),
    attachments: input.attachments ?? null,
  });
}

export async function runHandoffDispatch(
  target: HandoffTarget,
  input: HandoffDispatchInput,
  deps: HandoffDispatchDeps,
  attempt = 1,
  retryDispatch?: (nextAttempt: number) => Promise<HandoffOutcome>,
): Promise<HandoffOutcome> {
  if (target === 'claude-cowork' && attempt === 1) {
    let installOutcome: EnsureCoworkSkillOutcome;
    try {
      installOutcome = await deps.ensureCoworkSkillInstalled();
    } catch (err) {
      const message = err instanceof Error ? err.message : String(err);
      deps.toast.error(t`Couldn't install OpenKnowledge skill — ${message}`);
      return { ok: false, reason: 'dispatch-error', detail: `install-error: ${message}` };
    }
    if (installOutcome.kind === 'installed-now') {
      deps.toast.success(
        t`OpenKnowledge skill saved. Upload it in Claude Desktop, then click Cowork again.`,
      );
      return { ok: true };
    }
    if (installOutcome.kind === 'install-failed') {
      const message = installOutcome.message ?? installOutcome.reason;
      deps.toast.error(t`Couldn't install OpenKnowledge skill — ${message}`);
      return { ok: false, reason: 'dispatch-error', detail: `install-failed: ${message}` };
    }
  }

  const payload: HandoffPayload = {
    target,
    projectDir: input.projectDir,
    docPath: input.docPath,
    prompt: selectScopedPrompt(input, target, deps.autoOpen, 'url'),
  };

  const outcome = await deps.dispatchHandoff(payload);

  const host: HandoffHost = deps.isElectronHost() ? 'electron' : 'web';
  const ts = deps.now().toISOString();
  const compose = input.compose;
  const shipsSelection =
    input.selection != null || (compose?.scope === 'doc' && compose.selection !== undefined);
  const line = buildStatsLine(target, outcome, host, ts, shipsSelection ? 'selection' : undefined);
  await deps.recordHandoff(line);

  const displayName = deps.getDisplayName(target);
  if (outcome.ok) {
    deps.toast.success(successToastMessage(displayName));
  } else {
    const label = retryActionLabel(attempt);
    const message = errorToastMessage(displayName, attempt);
    if (label !== null) {
      deps.toast.error(message, {
        action: {
          label,
          onClick: () => {
            void (
              retryDispatch?.(attempt + 1) ?? runHandoffDispatch(target, input, deps, attempt + 1)
            ).then((retryOutcome) => {
              if (!retryOutcome.ok && retryOutcome.reason === 'superseded') {
                deps.toast.error(t`A newer handoff replaced this retry.`);
              }
            });
          },
        },
      });
    } else {
      deps.toast.error(message);
    }
  }

  return outcome;
}

export function getDisplayNameDefault(target: HandoffTarget): string {
  const entry = KNOWN_TARGETS.find((t) => t.id === target);
  return entry?.displayName ?? target;
}

export function isElectronHostDefault(
  windowLike: { okDesktop?: unknown } | undefined = typeof window !== 'undefined'
    ? window
    : undefined,
): boolean {
  return windowLike?.okDesktop != null;
}

export function defaultHandoffDispatchDeps(): HandoffDispatchDeps {
  return {
    dispatchHandoff: defaultDispatchHandoff,
    recordHandoff: defaultRecordHandoff,
    toast: {
      success: (message: string) => {
        sonnerToast.success(message);
      },
      error: (message: string, options?: { action?: ToastAction }) => {
        sonnerToast.error(message, options ? { action: options.action } : undefined);
      },
    },
    now: () => new Date(),
    isElectronHost: () => isElectronHostDefault(),
    getDisplayName: getDisplayNameDefault,
    ensureCoworkSkillInstalled: ensureCoworkSkillInstalledWithDefaults,
    autoOpen: true,
  };
}

interface UseHandoffDispatchResult {
  dispatch: (
    target: HandoffTarget,
    input: HandoffDispatchInput,
    options: HandoffDispatchOptions,
  ) => Promise<HandoffOutcome>;
  reinstallCoworkSkill: () => Promise<EnsureCoworkSkillOutcome>;
}

export interface HandoffDispatchOptions {
  readonly installState: InstallState;
  readonly restoreFocus?: () => void;
}

export function useHandoffDispatch(): UseHandoffDispatchResult {
  const { merged } = useConfigContext();
  const gate = useExternalHandoffGate();
  const autoOpen = merged?.appearance?.preview?.autoOpen ?? true;
  const dispatchAttempt = (
    target: HandoffTarget,
    input: HandoffDispatchInput,
    attempt: number,
    options: HandoffDispatchOptions,
  ): Promise<HandoffOutcome> =>
    gate.dispatch(
      target,
      () =>
        runHandoffDispatch(
          target,
          input,
          { ...defaultHandoffDispatchDeps(), autoOpen },
          attempt,
          (nextAttempt) => dispatchAttempt(target, input, nextAttempt, options),
        ),
      { ...options, projectDir: input.projectDir },
    );
  return {
    dispatch: (target, input, options) => dispatchAttempt(target, input, 1, options),
    reinstallCoworkSkill,
  };
}