nolo-cli 0.1.23 → 0.1.29

package/server/handlers/agentRun/machineConnector.ts

@@ -0,0 +1,235 @@
+import type { ChatMessage } from "./types";
+import { resolveMachineRunPermissionPolicy } from "../../../ai/agent/machineRunPermissions";
+import {
+  connectorConnectionRegistry,
+  type ConnectorAgentRunResult,
+  type ConnectorAgentRunOptions,
+  type ConnectorAgentRunProgress,
+} from "../connector/connectorConnectionRegistry";
+import {
+  buildMachineAuditInputPreview,
+  classifyMachineAuditFailure,
+  recordMachineAgentAudit,
+  type MachineAgentAuditEvent,
+} from "./machineRunAudit";
+
+type MachineConnectorRegistry = Pick<
+  typeof connectorConnectionRegistry,
+  "hasConnection" | "sendAgentRun"
+>;
+
+export type MachineConnectorRunProgress = ConnectorAgentRunProgress;
+
+type MachineAuditRecorder = (event: MachineAgentAuditEvent) => Promise<unknown>;
+
+function omitUndefined<T extends Record<string, unknown>>(record: T): Partial<T> {
+  return Object.fromEntries(
+    Object.entries(record).filter(([, value]) => value !== undefined)
+  ) as Partial<T>;
+}
+
+export function resolveAgentMachineCapabilities(agentConfig: any): string[] {
+  if (agentConfig?.apiSource !== "cli") return [];
+  const cliProvider = String(agentConfig?.cliProvider ?? "").trim();
+  const capabilityByProvider: Record<string, string> = {
+    codex: "codex-cli",
+    claude: "claude-code",
+    copilot: "copilot-cli",
+    gemini: "gemini-cli",
+    kimi: "kimi-cli",
+    agy: "agy-cli",
+  };
+  const capability = capabilityByProvider[cliProvider];
+  return capability ? [capability] : [];
+}
+
+export function resolveAgentRuntimeMachineId(agentConfig: any): string {
+  return String(agentConfig?.runtimeBinding?.machineId ?? "").trim();
+}
+
+export function shouldUseMachineConnector(agentConfig: any): boolean {
+  return agentConfig?.apiSource === "cli" && !!resolveAgentRuntimeMachineId(agentConfig);
+}
+
+function isRecord(value: unknown): value is Record<string, any> {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+
+function hasConfiguredMachinePermissions(agentConfig: any) {
+  const runtimeBinding = isRecord(agentConfig?.runtimeBinding) ? agentConfig.runtimeBinding : {};
+  return Boolean(
+    isRecord(agentConfig?.machinePermissions) ||
+      isRecord(runtimeBinding.permissions) ||
+      isRecord(runtimeBinding.machinePermissions) ||
+      isRecord(agentConfig?.boundRuntimeMachine?.permissions)
+  );
+}
+
+function shouldUseWorkspaceMachineRuntime(args: {
+  agentConfig: any;
+  runtimeToolPolicySnapshot?: unknown;
+}) {
+  if (!resolveAgentRuntimeMachineId(args.agentConfig)) return false;
+  const policy = args.runtimeToolPolicySnapshot && typeof args.runtimeToolPolicySnapshot === "object"
+    ? args.runtimeToolPolicySnapshot as any
+    : args.agentConfig?.runtimeToolPolicy;
+  const runtimeTools = Array.isArray(policy?.runtimeTools) ? policy.runtimeTools : [];
+  const workspaceMode = policy?.workspace?.mode;
+  return runtimeTools.some((tool: unknown) => tool === "execShell") ||
+    workspaceMode === "task-worktree" ||
+    workspaceMode === "lease";
+}
+
+export function resolveAgentRuntimeMachineRoute(
+  agentConfig: any,
+  fallbackUserId: string
+): { machineId: string; ownerUserId: string } {
+  const machineId = resolveAgentRuntimeMachineId(agentConfig);
+  const ownerUserId = String(agentConfig?.runtimeBinding?.ownerUserId ?? "").trim() || fallbackUserId;
+  return { machineId, ownerUserId };
+}
+
+export class ConnectorOfflineError extends Error {
+  readonly machineId: string;
+
+  constructor(machineId: string) {
+    super(
+      `Bound machine ${machineId} is online, but no live connector is attached. Run \`nolo connect --ws\` on that computer.`
+    );
+    this.machineId = machineId;
+  }
+}
+
+export async function runViaMachineConnector(args: {
+  agentConfig: any;
+  agentKey: string;
+  category?: string;
+  continueDialogId?: string;
+  messages: ChatMessage[];
+  runtimeContext: unknown;
+  spaceId?: string;
+  userId: string;
+  userInput: string;
+  requestTimeoutMs?: number;
+  runtimeToolPolicySnapshot?: unknown;
+  runtimePromptPage?: unknown;
+  auditRecorder?: MachineAuditRecorder;
+  connectorRegistry?: MachineConnectorRegistry;
+  onProgress?: (progress: ConnectorAgentRunProgress) => void | Promise<void>;
+}): Promise<ConnectorAgentRunResult | null> {
+  // Machine connector is an explicit runtime for CLI/local-model agents.
+  // Platform agents may still carry historical runtimeBinding metadata, but
+  // they must use the server-side model/tool loop instead of machine presence.
+  // Future user-hosted local models should attach through this connector as a
+  // separate runtime capability, not by changing platform agent availability.
+  if (!shouldUseMachineConnector(args.agentConfig) && !shouldUseWorkspaceMachineRuntime(args)) {
+    return null;
+  }
+
+  const { machineId, ownerUserId } = resolveAgentRuntimeMachineRoute(args.agentConfig, args.userId);
+  if (!machineId) return null;
+
+  const connectorRegistry = args.connectorRegistry ?? connectorConnectionRegistry;
+  if (!connectorRegistry.hasConnection(ownerUserId, machineId)) {
+    throw new ConnectorOfflineError(machineId);
+  }
+
+  const machinePermissions = resolveMachineRunPermissionPolicy(args.agentConfig);
+  const auditRecorder = args.auditRecorder ?? recordMachineAgentAudit;
+  const auditBase = {
+    userId: args.userId,
+    machineId,
+    agentKey: args.agentKey,
+    cliProvider: typeof args.agentConfig?.cliProvider === "string" ? args.agentConfig.cliProvider : null,
+    permissionMode: machinePermissions.mode,
+    inputPreview: buildMachineAuditInputPreview(args.userInput),
+    inputLength: args.userInput.length,
+  };
+
+  try {
+    await auditRecorder({
+      ...auditBase,
+      eventType: "agent_run_dispatched",
+      status: "accepted",
+    });
+  } catch (error) {
+    console.warn("[machine-agent-audit] dispatch audit failed", error);
+  }
+
+  try {
+    const effectiveRuntimeToolPolicy =
+      args.runtimeToolPolicySnapshot ?? args.agentConfig?.runtimeToolPolicy;
+    const connectorPayload = {
+      agentKey: args.agentKey,
+      userInput: args.userInput,
+      ...(typeof args.requestTimeoutMs === "number" &&
+      Number.isFinite(args.requestTimeoutMs) &&
+      args.requestTimeoutMs > 0
+        ? { timeoutMs: args.requestTimeoutMs }
+        : {}),
+      agentConfig: omitUndefined({
+        apiSource: args.agentConfig?.apiSource,
+        provider: args.agentConfig?.provider,
+        cliProvider: args.agentConfig?.cliProvider,
+        model: args.agentConfig?.model,
+        prompt: args.agentConfig?.prompt,
+        customProviderUrl: args.agentConfig?.customProviderUrl,
+        tools: args.agentConfig?.tools,
+        toolNames: args.agentConfig?.toolNames,
+        runtimeBinding: args.agentConfig?.runtimeBinding,
+        localWorkspaceMode: args.agentConfig?.localWorkspaceMode,
+        temperature: args.agentConfig?.temperature,
+        top_p: args.agentConfig?.top_p,
+        frequency_penalty: args.agentConfig?.frequency_penalty,
+        presence_penalty: args.agentConfig?.presence_penalty,
+        max_tokens: args.agentConfig?.max_tokens,
+        reasoning_effort: args.agentConfig?.reasoning_effort,
+        ...(hasConfiguredMachinePermissions(args.agentConfig)
+          ? { machinePermissions }
+          : {}),
+        ...(effectiveRuntimeToolPolicy
+          ? { runtimeToolPolicy: effectiveRuntimeToolPolicy }
+          : {}),
+      }),
+      messages: args.messages,
+      runtimeContext: args.runtimeContext,
+      spaceId: args.spaceId,
+      category: args.category,
+      continueDialogId: args.continueDialogId,
+      meta: {
+        source: "agent.run",
+        machineId,
+        machinePermissions,
+        ...(args.runtimePromptPage
+          ? { runtimePromptPage: args.runtimePromptPage }
+          : {}),
+        ...(effectiveRuntimeToolPolicy
+          ? { runtimeToolPolicySnapshot: effectiveRuntimeToolPolicy }
+          : {}),
+      },
+    };
+    const connectorOptions: ConnectorAgentRunOptions = {
+      ...(typeof args.requestTimeoutMs === "number" &&
+      Number.isFinite(args.requestTimeoutMs) &&
+      args.requestTimeoutMs > 0
+        ? { requestTimeoutMs: args.requestTimeoutMs }
+        : {}),
+      ...(args.onProgress ? { onProgress: args.onProgress } : {}),
+    };
+    return await (Object.keys(connectorOptions).length > 0
+      ? connectorRegistry.sendAgentRun(ownerUserId, machineId, connectorPayload, connectorOptions)
+      : connectorRegistry.sendAgentRun(ownerUserId, machineId, connectorPayload));
+  } catch (error) {
+    try {
+      await auditRecorder({
+        ...auditBase,
+        eventType: "agent_run_failed",
+        status: classifyMachineAuditFailure(error),
+        errorMessage: error instanceof Error ? error.message : String(error),
+      });
+    } catch (auditError) {
+      console.warn("[machine-agent-audit] failure audit failed", auditError);
+    }
+    throw error;
+  }
+}

package/server/handlers/agentRun/machineRunAudit.ts

@@ -0,0 +1,49 @@
+export type MachineAgentAuditEventType =
+  | "agent_run_dispatched"
+  | "agent_run_failed";
+
+export type MachineAgentAuditStatus = "accepted" | "denied" | "failed";
+
+export type MachineAgentAuditEvent = {
+  eventType: MachineAgentAuditEventType;
+  userId: string;
+  machineId: string;
+  agentKey: string;
+  cliProvider?: string | null;
+  permissionMode?: string | null;
+  status: MachineAgentAuditStatus;
+  inputPreview?: string;
+  inputLength?: number;
+  errorMessage?: string;
+  createdAt?: number;
+};
+
+const MAX_PREVIEW_CHARS = 180;
+
+export function buildMachineAuditInputPreview(input: string, max = MAX_PREVIEW_CHARS) {
+  const normalized = input.replace(/\s+/g, " ").trim();
+  const compressed = normalized.replace(/(.)\1{11,}/g, (match, char) => `${char}[repeated ${match.length}]`);
+  if (compressed.length <= max) return compressed;
+  return `${compressed.slice(0, Math.max(0, max - 12)).trimEnd()} [truncated]`;
+}
+
+export function classifyMachineAuditFailure(error: unknown): MachineAgentAuditStatus {
+  const message = error instanceof Error ? error.message : String(error ?? "");
+  return /permission denied|not allowed|denied/i.test(message) ? "denied" : "failed";
+}
+
+export async function recordMachineAgentAudit(event: MachineAgentAuditEvent) {
+  const load = new Function("specifier", "return import(specifier)") as (
+    specifier: string
+  ) => Promise<any>;
+  const { default: serverDb } = await load("database/server/db");
+  const createdAt = event.createdAt ?? Date.now();
+  const id = crypto.randomUUID();
+  const key = `machine-agent-audit-${event.userId}-${createdAt}-${id}`;
+  await serverDb.put(key, {
+    ...event,
+    createdAt,
+    schemaVersion: 1,
+  });
+  return { key };
+}

package/server/handlers/agentRun/modelUsageToolHandlers.ts

@@ -0,0 +1,368 @@
+import { computeNextScheduledAt } from "../../../chat/dialog/schedule";
+import type { DialogConfig, DialogGoalState, ScheduledTaskConfig } from "../../../app/types";
+import { DataType } from "../../../create/types";
+import { createSpaceKey } from "../../../create/space/spaceKeys";
+import { checkSpaceMembership } from "../../../create/space/utils/permissions";
+import { isAIAdmin } from "../../../core/init";
+import { extractCustomId } from "../../../core/prefix";
+import { createTaskKey, createUserKey } from "../../../database/keys";
+import serverDb from "../../../database/server/db";
+import { queryModelUsage } from "../../../ai/token/modelUsageQuery";
+import { emitAgentNoticeNotification } from "../notificationEmitter";
+import type { ToolExecutionContext } from "./types";
+import { resolveExistingDialogRef } from "./dialogLookup";
+import {
+  buildDialogGoal,
+  completeDialogGoal as completeDialogGoalRecord,
+  getDialogGoalReport,
+} from "../../../chat/dialog/goal";
+
+type ScheduledRunFn = (args: {
+  taskKey: string;
+  task: ScheduledTaskConfig;
+  startedAt: number;
+}) => Promise<{ durationMs: number; nextRunAt: number | null; runDialogKey?: string }>;
+
+const defaultDeps = {
+  executeScheduledTaskRun: null as ScheduledRunFn | null,
+};
+
+let deps = defaultDeps;
+
+export function __setModelUsageToolHandlerDepsForTest(
+  overrides: Partial<typeof defaultDeps> | null,
+) {
+  deps = overrides ? { ...defaultDeps, ...overrides } : defaultDeps;
+}
+
+const trimString = (value: unknown): string =>
+  typeof value === "string" ? value.trim() : "";
+
+const boolValue = (value: unknown): boolean => value === true;
+const FEEDBACK_AGENT_ID = "01NOLOFEEDBACKA000000000R1";
+const FEEDBACK_NOTIFICATION_USER_ID = "0e95801d90";
+
+const requireCurrentUser = (context?: ToolExecutionContext): string => {
+  const userId = trimString(context?.userId);
+  if (!userId) {
+    throw new Error("AUTH_REQUIRED: model usage tools need a signed-in user");
+  }
+  return userId;
+};
+
+const readOptionalRecord = async (key: string): Promise<unknown | null> => {
+  try {
+    return await serverDb.get(key);
+  } catch {
+    return null;
+  }
+};
+
+const canManageModelUsage = async (userId: string): Promise<boolean> => {
+  if (isAIAdmin(userId)) return true;
+  const [settings, profile] = await Promise.all([
+    readOptionalRecord(createUserKey.settings(userId)),
+    readOptionalRecord(createUserKey.profile(userId)),
+  ]);
+  return isAIAdmin(userId, settings, profile);
+};
+
+const normalizeDialogId = (
+  args: Record<string, any>,
+  context?: ToolExecutionContext,
+): string => trimString(args.dialogId) || trimString(context?.dialogId);
+
+const resolveOwnedDialogForGoal = async (
+  args: Record<string, any>,
+  context?: ToolExecutionContext,
+) => {
+  const userId = requireCurrentUser(context);
+  const dialogId = normalizeDialogId(args, context);
+  if (!dialogId) {
+    throw new Error("DIALOG_GOAL_INVALID_ARGS: dialogId is required");
+  }
+
+  const ref = await resolveExistingDialogRef({
+    dialogId,
+    preferredUserId: userId,
+  });
+  if (!ref) {
+    throw new Error("DIALOG_GOAL_NOT_FOUND");
+  }
+  if (ref.dialogUserId !== userId) {
+    throw new Error("DIALOG_GOAL_FORBIDDEN");
+  }
+
+  return {
+    dialogId,
+    dialogKey: ref.dialogKey,
+    dialog: ref.dialogRecord as DialogConfig,
+  };
+};
+
+const persistDialogGoal = async (
+  dialogKey: string,
+  dialog: DialogConfig,
+  goal: DialogGoalState,
+) => {
+  await serverDb.put(dialogKey, {
+    ...dialog,
+    goal,
+    updatedAt: new Date().toISOString(),
+  });
+};
+
+const attachScheduledTaskToSpace = async (args: {
+  userId: string;
+  spaceId: string;
+  taskKey: string;
+  title: string;
+  now: number;
+}) => {
+  const spaceKey = createSpaceKey.space(args.spaceId);
+  const spaceRecord = (await serverDb.get(spaceKey).catch(() => null)) as any;
+  checkSpaceMembership(spaceRecord, args.userId);
+
+  await serverDb.put(spaceKey, {
+    ...spaceRecord,
+    contents: {
+      ...(spaceRecord.contents ?? {}),
+      [args.taskKey]: {
+        ...(spaceRecord.contents?.[args.taskKey] ?? {}),
+        title: args.title,
+        type: DataType.TASK,
+        contentKey: args.taskKey,
+        pinned: spaceRecord.contents?.[args.taskKey]?.pinned ?? false,
+        createdAt: spaceRecord.contents?.[args.taskKey]?.createdAt ?? args.now,
+        updatedAt: args.now,
+      },
+    },
+    updatedAt: args.now,
+  });
+};
+
+export async function runQueryModelUsageTool(
+  args: Record<string, any>,
+  context?: ToolExecutionContext,
+) {
+  const requestUserId = requireCurrentUser(context);
+  return queryModelUsage(serverDb, {
+    ...args,
+    requestUserId,
+    isAdmin: await canManageModelUsage(requestUserId),
+  });
+}
+
+export async function runNotifyUserTool(
+  args: Record<string, any>,
+  context?: ToolExecutionContext,
+) {
+  const userId = requireCurrentUser(context);
+  const requestedTargetUserId = trimString(args.targetUserId);
+  const targetUserId = requestedTargetUserId || userId;
+  const title = trimString(args.title);
+  const message = trimString(args.message);
+  if (!title || !message) {
+    throw new Error("NOTIFY_USER_INVALID_ARGS: title and message are required");
+  }
+  if (targetUserId !== userId) {
+    const agentKey = trimString(context?.agentKey);
+    const isTrustedFeedbackAgent =
+      targetUserId === FEEDBACK_NOTIFICATION_USER_ID &&
+      (agentKey === `agent-pub-${FEEDBACK_AGENT_ID}` ||
+        agentKey.endsWith(`-${FEEDBACK_AGENT_ID}`));
+    if (!isTrustedFeedbackAgent && !(await canManageModelUsage(userId))) {
+      throw new Error("NOTIFY_USER_FORBIDDEN: cannot notify another user");
+    }
+  }
+
+  const notification = await emitAgentNoticeNotification({
+    userId: targetUserId,
+    title,
+    message,
+    severity: trimString(args.severity) || "info",
+    href: trimString(args.href) || undefined,
+  });
+
+  return {
+    success: true,
+    notificationId: notification?.notificationId ?? null,
+    kind: notification?.kind ?? null,
+  };
+}
+
+export async function runCreateDialogGoalTool(
+  args: Record<string, any>,
+  context?: ToolExecutionContext,
+) {
+  const { dialogId, dialogKey, dialog } = await resolveOwnedDialogForGoal(args, context);
+  const goal = buildDialogGoal({
+    objective: args.objective,
+    tokenBudget: args.tokenBudget,
+    now: typeof args.now === "number" ? args.now : undefined,
+  });
+  await persistDialogGoal(dialogKey, dialog, goal);
+
+  return {
+    success: true,
+    dialogId,
+    dialogKey,
+    goal,
+    report: getDialogGoalReport({ ...dialog, goal }),
+  };
+}
+
+export async function runGetDialogGoalTool(
+  args: Record<string, any>,
+  context?: ToolExecutionContext,
+) {
+  const { dialogId, dialogKey, dialog } = await resolveOwnedDialogForGoal(args, context);
+  return {
+    success: true,
+    dialogId,
+    dialogKey,
+    goal: dialog.goal ?? null,
+    report: getDialogGoalReport(dialog),
+  };
+}
+
+export async function runCompleteDialogGoalTool(
+  args: Record<string, any>,
+  context?: ToolExecutionContext,
+) {
+  const { dialogId, dialogKey, dialog } = await resolveOwnedDialogForGoal(args, context);
+  if (!dialog.goal) {
+    throw new Error("DIALOG_GOAL_MISSING");
+  }
+  const completed = completeDialogGoalRecord(
+    dialog,
+    typeof args.now === "number" ? args.now : undefined,
+  );
+  await persistDialogGoal(dialogKey, dialog, completed.goal!);
+
+  return {
+    success: true,
+    dialogId,
+    dialogKey,
+    goal: completed.goal,
+    report: getDialogGoalReport(completed),
+  };
+}
+
+export async function runCreateScheduledTaskTool(
+  args: Record<string, any>,
+  context?: ToolExecutionContext,
+) {
+  const userId = requireCurrentUser(context);
+  const agentKey = trimString(args.agentKey) || trimString(context?.agentKey);
+  const schedule = trimString(args.schedule);
+  const taskPrompt = trimString(args.taskPrompt);
+  if (!agentKey) {
+    throw new Error("CREATE_SCHEDULED_TASK_INVALID_ARGS: agentKey is required");
+  }
+  if (!schedule || !taskPrompt) {
+    throw new Error("CREATE_SCHEDULED_TASK_INVALID_ARGS: schedule and taskPrompt are required");
+  }
+
+  const nextRunAt = computeNextScheduledAt(schedule);
+  if (!nextRunAt) {
+    throw new Error("CREATE_SCHEDULED_TASK_INVALID_ARGS: invalid cron schedule");
+  }
+
+  const taskKey = createTaskKey(userId);
+  const taskId = extractCustomId(taskKey);
+  const nowIso = new Date().toISOString();
+  const nowMs = Date.now();
+  const title = trimString(args.title) || "Scheduled agent task";
+  const spaceId = trimString(args.spaceId) || trimString(context?.currentSpaceId);
+  const task: ScheduledTaskConfig = {
+    id: taskId,
+    dbKey: taskKey,
+    type: DataType.TASK,
+    title,
+    agentKey,
+    cybots: [agentKey],
+    createdBy: userId,
+    createdAt: nowIso,
+    updatedAt: nowIso,
+    status: "active",
+    runStatus: "idle",
+    schedule,
+    taskPrompt,
+    nextRunAt,
+    runDialogKeys: [],
+    ...(spaceId ? { spaceId } : {}),
+  };
+
+  await serverDb.put(taskKey, task);
+  if (spaceId) {
+    await attachScheduledTaskToSpace({
+      userId,
+      spaceId,
+      taskKey,
+      title,
+      now: nowMs,
+    });
+  }
+
+  let runOnce: Record<string, unknown> | null = null;
+  if (boolValue(args.runOnceNow)) {
+    const startedAt = Date.now();
+    await serverDb.put(taskKey, {
+      ...task,
+      runStatus: "running",
+      updatedAt: new Date().toISOString(),
+    });
+    try {
+      const executeScheduledTaskRun =
+        deps.executeScheduledTaskRun ??
+        (await import("../../scheduler/scheduledTaskRuntime")).executeScheduledTaskRun;
+      const result = await executeScheduledTaskRun({
+        taskKey,
+        task,
+        startedAt,
+      });
+      await serverDb.put(taskKey, {
+        ...task,
+        runStatus: "done",
+        nextRunAt: result.nextRunAt ?? nextRunAt,
+        lastRunAt: startedAt,
+        ...(result.runDialogKey ? {
+          lastRunDialogKey: result.runDialogKey,
+          runDialogKeys: [result.runDialogKey],
+        } : {}),
+        updatedAt: new Date().toISOString(),
+      });
+      runOnce = {
+        success: true,
+        durationMs: result.durationMs,
+        nextRunAt: result.nextRunAt ?? nextRunAt,
+        runDialogKey: result.runDialogKey ?? null,
+      };
+    } catch (err: any) {
+      const errorMessage = err?.message ?? String(err);
+      await serverDb.put(taskKey, {
+        ...task,
+        runStatus: "failed",
+        lastRunAt: startedAt,
+        lastRunError: errorMessage,
+        updatedAt: new Date().toISOString(),
+      });
+      runOnce = {
+        success: false,
+        error: errorMessage,
+      };
+    }
+  }
+
+  return {
+    success: true,
+    taskId,
+    taskKey,
+    title,
+    agentKey,
+    schedule,
+    nextRunAt,
+    runOnce,
+  };
+}

package/server/handlers/agentRun/referenceRuntime.ts

@@ -0,0 +1,50 @@
+import type { ReferenceItem } from "../../../app/types";
+import {
+  buildReferenceRuntimePromptBlock,
+  resolveSkillGraphFromRoots,
+  type SkillRuntimePageLike,
+} from "../../../ai/skills/referenceRuntime";
+
+type RuntimeReferenceResolution = {
+  requiredTools: string[];
+  recommendedTools: string[];
+  recommendedSkillHints: string[];
+  skillPromptPatches: string[];
+  promptBlock?: string;
+};
+
+type ResolveOptions = {
+  references?: ReferenceItem[];
+  loadPage: (identifier: string) => Promise<SkillRuntimePageLike>;
+};
+
+export async function resolveServerReferenceRuntime(
+  options: ResolveOptions,
+): Promise<RuntimeReferenceResolution> {
+  const references = options.references ?? [];
+  if (references.length === 0) {
+    return {
+      requiredTools: [],
+      recommendedTools: [],
+      recommendedSkillHints: [],
+      skillPromptPatches: [],
+    };
+  }
+
+  const resolved = await resolveSkillGraphFromRoots({
+    roots: references.map((reference) => ({
+      identifier: reference.dbKey,
+      mode: "required" as const,
+    })),
+    loadPage: options.loadPage,
+  });
+
+  return {
+    requiredTools: resolved.requiredTools,
+    recommendedTools: resolved.recommendedTools,
+    recommendedSkillHints: resolved.recommendedSkillHints,
+    skillPromptPatches: resolved.skillPromptPatches,
+    promptBlock:
+      buildReferenceRuntimePromptBlock(resolved.visits, resolved.skillPromptPatches) || undefined,
+  };
+}