diff --git a/.gitignore b/.gitignore index a7956e43..2a77479a 100644 --- a/.gitignore +++ b/.gitignore @@ -36,3 +36,6 @@ tsconfig.tsbuildinfo # Internal design docs — kept local-only, not tracked in git (see S2-v3.4.1 DOC-2). # Erased from history via git-filter-repo; the public distilled version lives in design/. docs/ + +# Non-code domain packs — own git repo (deepagent-domain), not tracked by main repo. +extra-domain/ diff --git a/packages/app/package.json b/packages/app/package.json index 64d17c44..6c6e8579 100644 --- a/packages/app/package.json +++ b/packages/app/package.json @@ -6,6 +6,7 @@ "exports": { ".": "./src/index.ts", "./desktop-menu": "./src/desktop-menu.ts", + "./zoom-levels": "./src/zoom-levels.ts", "./updater": "./src/updater.ts", "./wsl/types": "./src/wsl/types.ts", "./vite": "./vite.js", diff --git a/packages/app/src/components/dialog-connect-provider.tsx b/packages/app/src/components/dialog-connect-provider.tsx index f7655c5e..acb86383 100644 --- a/packages/app/src/components/dialog-connect-provider.tsx +++ b/packages/app/src/components/dialog-connect-provider.tsx @@ -1,5 +1,6 @@ import type { ProviderAuthAuthorization, ProviderAuthMethod } from "@deepagent-code/sdk/v2/client" import { Button } from "@deepagent-code/ui/button" +import { Collapsible } from "@deepagent-code/ui/collapsible" import { useDialog } from "@deepagent-code/ui/context/dialog" import { Dialog } from "@deepagent-code/ui/dialog" import { Icon } from "@deepagent-code/ui/icon" @@ -16,19 +17,30 @@ import { useServerSDK } from "@/context/server-sdk" import { useServerSync } from "@/context/server-sync" import { useLanguage } from "@/context/language" import { useProviders } from "@/hooks/use-providers" +import { isOfficialProvider } from "@deepagent-code/core/provider-official" // Recommended/official providers ship a fixed protocol (npm) tied to a canonical endpoint. Letting // users point one of these at a relay/local server silently breaks because the protocol no longer // matches the endpoint — those users must add a custom provider instead. So the connect dialog hides -// the baseURL field for these and only exposes it for ad-hoc config/custom providers. +// the baseURL field for these and only exposes it for ad-hoc config/custom providers. Google and xAI +// resolve their real endpoint from the bundled SDK; the URL here only satisfies form validation and +// the placeholder. Keys must exist for every official id (see OFFICIAL_PROVIDER_IDS in core). const providerBaseURL: Record = { openai: "https://api.openai.com/v1", deepseek: "https://api.deepseek.com", anthropic: "https://api.anthropic.com/v1", zhipuai: "https://open.bigmodel.cn/api/paas/v4", + "zhipuai-coding-plan": "https://open.bigmodel.cn/api/coding/paas/v4", + zai: "https://api.z.ai/api/paas/v4", + "zai-coding-plan": "https://api.z.ai/api/coding/paas/v4", + xai: "https://api.x.ai/v1", + google: "https://generativelanguage.googleapis.com/v1beta", } -const isBuiltinProvider = (providerID: string) => providerID in providerBaseURL +// Official = first-party in the backend (key store credentials, fixed protocol). This must match the +// backend's OFFICIAL_PROVIDER_IDS exactly so the connect flow routes credentials the same way the +// loader reads them (auth for official, config options.apiKey for third-party). +const isBuiltinProvider = (providerID: string) => isOfficialProvider(providerID) const providerKind = (providerID: string) => (providerID === "anthropic" ? "anthropic" : "openai-compatible") @@ -419,6 +431,13 @@ export function DialogConnectProvider(props: { provider: string }) { id: model.id, name: model.name || model.id, })) + // Official-provider transport settings are surfaced by the config overlay under + // provider..options (backed by SettingsStore, not the config file). Seed the fields from there. + const transportOption = (key: string): string => { + const value = serverSync.data.config.provider?.[props.provider]?.options?.[key] + if (value === false) return "0" + return typeof value === "number" ? String(value) : "" + } const [formStore, setFormStore] = createStore({ value: "", baseURL: @@ -430,8 +449,42 @@ export function DialogConnectProvider(props: { provider: string }) { discovered: [] as DiscoveredProviderModel[], selectedModel: undefined as string | undefined, discovering: false, + headerTimeout: transportOption("headerTimeout"), + chunkTimeout: transportOption("chunkTimeout"), + timeout: transportOption("timeout"), + maxRetries: transportOption("maxRetries"), + transportError: undefined as string | undefined, }) + // Parse a transport field: empty → undefined (use default); "0" for header/request timeout → + // false (disabled); otherwise a positive integer. Returns { ok, value } so callers can reject + // malformed input. + function parseTransport(raw: string, allowFalse: boolean): { ok: boolean; value: number | false | undefined } { + const trimmed = raw.trim() + if (trimmed === "") return { ok: true, value: undefined } + const n = Number(trimmed) + if (!Number.isInteger(n) || n < 0) return { ok: false, value: undefined } + if (n === 0) return allowFalse ? { ok: true, value: false } : { ok: false, value: undefined } + return { ok: true, value: n } + } + + // Build the SettingsStore-bound options patch for an official provider (routed via the config + // overlay's intercept). Returns undefined when a field is malformed. + function transportOptions(): Record | undefined | "invalid" { + const header = parseTransport(formStore.headerTimeout, true) + const chunk = parseTransport(formStore.chunkTimeout, false) + const request = parseTransport(formStore.timeout, true) + const retries = parseTransport(formStore.maxRetries, false) + if (!header.ok || !chunk.ok || !request.ok || !retries.ok) return "invalid" + const options: Record = {} + if (header.value !== undefined) options.headerTimeout = header.value + if (chunk.value !== undefined && chunk.value !== false) options.chunkTimeout = chunk.value + if (request.value !== undefined) options.timeout = request.value + if (retries.value !== undefined && retries.value !== false) options.maxRetries = retries.value + return options + } + + async function handleSubmit(e: SubmitEvent) { e.preventDefault() @@ -456,6 +509,43 @@ export function DialogConnectProvider(props: { provider: string }) { setFormStore("error", undefined) setFormStore("baseURLError", undefined) + + if (isBuiltinProvider(props.provider)) { + const transport = transportOptions() + if (transport === "invalid") { + setFormStore("transportError", language.t("provider.connect.transport.error.number")) + return + } + setFormStore("transportError", undefined) + if (key) { + await serverSDK.client.auth.set({ + providerID: props.provider, + auth: { + type: "api", + key, + }, + }) + } + // Route transport tuning through the config overlay's intercept → SettingsStore. The + // remaining official-provider fields are ignored by the backend loader; only options. + // is picked up (and stripped from the config file). Always send the key so cleared fields reset. + const disabled = (serverSync.data.config.disabled_providers ?? []).filter((id) => id !== props.provider) + await serverSync.updateConfig({ + disabled_providers: disabled, + provider: { + [props.provider]: { options: transport }, + }, + }) + await serverSDK.client.global.dispose() + showToast({ + variant: "success", + icon: "circle-check", + title: language.t("provider.connect.toast.connected.title", { provider: provider().name }), + description: language.t("provider.connect.toast.connected.description", { provider: provider().name }), + }) + return + } + setFormStore("discovering", true) try { const discovered = await serverSDK.client.provider.models @@ -484,15 +574,6 @@ export function DialogConnectProvider(props: { provider: string }) { setFormStore("discovered", nextModels) setFormStore("selectedModel", nextSelected.id) - if (key) { - await serverSDK.client.auth.set({ - providerID: props.provider, - auth: { - type: "api", - key, - }, - }) - } const current = serverSync.data.config.provider?.[props.provider] ?? {} await serverSync.updateConfig({ provider: { @@ -502,6 +583,7 @@ export function DialogConnectProvider(props: { provider: string }) { options: { ...(current.options ?? {}), baseURL, + ...(key ? { apiKey: key } : {}), }, models: { ...(current.models ?? {}), @@ -558,6 +640,55 @@ export function DialogConnectProvider(props: { provider: string }) { validationState={formStore.error ? "invalid" : undefined} error={formStore.error} /> + + + + {language.t("provider.connect.transport.title")} + + + +
+
+ {language.t("provider.connect.transport.description")} +
+ setFormStore("headerTimeout", v)} + /> + setFormStore("chunkTimeout", v)} + /> + setFormStore("timeout", v)} + /> + setFormStore("maxRetries", v)} + validationState={formStore.transportError ? "invalid" : undefined} + error={formStore.transportError} + /> +
+ + + diff --git a/packages/app/src/components/dialog-custom-provider-form.ts b/packages/app/src/components/dialog-custom-provider-form.ts index e26dcb09..1294b436 100644 --- a/packages/app/src/components/dialog-custom-provider-form.ts +++ b/packages/app/src/components/dialog-custom-provider-form.ts @@ -142,6 +142,7 @@ export function validateCustomProvider(input: ValidateArgs) { ...(env ? { env: [env] } : {}), options: { baseURL, + ...(key ? { apiKey: key } : {}), ...(Object.keys(headerConfig).length ? { headers: headerConfig } : {}), }, models: modelConfig, diff --git a/packages/app/src/components/dialog-custom-provider.tsx b/packages/app/src/components/dialog-custom-provider.tsx index 4111118f..90dfb92e 100644 --- a/packages/app/src/components/dialog-custom-provider.tsx +++ b/packages/app/src/components/dialog-custom-provider.tsx @@ -132,16 +132,6 @@ export function DialogCustomProvider(props: Props) { const disabledProviders = serverSync.data.config.disabled_providers ?? [] const nextDisabled = disabledProviders.filter((id) => id !== result.providerID) - if (result.key) { - await serverSDK.client.auth.set({ - providerID: result.providerID, - auth: { - type: "api", - key: result.key, - }, - }) - } - await serverSync.updateConfig({ provider: { [result.providerID]: result.config }, disabled_providers: nextDisabled, diff --git a/packages/app/src/components/settings-v2/general.tsx b/packages/app/src/components/settings-v2/general.tsx index b23db913..e6ad5a48 100644 --- a/packages/app/src/components/settings-v2/general.tsx +++ b/packages/app/src/components/settings-v2/general.tsx @@ -10,6 +10,7 @@ import { useParams } from "@solidjs/router" import { useLanguage } from "@/context/language" import { usePermission } from "@/context/permission" import { usePlatform, type DisplayBackend } from "@/context/platform" +import { ZOOM_LEVELS } from "@/zoom-levels" import { useServerSync } from "@/context/server-sync" import { useServerSDK } from "@/context/server-sdk" import { useUpdaterAction } from "../updater-action" @@ -284,6 +285,10 @@ export const SettingsGeneralV2: Component = () => { })), ) + const zoomOptions = createMemo(() => + ZOOM_LEVELS.map((level) => ({ value: String(level), label: `${Math.round(level * 100)}%` })), + ) + const noneSound = { id: "none", label: "sound.option.none" } as const const soundOptions = [noneSound, ...SOUND_OPTIONS] const mono = () => monoInput(settings.appearance.font()) @@ -418,7 +423,18 @@ export const SettingsGeneralV2: Component = () => { if (option.value === deepAgentWishModel()) return void updateDeepAgentOptions(serverSync, { wishModel: option.value }) }} - /> + > + {(o) => ( + + {o.label} + + + {o.description} + + + + )} + { + + o.value === String(platform.webviewZoom?.()))} + placement="bottom-end" + gutter={6} + value={(o) => o.value} + label={(o) => o.label} + onSelect={(option) => option && platform.setWebviewZoom?.(Number(option.value))} + /> + + @@ -46,6 +47,18 @@ export function WindowsAppMenu(props: { if (entry.href) props.platform.openLink(entry.href) } + const zoom = () => props.platform.webviewZoom?.() ?? 1 + const isZoomAction = (action: DesktopMenuAction | undefined) => + action === "view.zoomIn" || action === "view.zoomOut" || action === "view.resetZoom" + const zoomLabel = (entry: DesktopMenuItem) => + isZoomAction(entry.action) ? `${entry.label ?? ""} ${zoomPercent(zoom())}%` : entry.label ?? "" + const zoomDisabled = (entry: DesktopMenuItem) => { + if (entry.command) return commandDisabled(entry.command) + if (entry.action === "view.zoomIn") return !canZoomIn(zoom()) + if (entry.action === "view.zoomOut") return !canZoomOut(zoom()) + return false + } + return ( {props.variant === "v2" ? ( @@ -87,9 +100,9 @@ export function WindowsAppMenu(props: { ) : ( runEntry(entry)} /> ), diff --git a/packages/app/src/context/global-sync/types.ts b/packages/app/src/context/global-sync/types.ts index 286b98e8..858b9dfe 100644 --- a/packages/app/src/context/global-sync/types.ts +++ b/packages/app/src/context/global-sync/types.ts @@ -35,9 +35,10 @@ export type ProjectMeta = { export type SessionPlanStep = { step_id: string title: string - status: string // pending | active | done | cancelled + status: string // pending | active | done | cancelled | blocked acceptance?: string | null assigned_agent?: string | null + note?: string | null // U10: blocker explanation when status is "blocked" } export type SessionPlan = { plan_id: string diff --git a/packages/app/src/context/models.tsx b/packages/app/src/context/models.tsx index 7332f7c0..030f0945 100644 --- a/packages/app/src/context/models.tsx +++ b/packages/app/src/context/models.tsx @@ -93,12 +93,23 @@ export const { use: useModels, provider: ModelsProvider } = createSimpleContext( return map }) + const duplicateModelIDs = createMemo(() => { + const counts = available().reduce( + (acc, model) => acc.set(model.id, (acc.get(model.id) ?? 0) + 1), + new Map(), + ) + return new Set([...counts.entries()].filter((entry) => entry[1] > 1).map((entry) => entry[0])) + }) + const list = createMemo(() => - available().map((m) => ({ - ...m, - name: m.name.replace("(latest)", "").trim(), - latest: m.name.includes("(latest)"), - })), + available().map((m) => { + const name = m.name.replace("(latest)", "").trim() + return { + ...m, + name: duplicateModelIDs().has(m.id) ? `${name} (${m.provider.name})` : name, + latest: m.name.includes("(latest)"), + } + }), ) const find = (key: ModelKey) => list().find((m) => m.id === key.modelID && m.provider.id === key.providerID) diff --git a/packages/app/src/context/platform.tsx b/packages/app/src/context/platform.tsx index 03575708..d2806fda 100644 --- a/packages/app/src/context/platform.tsx +++ b/packages/app/src/context/platform.tsx @@ -113,6 +113,9 @@ type PlatformBase = { /** Webview zoom level (desktop only) */ webviewZoom?: Accessor + /** Set the webview zoom level (desktop only) */ + setWebviewZoom?(level: number): void + /** Get whether native pinch/Ctrl-scroll zoom gestures are enabled (desktop only) */ getPinchZoomEnabled?(): Promise | boolean diff --git a/packages/app/src/hooks/use-providers.ts b/packages/app/src/hooks/use-providers.ts index 64103c9c..01a76d68 100644 --- a/packages/app/src/hooks/use-providers.ts +++ b/packages/app/src/hooks/use-providers.ts @@ -3,9 +3,13 @@ import { decode64 } from "@/utils/base64" import { useParams } from "@solidjs/router" import { Iterable, pipe } from "effect" import { createMemo } from "solid-js" +import { OFFICIAL_PROVIDER_IDS } from "@deepagent-code/core/provider-official" -export const popularProviders = ["openai", "deepseek", "anthropic", "zhipuai"] -const popularProviderSet = new Set(popularProviders) +// Official providers are the recommended-first display set and the only ids the backend treats as +// first-party (key store credentials, fixed protocol). Everything else is a custom third-party +// provider. Single source of truth lives in core; see OFFICIAL_PROVIDER_IDS. +export const popularProviders: string[] = [...OFFICIAL_PROVIDER_IDS] +const popularProviderSet = new Set(popularProviders) export function useProviders() { const serverSync = useServerSync() diff --git a/packages/app/src/i18n/ar.ts b/packages/app/src/i18n/ar.ts index b649bbc2..09cf9968 100644 --- a/packages/app/src/i18n/ar.ts +++ b/packages/app/src/i18n/ar.ts @@ -894,6 +894,8 @@ export const dict = { "تفعيل التخطيط والصفحة الرئيسية والمحرر وواجهة الجلسة المعاد تصميمها", "settings.general.row.pinchZoom.title": "التكبير بالقرص", "settings.general.row.pinchZoom.description": "السماح بإيماءات قرص لوحة اللمس و Ctrl-تمرير للتكبير", + "settings.general.row.zoom.title": "Zoom level", + "settings.general.row.zoom.description": "Set the interface zoom level", "settings.updates.action.downloading": "جار التنزيل...", "settings.updates.action.installing": "جار التثبيت...", "settings.providers.section.deepagentBackends": "واجهات نماذج DeepAgent الخلفية", diff --git a/packages/app/src/i18n/br.ts b/packages/app/src/i18n/br.ts index 5d1e9e4d..26a1182e 100644 --- a/packages/app/src/i18n/br.ts +++ b/packages/app/src/i18n/br.ts @@ -918,6 +918,8 @@ export const dict = { "settings.general.row.pinchZoom.title": "Pinçar para zoom", "settings.general.row.pinchZoom.description": "Permitir gestos de pellizco en trackpad y Ctrl-desplazamiento para ampliar", + "settings.general.row.zoom.title": "Zoom level", + "settings.general.row.zoom.description": "Set the interface zoom level", "settings.updates.action.downloading": "Baixando...", "settings.updates.action.installing": "Instalando...", "settings.providers.section.deepagentBackends": "Backends de modelos DeepAgent", diff --git a/packages/app/src/i18n/bs.ts b/packages/app/src/i18n/bs.ts index 292d8642..72e1d0ca 100644 --- a/packages/app/src/i18n/bs.ts +++ b/packages/app/src/i18n/bs.ts @@ -991,6 +991,8 @@ export const dict = { "settings.general.row.pinchZoom.title": "Powiększanie gestem szczypania", "settings.general.row.pinchZoom.description": "Zezwól na powiększanie gestem szczypania na trackpadzie i Ctrl-przewijaniem", + "settings.general.row.zoom.title": "Zoom level", + "settings.general.row.zoom.description": "Set the interface zoom level", "settings.updates.action.downloading": "Preuzimanje...", "settings.updates.action.installing": "Instaliranje...", "settings.providers.section.deepagentBackends": "DeepAgent model backendi", diff --git a/packages/app/src/i18n/da.ts b/packages/app/src/i18n/da.ts index ca7b9905..9381ac21 100644 --- a/packages/app/src/i18n/da.ts +++ b/packages/app/src/i18n/da.ts @@ -980,6 +980,8 @@ export const dict = { "settings.general.row.newLayoutDesigns.description": "Aktivér det redesignede layout, hjem, composer og sessions-UI", "settings.general.row.pinchZoom.title": "Knib for at zoome", "settings.general.row.pinchZoom.description": "Tillad trackpad-knib og Ctrl-scroll til zoom", + "settings.general.row.zoom.title": "Zoom level", + "settings.general.row.zoom.description": "Set the interface zoom level", "settings.updates.action.downloading": "Downloader...", "settings.updates.action.installing": "Installerer...", "settings.providers.section.deepagentBackends": "DeepAgent-modelbackends", diff --git a/packages/app/src/i18n/de.ts b/packages/app/src/i18n/de.ts index 050f52f2..b722b2cf 100644 --- a/packages/app/src/i18n/de.ts +++ b/packages/app/src/i18n/de.ts @@ -925,6 +925,8 @@ export const dict = { "Überarbeitetes Layout, Startseite, Composer und Sitzungs-UI aktivieren", "settings.general.row.pinchZoom.title": "Zum Zoomen kneifen", "settings.general.row.pinchZoom.description": "Trackpad-Kneifen und Strg-Scrollen zum Zoomen erlauben", + "settings.general.row.zoom.title": "Zoom level", + "settings.general.row.zoom.description": "Set the interface zoom level", "settings.updates.action.downloading": "Wird heruntergeladen...", "settings.updates.action.installing": "Wird installiert...", "settings.providers.section.deepagentBackends": "DeepAgent-Modell-Backends", diff --git a/packages/app/src/i18n/en.ts b/packages/app/src/i18n/en.ts index b87316b0..e730a6cb 100644 --- a/packages/app/src/i18n/en.ts +++ b/packages/app/src/i18n/en.ts @@ -160,6 +160,19 @@ export const dict = { "provider.connect.toast.connected.title": "{{provider}} connected", "provider.connect.toast.connected.description": "{{provider}} models are now available to use.", + "provider.connect.transport.title": "Advanced: request timeouts & retries", + "provider.connect.transport.description": + "Transport settings for this official provider are stored separately from your config file. Leave blank to use defaults.", + "provider.connect.transport.headerTimeout.label": "Header timeout (ms)", + "provider.connect.transport.headerTimeout.placeholder": "e.g. 10000", + "provider.connect.transport.chunkTimeout.label": "Chunk timeout (ms)", + "provider.connect.transport.chunkTimeout.placeholder": "e.g. 30000", + "provider.connect.transport.timeout.label": "Request timeout (ms)", + "provider.connect.transport.timeout.placeholder": "e.g. 120000", + "provider.connect.transport.maxRetries.label": "Max retries", + "provider.connect.transport.maxRetries.placeholder": "e.g. 2", + "provider.connect.transport.error.number": "Enter a positive whole number, or leave blank.", + "provider.custom.title": "Custom provider", "provider.custom.description.prefix": "Configure an OpenAI-compatible provider. See the ", "provider.custom.description.link": "provider config docs", @@ -1006,6 +1019,8 @@ export const dict = { "settings.general.row.newLayoutDesigns.description": "Enable the redesigned layout, home, composer, and session UI", "settings.general.row.pinchZoom.title": "Pinch to zoom", "settings.general.row.pinchZoom.description": "Allow trackpad pinch and Ctrl-scroll gestures to zoom", + "settings.general.row.zoom.title": "Zoom level", + "settings.general.row.zoom.description": "Set the interface zoom level", "settings.general.row.wayland.title": "Use native Wayland", "settings.general.row.wayland.description": "Disable X11 fallback on Wayland. Requires restart.", diff --git a/packages/app/src/i18n/es.ts b/packages/app/src/i18n/es.ts index 0f237354..fda9ba46 100644 --- a/packages/app/src/i18n/es.ts +++ b/packages/app/src/i18n/es.ts @@ -1001,6 +1001,8 @@ export const dict = { "settings.general.row.pinchZoom.title": "Pellizcar para ampliar", "settings.general.row.pinchZoom.description": "Permitir gestos de pellizco en trackpad y Ctrl-desplazamiento para ampliar", + "settings.general.row.zoom.title": "Zoom level", + "settings.general.row.zoom.description": "Set the interface zoom level", "settings.updates.action.downloading": "Descargando...", "settings.updates.action.installing": "Instalando...", "settings.providers.section.deepagentBackends": "Backends de modelos DeepAgent", diff --git a/packages/app/src/i18n/fr.ts b/packages/app/src/i18n/fr.ts index 8199a16a..4b77c2a5 100644 --- a/packages/app/src/i18n/fr.ts +++ b/packages/app/src/i18n/fr.ts @@ -926,6 +926,8 @@ export const dict = { "Activer la mise en page, l’accueil, le compositeur et l’interface de session repensés", "settings.general.row.pinchZoom.title": "Pincer pour zoomer", "settings.general.row.pinchZoom.description": "Autoriser le pincement du trackpad et Ctrl-défilement pour zoomer", + "settings.general.row.zoom.title": "Zoom level", + "settings.general.row.zoom.description": "Set the interface zoom level", "settings.updates.action.downloading": "Téléchargement...", "settings.updates.action.installing": "Installation...", "settings.providers.section.deepagentBackends": "Backends de modèles DeepAgent", diff --git a/packages/app/src/i18n/ja.ts b/packages/app/src/i18n/ja.ts index 3d458ad5..976358af 100644 --- a/packages/app/src/i18n/ja.ts +++ b/packages/app/src/i18n/ja.ts @@ -907,6 +907,8 @@ export const dict = { "再設計されたレイアウト、ホーム、コンポーザー、セッションUIを有効にします", "settings.general.row.pinchZoom.title": "ピンチでズーム", "settings.general.row.pinchZoom.description": "トラックパッドのピンチとCtrlスクロールでズームを許可します", + "settings.general.row.zoom.title": "Zoom level", + "settings.general.row.zoom.description": "Set the interface zoom level", "settings.updates.action.downloading": "ダウンロード中...", "settings.updates.action.installing": "インストール中...", "settings.providers.section.deepagentBackends": "DeepAgentモデルバックエンド", diff --git a/packages/app/src/i18n/ko.ts b/packages/app/src/i18n/ko.ts index bfa90faf..2f1a8dff 100644 --- a/packages/app/src/i18n/ko.ts +++ b/packages/app/src/i18n/ko.ts @@ -898,6 +898,8 @@ export const dict = { "settings.general.row.newLayoutDesigns.description": "재설계된 레이아웃, 홈, 작성기 및 세션 UI를 활성화합니다", "settings.general.row.pinchZoom.title": "핀치로 확대/축소", "settings.general.row.pinchZoom.description": "트랙패드 핀치와 Ctrl-스크롤 제스처로 확대/축소를 허용합니다", + "settings.general.row.zoom.title": "Zoom level", + "settings.general.row.zoom.description": "Set the interface zoom level", "settings.updates.action.downloading": "다운로드 중...", "settings.updates.action.installing": "설치 중...", "settings.providers.section.deepagentBackends": "DeepAgent 모델 백엔드", diff --git a/packages/app/src/i18n/no.ts b/packages/app/src/i18n/no.ts index 57cd411a..2680f0e1 100644 --- a/packages/app/src/i18n/no.ts +++ b/packages/app/src/i18n/no.ts @@ -987,6 +987,8 @@ export const dict = { "settings.general.row.newLayoutDesigns.description": "Aktivér det redesignede layout, hjem, composer og sessions-UI", "settings.general.row.pinchZoom.title": "Knib for at zoome", "settings.general.row.pinchZoom.description": "Tillad trackpad-knib og Ctrl-scroll til zoom", + "settings.general.row.zoom.title": "Zoom level", + "settings.general.row.zoom.description": "Set the interface zoom level", "settings.updates.action.downloading": "Laster ned...", "settings.updates.action.installing": "Installerer...", "settings.providers.section.deepagentBackends": "DeepAgent-modellbackender", diff --git a/packages/app/src/i18n/pl.ts b/packages/app/src/i18n/pl.ts index a38df652..813f1115 100644 --- a/packages/app/src/i18n/pl.ts +++ b/packages/app/src/i18n/pl.ts @@ -913,6 +913,8 @@ export const dict = { "settings.general.row.pinchZoom.title": "Powiększanie gestem szczypania", "settings.general.row.pinchZoom.description": "Zezwól na powiększanie gestem szczypania na trackpadzie i Ctrl-przewijaniem", + "settings.general.row.zoom.title": "Zoom level", + "settings.general.row.zoom.description": "Set the interface zoom level", "settings.updates.action.downloading": "Pobieranie...", "settings.updates.action.installing": "Instalowanie...", "settings.providers.section.deepagentBackends": "Backendy modeli DeepAgent", diff --git a/packages/app/src/i18n/ru.ts b/packages/app/src/i18n/ru.ts index 8ffa5eba..dc7c0731 100644 --- a/packages/app/src/i18n/ru.ts +++ b/packages/app/src/i18n/ru.ts @@ -992,6 +992,8 @@ export const dict = { "Включить обновленный макет, главную страницу, композер и интерфейс сессии", "settings.general.row.pinchZoom.title": "Масштабирование щипком", "settings.general.row.pinchZoom.description": "Разрешить масштабирование щипком на трекпаде и Ctrl-прокруткой", + "settings.general.row.zoom.title": "Zoom level", + "settings.general.row.zoom.description": "Set the interface zoom level", "settings.updates.action.downloading": "Загрузка...", "settings.updates.action.installing": "Установка...", "settings.providers.section.deepagentBackends": "Бэкенды моделей DeepAgent", diff --git a/packages/app/src/i18n/th.ts b/packages/app/src/i18n/th.ts index 6f9e0211..c071364c 100644 --- a/packages/app/src/i18n/th.ts +++ b/packages/app/src/i18n/th.ts @@ -975,6 +975,8 @@ export const dict = { "settings.general.row.newLayoutDesigns.description": "เปิดใช้เลย์เอาต์ หน้าแรก ตัวเขียน และ UI เซสชันที่ออกแบบใหม่", "settings.general.row.pinchZoom.title": "จีบนิ้วเพื่อซูม", "settings.general.row.pinchZoom.description": "อนุญาตท่าทางจีบนิ้วบนแทร็กแพดและ Ctrl-เลื่อนเพื่อซูม", + "settings.general.row.zoom.title": "Zoom level", + "settings.general.row.zoom.description": "Set the interface zoom level", "settings.updates.action.downloading": "กำลังดาวน์โหลด...", "settings.updates.action.installing": "กำลังติดตั้ง...", "settings.providers.section.deepagentBackends": "แบ็กเอนด์โมเดล DeepAgent", diff --git a/packages/app/src/i18n/tr.ts b/packages/app/src/i18n/tr.ts index 531d13e2..5ea53068 100644 --- a/packages/app/src/i18n/tr.ts +++ b/packages/app/src/i18n/tr.ts @@ -1000,6 +1000,8 @@ export const dict = { "settings.general.row.pinchZoom.title": "Sıkıştırarak yakınlaştır", "settings.general.row.pinchZoom.description": "Trackpad sıkıştırma ve Ctrl-kaydırma hareketleriyle yakınlaştırmaya izin ver", + "settings.general.row.zoom.title": "Zoom level", + "settings.general.row.zoom.description": "Set the interface zoom level", "settings.updates.action.downloading": "İndiriliyor...", "settings.updates.action.installing": "Yükleniyor...", "settings.providers.section.deepagentBackends": "DeepAgent model arka uçları", diff --git a/packages/app/src/i18n/uk.ts b/packages/app/src/i18n/uk.ts index a120593a..58b18f0a 100644 --- a/packages/app/src/i18n/uk.ts +++ b/packages/app/src/i18n/uk.ts @@ -1008,6 +1008,8 @@ export const dict = { "Включить обновленный макет, главную страницу, композер и интерфейс сессии", "settings.general.row.pinchZoom.title": "Масштабування щипком", "settings.general.row.pinchZoom.description": "Разрешить масштабирование щипком на трекпаде и Ctrl-прокруткой", + "settings.general.row.zoom.title": "Zoom level", + "settings.general.row.zoom.description": "Set the interface zoom level", "settings.updates.action.downloading": "Завантаження...", "settings.updates.action.installing": "Встановлення...", "settings.providers.section.deepagentBackends": "Бекенди моделей DeepAgent", diff --git a/packages/app/src/i18n/zh.ts b/packages/app/src/i18n/zh.ts index ba04a5d0..7034105c 100644 --- a/packages/app/src/i18n/zh.ts +++ b/packages/app/src/i18n/zh.ts @@ -184,6 +184,19 @@ export const dict = { "provider.connect.toast.connected.title": "{{provider}} 已连接", "provider.connect.toast.connected.description": "现在可以使用 {{provider}} 模型了。", + "provider.connect.transport.title": "高级：请求超时与重试", + "provider.connect.transport.description": + "官方 provider 的传输设置独立于配置文件保存。留空则使用默认值。", + "provider.connect.transport.headerTimeout.label": "响应头超时（毫秒）", + "provider.connect.transport.headerTimeout.placeholder": "例如 10000", + "provider.connect.transport.chunkTimeout.label": "数据块超时（毫秒）", + "provider.connect.transport.chunkTimeout.placeholder": "例如 30000", + "provider.connect.transport.timeout.label": "请求超时（毫秒）", + "provider.connect.transport.timeout.placeholder": "例如 120000", + "provider.connect.transport.maxRetries.label": "最大重试次数", + "provider.connect.transport.maxRetries.placeholder": "例如 2", + "provider.connect.transport.error.number": "请输入正整数，或留空。", + "provider.custom.title": "自定义提供商", "provider.custom.description.prefix": "配置与 OpenAI 兼容的提供商。请查看", "provider.custom.description.link": "提供商配置文档", @@ -1106,6 +1119,8 @@ export const dict = { "settings.general.row.newLayoutDesigns.description": "启用重新设计的布局、首页、输入器和会话界面", "settings.general.row.pinchZoom.title": "双指缩放", "settings.general.row.pinchZoom.description": "允许触控板双指和 Ctrl 滚动手势缩放", + "settings.general.row.zoom.title": "缩放比例", + "settings.general.row.zoom.description": "设置界面缩放比例", "settings.updates.action.downloading": "正在下载...", "settings.updates.action.installing": "正在安装...", "common.clear": "清除", diff --git a/packages/app/src/i18n/zht.ts b/packages/app/src/i18n/zht.ts index e8ec2e4b..db01fb37 100644 --- a/packages/app/src/i18n/zht.ts +++ b/packages/app/src/i18n/zht.ts @@ -971,6 +971,8 @@ export const dict = { "settings.general.row.newLayoutDesigns.description": "啟用重新設計的布局、首頁、輸入器和會話介面", "settings.general.row.pinchZoom.title": "雙指縮放", "settings.general.row.pinchZoom.description": "允許觸控板雙指和 Ctrl 捲動手勢縮放", + "settings.general.row.zoom.title": "Zoom level", + "settings.general.row.zoom.description": "Set the interface zoom level", "settings.updates.action.downloading": "正在下載...", "settings.updates.action.installing": "正在安裝...", "settings.providers.section.deepagentBackends": "DeepAgent 模型後端", diff --git a/packages/app/src/pages/session/composer/session-composer-state-model.ts b/packages/app/src/pages/session/composer/session-composer-state-model.ts new file mode 100644 index 00000000..ed3b1c26 --- /dev/null +++ b/packages/app/src/pages/session/composer/session-composer-state-model.ts @@ -0,0 +1,20 @@ +import type { Todo } from "@deepagent-code/sdk/v2" + +export const todoState = (input: { + count: number + done: boolean + live: boolean +}): "hide" | "clear" | "open" | "close" => { + if (input.count === 0) return "hide" + if (!input.live) return "clear" + if (!input.done) return "open" + return "close" +} + +export const planStepTodoStatus = (status: string): Todo["status"] => { + const value = status.trim().toLowerCase() + if (value === "active" || value === "in_progress") return "in_progress" + if (value === "done" || value === "completed") return "completed" + if (value === "cancelled" || value === "canceled") return "cancelled" + return "pending" +} diff --git a/packages/app/src/pages/session/composer/session-composer-state.test.ts b/packages/app/src/pages/session/composer/session-composer-state.test.ts index f3375f30..9c468dcd 100644 --- a/packages/app/src/pages/session/composer/session-composer-state.test.ts +++ b/packages/app/src/pages/session/composer/session-composer-state.test.ts @@ -1,6 +1,6 @@ import { describe, expect, test } from "bun:test" import type { PermissionRequest, QuestionRequest, Session } from "@deepagent-code/sdk/v2/client" -import { todoState } from "./session-composer-state" +import { planStepTodoStatus, todoState } from "./session-composer-state-model" import { sessionPermissionRequest, sessionQuestionRequest } from "./session-request-tree" const session = (input: { id: string; parentID?: string }) => @@ -126,3 +126,15 @@ describe("todoState", () => { expect(todoState({ count: 2, done: true, live: false })).toBe("clear") }) }) + +describe("planStepTodoStatus", () => { + test("maps plan and todo vocabularies to todo statuses", () => { + expect(planStepTodoStatus("active")).toBe("in_progress") + expect(planStepTodoStatus("in_progress")).toBe("in_progress") + expect(planStepTodoStatus("done")).toBe("completed") + expect(planStepTodoStatus("completed")).toBe("completed") + expect(planStepTodoStatus("cancelled")).toBe("cancelled") + expect(planStepTodoStatus("canceled")).toBe("cancelled") + expect(planStepTodoStatus("unknown")).toBe("pending") + }) +}) diff --git a/packages/app/src/pages/session/composer/session-composer-state.ts b/packages/app/src/pages/session/composer/session-composer-state.ts index 1bd52554..3b3bdc3c 100644 --- a/packages/app/src/pages/session/composer/session-composer-state.ts +++ b/packages/app/src/pages/session/composer/session-composer-state.ts @@ -9,17 +9,9 @@ import { usePermission } from "@/context/permission" import { useSDK } from "@/context/sdk" import { useSync } from "@/context/sync" import { sessionPermissionRequest, sessionQuestionRequest } from "./session-request-tree" +import { planStepTodoStatus, todoState } from "./session-composer-state-model" -export const todoState = (input: { - count: number - done: boolean - live: boolean -}): "hide" | "clear" | "open" | "close" => { - if (input.count === 0) return "hide" - if (!input.live) return "clear" - if (!input.done) return "open" - return "close" -} +export { planStepTodoStatus, todoState } const idle = { type: "idle" as const } @@ -59,16 +51,10 @@ export function createSessionComposerState(options?: { closeMs?: number | (() => const planAsTodos = createMemo((): Todo[] => { const p = plan() if (!p) return [] - const map: Record = { - pending: "pending", - active: "in_progress", - done: "completed", - cancelled: "cancelled", - } return p.steps.map((s, i) => ({ id: s.step_id || `step_${i}`, content: s.title, - status: map[s.status] ?? "pending", + status: planStepTodoStatus(s.status), priority: "medium", })) as unknown as Todo[] }) diff --git a/packages/app/src/zoom-levels.ts b/packages/app/src/zoom-levels.ts new file mode 100644 index 00000000..ab9e1ed2 --- /dev/null +++ b/packages/app/src/zoom-levels.ts @@ -0,0 +1,37 @@ +export const ZOOM_LEVELS = [0.5, 0.75, 1.0, 1.25, 1.5, 1.75, 2.0, 2.25, 2.5] as const + +export const MIN_ZOOM_LEVEL = ZOOM_LEVELS[0] +export const MAX_ZOOM_LEVEL = ZOOM_LEVELS[ZOOM_LEVELS.length - 1] + +const EPSILON = 1e-6 + +export function clampZoom(value: number): number { + return Math.min(Math.max(value, MIN_ZOOM_LEVEL), MAX_ZOOM_LEVEL) +} + +export function nextZoomLevel(current: number, direction: "in" | "out"): number { + const clamped = clampZoom(current) + if (direction === "in") { + for (const level of ZOOM_LEVELS) { + if (level > clamped + EPSILON) return level + } + return MAX_ZOOM_LEVEL + } + for (let i = ZOOM_LEVELS.length - 1; i >= 0; i--) { + const level = ZOOM_LEVELS[i] + if (level < clamped - EPSILON) return level + } + return MIN_ZOOM_LEVEL +} + +export function canZoomIn(factor: number): boolean { + return clampZoom(factor) < MAX_ZOOM_LEVEL - EPSILON +} + +export function canZoomOut(factor: number): boolean { + return clampZoom(factor) > MIN_ZOOM_LEVEL + EPSILON +} + +export function zoomPercent(factor: number): number { + return Math.round(clampZoom(factor) * 100) +} diff --git a/packages/core/src/agent-gateway.ts b/packages/core/src/agent-gateway.ts index fa1417cd..29f2c239 100644 --- a/packages/core/src/agent-gateway.ts +++ b/packages/core/src/agent-gateway.ts @@ -1429,6 +1429,22 @@ const modelWorkPackage = (run: RunRecord) => { visibility: "tool_only" as const, evidence_kind: "lsp_query" as EvidenceKind, }, + // D4 (S1-v3.5): debug session evidence artifact (debug tool produces at terminate). + { + ref_id: "artifact:debug_session", + path: "DEBUG_SESSION.json", + artifact_type: "debug_session", + visibility: "tool_only" as const, + evidence_kind: "debug_session" as EvidenceKind, + }, + // P4A (S1-v3.5): profiling evidence artifact (profile tool produces after collect→normalize). + { + ref_id: "artifact:profile_result", + path: "PROFILE_RESULT.json", + artifact_type: "profile_result", + visibility: "tool_only" as const, + evidence_kind: "profile" as EvidenceKind, + }, ], allowed_reads: [ "RUN_CONTEXT.md", diff --git a/packages/core/src/deepagent/plan-controller.ts b/packages/core/src/deepagent/plan-controller.ts index 51028be2..4ee62577 100644 --- a/packages/core/src/deepagent/plan-controller.ts +++ b/packages/core/src/deepagent/plan-controller.ts @@ -23,7 +23,12 @@ export type StaleReason = | "diagnostics_error" // L4 (S1-v3.4): post-edit LSP diagnostics surfaced an error (high+ only) export type PlanLatch = "fresh" | "stale" -export type PlanStepStatus = "pending" | "active" | "done" | "cancelled" +// U10: `blocked` is an HONEST terminal state for a step the model cannot finish (missing access, +// external dependency, ambiguous requirement). It is treated as RESOLVED for completion (so it does +// not deadlock finalize the way pending/active do), but it forces the run to needs_human at finalize +// so the operator sees WHY the plan could not be fully executed — this is the "or explain the +// blocker" escape hatch that keeps the model from marking a step falsely `done` to satisfy the gate. +export type PlanStepStatus = "pending" | "active" | "done" | "cancelled" | "blocked" export type PlanStep = { readonly step_id: string @@ -35,6 +40,9 @@ export type PlanStep = { // U4 reserve: a step may be delegated to a subagent; evidence is the subagent's returned summary. readonly assigned_agent?: string | null readonly evidence?: readonly string[] + // U10: why a step is `blocked` (or any short note the model attaches). Surfaced in the completion + // report so the needs_human handoff explains the blocker instead of just naming the step. + readonly note?: string | null } // The structural plan. Persisted in DocumentStore (type "plan", scope "run:"). Its @@ -134,6 +142,7 @@ export type PlanStepInput = { readonly status?: string readonly acceptance?: string | null readonly assigned_agent?: string | null + readonly note?: string | null } export type PlanInput = { readonly goal: string @@ -142,22 +151,41 @@ export type PlanInput = { readonly active_step_id?: string | null } -const STEP_STATUSES: ReadonlySet = new Set(["pending", "active", "done", "cancelled"]) -const normStatus = (s: string | undefined): PlanStepStatus => - s && STEP_STATUSES.has(s as PlanStepStatus) ? (s as PlanStepStatus) : "pending" +const STEP_STATUSES: ReadonlySet = new Set(["pending", "active", "done", "cancelled", "blocked"]) +const STATUS_ALIASES: Record = { + completed: "done", + in_progress: "active", + in_review: "active", + skipped: "cancelled", + stuck: "blocked", +} +const normStatus = (s: string | undefined): PlanStepStatus => { + const status = s?.trim().toLowerCase() + if (!status) return "pending" + if (STEP_STATUSES.has(status as PlanStepStatus)) return status as PlanStepStatus + return STATUS_ALIASES[status] ?? "pending" +} // Build a PlanDoc from the tool's loose input. Preserves an existing plan_id/created_at when the // model is UPDATING (re-writing) the plan rather than creating it, so the run-state plan keeps a -// stable identity across edits. Assigns step ids by index when omitted. +// stable identity across edits. Assigns step ids by index when omitted. Evidence is runtime-owned +// (never taken from tool input): a step carries forward the evidence recorded on the matching +// previous step so re-writing the plan does not wipe accumulated proof. export const buildPlanFromInput = (sessionId: string, input: PlanInput, previous?: PlanDoc | null): PlanDoc => { - const steps: PlanStep[] = input.steps.map((s, i) => ({ - step_id: s.step_id ?? `step_${i + 1}`, - title: s.title, - status: normStatus(s.status), - acceptance: s.acceptance ?? null, - assigned_agent: s.assigned_agent ?? null, - evidence: [], - })) + const priorById = new Map((previous?.steps ?? []).map((s) => [s.step_id, s] as const)) + const steps: PlanStep[] = input.steps.map((s, i) => { + const stepId = s.step_id ?? `step_${i + 1}` + const prior = priorById.get(stepId) + return { + step_id: stepId, + title: s.title, + status: normStatus(s.status), + acceptance: s.acceptance ?? null, + assigned_agent: s.assigned_agent ?? null, + evidence: prior?.evidence ?? [], + note: s.note ?? prior?.note ?? null, + } + }) const active = input.active_step_id ?? steps.find((s) => s.status === "active")?.step_id ?? null return { plan_id: previous?.plan_id ?? `plan_${randomUUID()}`, @@ -213,6 +241,7 @@ export type CompletionReport = { readonly goal: string readonly done: readonly string[] // step titles completed readonly cancelled: readonly string[] // step titles cancelled + readonly blocked: readonly string[] // U10: step titles blocked, each with its note if present readonly outstanding: readonly string[] // step titles still pending/active readonly evidence: readonly string[] readonly complete: boolean // true only when nothing outstanding @@ -221,6 +250,12 @@ export type CompletionReport = { export const buildCompletionReport = (plan: PlanDoc): CompletionReport => { const done = plan.steps.filter((s) => s.status === "done").map((s) => s.title) const cancelled = plan.steps.filter((s) => s.status === "cancelled").map((s) => s.title) + // U10: a blocked step is RESOLVED for the purpose of `complete` (it will never finish on its own, + // so leaving it outstanding would deadlock finalize behind the escape hatch). Its note travels with + // the title so the needs_human suggestion explains the blocker. + const blocked = plan.steps + .filter((s) => s.status === "blocked") + .map((s) => (s.note && s.note.trim() !== "" ? `${s.title} (${s.note.trim()})` : s.title)) const outstanding = plan.steps.filter((s) => s.status === "pending" || s.status === "active").map((s) => s.title) const evidence = plan.steps.flatMap((s) => s.evidence ?? []) return { @@ -228,8 +263,163 @@ export const buildCompletionReport = (plan: PlanDoc): CompletionReport => { goal: plan.goal, done, cancelled, + blocked, outstanding, evidence, complete: outstanding.length === 0, } } + +// U10: true when the plan is complete BUT some step is blocked. Finalize is allowed (not deadlocked), +// yet the run must route to needs_human so a human sees the blocker rather than a clean "done". +export const hasBlockedSteps = (plan: PlanDoc | null): boolean => + plan != null && plan.steps.some((s) => s.status === "blocked") + +// --- U10 step-reporting: status diff, snapshot, nudge, evidence -------------------------------- +// These power the "execute a step -> report a step -> update a step" closed loop. The runtime NEVER +// infers a step is done; it only (a) re-surfaces the model's own plan each turn so it can report, +// (b) nudges (soft, never blocks) when many edits happened without a plan update, and (c) computes +// the status DIFF from before/after itself so the summary can't drift from the model's prose. + +const STATUS_MARK: Record = { + done: "x", + cancelled: "-", + blocked: "!", + active: ">", + pending: " ", +} + +// A single status transition, computed by the runtime from prev vs next plan (not model self-report). +export type StepStatusChange = { + readonly step_id: string + readonly title: string + readonly from: PlanStepStatus | null // null when the step is newly added + readonly to: PlanStepStatus +} + +// Diff two plan docs by step_id. Reports steps whose status changed (or that were newly added). Used +// for the tool-output summary and the plan.updated event so logs/UI show WHAT changed, not just the +// new state. A removed step is not reported (the model chose to drop it; cancelled is the honest path). +export const diffStepStatuses = (previous: PlanDoc | null | undefined, next: PlanDoc): readonly StepStatusChange[] => { + const priorById = new Map((previous?.steps ?? []).map((s) => [s.step_id, s] as const)) + const changes: StepStatusChange[] = [] + for (const s of next.steps) { + const prior = priorById.get(s.step_id) + if (!prior) { + changes.push({ step_id: s.step_id, title: s.title, from: null, to: s.status }) + } else if (prior.status !== s.status) { + changes.push({ step_id: s.step_id, title: s.title, from: prior.status, to: s.status }) + } + } + return changes +} + +// True when a plan write actually moved at least one step's status (or added a step). Used to reset +// the "mutations since last report" counter ONLY on a real status change — a no-op plan re-write +// (same statuses) must NOT clear the nudge, otherwise the model could silence the reminder with an +// empty update ("report theater"). +export const planStatusesChanged = (previous: PlanDoc | null | undefined, next: PlanDoc): boolean => + diffStepStatuses(previous, next).length > 0 + +// Render a status transition as "Title: from→to" (from omitted for a new step). +export const formatStepChange = (c: StepStatusChange): string => + c.from === null ? `${c.title}: →${c.to}` : `${c.title}: ${c.from}→${c.to}` + +// Compact, constant-size plan snapshot re-injected into context each turn (high+ only) so the model +// can SEE its own checklist and report against it. One line per step; goal + progress header. We +// deliberately omit acceptance/assumptions/evidence to keep this small (it is re-injected every +// turn, so it must not grow with history). +export const renderPlanSnapshot = (plan: PlanDoc): string => { + const { done, total } = planProgress(plan) + const active = plan.steps.find((s) => s.step_id === plan.active_step_id) ?? null + const lines = plan.steps.map((s) => `[${STATUS_MARK[s.status]}] ${s.title}`) + const header = `Current plan (${done}/${total} done) — goal: ${plan.goal}` + const activeLine = active ? `Active step: ${active.title}` : "No step is marked active." + return `${header}\n${lines.join("\n")}\n${activeLine}` +} + +// Progress-nudge budget (the COUNT BACKSTOP of the hybrid trigger). This is deliberately NOT the +// primary signal: raw edit count conflates "the step is genuinely large" with "the model forgot to +// report". The count only guarantees the model is reminded eventually when no semantic boundary +// fires (e.g. a workspace with no validation configured). It scales by mode so stricter modes are +// reminded sooner: xhigh/max/ultra (autonomous, must stay tight) at 4; high (lenient) at 6. +export const NUDGE_MUTATION_STRICT = 4 +export const NUDGE_MUTATION_LENIENT = 6 +// Back-compat alias (older callers/tests referenced a single constant). Prefer nudgeMutationThreshold. +export const NUDGE_MUTATION_THRESHOLD = NUDGE_MUTATION_STRICT + +export const nudgeMutationThreshold = (mode: AgentMode | string): number => + hardGateStrict(mode) ? NUDGE_MUTATION_STRICT : NUDGE_MUTATION_LENIENT + +// Why the nudge fired this turn — lets the caller phrase the reminder honestly. +export type NudgeTrigger = "validation_passed" | "mutation_backstop" | null + +// Hybrid progress-report trigger. Fires ONLY when the plan still has unresolved work +// (pending/active) — a finished plan is never nagged. Given that, it fires on either: +// (a) SEMANTIC (primary): a validation just went (back) to passing since the last plan update, and +// the model made at least one edit since — a natural "a step probably just finished" moment +// the runtime already observes. Precise: it aligns to real completion boundaries, not a count. +// (b) COUNT BACKSTOP: >= mode-scaled mutating calls since the last status change — the catch-all +// for runs with no validation signal, so the model is always reminded eventually. +// Advisory only: the caller injects a reminder, never a block (avoids report theater / deadlock). +export const nudgeTrigger = ( + plan: PlanDoc | null, + input: { mutationsSinceReport: number; validationPassedSinceReport: boolean; mode: AgentMode | string }, +): NudgeTrigger => { + if (plan == null) return null + const hasOutstanding = plan.steps.some((s) => s.status === "pending" || s.status === "active") + if (!hasOutstanding) return null + // Semantic first: a fresh pass + at least one edit since last report is the strongest "step done" + // signal. Requiring >=1 mutation avoids nagging when the pass merely confirms an already-reported + // step (no new work happened since the last plan update). + if (input.validationPassedSinceReport && input.mutationsSinceReport >= 1) return "validation_passed" + if (input.mutationsSinceReport >= nudgeMutationThreshold(input.mode)) return "mutation_backstop" + return null +} + +// Back-compat boolean wrapper. New callers should use nudgeTrigger (it also says WHY). +export const shouldNudgeReport = ( + plan: PlanDoc | null, + mutationsSinceReport: number, + opts?: { validationPassedSinceReport?: boolean; mode?: AgentMode | string }, +): boolean => + nudgeTrigger(plan, { + mutationsSinceReport, + validationPassedSinceReport: opts?.validationPassedSinceReport ?? false, + // Default to the strict threshold when no mode is supplied (matches the old constant). + mode: opts?.mode ?? "max", + }) !== null + +export const PROGRESS_NUDGE = (trigger: NudgeTrigger, mutations: number): string => { + const lead = + trigger === "validation_passed" + ? `A validation just passed and you have made ${mutations} change(s) since your last plan update.` + : `You have made ${mutations} file/command changes without updating your plan.` + return `${lead} If the active step is complete, call the \`plan\` tool now: mark it \`done\`, set the next step \`active\`. If you are stuck, mark the step \`blocked\` with a note. Do not batch several finished steps into one late update.` +} + +// U10 / P2-E: attach runtime evidence to steps that JUST moved to `done`. The model reports the +// status; the runtime supplies the proof (latest validation summary) so the completion report is +// backed by facts, not the model's word. Returns a new plan (pure); only newly-done steps that have +// no evidence yet receive the summary, so re-writes don't duplicate it. +export const attachEvidenceToNewlyDone = ( + previous: PlanDoc | null | undefined, + next: PlanDoc, + evidenceSummary: string | null, +): PlanDoc => { + if (!evidenceSummary || evidenceSummary.trim() === "") return next + const priorById = new Map((previous?.steps ?? []).map((s) => [s.step_id, s] as const)) + let changed = false + const steps = next.steps.map((s) => { + const prior = priorById.get(s.step_id) + const justDone = s.status === "done" && prior?.status !== "done" + if (justDone && (s.evidence == null || s.evidence.length === 0)) { + changed = true + return { ...s, evidence: [evidenceSummary] } + } + return s + }) + return changed ? { ...next, steps } : next +} + + diff --git a/packages/core/src/deepagent/session-state.ts b/packages/core/src/deepagent/session-state.ts index dec9d49c..40a921a6 100644 --- a/packages/core/src/deepagent/session-state.ts +++ b/packages/core/src/deepagent/session-state.ts @@ -21,6 +21,7 @@ import { initialPlanLatch, markStale, clearStale, + planStatusesChanged, type PlanLatchState, type StaleReason, type PlanDoc, @@ -45,6 +46,14 @@ export type SessionRunState = { // Kept on run state (hot path, atomically persisted) — graduated into the durable run-graph as a // `plan` doc at run close, mirroring how DESIGN.md is materialized. plan: PlanDoc | null + // U10 step-reporting: count of mutating tool calls since the model last CHANGED a plan step's + // status. Drives the progress-nudge count backstop (nudgeTrigger). Reset to 0 only when setPlan + // detects a real status change — a no-op plan re-write must not silence the nudge. + mutationsSinceReport: number + // U10 hybrid nudge: set true when a validation run went (back) to all-passing since the last plan + // update. The SEMANTIC primary trigger for the progress nudge ("a step probably just finished"). + // Reset with the counter on a real status change. + validationPassedSinceReport: boolean createdAt: string completedAt: string | null } @@ -75,6 +84,8 @@ export const getOrCreate = (sessionId: string, mode: AgentMode): SessionRunState runId: `run_${randomUUID()}`, planLatch: initialPlanLatch(), plan: null, + mutationsSinceReport: 0, + validationPassedSinceReport: false, createdAt: new Date().toISOString(), completedAt: null, } @@ -124,6 +135,11 @@ export const recordValidation = (sessionId: string, results: ValidationResult[], // flip the latch from truth, not from the model's self-report. if (results.some((r) => !r.passed)) { state.planLatch = markStale(state.planLatch, "validation_failed") + } else if (results.length > 0) { + // U10 hybrid nudge: an all-passing validation is the SEMANTIC signal that a step probably just + // finished. Latch it (cleared on the next real plan status change) so the nudge can fire on this + // completion boundary rather than waiting for the count backstop. + state.validationPassedSinceReport = true } saveToDisk() } @@ -141,6 +157,13 @@ export const advanceToNextRound = (sessionId: string, decision: import("./mode") export const setPlan = (sessionId: string, plan: PlanDoc): void => { const state = sessions.get(sessionId) if (!state) return + // U10: reset the progress-nudge state ONLY when the model actually moved a step's status (or + // added a step). A no-op re-write leaves the counter/flag running so the nudge is not silenced by + // an empty update ("report theater"). + if (planStatusesChanged(state.plan, plan)) { + state.mutationsSinceReport = 0 + state.validationPassedSinceReport = false + } state.plan = plan state.planLatch = clearStale({ ...state.planLatch, plan_id: plan.plan_id }) saveToDisk() @@ -148,6 +171,32 @@ export const setPlan = (sessionId: string, plan: PlanDoc): void => { export const getPlan = (sessionId: string): PlanDoc | null => sessions.get(sessionId)?.plan ?? null +// U10: count one mutating tool call toward the progress-nudge budget. Called after a mutating tool +// executes. No-op when there is no plan (the nudge only applies once the model has a plan to report +// against). +export const recordMutation = (sessionId: string): void => { + const state = sessions.get(sessionId) + if (!state || state.plan == null) return + state.mutationsSinceReport += 1 + saveToDisk() +} + +export const mutationsSinceReport = (sessionId: string): number => sessions.get(sessionId)?.mutationsSinceReport ?? 0 + +export const validationPassedSinceReport = (sessionId: string): boolean => + sessions.get(sessionId)?.validationPassedSinceReport ?? false + +// U10 / P2-E: a compact summary of the latest validation run, used as step evidence when a step +// moves to `done`. Null when nothing has been validated yet. +export const lastValidationSummary = (sessionId: string): string | null => { + const state = sessions.get(sessionId) + if (!state || state.lastValidationResults.length === 0) return null + const results = state.lastValidationResults + const passed = results.filter((r) => r.passed).length + const cmds = results.map((r) => `${r.command}${r.passed ? "✓" : "✗"}`).join(", ") + return `validation ${passed}/${results.length} passed: ${cmds}` +} + // U1: flip the latch to stale from a RUNTIME signal (never from the model). Idempotent on reason. export const markPlanStale = (sessionId: string, reason: StaleReason): void => { const state = sessions.get(sessionId) @@ -238,6 +287,9 @@ function normalizeState(state: SessionRunState): SessionRunState { // Backfill: sessions persisted before U1 have no planLatch/plan on disk. planLatch: state.planLatch ?? initialPlanLatch(), plan: state.plan ?? null, + // Backfill: sessions persisted before U10 have no counter on disk. + mutationsSinceReport: state.mutationsSinceReport ?? 0, + validationPassedSinceReport: state.validationPassedSinceReport ?? false, } sessions.set(state.sessionId, normalized) return normalized diff --git a/packages/core/src/provider-official.ts b/packages/core/src/provider-official.ts new file mode 100644 index 00000000..61027b75 --- /dev/null +++ b/packages/core/src/provider-official.ts @@ -0,0 +1,46 @@ +/** + * Official provider identity — dependency-free leaf module. + * + * These are plain constants (a string tuple + a Set + a predicate) with ZERO + * imports. They live in their own module — NOT in `provider.ts` — because the + * browser/renderer (app) needs them, and `provider.ts` transitively pulls in + * `./schema` -> `./util/hash` -> node `crypto` (`createHash`), which Vite + * externalizes for the browser and would crash the renderer at load time. + * + * `provider.ts` re-exports these so existing backend imports of + * `@deepagent-code/core/provider` keep working unchanged. + */ + +/** + * The fixed set of first-party ("official") providers. Single source of truth. + * + * The Zhipu/Z.AI family is four distinct API faces (2 brands × 2 billing planes), + * all resolved from the models.dev catalog with the `@ai-sdk/openai-compatible` + * protocol against a fixed endpoint: + * - `zhipuai` open.bigmodel.cn /api/paas/v4 (pay-as-you-go, CN) + * - `zhipuai-coding-plan` open.bigmodel.cn /api/coding/paas/v4 (subscription, CN) + * - `zai` api.z.ai /api/paas/v4 (pay-as-you-go, intl) + * - `zai-coding-plan` api.z.ai /api/coding/paas/v4 (subscription, intl) + * Each takes its own API key from the auth key store (users connect only the ones + * they hold); coding-plan thinking/billing keys off the catalog `api.url`, not config. + */ +export const OFFICIAL_PROVIDER_IDS = [ + "openai", + "deepseek", + "anthropic", + "zhipuai", + "zhipuai-coding-plan", + "zai", + "zai-coding-plan", + "xai", + "google", +] as const + +export type OfficialProviderID = (typeof OFFICIAL_PROVIDER_IDS)[number] + +export const OFFICIAL_PROVIDER_ID_SET: ReadonlySet = new Set(OFFICIAL_PROVIDER_IDS) + +/** True when `providerID` is one of the fixed official providers. */ +export function isOfficialProvider(providerID: string): boolean { + return OFFICIAL_PROVIDER_ID_SET.has(providerID) +} diff --git a/packages/core/src/provider.ts b/packages/core/src/provider.ts index 801960c1..55cfa1ee 100644 --- a/packages/core/src/provider.ts +++ b/packages/core/src/provider.ts @@ -22,6 +22,23 @@ export const ID = Schema.String.pipe( ) export type ID = typeof ID.Type +// The closed set of first-party "official" providers. These are the only ids whose credentials come +// from the auth key store and whose identity/protocol is fixed by the catalog. Every other provider +// id — including other models.dev catalog entries — is treated as a user-configured third-party +// provider (credentials from config `options.apiKey` or env). This list is the single source of +// truth shared by the backend provider loader and the app connect UI; keep them in sync. +// Order is display order (recommended-first) in the app. +// +// The constants live in the dependency-free `./provider-official` leaf so the browser/renderer can +// import them WITHOUT pulling this module's `./schema` -> `./util/hash` -> node `crypto` chain +// (which Vite externalizes and would crash the renderer). Re-exported here for backend callers. +export { + OFFICIAL_PROVIDER_IDS, + OFFICIAL_PROVIDER_ID_SET, + isOfficialProvider, + type OfficialProviderID, +} from "./provider-official" + export const AISDK = Schema.Struct({ type: Schema.Literal("aisdk"), package: Schema.String, diff --git a/packages/core/src/v1/config/mcp.ts b/packages/core/src/v1/config/mcp.ts index 3eaeabf0..60a20967 100644 --- a/packages/core/src/v1/config/mcp.ts +++ b/packages/core/src/v1/config/mcp.ts @@ -22,7 +22,8 @@ export const Local = Schema.Struct({ description: "Command and arguments to run the MCP server", }), environment: Schema.optional(Schema.Record(Schema.String, Schema.String)).annotate({ - description: "Environment variables to set when running the MCP server", + description: + "Environment variables to set when running the MCP server. M-CRED (S1-v3.5): a value may be a literal, a `${VAR}` / `${VAR:-default}` env reference resolved from the process environment at connect time, or a `secret://` keychain handle resolved from the OS keychain at connect time. Secret credentials are stored as references/handles — never as plaintext in this file. A missing `${VAR}` warns (by name) but does not block.", }), enabled: Schema.optional(Schema.Boolean).annotate({ description: "Enable or disable the MCP server on startup", @@ -59,7 +60,8 @@ export const Remote = Schema.Struct({ description: "Enable or disable the MCP server on startup", }), headers: Schema.optional(Schema.Record(Schema.String, Schema.String)).annotate({ - description: "Headers to send with the request", + description: + "Headers to send with the request. M-CRED (S1-v3.5): a value may be a literal, a `${VAR}` / `${VAR:-default}` env reference resolved from the process environment at connect time, or a `secret://` keychain handle resolved from the OS keychain at connect time. Secret-bearing headers (e.g. Authorization) are stored as references/handles — never as plaintext in this file. A missing `${VAR}` warns (by name) but does not block.", }), oauth: Schema.optional(Schema.Union([OAuth, Schema.Literal(false)])).annotate({ description: "OAuth authentication configuration for the MCP server. Set to false to disable OAuth auto-detection.", diff --git a/packages/core/test/deepagent/plan-controller.test.ts b/packages/core/test/deepagent/plan-controller.test.ts index 5c195afd..94e4a3e4 100644 --- a/packages/core/test/deepagent/plan-controller.test.ts +++ b/packages/core/test/deepagent/plan-controller.test.ts @@ -7,8 +7,25 @@ import { isLightweightMode, isMutatingTool, createPlanDoc, + buildPlanFromInput, + planProgress, planScope, DEFAULT_REPLAN_LIMIT, + buildCompletionReport, + hasBlockedSteps, + diffStepStatuses, + planStatusesChanged, + formatStepChange, + renderPlanSnapshot, + shouldNudgeReport, + nudgeTrigger, + nudgeMutationThreshold, + attachEvidenceToNewlyDone, + NUDGE_MUTATION_THRESHOLD, + NUDGE_MUTATION_STRICT, + NUDGE_MUTATION_LENIENT, + PROGRESS_NUDGE, + type PlanDoc, } from "../../src/deepagent/plan-controller" import { planGate, stopHookGate, HookPolicy } from "../../src/deepagent/hooks" @@ -171,4 +188,213 @@ describe("plan doc scaffold", () => { test("planScope reuses the run scope", () => { expect(planScope("abc")).toBe("run:abc") }) + + test("buildPlanFromInput accepts todo status vocabulary", () => { + const doc = buildPlanFromInput("sess1", { + goal: "finish docs", + steps: [ + { title: "write", status: "completed" }, + { title: "review", status: "in_progress" }, + ], + }) + + expect(doc.steps.map((step) => step.status)).toEqual(["done", "active"]) + expect(doc.active_step_id).toBe("step_2") + expect(planProgress(doc)).toEqual({ done: 1, total: 2 }) + }) + + test("buildPlanFromInput accepts blocked + skipped/stuck aliases and carries note", () => { + const doc = buildPlanFromInput("sess1", { + goal: "ship", + steps: [ + { title: "a", status: "blocked", note: "waiting on API key" }, + { title: "b", status: "skipped" }, + { title: "c", status: "stuck" }, + ], + }) + expect(doc.steps.map((s) => s.status)).toEqual(["blocked", "cancelled", "blocked"]) + expect(doc.steps[0].note).toBe("waiting on API key") + }) +}) + +// U10 step-reporting ----------------------------------------------------------------------------- +const mkPlan = (steps: PlanDoc["steps"], activeId: string | null = null): PlanDoc => ({ + plan_id: "p1", + session_id: "s1", + goal: "ship the feature", + assumptions: [], + steps, + active_step_id: activeId, + created_at: "2026-01-01T00:00:00.000Z", +}) + +describe("blocked status + completion report", () => { + test("blocked step is resolved (not outstanding) but reported with its note", () => { + const plan = mkPlan([ + { step_id: "s1", title: "build", status: "done" }, + { step_id: "s2", title: "deploy", status: "blocked", note: "no prod creds" }, + ]) + const r = buildCompletionReport(plan) + expect(r.outstanding).toEqual([]) // blocked does NOT keep the plan incomplete + expect(r.complete).toBe(true) // so finalize is not deadlocked + expect(r.blocked).toEqual(["deploy (no prod creds)"]) + }) + + test("pending/active still block completion", () => { + const plan = mkPlan([ + { step_id: "s1", title: "build", status: "active" }, + { step_id: "s2", title: "docs", status: "pending" }, + ]) + expect(buildCompletionReport(plan).complete).toBe(false) + }) + + test("hasBlockedSteps reflects any blocked step", () => { + expect(hasBlockedSteps(mkPlan([{ step_id: "s1", title: "t", status: "done" }]))).toBe(false) + expect(hasBlockedSteps(mkPlan([{ step_id: "s1", title: "t", status: "blocked" }]))).toBe(true) + expect(hasBlockedSteps(null)).toBe(false) + }) +}) + +describe("status diff (runtime-computed, not model prose)", () => { + const prev = mkPlan([ + { step_id: "s1", title: "build", status: "active" }, + { step_id: "s2", title: "docs", status: "pending" }, + ]) + + test("reports only steps whose status changed", () => { + const next = mkPlan([ + { step_id: "s1", title: "build", status: "done" }, + { step_id: "s2", title: "docs", status: "pending" }, + ]) + const changes = diffStepStatuses(prev, next) + expect(changes).toHaveLength(1) + expect(formatStepChange(changes[0])).toBe("build: active→done") + expect(planStatusesChanged(prev, next)).toBe(true) + }) + + test("a newly added step is reported with no `from`", () => { + const next = mkPlan([ + { step_id: "s1", title: "build", status: "active" }, + { step_id: "s2", title: "docs", status: "pending" }, + { step_id: "s3", title: "release", status: "pending" }, + ]) + const changes = diffStepStatuses(prev, next) + expect(changes).toHaveLength(1) + expect(formatStepChange(changes[0])).toBe("release: →pending") + }) + + test("a no-op re-write reports no change (nudge must not be silenced)", () => { + expect(diffStepStatuses(prev, prev)).toEqual([]) + expect(planStatusesChanged(prev, prev)).toBe(false) + }) + + test("null previous treats every step as new", () => { + expect(planStatusesChanged(null, prev)).toBe(true) + expect(diffStepStatuses(null, prev)).toHaveLength(2) + }) +}) + +describe("plan snapshot render", () => { + test("compact one-line-per-step with progress header and active line", () => { + const plan = mkPlan( + [ + { step_id: "s1", title: "build", status: "done" }, + { step_id: "s2", title: "test", status: "active" }, + { step_id: "s3", title: "deploy", status: "blocked", note: "creds" }, + { step_id: "s4", title: "docs", status: "pending" }, + ], + "s2", + ) + const out = renderPlanSnapshot(plan) + expect(out).toContain("Current plan (1/4 done)") + expect(out).toContain("[x] build") + expect(out).toContain("[>] test") + expect(out).toContain("[!] deploy") + expect(out).toContain("[ ] docs") + expect(out).toContain("Active step: test") + }) +}) + +describe("progress nudge (hybrid: semantic primary + mode-scaled count backstop)", () => { + const plan = mkPlan([ + { step_id: "s1", title: "build", status: "active" }, + { step_id: "s2", title: "docs", status: "pending" }, + ]) + const donePlan = mkPlan([{ step_id: "s1", title: "build", status: "done" }]) + + test("mode-scaled backstop: xhigh/max strict (4), high lenient (6)", () => { + expect(nudgeMutationThreshold("max")).toBe(NUDGE_MUTATION_STRICT) + expect(nudgeMutationThreshold("xhigh")).toBe(NUDGE_MUTATION_STRICT) + expect(nudgeMutationThreshold("ultra")).toBe(NUDGE_MUTATION_STRICT) + expect(nudgeMutationThreshold("high")).toBe(NUDGE_MUTATION_LENIENT) + }) + + test("count backstop fires at the mode-scaled threshold", () => { + const under = { mutationsSinceReport: 3, validationPassedSinceReport: false, mode: "max" as const } + const at = { mutationsSinceReport: 4, validationPassedSinceReport: false, mode: "max" as const } + expect(nudgeTrigger(plan, under)).toBeNull() + expect(nudgeTrigger(plan, at)).toBe("mutation_backstop") + // high is more lenient: 4 is not enough, 6 is + expect(nudgeTrigger(plan, { mutationsSinceReport: 4, validationPassedSinceReport: false, mode: "high" })).toBeNull() + expect(nudgeTrigger(plan, { mutationsSinceReport: 6, validationPassedSinceReport: false, mode: "high" })).toBe( + "mutation_backstop", + ) + }) + + test("SEMANTIC primary: a fresh validation pass + >=1 edit fires well before the count backstop", () => { + const t = nudgeTrigger(plan, { mutationsSinceReport: 1, validationPassedSinceReport: true, mode: "max" }) + expect(t).toBe("validation_passed") + }) + + test("validation pass with ZERO edits since last report does NOT nudge (nothing new happened)", () => { + const t = nudgeTrigger(plan, { mutationsSinceReport: 0, validationPassedSinceReport: true, mode: "max" }) + expect(t).toBeNull() + }) + + test("never nudges when nothing is outstanding, regardless of trigger", () => { + expect(nudgeTrigger(donePlan, { mutationsSinceReport: 99, validationPassedSinceReport: true, mode: "max" })).toBeNull() + }) + + test("never nudges without a plan", () => { + expect(nudgeTrigger(null, { mutationsSinceReport: 99, validationPassedSinceReport: true, mode: "max" })).toBeNull() + }) + + test("PROGRESS_NUDGE phrasing reflects the trigger", () => { + expect(PROGRESS_NUDGE("validation_passed", 2)).toContain("validation just passed") + expect(PROGRESS_NUDGE("mutation_backstop", 5)).toContain("without updating your plan") + }) + + test("back-compat shouldNudgeReport wrapper still works", () => { + expect(shouldNudgeReport(plan, NUDGE_MUTATION_THRESHOLD - 1)).toBe(false) + expect(shouldNudgeReport(plan, NUDGE_MUTATION_THRESHOLD)).toBe(true) + expect(shouldNudgeReport(plan, 1, { validationPassedSinceReport: true })).toBe(true) + expect(shouldNudgeReport(donePlan, 99)).toBe(false) + expect(shouldNudgeReport(null, 99)).toBe(false) + }) +}) + +describe("evidence attachment (runtime supplies proof for newly-done steps)", () => { + const prev = mkPlan([ + { step_id: "s1", title: "build", status: "active" }, + { step_id: "s2", title: "docs", status: "pending" }, + ]) + test("attaches the validation summary only to a step that just moved to done", () => { + const next = mkPlan([ + { step_id: "s1", title: "build", status: "done" }, + { step_id: "s2", title: "docs", status: "pending" }, + ]) + const withEvidence = attachEvidenceToNewlyDone(prev, next, "validation 2/2 passed: tsc✓, test✓") + expect(withEvidence.steps[0].evidence).toEqual(["validation 2/2 passed: tsc✓, test✓"]) + expect(withEvidence.steps[1].evidence ?? []).toEqual([]) // not done -> no evidence attached + }) + test("no summary -> plan unchanged", () => { + const next = mkPlan([{ step_id: "s1", title: "build", status: "done" }]) + expect(attachEvidenceToNewlyDone(prev, next, null)).toBe(next) + }) + test("a step already done keeps its prior evidence (no duplicate)", () => { + const prevDone = mkPlan([{ step_id: "s1", title: "build", status: "done", evidence: ["run:1"] }]) + const nextDone = mkPlan([{ step_id: "s1", title: "build", status: "done", evidence: ["run:1"] }]) + const out = attachEvidenceToNewlyDone(prevDone, nextDone, "new summary") + expect(out.steps[0].evidence).toEqual(["run:1"]) + }) }) diff --git a/packages/core/test/deepagent/session-state-plan-latch.test.ts b/packages/core/test/deepagent/session-state-plan-latch.test.ts index 70d53a19..219b27da 100644 --- a/packages/core/test/deepagent/session-state-plan-latch.test.ts +++ b/packages/core/test/deepagent/session-state-plan-latch.test.ts @@ -76,3 +76,121 @@ describe("session-state plan latch", () => { expect(reloaded.planLatch.stale_reason).toBe("no_progress") }) }) + +// U10 step-reporting: the mutation-since-report counter and evidence plumbing on the production seam. +describe("session-state progress-nudge counter", () => { + beforeEach(() => { + SessionState.configure(mkdtempSync(path.join(tmpdir(), "plan-nudge-"))) + }) + + const plan = (steps: Array<{ id: string; status: string }>, activeId: string | null = null) => ({ + plan_id: "plan_x", + session_id: "sess", + goal: "g", + assumptions: [] as string[], + steps: steps.map((s) => ({ step_id: s.id, title: s.id, status: s.status as never })), + active_step_id: activeId, + created_at: new Date().toISOString(), + }) + + test("recordMutation is a no-op until a plan exists", () => { + SessionState.getOrCreate("nudge-s1", "high") + SessionState.recordMutation("nudge-s1") + expect(SessionState.mutationsSinceReport("nudge-s1")).toBe(0) + }) + + test("recordMutation counts once a plan exists", () => { + SessionState.getOrCreate("nudge-s2", "high") + SessionState.setPlan("nudge-s2", plan([{ id: "s1", status: "active" }], "s1")) + SessionState.recordMutation("nudge-s2") + SessionState.recordMutation("nudge-s2") + expect(SessionState.mutationsSinceReport("nudge-s2")).toBe(2) + }) + + test("a real status change resets the counter; a no-op re-write does not", () => { + SessionState.getOrCreate("nudge-s3", "high") + SessionState.setPlan("nudge-s3", plan([{ id: "s1", status: "active" }], "s1")) + SessionState.recordMutation("nudge-s3") + SessionState.recordMutation("nudge-s3") + // no-op re-write (same statuses) -> counter keeps running (no report theater) + SessionState.setPlan("nudge-s3", plan([{ id: "s1", status: "active" }], "s1")) + expect(SessionState.mutationsSinceReport("nudge-s3")).toBe(2) + // real status change -> reset + SessionState.setPlan("nudge-s3", plan([{ id: "s1", status: "done" }])) + expect(SessionState.mutationsSinceReport("nudge-s3")).toBe(0) + }) + + test("setPlan preserves evidence across a re-write (evidence is runtime-owned)", () => { + SessionState.getOrCreate("nudge-s4", "high") + SessionState.setPlan("nudge-s4", { + ...plan([{ id: "s1", status: "done" }]), + steps: [{ step_id: "s1", title: "build", status: "done", evidence: ["run:1"] }], + }) + // model re-writes the plan (adds a step) without repeating evidence + SessionState.setPlan("nudge-s4", { + ...plan([ + { id: "s1", status: "done" }, + { id: "s2", status: "active" }, + ]), + steps: [ + { step_id: "s1", title: "build", status: "done" }, + { step_id: "s2", title: "test", status: "active" }, + ], + }) + // buildPlanFromInput is where preservation happens; setPlan stores what it is given, so this test + // asserts the getPlan round-trip is intact for the stored value. + expect(SessionState.getPlan("nudge-s4")?.steps[0].step_id).toBe("s1") + }) + + test("lastValidationSummary reflects the latest validation run", () => { + SessionState.getOrCreate("nudge-s5", "high") + expect(SessionState.lastValidationSummary("nudge-s5")).toBeNull() + SessionState.recordValidation( + "nudge-s5", + [ + { command: "tsc", passed: true, exit_code: 0, output: "ok", duration_ms: 1 }, + { command: "test", passed: false, exit_code: 1, output: "err", duration_ms: 1 }, + ], + "mixed", + ) + const summary = SessionState.lastValidationSummary("nudge-s5") + expect(summary).toContain("1/2 passed") + expect(summary).toContain("tsc✓") + expect(summary).toContain("test✗") + }) + + test("validationPassedSinceReport: set by an all-pass run, reset on a real status change", () => { + SessionState.getOrCreate("nudge-s6", "high") + SessionState.setPlan("nudge-s6", plan([{ id: "s1", status: "active" }], "s1")) + expect(SessionState.validationPassedSinceReport("nudge-s6")).toBe(false) + // a failing run does NOT set the semantic flag (it marks the latch stale instead) + SessionState.recordValidation( + "nudge-s6", + [{ command: "tsc", passed: false, exit_code: 1, output: "err", duration_ms: 1 }], + "err", + ) + expect(SessionState.validationPassedSinceReport("nudge-s6")).toBe(false) + // an all-passing run sets it + SessionState.recordValidation( + "nudge-s6", + [{ command: "tsc", passed: true, exit_code: 0, output: "ok", duration_ms: 1 }], + "ok", + ) + expect(SessionState.validationPassedSinceReport("nudge-s6")).toBe(true) + // a real status change clears it (fresh reporting window) + SessionState.setPlan("nudge-s6", plan([{ id: "s1", status: "done" }])) + expect(SessionState.validationPassedSinceReport("nudge-s6")).toBe(false) + }) + + test("validationPassedSinceReport: a no-op plan re-write does NOT clear the flag", () => { + SessionState.getOrCreate("nudge-s7", "high") + SessionState.setPlan("nudge-s7", plan([{ id: "s1", status: "active" }], "s1")) + SessionState.recordValidation( + "nudge-s7", + [{ command: "tsc", passed: true, exit_code: 0, output: "ok", duration_ms: 1 }], + "ok", + ) + SessionState.setPlan("nudge-s7", plan([{ id: "s1", status: "active" }], "s1")) // no status change + expect(SessionState.validationPassedSinceReport("nudge-s7")).toBe(true) + }) +}) diff --git a/packages/deepagent-code/src/config/config.ts b/packages/deepagent-code/src/config/config.ts index b1acb06d..cb73d5a0 100644 --- a/packages/deepagent-code/src/config/config.ts +++ b/packages/deepagent-code/src/config/config.ts @@ -33,6 +33,8 @@ import { ConfigPaths } from "./paths" import { ConfigPlugin } from "./plugin" import { ConfigVariable } from "./variable" import { Npm } from "@deepagent-code/core/npm" +import { SettingsStore } from "@/settings/store" +import { OFFICIAL_PROVIDER_ID_SET } from "@deepagent-code/core/provider-official" import { withTransientReadRetry } from "@/util/effect-http-client" const log = Log.create({ service: "config" }) @@ -277,6 +279,164 @@ function writableGlobal(info: Info) { return next } +// ── First-party settings overlay ───────────────────────────────────────────────────────────────── +// First-party runtime settings live in SettingsStore (~/.deepagent/code/settings.json), NOT the +// user config file (which is reserved for third-party providers). To keep every existing reader +// working unchanged (backend gatewayConfig/wishModel read `provider.deepagent.options`; the frontend +// reads the synced config), we OVERLAY those settings onto the in-memory config on read, and +// INTERCEPT+STRIP them on write so they never land in the config file. + +// The DeepAgent first-party settings are surfaced under this pseudo-provider id (matches the historic +// `provider.deepagent.options` location that every reader already knows). +const DEEPAGENT_PSEUDO_PROVIDER_ID = "deepagent" + +// Transport keys that official providers accept only via SettingsStore (config is ignored for them). +const OFFICIAL_TRANSPORT_KEYS = ["headerTimeout", "chunkTimeout", "timeout", "maxRetries"] as const + +/** + * Merge SettingsStore values onto a config object (returns a shallow-cloned copy; never mutates input). + * - deepagent runtime settings → `provider.deepagent.options` (always; deepagent is not an official + * provider so this never triggers the official-conflict check in the provider loader). + * - official-provider transport → `provider..options` (only when `officialTransport` is true; + * the backend provider loader reads transport straight from SettingsStore, and overlaying an + * official id into the config the loader sees would trip the official-conflict rejection — so this + * overlay is for the FRONTEND view only, via getGlobal()). + */ +function overlaySettings(info: Info, settings: SettingsStore.Settings, officialTransport: boolean): Info { + if (!settings.deepagent && !(officialTransport && settings.providers)) return info + const provider = { ...(info.provider ?? {}) } + + if (settings.deepagent && Object.keys(settings.deepagent).length > 0) { + const existing = provider[DEEPAGENT_PSEUDO_PROVIDER_ID] ?? {} + provider[DEEPAGENT_PSEUDO_PROVIDER_ID] = { + name: "DeepAgent", + ...existing, + options: { ...(existing.options ?? {}), ...settings.deepagent }, + models: existing.models ?? {}, + } + } + + if (officialTransport && settings.providers) { + for (const [id, transport] of Object.entries(settings.providers)) { + if (!transport || Object.keys(transport).length === 0) continue + const existing = provider[id] ?? {} + provider[id] = { + ...existing, + options: { ...(existing.options ?? {}), ...transport }, + } + } + } + + return { ...info, provider } +} + +/** + * Pull first-party settings out of an incoming config patch and produce (a) the SettingsStore patch + * to persist and (b) a cleaned config with those keys removed so they never reach the config file. + */ +function extractSettingsPatch(config: Info): { + cleaned: Info + patch: { deepagent?: SettingsStore.DeepAgentSettings; providers?: Record } + hasPatch: boolean +} { + const patch: { + deepagent?: SettingsStore.DeepAgentSettings + providers?: Record + } = {} + if (!config.provider) return { cleaned: config, patch, hasPatch: false } + + const provider = { ...config.provider } + let changed = false + + // deepagent: the whole pseudo-provider entry is first-party — route its options, drop it from file. + const deepagent = provider[DEEPAGENT_PSEUDO_PROVIDER_ID] + if (deepagent) { + const opts = (deepagent.options ?? {}) as Record + patch.deepagent = { + promptMode: opts.promptMode as SettingsStore.PromptMode | undefined, + wishModel: typeof opts.wishModel === "string" ? opts.wishModel : undefined, + agentMode: opts.agentMode as SettingsStore.AgentMode | undefined, + selfLearning: opts.selfLearning as SettingsStore.SelfLearning | undefined, + runsDir: typeof opts.runsDir === "string" ? opts.runsDir : undefined, + allowProviderExecutedTools: + typeof opts.allowProviderExecutedTools === "boolean" ? opts.allowProviderExecutedTools : undefined, + allowProviderExecutedToolNames: Array.isArray(opts.allowProviderExecutedToolNames) + ? (opts.allowProviderExecutedToolNames.filter((i) => typeof i === "string") as string[]) + : undefined, + } + delete provider[DEEPAGENT_PSEUDO_PROVIDER_ID] + changed = true + } + + // official providers: route only the transport keys; the rest of an official entry is ignored by + // the loader anyway, so we drop the whole entry to keep the file third-party-only. + const providers: Record = {} + for (const id of Object.keys(provider)) { + if (!OFFICIAL_PROVIDER_ID_SET.has(id)) continue + const opts = (provider[id]?.options ?? {}) as Record + const transport: SettingsStore.TransportSettings = {} + for (const key of OFFICIAL_TRANSPORT_KEYS) { + if (key in opts) (transport as Record)[key] = opts[key] + } + if (Object.keys(transport).length > 0) providers[id] = transport + delete provider[id] + changed = true + } + if (Object.keys(providers).length > 0) patch.providers = providers + + const hasPatch = patch.deepagent !== undefined || patch.providers !== undefined + return { cleaned: changed ? { ...config, provider } : config, patch, hasPatch } +} + +/** + * One-shot migration: move any `provider.deepagent.options` from the config file into SettingsStore, + * then strip the `provider.deepagent` entry from the file so the config file is third-party-only. + * Idempotent: if SettingsStore already has deepagent settings we still strip the stale file entry. + */ +async function migrateFirstPartySettings() { + const file = globalConfigFile() + let text: string + try { + text = await fsNode.readFile(file, "utf8") + } catch { + return // no config file yet — nothing to migrate + } + let parsed: Record + try { + const value = ConfigParse.jsonc(text, "settings-migrate") + if (!isRecord(value)) return + ConfigParse.schema(ConfigV1.Info, value, "settings-migrate") // skip migration if the file is broken + parsed = value as Record + } catch { + return + } + const provider = isRecord(parsed.provider) ? parsed.provider : undefined + const deepagent = provider && isRecord(provider.deepagent) ? provider.deepagent : undefined + if (!deepagent) return + + const opts = isRecord(deepagent.options) ? deepagent.options : {} + const existing = await SettingsStore.read() + if (!existing.deepagent) { + await SettingsStore.update({ + deepagent: { + promptMode: opts.promptMode as SettingsStore.PromptMode | undefined, + wishModel: typeof opts.wishModel === "string" ? opts.wishModel : undefined, + agentMode: opts.agentMode as SettingsStore.AgentMode | undefined, + selfLearning: opts.selfLearning as SettingsStore.SelfLearning | undefined, + runsDir: typeof opts.runsDir === "string" ? opts.runsDir : undefined, + allowProviderExecutedTools: + typeof opts.allowProviderExecutedTools === "boolean" ? opts.allowProviderExecutedTools : undefined, + allowProviderExecutedToolNames: Array.isArray(opts.allowProviderExecutedToolNames) + ? (opts.allowProviderExecutedToolNames.filter((i) => typeof i === "string") as string[]) + : undefined, + }, + }) + } + // Strip provider.deepagent from the file (preserving comments/formatting for the rest). + const stripped = patchJsonc(text, { deepagent: undefined }, ["provider"]) + if (stripped !== text) await fsNode.writeFile(file, stripped).catch(() => {}) +} + export const layer = Layer.effect( Service, Effect.gen(function* () { @@ -362,6 +522,9 @@ export const layer = Layer.effect( // deepagent-code.jsonc and remove the old files, so there is one config file to edit. // Best-effort: a failure here must not block config loading (we still merge all names below). yield* Effect.promise(() => migrateGlobalConfigFiles()).pipe(Effect.catch(() => Effect.void)) + // Move any first-party runtime settings (provider.deepagent.options) out of the config file + // into SettingsStore, so the config file stays third-party-only. Best-effort. + yield* Effect.promise(() => migrateFirstPartySettings()).pipe(Effect.catch(() => Effect.void)) const file = globalConfigFile() if (!existsSync(file)) { yield* fs @@ -403,7 +566,12 @@ export const layer = Layer.effect( ) const getGlobal = Effect.fn("Config.getGlobal")(function* () { - return (yield* cachedGlobal).config + const base = (yield* cachedGlobal).config + // Frontend view: overlay first-party settings so the app renders current values. Official + // transport is included here (getGlobal is only read by the app / global routes, never by the + // provider loader), so the connect dialog can show/edit timeouts. + const settings = yield* Effect.promise(() => SettingsStore.read()) + return overlaySettings(base, settings, true) }) const ensureGitignore = Effect.fn("Config.ensureGitignore")(function* (dir: string) { @@ -731,7 +899,13 @@ export const layer = Layer.effect( ) const get = Effect.fn("Config.get")(function* () { - return yield* InstanceState.use(state, (s) => s.config) + const base = yield* InstanceState.use(state, (s) => s.config) + // Backend view: overlay ONLY the deepagent runtime settings (gatewayConfig/wishModel read them + // from provider.deepagent.options). Official-provider transport is deliberately NOT overlaid + // here — the provider loader reads transport straight from SettingsStore, and injecting an + // official id into the config it sees would trip the official-conflict rejection. + const settings = yield* Effect.promise(() => SettingsStore.read()) + return overlaySettings(base, settings, false) }) const directories = Effect.fn("Config.directories")(function* () { @@ -766,28 +940,40 @@ export const layer = Layer.effect( }) const updateGlobal = Effect.fn("Config.updateGlobal")(function* (config: Info) { + // Route first-party settings (deepagent runtime + official transport) to SettingsStore and strip + // them from the config payload so they never land in the third-party-only config file. + const { cleaned, patch, hasPatch } = extractSettingsPatch(config) + let settingsChanged = false + if (hasPatch) { + const result = yield* Effect.promise(() => SettingsStore.update(patch)) + settingsChanged = result.changed + } + const file = globalConfigFile() const before = (yield* readConfigFile(file)) ?? "{}" - const patch = writableGlobal(config) + const patchGlobal = writableGlobal(cleaned) let next: Info let changed: boolean if (!file.endsWith(".jsonc")) { const existing = ConfigParse.schema(ConfigV1.Info, ConfigParse.jsonc(before, file), file) - const merged = mergeDeep(writable(existing), patch) + const merged = mergeDeep(writable(existing), patchGlobal) const serialized = JSON.stringify(merged, null, 2) changed = serialized !== before if (changed) yield* fs.writeFileString(file, serialized).pipe(Effect.orDie) next = merged } else { - const updated = patchJsonc(before, patch) + const updated = patchJsonc(before, patchGlobal) next = ConfigParse.schema(ConfigV1.Info, ConfigParse.jsonc(updated, file), file) changed = updated !== before if (changed) yield* fs.writeFileString(file, updated).pipe(Effect.orDie) } if (changed) yield* invalidate() - return { info: next, changed } + // Re-overlay the persisted settings onto the returned info so the caller (app) immediately sees + // the values it just set, including official transport (this is the getGlobal-equivalent view). + const settings = yield* Effect.promise(() => SettingsStore.read()) + return { info: overlaySettings(next, settings, true), changed: changed || settingsChanged } }) return Service.of({ diff --git a/packages/deepagent-code/src/debug/adapter.ts b/packages/deepagent-code/src/debug/adapter.ts new file mode 100644 index 00000000..298c78fb --- /dev/null +++ b/packages/deepagent-code/src/debug/adapter.ts @@ -0,0 +1,276 @@ +import { which } from "@deepagent-code/core/util/which" +import * as Log from "@deepagent-code/core/util/log" +import { RuntimeBase } from "@/runtime/base" +import type { AdapterSpec } from "./types" + +const log = Log.create({ service: "debug.adapter" }) + +/** + * D2 (S1-v3.5): the debug-adapter registry. + * + * Mirrors the LSP server registry (`lsp/server.ts`): a declarative adapter + * `Info` definition + an on-demand "resolve the binary, build the launch spec" + * step, with graceful-missing handling (binary absent → a clear "please install + * X" message, NEVER a thrown Die — exactly how `lsp/server.ts` returns + * `undefined` and logs "please install …"). + * + * D1 owns the concrete `AdapterSpec` shape and consumes it in + * `DebugService.start`; D2 PRODUCES those specs. D2 never speaks DAP and never + * spawns anything itself — it only declares how to spawn and resolves the binary + * location (control-plane only). + * + * Base set ships with core: debugpy (Python), delve (Go), lldb (C/C++/Rust/ + * Swift). Domain-pack adapters (e.g. GDB for a native/systems-programming pack) + * register through `register()` when the pack activates, so the common core + * stays clean and an adapter is only visible while its pack is active. + */ +export namespace DebugAdapter { + // —— binary probe (injectable, mirrors RuntimeBase.make(probe)) —————————————— + + /** + * Locates an adapter executable on PATH. Pure detection — no spawn, no side + * effects. Injected so tests can simulate "installed" / "missing" without + * touching the real system, exactly like R0 injects its `PrivilegeProbe`. + */ + export interface BinaryProbe { + /** Resolve an executable to its absolute path, or null when absent. Mirrors `which`. */ + readonly locate: (command: string) => string | null + } + + /** Default probe: real PATH lookup via core's `which` (same as `lsp/server.ts`). */ + export const defaultProbe: BinaryProbe = { locate: (command) => which(command) } + + /** Test probe: only the named commands are "installed"; everything else is missing. */ + export const installedProbe = (installed: Iterable): BinaryProbe => { + const set = new Set(installed) + return { locate: (command) => (set.has(command) ? `/usr/bin/${command}` : null) } + } + + /** Test probe: every binary is missing (for graceful-missing assertions). */ + export const missingProbe: BinaryProbe = { locate: () => null } + + // —— adapter definition (declarative, mirrors lsp/server.ts `Info`) ——————————— + + export interface Info { + /** Stable adapter id, e.g. "debugpy" | "delve" | "lldb" | "gdb". */ + id: string + /** Languages this adapter serves, lowercase, e.g. ["python"] / ["c","cpp","rust"]. */ + languages: string[] + /** Privileges the adapter needs; declared here, enforced by R0's fail-closed gate. */ + privileges: RuntimeBase.PrivilegeSpec[] + /** Transport to the adapter. D1 implements "stdio"; "socket" is reserved. */ + transport: "stdio" | "socket" + /** Human-readable install guidance, surfaced when the binary is missing. */ + install: string + /** + * Resolve how to launch this adapter using the injected probe. Returns the + * command + args, or `undefined` when the binary is not installed — the + * registry then reports graceful-missing (no Die), same as an LSP server + * `spawn` returning `undefined`. + */ + spawn(probe: BinaryProbe): { command: string; args: string[] } | undefined + } + + // —— base set (ships with core) —————————————————————————————————————————————— + + /** + * Python — debugpy's DAP adapter, launched as `python -m debugpy.adapter`. + * Pure-Python debugging needs no special OS privilege. + */ + export const Debugpy: Info = { + id: "debugpy", + languages: ["python"], + privileges: [], + transport: "stdio", + install: "Install debugpy: `pip install debugpy` (run inside the project's interpreter/venv).", + spawn(probe) { + const python = probe.locate("python3") ?? probe.locate("python") + if (!python) return undefined + return { command: python, args: ["-m", "debugpy.adapter"] } + }, + } + + /** + * Go — Delve in DAP mode (`dlv dap`). Delve manages its own tracing backend; + * no ptrace privilege is declared at the DeepAgent layer. + */ + export const Delve: Info = { + id: "delve", + languages: ["go"], + privileges: [], + transport: "stdio", + install: "Install Delve: `go install github.com/go-delve/delve/cmd/dlv@latest` (provides `dlv dap`).", + spawn(probe) { + const dlv = probe.locate("dlv") + if (!dlv) return undefined + return { command: dlv, args: ["dap"] } + }, + } + + /** + * C / C++ / Rust / Swift — LLVM's `lldb-dap` (formerly `lldb-vscode`). Native + * attach/inspection goes through ptrace, declared for R0's fail-closed gate. + */ + export const Lldb: Info = { + id: "lldb", + languages: ["c", "cpp", "rust", "swift"], + privileges: [{ kind: "ptrace", reason: "lldb attaches to and inspects the debuggee process via ptrace" }], + transport: "stdio", + install: "Install LLVM/LLDB providing `lldb-dap` (e.g. `brew install llvm`, or your distro's lldb package).", + spawn(probe) { + const bin = probe.locate("lldb-dap") ?? probe.locate("lldb-vscode") + if (!bin) return undefined + return { command: bin, args: [] } + }, + } + + /** The adapters that ship with the common core (no domain pack required). */ + export const BASE_SET: readonly Info[] = [Debugpy, Delve, Lldb] + + // —— domain-pack contributed adapters ———————————————————————————————————————— + + /** + * GDB — `gdb --interpreter=dap` (GDB 14+). Contributed by a native/systems- + * programming domain pack, NOT part of the base set: it is only visible after + * a pack calls `register(GDB)` (see `registerGdb`). Like lldb, it declares the + * ptrace privilege for R0. + */ + export const GDB: Info = { + id: "gdb", + languages: ["c", "cpp", "rust"], + privileges: [{ kind: "ptrace", reason: "gdb attaches to and inspects the debuggee process via ptrace" }], + transport: "stdio", + install: "Install GDB 14 or newer (provides `gdb --interpreter=dap`).", + spawn(probe) { + const gdb = probe.locate("gdb") + if (!gdb) return undefined + return { command: gdb, args: ["--interpreter=dap"] } + }, + } + + // —— resolution result ———————————————————————————————————————————————————————— + + /** + * The outcome of resolving an adapter. Either an `AdapterSpec` ready for + * `DebugService.start`, or a graceful "not installed / not registered" report + * carrying a clear install message — never an exception. + */ + export type Resolution = + | { readonly available: true; readonly spec: AdapterSpec } + | { readonly available: false; readonly adapterId: string; readonly message: string } + + // —— registry ————————————————————————————————————————————————————————————————— + + /** + * The adapter registry D3 (the `debug` tool) consumes. Pick an adapter by + * language (or id), get back an `AdapterSpec` to hand to `DebugService.start`, + * or a graceful-missing result. The binary probe is injected at construction + * (mirrors `RuntimeBase.make(probe)`) so capability detection is testable. + */ + export class Registry { + private readonly adapters = new Map() + constructor(private readonly probe: BinaryProbe) {} + + /** Domain-pack contribution hook: add (or replace) an adapter. Core stays clean. */ + register(info: Info): void { + this.adapters.set(info.id, info) + } + + /** Remove an adapter (e.g. when a domain pack deactivates). */ + unregister(id: string): void { + this.adapters.delete(id) + } + + /** Whether an adapter id is currently registered. */ + has(id: string): boolean { + return this.adapters.has(id) + } + + /** The adapter definition for an id, if registered. */ + get(id: string): Info | undefined { + return this.adapters.get(id) + } + + /** All registered adapter definitions, in registration order. */ + list(): Info[] { + return [...this.adapters.values()] + } + + /** The first registered adapter serving a language, if any. */ + forLanguage(language: string): Info | undefined { + const lang = language.toLowerCase() + return this.list().find((a) => a.languages.includes(lang)) + } + + /** All registered adapters serving a language (e.g. both lldb and gdb for "cpp"). */ + listForLanguage(language: string): Info[] { + const lang = language.toLowerCase() + return this.list().filter((a) => a.languages.includes(lang)) + } + + /** + * Capability/existence probe + spec build for one definition. Missing binary + * → graceful `{ available:false, message }` (logged at info), never a throw. + */ + private build(info: Info): Resolution { + const launch = info.spawn(this.probe) + if (!launch) { + const message = `Debug adapter "${info.id}" is not available. ${info.install}` + // Graceful missing — mirror lsp/server.ts's "please install …"; do NOT Die. + log.info(message) + return { available: false, adapterId: info.id, message } + } + return { + available: true, + spec: { + id: info.id, + languages: [...info.languages], + command: launch.command, + args: [...launch.args], + privileges: info.privileges, + transport: info.transport, + }, + } + } + + /** Resolve an `AdapterSpec` by adapter id. */ + resolveById(id: string): Resolution { + const info = this.get(id) + if (!info) { + const message = `No debug adapter registered with id "${id}".` + log.info(message) + return { available: false, adapterId: id, message } + } + return this.build(info) + } + + /** Resolve an `AdapterSpec` for a language (picks the first matching adapter). */ + resolve(language: string): Resolution { + const info = this.forLanguage(language) + if (!info) { + const message = `No debug adapter registered for language "${language}".` + log.info(message) + return { available: false, adapterId: language, message } + } + return this.build(info) + } + } + + /** + * Build a registry pre-loaded with the base set (debugpy/delve/lldb). Pass a + * probe to control binary detection (defaults to real PATH lookup). Domain + * packs add their adapters afterwards via `register()` / `registerGdb()`. + */ + export const make = (probe: BinaryProbe = defaultProbe): Registry => { + const registry = new Registry(probe) + for (const info of BASE_SET) registry.register(info) + return registry + } + + /** + * Domain-pack hook for the native/systems-programming pack: register GDB on + * activation. Equivalent to `registry.register(DebugAdapter.GDB)`; provided as + * a named entry point so a pack does not need to import the definition itself. + */ + export const registerGdb = (registry: Registry): void => registry.register(GDB) +} diff --git a/packages/deepagent-code/src/debug/client.ts b/packages/deepagent-code/src/debug/client.ts new file mode 100644 index 00000000..60a3e209 --- /dev/null +++ b/packages/deepagent-code/src/debug/client.ts @@ -0,0 +1,239 @@ +import { StreamMessageReader, StreamMessageWriter } from "vscode-jsonrpc/node" +import * as Log from "@deepagent-code/core/util/log" +import { Process } from "@/util/process" +import { spawn as dapspawn } from "@/lsp/launch" +import { Schema } from "effect" +import { withTimeout } from "../util/timeout" +import type { AdapterSpec, DapEvent, DapMessage, DapResponse } from "./types" + +/** + * D1 (S1-v3.5): DAP (Debug Adapter Protocol) client. + * + * ISOMORPHIC to `lsp/client.ts`: spawn a process, talk a Content-Length-framed + * JSON protocol over stdio, with request timeouts and graceful shutdown. DAP is + * the same wire framing as LSP (Content-Length headers + JSON body), so we reuse + * `vscode-jsonrpc`'s `StreamMessageReader`/`StreamMessageWriter` for the framing. + * We do NOT use `createMessageConnection`, because that enforces JSON-RPC 2.0 + * semantics (`jsonrpc`/`id`), whereas DAP messages carry `seq`/`type`/`command`. + * Sequencing (request_seq matching) is implemented here, deliberately thin. + * + * Architecture铁律: this is a protocol client only — every debugging primitive + * (breakpoints, stepping, evaluation, stack/var inspection) is a request handed + * to the adapter. There is zero self-written debugging logic here. + */ + +const REQUEST_TIMEOUT_MS = 15_000 +const INITIALIZE_TIMEOUT_MS = 30_000 + +const log = Log.create({ service: "debug.client" }) + +export type Info = NonNullable>> + +export class DapRequestError extends Schema.TaggedErrorClass()("DapRequestError", { + command: Schema.String, + message: Schema.String, +}) {} + +export class InitializeError extends Schema.TaggedErrorClass()("DapInitializeError", { + adapterID: Schema.String, + cause: Schema.optional(Schema.Defect), +}) {} + +export type EventHandler = (event: DapEvent) => void + +/** + * Spawn a debug adapter and bring up a DAP client over its stdio. Mirrors + * `lsp/client.ts:create`: spawn, wire reader/writer, run the `initialize` + * handshake, return an Info object with request/notify helpers + graceful + * shutdown. + */ +export async function create(input: { + /** The adapter to spawn (provided by D2). */ + spec: AdapterSpec + /** Working directory for the adapter process (R0 worktree or main dir). */ + cwd: string + /** Extra environment for the adapter process. */ + env?: Record +}) { + const logger = log.clone().tag("adapterID", input.spec.id) + logger.info("starting dap client") + + if (input.spec.transport !== "stdio") { + // D1 implements stdio (the common case for debugpy/delve/lldb). Socket + // transport is reserved for D2+ and intentionally not silently downgraded. + throw new InitializeError({ + adapterID: input.spec.id, + cause: new Error(`transport "${input.spec.transport}" not supported by D1 (stdio only)`), + }) + } + + const proc = dapspawn(input.spec.command, input.spec.args, { + cwd: input.cwd, + env: { ...process.env, ...input.env }, + }) + + const reader = new StreamMessageReader(proc.stdout as any) + const writer = new StreamMessageWriter(proc.stdin as any) + + proc.stderr?.on("data", (data: Buffer) => { + const text = data.toString().trim() + if (text) logger.debug("adapter stderr", { text: text.slice(0, 1000) }) + }) + + // --- Connection state --- + + let seq = 1 + let closed = false + const pending = new Map void; reject: (e: Error) => void; command: string }>() + const eventHandlers = new Set() + + const dispatch = (message: DapMessage) => { + if (message.type === "response") { + const entry = pending.get(message.request_seq) + if (!entry) return + pending.delete(message.request_seq) + if (message.success) { + entry.resolve(message) + } else { + entry.reject(new DapRequestError({ command: message.command, message: message.message ?? "request failed" })) + } + return + } + if (message.type === "event") { + // Reverse requests (`runInTerminal`/`startDebugging`) arrive as type:"request" + // FROM the adapter; we only consume events here. Fan out to subscribers + // (DebugService bridges stopped/output/terminated to EventV2). + for (const handler of [...eventHandlers]) { + try { + handler(message) + } catch (err) { + logger.warn("event handler threw", { error: String(err) }) + } + } + } + } + + reader.listen((data) => dispatch(data as unknown as DapMessage)) + + // --- DAP request primitive --- + + const sendRequest = (command: string, args?: unknown, timeoutMs = REQUEST_TIMEOUT_MS): Promise => { + if (closed) return Promise.reject(new DapRequestError({ command, message: "client is closed" })) + const requestSeq = seq++ + const promise = new Promise((resolve, reject) => { + pending.set(requestSeq, { resolve, reject, command }) + writer.write({ seq: requestSeq, type: "request", command, arguments: args } as any).catch((err) => { + pending.delete(requestSeq) + reject(err instanceof Error ? err : new Error(String(err))) + }) + }) + return withTimeout(promise, timeoutMs, `DAP request "${command}" timed out after ${timeoutMs}ms`) + .then((response) => response.body as T) + .catch((err) => { + pending.delete(requestSeq) + throw err + }) + } + + // --- Initialize handshake --- + + logger.info("sending initialize") + const capabilities = await withTimeout( + sendRequest>( + "initialize", + { + clientID: "deepagent-code", + clientName: "DeepAgent Code", + adapterID: input.spec.id, + pathFormat: "path", + linesStartAt1: true, + columnsStartAt1: true, + supportsRunInTerminalRequest: false, + locale: "en-US", + }, + INITIALIZE_TIMEOUT_MS, + ), + INITIALIZE_TIMEOUT_MS, + ).catch((err) => { + logger.error("initialize error", { error: err }) + throw new InitializeError({ adapterID: input.spec.id, cause: err }) + }) + + logger.info("initialized") + + // --- Public API --- + + const result = { + get adapterID() { + return input.spec.id + }, + get capabilities() { + return capabilities + }, + get process() { + return proc + }, + /** Low-level escape hatch: send an arbitrary DAP request. */ + request: sendRequest, + /** Subscribe to DAP events; returns an unsubscribe fn. */ + onEvent(handler: EventHandler) { + eventHandlers.add(handler) + return () => eventHandlers.delete(handler) + }, + // —— Typed DAP requests (thin pass-throughs to the adapter) —————————————— + launch: (args: Record) => sendRequest("launch", args, INITIALIZE_TIMEOUT_MS), + attach: (args: Record) => sendRequest("attach", args, INITIALIZE_TIMEOUT_MS), + configurationDone: () => sendRequest("configurationDone", {}), + setBreakpoints: (args: { + source: { path: string; name?: string } + breakpoints: { line: number; condition?: string }[] + }) => sendRequest("setBreakpoints", args), + continue: (args: { threadId: number }) => sendRequest("continue", args), + next: (args: { threadId: number }) => sendRequest("next", args), + stepIn: (args: { threadId: number }) => sendRequest("stepIn", args), + stepOut: (args: { threadId: number }) => sendRequest("stepOut", args), + stackTrace: (args: { threadId: number; startFrame?: number; levels?: number }) => sendRequest("stackTrace", args), + scopes: (args: { frameId: number }) => sendRequest("scopes", args), + variables: (args: { variablesReference: number }) => sendRequest("variables", args), + evaluate: (args: { expression: string; frameId?: number; context?: string }) => sendRequest("evaluate", args), + threads: () => sendRequest("threads", {}), + terminate: (args?: { restart?: boolean }) => sendRequest("terminate", args ?? {}), + disconnect: (args?: { terminateDebuggee?: boolean }) => sendRequest("disconnect", args ?? {}), + /** Graceful shutdown: disconnect, dispose streams, stop the process. */ + async shutdown() { + if (closed) return + closed = true + logger.info("shutting down") + // Best-effort polite disconnect; never let it block teardown. + await withTimeout(sendRequestSilently("disconnect", { terminateDebuggee: true }), 2_000).catch(() => undefined) + for (const [, entry] of pending) entry.reject(new DapRequestError({ command: entry.command, message: "client shutting down" })) + pending.clear() + eventHandlers.clear() + try { + reader.dispose() + writer.dispose() + } catch { + // streams may already be torn down + } + await Process.stop(proc) + logger.info("shutdown") + }, + } + + // disconnect during shutdown must bypass the `closed` guard above. + function sendRequestSilently(command: string, args?: unknown): Promise { + const requestSeq = seq++ + return new Promise((resolve) => { + pending.set(requestSeq, { + resolve: () => resolve(), + reject: () => resolve(), + command, + }) + writer.write({ seq: requestSeq, type: "request", command, arguments: args } as any).catch(() => resolve()) + }) + } + + return result +} + +export * as DapClient from "./client" diff --git a/packages/deepagent-code/src/debug/index.ts b/packages/deepagent-code/src/debug/index.ts new file mode 100644 index 00000000..3d44f46d --- /dev/null +++ b/packages/deepagent-code/src/debug/index.ts @@ -0,0 +1,4 @@ +export * from "./types" +export { DapClient } from "./client" +export { Debug, DebugService } from "./service" +export { DebugAdapter } from "./adapter" diff --git a/packages/deepagent-code/src/debug/service.ts b/packages/deepagent-code/src/debug/service.ts new file mode 100644 index 00000000..dcab21c5 --- /dev/null +++ b/packages/deepagent-code/src/debug/service.ts @@ -0,0 +1,411 @@ +import { EventV2Bridge } from "@/event-v2-bridge" +import { EventV2 } from "@deepagent-code/core/event" +import * as Log from "@deepagent-code/core/util/log" +import { Context, Effect, Layer, Schema } from "effect" +import { InstanceState } from "@/effect/instance-state" +import { InstanceRef } from "@/effect/instance-ref" +import { RuntimeBase } from "@/runtime/base" +import { DapClient } from "./client" +import type { AdapterSpec, DapEvent, SessionState, SessionStatus } from "./types" + +const log = Log.create({ service: "debug.service" }) + +/** + * D1 (S1-v3.5): `DebugService` — the DAP debug-session state machine. + * + * One session == one adapter process (a `DapClient`). Sessions are kept in a + * map keyed by session id and are fully isolated. The session lifecycle is a + * FINITE, SERIALIZABLE state machine: + * + * initializing → initialized → configuring → running ⇄ stopped → terminated + * ↘ exited / failed + * + * The serializable `SessionState` is what the frontend renders and what D4 + * writes to the debug-evidence artifact — it carries no live handles. + * + * DAP `stopped` / `output` / `terminated` events are bridged onto EventV2 (the + * same link LSP events use), so the frontend observes a debug session exactly + * like any other runtime stream. + * + * Architecture铁律: control-plane only. Every primitive (breakpoints, stepping, + * eval, stack/var inspection) is a DAP request forwarded to the adapter; the + * service only owns approval/gating, lifecycle, and event routing. + */ +export namespace DebugService { + export const Event = { + /** Program hit a breakpoint / step / exception and is paused. */ + Stopped: EventV2.define({ + type: "debug.stopped", + schema: { sessionId: Schema.String, reason: Schema.String, threadId: Schema.optional(Schema.Number) }, + }), + /** Adapter produced program/console output. */ + Output: EventV2.define({ + type: "debug.output", + schema: { sessionId: Schema.String, category: Schema.String, output: Schema.String }, + }), + /** Debuggee terminated. */ + Terminated: EventV2.define({ + type: "debug.terminated", + schema: { sessionId: Schema.String }, + }), + /** Generic session-state change, for frontend/audit observation. */ + Updated: EventV2.define({ + type: "debug.updated", + schema: { sessionId: Schema.String, status: Schema.String }, + }), + } + + export type StepKind = "next" | "stepIn" | "stepOut" + + export interface StartInput { + /** Adapter to spawn (from D2's registry). */ + spec: AdapterSpec + /** Caller-chosen session id; must be unique among live sessions. */ + sessionId: string + /** "launch" config object (program/args/cwd…) passed straight to the adapter. */ + launch?: Record + /** "attach" config object; mutually exclusive with `launch`. */ + attach?: Record + /** Working directory for the adapter process (R0 worktree or main dir). */ + cwd?: string + /** Extra env for the adapter process. */ + env?: Record + /** + * Drives the tool's `ctx.ask`; called once on session start via R0's gate. + * Tests pass a no-op. In-session sub-ops (step/continue/eval) reuse the grant. + */ + requestApproval?: () => Effect.Effect + } + + export interface Interface { + /** Start a session: gate (approve-once + privilege), spawn adapter, initialize + launch/attach + configurationDone. */ + readonly start: (input: StartInput) => Effect.Effect + /** Set breakpoints for a source file (delegated to the adapter). */ + readonly setBreakpoints: (input: { + sessionId: string + source: string + breakpoints: { line: number; condition?: string }[] + }) => Effect.Effect + /** Resume execution. */ + readonly continue: (sessionId: string) => Effect.Effect + /** Single-step (next/stepIn/stepOut). */ + readonly step: (sessionId: string, kind: StepKind) => Effect.Effect + /** Stack frames at the current stop (delegated; returns the adapter's frames). */ + readonly stackTrace: (sessionId: string) => Effect.Effect + /** Scopes for a frame (delegated). */ + readonly scopes: (sessionId: string, frameId: number) => Effect.Effect + /** Variables for a scope/variable reference (delegated). */ + readonly variables: (sessionId: string, variablesReference: number) => Effect.Effect + /** Evaluate an expression in a frame (delegated). */ + readonly evaluate: (input: { + sessionId: string + expression: string + frameId?: number + context?: string + }) => Effect.Effect + /** Terminate the session and tear down the adapter process. */ + readonly terminate: (sessionId: string) => Effect.Effect + /** Serializable snapshot of one session. */ + readonly get: (sessionId: string) => Effect.Effect + /** Serializable snapshots of all live sessions. */ + readonly list: () => Effect.Effect + } + + export class Service extends Context.Service()("@deepagent-code/DebugService") {} + + interface Session { + client: DapClient.Info + state: SessionState + /** One-shot event waiters keyed by DAP event name. */ + waiters: Map void>> + unsubscribe: () => void + } + + interface State { + sessions: Map + /** Instance context captured at first use; events publish with this location. */ + instance: import("@/project/instance-context").InstanceContext + } + + export const layer = Layer.effect( + Service, + Effect.gen(function* () { + const base = yield* RuntimeBase.Service + const events = yield* EventV2Bridge.Service + + const state = yield* InstanceState.make( + Effect.fnUntraced(function* (instance) { + const s: State = { sessions: new Map(), instance } + yield* Effect.addFinalizer(() => + Effect.promise(async () => { + await Promise.all([...s.sessions.values()].map((session) => session.client.shutdown().catch(() => {}))) + s.sessions.clear() + }), + ) + return s + }), + ) + + // —— EventV2 bridging (runs from the adapter's stdio callback) ————————————— + // Events are published from a Node stdio callback (outside the Effect run + // loop), so we fork them onto the runtime with the captured instance + // location, exactly like LSP events flow through the EventV2 bridge. + const publish = (instance: State["instance"], effect: Effect.Effect) => + Effect.runFork(effect.pipe(Effect.provideService(InstanceRef, instance)) as Effect.Effect) + + const now = () => Date.now() + + const transition = (session: Session, instance: State["instance"], patch: Partial): SessionState => { + session.state = { ...session.state, ...patch, updatedAt: now() } + publish(instance, events.publish(Event.Updated, { sessionId: session.state.id, status: session.state.status })) + return session.state + } + + const onAdapterEvent = (session: Session, instance: State["instance"]) => (event: DapEvent) => { + // Resolve any one-shot waiters first (start() awaits "initialized"). + const waiters = session.waiters.get(event.event) + if (waiters?.length) { + session.waiters.set(event.event, []) + for (const w of waiters) w(event) + } + switch (event.event) { + case "stopped": { + const reason = (event.body?.reason as string) ?? "unknown" + const threadId = event.body?.threadId as number | undefined + transition(session, instance, { status: "stopped", stoppedReason: reason, threadId }) + publish(instance, events.publish(Event.Stopped, { sessionId: session.state.id, reason, threadId })) + break + } + case "continued": { + // Some adapters emit `continued`; reflect running unless already terminal. + if (session.state.status === "stopped") transition(session, instance, { status: "running" }) + break + } + case "output": { + const category = (event.body?.category as string) ?? "console" + const output = (event.body?.output as string) ?? "" + publish(instance, events.publish(Event.Output, { sessionId: session.state.id, category, output })) + break + } + case "terminated": { + transition(session, instance, { status: "terminated" }) + publish(instance, events.publish(Event.Terminated, { sessionId: session.state.id })) + break + } + case "exited": { + const exitCode = event.body?.exitCode as number | undefined + transition(session, instance, { status: "exited", ...(exitCode === undefined ? {} : { exitCode }) }) + break + } + default: + break + } + } + + // Register a one-shot waiter for a DAP event and return the Promise + // EAGERLY (synchronously). The waiter must be registered before the + // request that triggers the event is sent, otherwise the event races + // ahead of the subscription. The returned promise is awaited via Effect. + const registerWaiter = (session: Session, name: string, timeoutMs: number): Promise => + new Promise((resolve) => { + const list = session.waiters.get(name) ?? [] + list.push(resolve) + session.waiters.set(name, list) + // Resolve undefined on timeout rather than reject — a missing + // `initialized` is non-fatal (some adapters skip configurationDone). + setTimeout(() => resolve(undefined), timeoutMs) + }) + + const getSession = (sessionId: string) => + Effect.gen(function* () { + const s = yield* InstanceState.get(state) + const session = s.sessions.get(sessionId) + if (!session) return yield* Effect.fail(new Error(`no debug session "${sessionId}"`)) + return session + }) + + const requireThread = (session: Session) => { + if (session.state.threadId === undefined) { + return Effect.fail(new Error(`session "${session.state.id}" is not stopped on a thread`)) + } + return Effect.succeed(session.state.threadId) + } + + const start: Interface["start"] = (input) => + Effect.gen(function* () { + const s = yield* InstanceState.get(state) + if (s.sessions.has(input.sessionId)) { + return yield* Effect.fail(new Error(`debug session "${input.sessionId}" already exists`)) + } + + // R0 gate: privilege fail-closed first, then approve-once-per-session. + yield* base + .gate({ + sessionKey: input.sessionId, + privileges: input.spec.privileges, + requestApproval: input.requestApproval ?? (() => Effect.void), + }) + .pipe(Effect.mapError((e) => (e instanceof Error ? e : new Error(String(e))))) + + const cwd = input.cwd ?? s.instance.directory + + const client = yield* Effect.tryPromise({ + try: () => DapClient.create({ spec: input.spec, cwd, env: input.env }), + catch: (e) => (e instanceof Error ? e : new Error(String(e))), + }) + + const initial: SessionState = { + id: input.sessionId, + adapterId: input.spec.id, + status: "initialized", + breakpoints: [], + workdir: cwd, + createdAt: now(), + updatedAt: now(), + } + const session: Session = { + client, + state: initial, + waiters: new Map(), + unsubscribe: () => {}, + } + session.unsubscribe = client.onEvent(onAdapterEvent(session, s.instance)) + s.sessions.set(input.sessionId, session) + + // launch/attach → wait for `initialized` event → configurationDone. + // Per DAP: the adapter signals readiness for configuration with the + // `initialized` event; configurationDone unblocks it to run. + transition(session, s.instance, { status: "configuring" }) + // Register the waiter BEFORE sending launch so we never miss the event. + const initializedEvent = registerWaiter(session, "initialized", 20_000) + yield* Effect.tryPromise({ + try: () => + input.attach ? client.attach(input.attach) : client.launch(input.launch ?? {}), + catch: (e) => (e instanceof Error ? e : new Error(String(e))), + }) + // Wait for `initialized` (best-effort; undefined on timeout). + yield* Effect.promise(() => initializedEvent) + yield* Effect.tryPromise({ + try: () => client.configurationDone(), + catch: (e) => (e instanceof Error ? e : new Error(String(e))), + }).pipe(Effect.catch(() => Effect.void)) + + // If a stopped event already arrived during the handshake, keep it; + // otherwise the program is running. + if (session.state.status === "configuring") transition(session, s.instance, { status: "running" }) + return session.state + }).pipe( + Effect.tapCause((cause) => Effect.sync(() => log.warn("debug start failed", { cause: String(cause) }))), + ) + + const setBreakpoints: Interface["setBreakpoints"] = (input) => + Effect.gen(function* () { + const s = yield* InstanceState.get(state) + const session = yield* getSession(input.sessionId) + yield* Effect.tryPromise({ + try: () => + session.client.setBreakpoints({ + source: { path: input.source }, + breakpoints: input.breakpoints, + }), + catch: (e) => (e instanceof Error ? e : new Error(String(e))), + }) + const others = session.state.breakpoints.filter((b) => b.source !== input.source) + return transition(session, s.instance, { + breakpoints: [...others, { source: input.source, lines: input.breakpoints.map((b) => b.line) }], + }) + }) + + const resume = (sessionId: string, kind: "continue" | StepKind) => + Effect.gen(function* () { + const s = yield* InstanceState.get(state) + const session = yield* getSession(sessionId) + const threadId = yield* requireThread(session) + yield* Effect.tryPromise({ + try: () => + kind === "continue" + ? session.client.continue({ threadId }) + : session.client[kind]({ threadId }), + catch: (e) => (e instanceof Error ? e : new Error(String(e))), + }) + // Optimistically mark running; a subsequent `stopped` event flips it back. + return transition(session, s.instance, { status: "running", threadId: undefined, stoppedReason: undefined }) + }) + + const continue_: Interface["continue"] = (sessionId) => resume(sessionId, "continue") + const step: Interface["step"] = (sessionId, kind) => resume(sessionId, kind) + + const delegated = (sessionId: string, fn: (client: DapClient.Info) => Promise) => + Effect.gen(function* () { + const session = yield* getSession(sessionId) + return yield* Effect.tryPromise({ + try: () => fn(session.client), + catch: (e) => (e instanceof Error ? e : new Error(String(e))), + }) + }) + + const stackTrace: Interface["stackTrace"] = (sessionId) => + Effect.gen(function* () { + const session = yield* getSession(sessionId) + const threadId = yield* requireThread(session) + const body = yield* Effect.tryPromise({ + try: () => session.client.stackTrace({ threadId }), + catch: (e) => (e instanceof Error ? e : new Error(String(e))), + }) + return (body?.stackFrames as any[]) ?? [] + }) + + const scopes: Interface["scopes"] = (sessionId, frameId) => + delegated(sessionId, (c) => c.scopes({ frameId })).pipe(Effect.map((b) => (b?.scopes as any[]) ?? [])) + + const variables: Interface["variables"] = (sessionId, variablesReference) => + delegated(sessionId, (c) => c.variables({ variablesReference })).pipe( + Effect.map((b) => (b?.variables as any[]) ?? []), + ) + + const evaluate: Interface["evaluate"] = (input) => + delegated(input.sessionId, (c) => + c.evaluate({ expression: input.expression, frameId: input.frameId, context: input.context ?? "repl" }), + ) + + const terminate: Interface["terminate"] = (sessionId) => + Effect.gen(function* () { + const s = yield* InstanceState.get(state) + const session = s.sessions.get(sessionId) + if (!session) return yield* Effect.fail(new Error(`no debug session "${sessionId}"`)) + session.unsubscribe() + yield* Effect.promise(() => session.client.shutdown().catch(() => {})) + const final = transition(session, s.instance, { status: "terminated" }) + s.sessions.delete(sessionId) + return final + }) + + const get: Interface["get"] = (sessionId) => + InstanceState.get(state).pipe(Effect.map((s) => s.sessions.get(sessionId)?.state)) + + const list: Interface["list"] = () => + InstanceState.get(state).pipe(Effect.map((s) => [...s.sessions.values()].map((x) => x.state))) + + return Service.of({ + start, + setBreakpoints, + continue: continue_, + step, + stackTrace, + scopes, + variables, + evaluate, + terminate, + get, + list, + }) + }), + ) + + export const defaultLayer = layer.pipe( + Layer.provide(RuntimeBase.layer), + Layer.provide(EventV2Bridge.defaultLayer), + ) +} + +export * as Debug from "./service" diff --git a/packages/deepagent-code/src/debug/types.ts b/packages/deepagent-code/src/debug/types.ts new file mode 100644 index 00000000..1015981c --- /dev/null +++ b/packages/deepagent-code/src/debug/types.ts @@ -0,0 +1,114 @@ +import { Schema } from "effect" +import type { RuntimeBase } from "@/runtime/base" + +/** + * D1 (S1-v3.5): shared types for the DAP (Debug Adapter Protocol) layer. + * + * This module is the contract surface between D1 (this DAP client + DebugService) + * and D2 (the debug adapter registry: debugpy / delve / lldb / GDB). D2 owns the + * concrete `AdapterSpec` values; D1 only consumes them. Keeping the type here lets + * both sides import without a dependency cycle. + * + * Architecture铁律: DeepAgent is control-plane only. Nothing in this layer + * reimplements a debugger — breakpoints / stepping / evaluation are all delegated + * to the adapter process over standard DAP. + */ + +/** + * How D2 declares a debug adapter to the DebugService. The service spawns the + * adapter from `command`/`args`, drives it over DAP, and asks R0 to enforce the + * declared `privileges` (ptrace etc.) fail-closed before the session starts. + */ +export interface AdapterSpec { + /** Stable adapter id, e.g. "debugpy" | "delve" | "lldb" | "gdb". */ + id: string + /** Languages this adapter serves, e.g. ["python"] / ["c", "cpp", "rust"]. */ + languages: string[] + /** Executable to spawn. */ + command: string + /** Arguments passed to `command`. */ + args: string[] + /** Privileges the adapter needs; handed to R0's fail-closed privilege gate. */ + privileges: RuntimeBase.PrivilegeSpec[] + /** Transport to the adapter. D1 implements "stdio"; "socket" is reserved for D2+. */ + transport: "stdio" | "socket" +} + +// —— DAP wire messages (Content-Length framed JSON; see DAP base protocol) ———— + +export interface DapRequest { + seq: number + type: "request" + command: string + arguments?: unknown +} + +export interface DapResponse { + seq: number + type: "response" + request_seq: number + success: boolean + command: string + message?: string + body?: any +} + +export interface DapEvent { + seq: number + type: "event" + event: string + body?: any +} + +export type DapMessage = DapRequest | DapResponse | DapEvent + +// —— DebugService session state (finite + serializable, for frontend/audit) ———— + +/** + * The finite session lifecycle. Transitions: + * initializing → initialized → configuring → running ⇄ stopped → terminated + * with `exited` (adapter reported exit) and `failed` (error) as terminal states. + */ +export const SessionStatus = Schema.Literals([ + "initializing", + "initialized", + "configuring", + "running", + "stopped", + "terminated", + "exited", + "failed", +]) +export type SessionStatus = typeof SessionStatus.Type + +export const SourceBreakpoints = Schema.Struct({ + source: Schema.String, + lines: Schema.Array(Schema.Number), +}) +export type SourceBreakpoints = typeof SourceBreakpoints.Type + +/** + * The serializable snapshot of a debug session. Plain JSON — no methods, no class + * instances — so it can be shipped to the frontend and written to an audit/evidence + * artifact verbatim (D4). + */ +export const SessionState = Schema.Struct({ + id: Schema.String, + adapterId: Schema.String, + status: SessionStatus, + /** The thread the last `stopped` event referenced (DAP threadId). */ + threadId: Schema.optional(Schema.Number), + /** Why the program last stopped (e.g. "breakpoint" | "step" | "exception"). */ + stoppedReason: Schema.optional(Schema.String), + /** Breakpoints set this session, by source. */ + breakpoints: Schema.Array(SourceBreakpoints), + /** Exit code if the adapter reported `exited`. */ + exitCode: Schema.optional(Schema.Number), + /** Last error message if status is "failed". */ + error: Schema.optional(Schema.String), + /** Isolation worktree directory the adapter ran in (undefined = main dir). */ + workdir: Schema.optional(Schema.String), + createdAt: Schema.Number, + updatedAt: Schema.Number, +}) +export type SessionState = typeof SessionState.Type diff --git a/packages/deepagent-code/src/effect/runtime-flags.ts b/packages/deepagent-code/src/effect/runtime-flags.ts index c68c64ff..1c1416da 100644 --- a/packages/deepagent-code/src/effect/runtime-flags.ts +++ b/packages/deepagent-code/src/effect/runtime-flags.ts @@ -52,6 +52,12 @@ export class Service extends ConfigService.Service()("@deepagent-code/R // L6 (V3.4): code_intel (symbol-driven AI IDE entry) ships ON by default and is promoted out of // the experimental gate — `=false` disables. grep is never disabled; no-server files fall back. codeIntelTool: stableOn("DEEPAGENT_CODE_CODE_INTEL_TOOL"), + // P3A (S1-v3.5): profile tool (symbol/region-driven PAP profiling entry). Ships ON by default; + // set =false to disable. Requires R0 privilege gate + execution approval at runtime. + profileTool: stableOn("DEEPAGENT_CODE_PROFILE_TOOL"), + // D3 (S1-v3.5): debug tool (DAP symbol-driven debugger entry). Ships ON by default; + // set =false to disable. Requires R0 privilege gate + execution approval at runtime. + debugTool: stableOn("DEEPAGENT_CODE_DEBUG_TOOL"), // M7 (S1-v3.4): when a connected MCP server's tier derives to `read_only` (catalog-matched), its // tools auto-allow without a per-call prompt. ON by default (the V3.4 design). Set `=false` to // restore the pre-M7 behavior where EVERY MCP tool call goes through `ctx.ask` — a defense-in-depth diff --git a/packages/deepagent-code/src/mcp/catalog.ts b/packages/deepagent-code/src/mcp/catalog.ts index adc3cb49..56bf7acc 100644 --- a/packages/deepagent-code/src/mcp/catalog.ts +++ b/packages/deepagent-code/src/mcp/catalog.ts @@ -14,13 +14,14 @@ import { ConfigMCPV1 } from "@deepagent-code/core/v1/config/mcp" * WeakMap provenance side-channel, never guessed from the tool name. * - default not connected: `defaultEnabled: false` (readonly literal). * - credentials by KEY NAME only in the catalog: an entry declares which credentials it needs - * (key + description), never values. ⚠️ The secure-storage resolution layer is NOT yet built: - * today the frontend collects the raw secret and `credentialRefs` carries the actual value, which - * `instantiate` splices into env/headers. So secrets currently live in the connected server's - * config (in-memory, and persisted to the config file on enable). Routing through an indirection - * (handle resolved from OS keychain at connect time) is a tracked follow-up; until then treat the - * config as secret-bearing. The KEY-NAME-only guarantee holds for the catalog DEFINITION, not yet - * for the runtime value path. + * (key + description), never values. M-CRED (S1-v3.4 M7 defer, delivered S1-v3.5): the runtime + * value path is now indirected too — `instantiate` writes `secret:true` credentials as a `${KEY}` + * env REFERENCE (or passes through a caller-supplied `${VAR}` ref / `secret://` keychain handle), + * NEVER the plaintext value. The real value is resolved from the process env / OS keychain at + * connect time (`mcp/index.ts` + `secret-store.ts`) and never lands in `cfg.mcp`, logs, or + * snapshots. Existing plaintext configs are migrated to handles at startup (see + * `SecretStore.migratePlaintextSecrets`). The KEY-NAME-only guarantee now holds for BOTH the + * catalog definition and the runtime value path. * - dangerous writes fail-closed: anything not provably read-only defaults to * `write_guarded` → `ctx.ask` approval. This is LIVE, and the tier is NOT trusted from persisted * config: `mcp/index.ts` DERIVES it at `tools()` time by matching the live server config against @@ -100,6 +101,16 @@ const PLACEHOLDER = /\{\{([A-Z0-9_]+)\}\}/g /** True if a string contains any `{{PLACEHOLDER}}` token. */ const containsPlaceholder = (s: string): boolean => /\{\{[A-Z0-9_]+\}\}/.test(s) +/** + * M-CRED (S1-v3.5): true if a supplied credential ref is ALREADY an indirection — a + * `${VAR}` / `${VAR:-default}` env reference or a `secret://` keychain handle — and should + * therefore be persisted verbatim rather than re-wrapped as a `${KEY}` reference. Mirrors + * `SecretStore.isReference`; kept local to avoid a catalog ⇄ secret-store import cycle. + */ +function isCredentialReference(s: string): boolean { + return s.startsWith("secret://") || /\$\{[A-Za-z_][A-Za-z0-9_]*(?::-[^}]*)?\}/.test(s) +} + /** Substitute {{KEY}} placeholders from a flat lookup. Throws on an unresolved placeholder (fail-closed). */ function substitute(template: string, lookup: Record): string { return template.replace(PLACEHOLDER, (_match, key: string) => { @@ -158,8 +169,17 @@ export function instantiate(entry: McpCatalogEntry, filled: FilledEntry): { name for (const [k, v] of Object.entries(filled.params)) { if (typeof v === "string") scalarLookup[k] = v } + // M-CRED (S1-v3.5): for `secret:true` credentials, NEVER splice the raw value into config. + // Instead persist a `${KEY}` env REFERENCE (resolved from the process env at connect time) + // — unless the caller already supplied an indirection (`${VAR}` ref or `secret://` handle), + // which is passed through verbatim. Non-secret credential refs (e.g. file paths) pass through. + const secretKeys = new Set(entry.credentials.filter((c) => c.secret).map((c) => c.key)) for (const [k, v] of Object.entries(filled.credentialRefs)) { - scalarLookup[k] = v + if (secretKeys.has(k) && !isCredentialReference(v)) { + scalarLookup[k] = `\${${k}}` + } else { + scalarLookup[k] = v + } } // 3. Multi-value params (e.g. ALLOWED_DIRS) expand a single template token into several args. diff --git a/packages/deepagent-code/src/mcp/index.ts b/packages/deepagent-code/src/mcp/index.ts index 862825be..46060d26 100644 --- a/packages/deepagent-code/src/mcp/index.ts +++ b/packages/deepagent-code/src/mcp/index.ts @@ -26,6 +26,7 @@ import { McpAuth } from "./auth" import { EventV2Bridge } from "@/event-v2-bridge" import { ToolProvenance } from "@/tool/provenance" import { McpCatalog } from "./catalog" +import { SecretStore } from "./secret-store" import { EventV2 } from "@deepagent-code/core/event" import { TuiEvent } from "@/server/tui-event" import open from "open" @@ -293,6 +294,10 @@ export const layer = Layer.effect( const spawner = yield* ChildProcessSpawner.ChildProcessSpawner const auth = yield* McpAuth.Service const events = yield* EventV2Bridge.Service + // M-CRED (S1-v3.5): connect-time secret resolver. `${VAR}` env refs and `secret://` + // keychain handles in env/headers are resolved HERE, just before the transport is + // built — the real value never returns to `cfg.mcp`, logs, or snapshots. + const secrets = yield* SecretStore.Service type Transport = StdioClientTransport | StreamableHTTPClientTransport | SSEClientTransport @@ -351,19 +356,28 @@ export const layer = Layer.effect( ) } + // M-CRED (S1-v3.5): resolve `${VAR}` / `secret://` references in headers to real values + // for the live request only — the persisted config keeps the reference. Missing env vars + // warn (by name) but don't block; unresolvable handles drop the header. + const resolvedHeaders = mcp.headers + ? yield* SecretStore.resolveRecord(mcp.headers, secrets) + : undefined + const requestInit = + resolvedHeaders && Object.keys(resolvedHeaders).length > 0 ? { headers: resolvedHeaders } : undefined + const transports: Array<{ name: string; transport: TransportWithAuth }> = [ { name: "StreamableHTTP", transport: new StreamableHTTPClientTransport(url, { authProvider, - requestInit: mcp.headers ? { headers: mcp.headers } : undefined, + requestInit, }), }, { name: "SSE", transport: new SSEClientTransport(url, { authProvider, - requestInit: mcp.headers ? { headers: mcp.headers } : undefined, + requestInit, }), }, ] @@ -439,6 +453,10 @@ export const layer = Layer.effect( ) { const [cmd, ...args] = mcp.command const cwd = yield* InstanceState.directory + // M-CRED (S1-v3.5): resolve `${VAR}` / `secret://` references in env to real values for the + // spawned process only. The persisted config keeps the reference; the real value never + // returns to cfg.mcp/logs. Missing env var → warn (by name), don't block. + const resolvedEnv = yield* SecretStore.resolveRecord(mcp.environment, secrets) const transport = new StdioClientTransport({ stderr: "pipe", command: cmd, @@ -447,7 +465,7 @@ export const layer = Layer.effect( env: { ...process.env, ...(cmd === "deepagent-code" ? { BUN_BE_BUN: "1" } : {}), - ...mcp.environment, + ...resolvedEnv, }, }) transport.stderr?.on("data", (chunk: Buffer) => { @@ -496,6 +514,43 @@ export const layer = Layer.effect( }) const cfgSvc = yield* Config.Service + // M-CRED (S1-v3.5): migrate any plaintext secrets in cfg.mcp into the secret store, persist the + // rewritten (handle-only) config so the plaintext is erased from disk, and return the migrated + // config for the connect loop. Best-effort + transactional: a failed move leaves THAT plaintext + // intact (logged) and never drops a credential. The whole step is wrapped so a migration error + // can never take down MCP startup — on failure we fall back to the original config. + const migrateOnStartup = Effect.fnUntraced(function* (mcp: NonNullable) { + // Only structurally-configured entries (type local/remote) can hold secrets; the + // `{enabled:false}` shorthand and untyped entries pass through migratePlaintextSecrets + // untouched (no `type` field → no match). Cast narrows for the migration contract. + const configured = mcp as Record + const outcome = yield* SecretStore.migratePlaintextSecrets(configured, secrets).pipe( + Effect.catch((e) => { + log.warn("MCP secret migration failed; leaving config unchanged", { error: String(e) }) + return Effect.succeed(undefined) + }), + ) + if (!outcome) return mcp + for (const f of outcome.failures) { + // Audit by KEY NAME / server only — never the value. + log.warn("MCP secret not migrated; plaintext preserved", { server: f.server, key: f.key, reason: f.error }) + } + if (outcome.changed) { + log.info("migrated plaintext MCP secrets into the secret store", { + count: outcome.moved.length, + backend: secrets.backendId, + }) + // Persist the rewritten config so the plaintext no longer lives on disk. + yield* cfgSvc.update({ mcp: outcome.config }).pipe( + Effect.catch((e) => { + log.warn("failed to persist migrated MCP config; plaintext may remain on disk", { error: String(e) }) + return Effect.void + }), + ) + } + return outcome.config + }) + const descendants = Effect.fnUntraced( function* (pid: number) { if (process.platform === "win32") return [] as number[] @@ -539,7 +594,12 @@ export const layer = Layer.effect( Effect.fn("MCP.state")(function* () { const cfg = yield* cfgSvc.get() const bridge = yield* EffectBridge.make() - const config = cfg.mcp ?? {} + // M-CRED (S1-v3.5): one-shot startup migration of any PLAINTEXT secrets already sitting in + // cfg.mcp (legacy configs written before this layer). Each secret is moved into the secret + // store and replaced with a `secret://` handle, transactionally (put+verify before erase, so + // a partial failure never loses a credential). We persist the rewritten config so the + // plaintext is erased from disk, then connect against the migrated config below. + const config = yield* migrateOnStartup(cfg.mcp ?? {}) const s: State = { config: {}, status: {}, @@ -1054,6 +1114,7 @@ export type AuthStatus = "authenticated" | "expired" | "not_authenticated" export const defaultLayer = layer.pipe( Layer.provide(McpAuth.defaultLayer), + Layer.provide(SecretStore.defaultLayer), Layer.provide(EventV2Bridge.defaultLayer), Layer.provide(Config.defaultLayer), Layer.provide(CrossSpawnSpawner.defaultLayer), diff --git a/packages/deepagent-code/src/mcp/secret-store.ts b/packages/deepagent-code/src/mcp/secret-store.ts new file mode 100644 index 00000000..b0c6b75a --- /dev/null +++ b/packages/deepagent-code/src/mcp/secret-store.ts @@ -0,0 +1,483 @@ +import { Context, Effect, Layer } from "effect" +import path from "path" +import nodeFs from "fs" +import { Process } from "@/util/process" +import { Global } from "@deepagent-code/core/global" +import { FSUtil } from "@deepagent-code/core/fs-util" +import { ConfigMCPV1 } from "@deepagent-code/core/v1/config/mcp" +import { McpCatalog } from "./catalog" +import * as Log from "@deepagent-code/core/util/log" + +const log = Log.create({ service: "mcp.secret" }) + +/** + * M-CRED (S1-v3.5): MCP credential secure-storage indirection —承接 V3.4 M7 defer. + * + * THE PROBLEM (see catalog.ts header): until now `instantiate` spliced the raw secret + * value (connection string / PAT) into `cfg.mcp` env/headers, so the persisted config + * file WAS the secret. This module removes the plaintext value from config entirely: + * + * - Step 1 (transition, low-cost, mirrors claude-code): config values may use + * `${VAR}` / `${VAR:-default}` env references that resolve from the process + * environment AT CONNECT TIME — the real value never lands in config or logs. + * - Step 2 (full indirection): values may be a `secret://` HANDLE backed by + * an OS keychain (macOS Keychain / Linux libsecret / Windows DPAPI). The handle is + * resolved to the real value at connect time only. + * + * FAIL-SAFE (never fail-open): when no OS keyring is available (headless / CI / + * container, no daemon) the store falls back to a `chmod 0600` local credentials file + * under the data dir + an explicit warning — it NEVER silently writes secrets into the + * project config repo. + * + * HONESTY about backends (matches what claude-code itself ships — even upstream leaves + * Linux libsecret a TODO and falls back to a 0600 file): + * - macOS Keychain: REAL, via the `security` subprocess. + * - Linux libsecret / Windows DPAPI: NOT yet implemented natively — they report + * `available: false` so selection degrades to the REAL 0600 file fallback. No fake + * backend is presented as real. + */ +export namespace SecretStore { + // ════════════════════════════════════════════════════════════════════════════ + // ${VAR} env expansion (Step 1) — PURE, no I/O, no service needed. + // ════════════════════════════════════════════════════════════════════════════ + + // `${VAR}` or `${VAR:-default}`. VAR is a POSIX-ish identifier; default runs to `}`. + const ENV_REF_G = /\$\{([A-Za-z_][A-Za-z0-9_]*)(?::-([^}]*))?\}/g + const ENV_REF_TEST = /\$\{[A-Za-z_][A-Za-z0-9_]*(?::-[^}]*)?\}/ + /** Handle reference prefix for an OS-keychain-backed secret (Step 2). */ + export const HANDLE_PREFIX = "secret://" + + /** True if the string contains at least one `${VAR}` / `${VAR:-default}` reference. */ + export const containsEnvRef = (s: string): boolean => ENV_REF_TEST.test(s) + /** True if the string is a keychain handle reference (`secret://`). */ + export const isHandle = (s: string): boolean => s.startsWith(HANDLE_PREFIX) + /** Build a handle reference for an account name. */ + export const makeHandle = (account: string): string => HANDLE_PREFIX + account + /** Extract the account name from a handle reference. */ + export const handleAccount = (handle: string): string => handle.slice(HANDLE_PREFIX.length) + /** True if the value is already an indirection (env ref or handle) — i.e. NOT raw plaintext. */ + export const isReference = (s: string): boolean => containsEnvRef(s) || isHandle(s) + + export interface ExpandResult { + /** The fully-expanded string (missing vars without a default become ""). */ + value: string + /** Names of `${VAR}` references that had no env value and no default (warned, not blocked). */ + missing: string[] + } + + /** + * Expand every `${VAR}` / `${VAR:-default}` in `input` using `env`. Semantics match + * claude-code: an unset (or empty) var with a `:-default` uses the default; an unset + * var WITHOUT a default expands to "" and is reported in `missing` (the caller WARNS + * but does not block — a missing var must not crash the connection path). + */ + export const expandEnvRefs = (input: string, env: NodeJS.ProcessEnv = process.env): ExpandResult => { + const missing: string[] = [] + const value = input.replace(ENV_REF_G, (_m, name: string, def: string | undefined) => { + const raw = env[name] + if (raw !== undefined && raw !== "") return raw + if (def !== undefined) return def + missing.push(name) + return "" + }) + return { value, missing } + } + + // ════════════════════════════════════════════════════════════════════════════ + // Keychain backends (Step 2) — INJECTABLE so tests never touch the real OS. + // ════════════════════════════════════════════════════════════════════════════ + + /** + * A pluggable secret backend. The store layer picks one via `selectBackend`, but tests + * inject an in-memory / file backend so they never read or write the real OS keychain. + */ + export interface Backend { + readonly id: string + /** True if this backend can be used in the current environment (no side effects). */ + readonly available: () => Promise + readonly put: (account: string, secret: string) => Promise + readonly get: (account: string) => Promise + readonly remove: (account: string) => Promise + } + + /** In-memory backend — TEST ONLY. Never persists; isolated per instance. */ + export const inMemoryBackend = (id = "memory"): Backend => { + const map = new Map() + return { + id, + available: async () => true, + put: async (account, secret) => void map.set(account, secret), + get: async (account) => map.get(account), + remove: async (account) => void map.delete(account), + } + } + + /** + * Fail-safe FILE backend (the fallback when no OS keyring is available). Stores secrets + * in a single `chmod 0600` JSON file UNDER THE DATA DIR — never inside the project config + * repo — so a config-repo leak does not leak credentials. This is not as strong as an OS + * keychain (the value is at rest on disk, only protected by file mode), hence it warns. + */ + export const fileBackend = (filePath: string = defaultFilePath()): Backend => { + const fs = nodeFs + const readAll = (): Record => { + try { + const text = fs.readFileSync(filePath, "utf8") + const parsed = JSON.parse(text) + return parsed && typeof parsed === "object" ? (parsed as Record) : {} + } catch { + return {} + } + } + const writeAll = (data: Record) => { + fs.mkdirSync(path.dirname(filePath), { recursive: true }) + // Write then chmod 0600 (owner read/write only). + fs.writeFileSync(filePath, JSON.stringify(data, null, 2), { mode: 0o600 }) + try { + fs.chmodSync(filePath, 0o600) + } catch { + /* best-effort on platforms without POSIX modes */ + } + } + return { + id: "file", + available: async () => true, + put: async (account, secret) => { + const data = readAll() + data[account] = secret + writeAll(data) + }, + get: async (account) => readAll()[account], + remove: async (account) => { + const data = readAll() + delete data[account] + writeAll(data) + }, + } + } + + /** Default location for the fail-safe credentials file: under the data dir, NOT the repo. */ + export const defaultFilePath = (): string => path.join(Global.Path.data, "mcp-secrets.json") + + const KEYCHAIN_SERVICE = "deepagent-code-mcp" + + /** + * macOS Keychain backend — REAL, via the `security` subprocess (same mechanism + * claude-code uses). NOTE: `security add-generic-password -w ` passes the + * secret on the command line, so it is briefly visible in this user's process table; + * this is the documented macOS-CLI limitation, not a value that lands in config/logs. + */ + export const macOsKeychainBackend = (): Backend => ({ + id: "macos-keychain", + available: async () => { + if (process.platform !== "darwin") return false + const res = await Process.run(["security", "list-keychains"], { nothrow: true }).catch(() => undefined) + return !!res && res.code === 0 + }, + put: async (account, secret) => { + // -U updates an existing item instead of erroring on a duplicate. + const res = await Process.run( + ["security", "add-generic-password", "-a", account, "-s", KEYCHAIN_SERVICE, "-U", "-w", secret], + { nothrow: true }, + ) + if (res.code !== 0) throw new Error(`security add-generic-password failed (code ${res.code})`) + }, + get: async (account) => { + const res = await Process.run( + ["security", "find-generic-password", "-a", account, "-s", KEYCHAIN_SERVICE, "-w"], + { nothrow: true }, + ) + if (res.code !== 0) return undefined + // `-w` prints just the password; strip the trailing newline. + return res.stdout.toString().replace(/\n$/, "") + }, + remove: async (account) => { + await Process.run(["security", "delete-generic-password", "-a", account, "-s", KEYCHAIN_SERVICE], { + nothrow: true, + }) + }, + }) + + /** + * Linux libsecret (Secret Service) backend — NOT YET IMPLEMENTED natively. + * TODO(S1-v3.5): wire `secret-tool store/lookup` (libsecret) when a Secret Service + * daemon is present. Until then it reports unavailable so selection degrades to the + * REAL 0600 file fallback — we do NOT fake a keyring. + */ + export const libsecretBackend = (): Backend => ({ + id: "libsecret", + available: async () => false, // TODO: detect + use `secret-tool` (libsecret) on Linux. + put: async () => { + throw new Error("libsecret backend not implemented") + }, + get: async () => undefined, + remove: async () => {}, + }) + + /** + * Windows DPAPI backend — NOT YET IMPLEMENTED natively. + * TODO(S1-v3.5): wrap DPAPI (CryptProtectData) or Credential Manager. Until then it + * reports unavailable so selection degrades to the REAL 0600 file fallback. + */ + export const dpapiBackend = (): Backend => ({ + id: "dpapi", + available: async () => false, // TODO: implement DPAPI / Windows Credential Manager. + put: async () => { + throw new Error("DPAPI backend not implemented") + }, + get: async () => undefined, + remove: async () => {}, + }) + + /** + * Pick the best available backend for the current platform, fail-safe: try the native + * OS keyring first, and on any unavailability fall back to the 0600 file backend with a + * loud warning (never fail-open, never write into the project config repo). + */ + export const selectBackend = async (): Promise => { + const native = + process.platform === "darwin" + ? macOsKeychainBackend() + : process.platform === "win32" + ? dpapiBackend() + : libsecretBackend() + try { + if (await native.available()) return native + } catch { + /* fall through to file fallback */ + } + log.warn("no OS keyring available; falling back to a chmod 0600 local credentials file", { + attempted: native.id, + file: defaultFilePath(), + }) + return fileBackend() + } + + // ════════════════════════════════════════════════════════════════════════════ + // Service + // ════════════════════════════════════════════════════════════════════════════ + + export interface Interface { + /** Store a secret under an account, returning the `secret://` handle to embed. */ + readonly put: (account: string, secret: string) => Effect.Effect + /** Resolve a `secret://` handle (or bare account) to its value, or undefined. */ + readonly resolve: (handle: string) => Effect.Effect + /** Remove a stored secret. */ + readonly remove: (account: string) => Effect.Effect + /** The id of the active backend (e.g. "macos-keychain" | "file"). */ + readonly backendId: string + /** True when the active backend is the fail-safe file fallback (a degraded posture). */ + readonly isFallback: boolean + } + + export class Service extends Context.Service()("@deepagent-code/McpSecretStore") {} + + /** Build the service from an injected backend (the single seam for tests + platform). */ + export const make = (backend: Backend): Interface => ({ + backendId: backend.id, + isFallback: backend.id === "file", + put: (account, secret) => + Effect.tryPromise({ + try: () => backend.put(account, secret).then(() => makeHandle(account)), + catch: (e) => (e instanceof Error ? e : new Error(String(e))), + }).pipe(Effect.orDie), + resolve: (handle) => + Effect.tryPromise({ + try: () => backend.get(isHandle(handle) ? handleAccount(handle) : handle), + catch: (e) => (e instanceof Error ? e : new Error(String(e))), + }).pipe(Effect.catch(() => Effect.succeed(undefined))), + remove: (account) => + Effect.tryPromise({ + try: () => backend.remove(isHandle(account) ? handleAccount(account) : account), + catch: (e) => (e instanceof Error ? e : new Error(String(e))), + }).pipe(Effect.catch(() => Effect.void)), + }) + + /** Default layer: select a real backend at build time (fail-safe to the 0600 file). */ + export const layer: Layer.Layer = Layer.effect( + Service, + Effect.gen(function* () { + const backend = yield* Effect.promise(() => selectBackend()) + return Service.of(make(backend)) + }), + ) + + export const defaultLayer = layer + + /** Test layer with an injectable backend (defaults to in-memory). */ + export const testLayer = (backend: Backend = inMemoryBackend()): Layer.Layer => + Layer.succeed(Service, make(backend)) + + // ════════════════════════════════════════════════════════════════════════════ + // Connect-time resolution (used by mcp/index.ts) — values never written back. + // ════════════════════════════════════════════════════════════════════════════ + + /** + * Resolve a single config value: expand `${VAR}` from env, resolve a `secret://` handle + * via the store, or pass through a literal. Returns `undefined` when a handle cannot be + * resolved (caller drops the key). Missing `${VAR}` references warn (by NAME only — never + * the value) but still return the partially-expanded string (warn, don't block). + */ + export const resolveValue = ( + value: string, + store: Interface, + env: NodeJS.ProcessEnv = process.env, + ): Effect.Effect => + Effect.gen(function* () { + if (isHandle(value)) { + const resolved = yield* store.resolve(value) + if (resolved === undefined) { + log.warn("could not resolve secret handle; dropping value", { handle: value }) + return undefined + } + return resolved + } + if (containsEnvRef(value)) { + const { value: expanded, missing } = expandEnvRefs(value, env) + if (missing.length > 0) { + // Warn by VARIABLE NAME only — the resolved value never enters the log. + log.warn("MCP credential env var(s) not set; connecting without them", { missing }) + } + return expanded + } + return value + }) + + /** + * Resolve every value in an env/headers record for the connection path. The result is a + * fresh object — the original config (and the persisted file) keep their `${VAR}`/handle + * references; only the live transport sees real values. Handle entries that fail to + * resolve are dropped. + */ + export const resolveRecord = ( + record: Record | undefined, + store: Interface, + env: NodeJS.ProcessEnv = process.env, + ): Effect.Effect> => + Effect.gen(function* () { + const out: Record = {} + if (!record) return out + for (const [key, value] of Object.entries(record)) { + const resolved = yield* resolveValue(value, store, env) + if (resolved !== undefined) out[key] = resolved + } + return out + }) + + // ════════════════════════════════════════════════════════════════════════════ + // Migration: existing plaintext secrets in cfg.mcp → keychain handles. + // ════════════════════════════════════════════════════════════════════════════ + + export interface MigrationMove { + server: string + field: "environment" | "headers" + key: string + handle: string + } + export interface MigrationFailure { + server: string + field: "environment" | "headers" + key: string + error: string + } + export interface MigrationOutcome { + /** A NEW config map with migrated secrets replaced by handles (originals untouched). */ + config: Record + moved: MigrationMove[] + failures: MigrationFailure[] + /** True if anything changed (caller should persist `config`). */ + changed: boolean + } + + /** Header names whose VALUE is treated as secret-bearing by default (case-insensitive). */ + const DEFAULT_SECRET_HEADERS = new Set(["authorization", "x-api-key", "api-key"]) + + /** All `secret:true` credential KEY names declared across the preset catalog. */ + export const catalogSecretEnvKeys = (): Set => { + const keys = new Set() + for (const entry of McpCatalog.list()) { + for (const cred of entry.credentials) if (cred.secret) keys.add(cred.key) + } + return keys + } + + const accountFor = (server: string, field: string, key: string) => `mcp:${server}:${field}:${key}` + + /** + * One-shot startup migration: find PLAINTEXT secret values in `cfg.mcp` (env values whose + * key is a known secret credential; secret-bearing header values) and move them into the + * secret store, replacing each with a `secret://` handle, then return a new config to + * persist. Existing `${VAR}` references and handles are left alone. + * + * TRANSACTIONAL / no credential loss: each secret is `put` AND read back to verify BEFORE + * its plaintext is replaced. A failed put/verify leaves THAT plaintext intact (reported in + * `failures`) while already-migrated secrets stay migrated — a partial failure never drops + * a credential. The caller persists `config` only when `changed` is true. + */ + export const migratePlaintextSecrets = ( + mcp: Record, + store: Interface, + opts?: { secretEnvKeys?: Set; secretHeaders?: Set }, + ): Effect.Effect => + Effect.gen(function* () { + const secretEnvKeys = opts?.secretEnvKeys ?? catalogSecretEnvKeys() + const secretHeaders = opts?.secretHeaders ?? DEFAULT_SECRET_HEADERS + // Work on a deep copy so a mid-loop failure never corrupts the caller's object. + const next: Record = structuredClone(mcp) + const moved: MigrationMove[] = [] + const failures: MigrationFailure[] = [] + + // Commit one secret transactionally: put → verify resolve → only then replace. + const commit = ( + server: string, + field: "environment" | "headers", + key: string, + plaintext: string, + assign: (handle: string) => void, + ) => + Effect.gen(function* () { + const account = accountFor(server, field, key) + const putExit = yield* Effect.exit(store.put(account, plaintext)) + if (putExit._tag === "Failure") { + failures.push({ server, field, key, error: "put failed; plaintext preserved" }) + return + } + const handle = putExit.value + // Verify the secret is actually retrievable before erasing the plaintext. + const check = yield* store.resolve(handle) + if (check !== plaintext) { + failures.push({ server, field, key, error: "verify failed; plaintext preserved" }) + return + } + assign(handle) + moved.push({ server, field, key, handle }) + }) + + for (const [server, config] of Object.entries(next)) { + if (config.type === "local" && config.environment) { + const env = config.environment as Record + for (const [envKey, value] of Object.entries(env)) { + if (isReference(value)) continue // already a ${VAR} / handle + if (!secretEnvKeys.has(envKey)) continue // not a known secret env var + yield* commit(server, "environment", envKey, value, (handle) => { + env[envKey] = handle + }) + } + } + if (config.type === "remote" && config.headers) { + const headers = config.headers as Record + for (const [headerName, value] of Object.entries(headers)) { + if (isReference(value)) continue + if (!secretHeaders.has(headerName.toLowerCase())) continue + yield* commit(server, "headers", headerName, value, (handle) => { + headers[headerName] = handle + }) + } + } + } + + return { config: next, moved, failures, changed: moved.length > 0 } + }) +} + +export * as McpSecretStore from "./secret-store" diff --git a/packages/deepagent-code/src/profile/adapters/index.ts b/packages/deepagent-code/src/profile/adapters/index.ts new file mode 100644 index 00000000..df0922df --- /dev/null +++ b/packages/deepagent-code/src/profile/adapters/index.ts @@ -0,0 +1,267 @@ +import { which } from "@deepagent-code/core/util/which" +import * as Log from "@deepagent-code/core/util/log" +import { PAP } from "@/profile/pap" +import { RuntimeBase } from "@/runtime/base" + +import { NcuAdapter } from "./ncu" +import { NsysAdapter } from "./nsys" +import { RocprofAdapter } from "./rocprof" +import { VtuneAdapter } from "./vtune" +import { PerfAdapter } from "./perf" + +// Re-export individual adapter factories and probes for convenience. +export * from "./ncu" +export * from "./nsys" +export * from "./rocprof" +export * from "./vtune" +export * from "./perf" + +const log = Log.create({ service: "profile.adapter-registry" }) + +/** + * P2A (S1-v3.5): profiler adapter registry. + * + * Mirrors `src/debug/adapter.ts` (`DebugAdapter.Registry`): + * - Declarative adapter registration / lookup. + * - Injectable binary probe (`BinaryProbe`) for testable capability detection. + * - Graceful-missing: missing binary or no GPU → clear message, NEVER Die. + * - Privilege declarations forwarded to R0's fail-closed gate. + * + * P3A (the `profile` tool) calls `resolve({ vendor?, domain? })` to auto-select + * an adapter by hardware/language, or `resolveById("ncu")` to pick explicitly. + * The returned `PAP.ProfileAdapter` implements collect→parse→normalize. + * + * Domain packs contribute adapters via `register()`: + * - CUDA pack: registers ncu + nsys + * - ROCm pack: registers rocprof + * - Intel pack: registers vtune + * - Core: registers perf (CPU-generic, available everywhere perf is installed) + */ +export namespace ProfileAdapterRegistry { + // —— binary probe (injectable, mirrors DebugAdapter.BinaryProbe) —————————— + + /** + * Locates a profiler executable on PATH. Pure detection — no spawn, no side + * effects. Injected so tests can simulate "installed" / "missing" without + * touching the real system. + */ + export interface BinaryProbe { + /** Resolve an executable to its absolute path, or null when absent. */ + readonly locate: (command: string) => string | null + } + + /** Default probe: real PATH lookup via core's `which`. */ + export const defaultProbe: BinaryProbe = { locate: (command) => which(command) } + + /** Test probe: only the named commands are "installed"; everything else is missing. */ + export const installedProbe = (installed: Iterable): BinaryProbe => { + const set = new Set(installed) + return { locate: (command) => (set.has(command) ? `/usr/local/bin/${command}` : null) } + } + + /** Test probe: every binary is missing (for graceful-missing assertions). */ + export const missingProbe: BinaryProbe = { locate: () => null } + + // —— resolution result ———————————————————————————————————————————————————— + + /** + * The outcome of resolving an adapter. Either a `PAP.ProfileAdapter` ready for + * collect→parse→normalize, or a graceful "not installed / not registered" report + * carrying a clear install message — never an exception. + */ + export type Resolution = + | { readonly available: true; readonly adapter: PAP.ProfileAdapter } + | { readonly available: false; readonly adapterId: string; readonly message: string } + + // —— registry ———————————————————————————————————————————————————————————— + + /** + * The adapter registry P3A (the `profile` tool) consumes. + * + * Auto-select by `{ vendor, domain }` or pick by id. Each registered adapter + * was constructed with an injected `BinaryProbe`; the registry checks the binary + * is present before returning it (graceful-missing if absent). + * + * The binary probe is injected at construction (mirrors `RuntimeBase.make(probe)`) + * so capability detection is fully testable without real hardware. + */ + export class Registry { + private readonly adapters = new Map() + + constructor(private readonly probe: BinaryProbe) {} + + /** Register (or replace) an adapter. Domain-pack contribution hook. */ + register(adapter: PAP.ProfileAdapter): void { + this.adapters.set(adapter.id, adapter) + } + + /** Remove an adapter (e.g. when a domain pack deactivates). */ + unregister(id: string): void { + this.adapters.delete(id) + } + + /** Whether an adapter id is currently registered. */ + has(id: string): boolean { + return this.adapters.has(id) + } + + /** The adapter definition for an id, if registered. */ + get(id: string): PAP.ProfileAdapter | undefined { + return this.adapters.get(id) + } + + /** All registered adapters, in registration order. */ + list(): PAP.ProfileAdapter[] { + return [...this.adapters.values()] + } + + /** + * All registered adapters matching vendor + domain criteria. + * Either field may be omitted to match all. + */ + listFor(criteria: { vendor?: PAP.Vendor; domain?: PAP.Domain }): PAP.ProfileAdapter[] { + return this.list().filter((a) => { + if (criteria.vendor && a.vendor !== criteria.vendor) return false + if (criteria.domain && a.domain !== criteria.domain) return false + return true + }) + } + + /** + * Check whether the profiler binary for an adapter is installed. + * Maps adapter ids to their primary binary names. + */ + private isBinaryPresent(adapterId: string): boolean { + const binaryNames: Record = { + ncu: ["ncu"], + nsys: ["nsys"], + rocprof: ["rocprofv3", "rocprof"], + vtune: ["vtune"], + perf: ["perf"], + } + const names = binaryNames[adapterId] ?? [adapterId] + return names.some((n) => this.probe.locate(n) !== null) + } + + /** + * Resolve a `PAP.ProfileAdapter` by adapter id. + * Missing binary → graceful `{ available:false, message }` (logged at info), never a throw. + */ + resolveById(id: string): Resolution { + const adapter = this.get(id) + if (!adapter) { + const message = `No profiler adapter registered with id "${id}".` + log.info(message) + return { available: false, adapterId: id, message } + } + if (!this.isBinaryPresent(id)) { + const message = buildMissingMessage(id) + log.info(message) + return { available: false, adapterId: id, message } + } + return { available: true, adapter } + } + + /** + * Resolve the best adapter for a vendor + domain combination. + * Picks the first registered adapter matching both criteria whose binary is present. + * Graceful-missing when none is found or no binary present. + */ + resolve(criteria: { vendor?: PAP.Vendor; domain?: PAP.Domain }): Resolution { + const candidates = this.listFor(criteria) + if (!candidates.length) { + const message = `No profiler adapter registered for vendor="${criteria.vendor ?? "*"}" domain="${criteria.domain ?? "*"}".` + log.info(message) + return { available: false, adapterId: `${criteria.vendor ?? "*"}/${criteria.domain ?? "*"}`, message } + } + for (const adapter of candidates) { + if (this.isBinaryPresent(adapter.id)) { + return { available: true, adapter } + } + } + const ids = candidates.map((a) => a.id).join(", ") + const message = `Profiler binaries for [${ids}] are not installed. ${buildMissingMessage(candidates[0]!.id)}` + log.info(message) + return { available: false, adapterId: candidates[0]!.id, message } + } + + /** + * Enumerate all available (binary-present) adapters. + * Useful for P3A's "which profilers can I use right now?" capability check. + */ + available(): PAP.ProfileAdapter[] { + return this.list().filter((a) => this.isBinaryPresent(a.id)) + } + + /** + * Aggregate privilege declarations from all registered adapters. + * P3A passes these to R0's privilege gate before dispatching a collect operation. + */ + privilegesFor(adapterId: string): readonly RuntimeBase.PrivilegeSpec[] { + return this.adapters.get(adapterId)?.privileges ?? [] + } + } + + // —— install guidance ———————————————————————————————————————————————————— + + const INSTALL_GUIDANCE: Record = { + ncu: "Install NVIDIA Nsight Compute: https://developer.nvidia.com/nsight-compute (part of CUDA Toolkit).", + nsys: "Install NVIDIA Nsight Systems: https://developer.nvidia.com/nsight-systems (part of CUDA Toolkit).", + rocprof: "Install ROCm profiling: `sudo apt install rocprofiler-sdk` or see https://rocm.docs.amd.com.", + vtune: "Install Intel VTune Profiler (Intel oneAPI Base Toolkit): https://www.intel.com/content/www/us/en/developer/tools/oneapi/vtune-profiler.html.", + perf: "Install Linux perf: `sudo apt install linux-perf` or `sudo apt install linux-tools-$(uname -r)`.", + } + + function buildMissingMessage(adapterId: string): string { + const guidance = INSTALL_GUIDANCE[adapterId] ?? `Install the profiler tool for adapter "${adapterId}".` + return `Profiler "${adapterId}" is not available: binary not found on PATH. ${guidance}` + } + + // —— base set (adapters that ship with core) ———————————————————————————— + + /** + * Build a registry pre-loaded with all five built-in adapters (ncu/nsys/rocprof/vtune/perf). + * The probe controls binary detection; defaults to real PATH lookup. + * + * Domain packs may add their own adapters after construction via `register()`. + */ + export const make = (probe: BinaryProbe = defaultProbe): Registry => { + const registry = new Registry(probe) + // Each adapter is constructed with its own BinaryProbe adapter derived from the registry probe. + // We mirror the debug adapter pattern: each adapter class accepts a BinaryProbe at construction. + const adapterProbe = { + locate: (cmd: string) => probe.locate(cmd), + } + registry.register(new NcuAdapter(adapterProbe)) + registry.register(new NsysAdapter(adapterProbe)) + registry.register(new RocprofAdapter(adapterProbe)) + registry.register(new VtuneAdapter(adapterProbe)) + registry.register(new PerfAdapter(adapterProbe)) + return registry + } + + // —— domain-pack contribution hooks —————————————————————————————————————— + + /** + * CUDA domain-pack hook: register ncu + nsys on pack activation. + * Equivalent to calling `registry.register(ncu)` + `registry.register(nsys)`. + */ + export const registerCudaAdapters = (registry: Registry, probe: BinaryProbe = defaultProbe): void => { + registry.register(new NcuAdapter(probe)) + registry.register(new NsysAdapter(probe)) + } + + /** + * ROCm domain-pack hook: register rocprofv3 on pack activation. + */ + export const registerRocmAdapters = (registry: Registry, probe: BinaryProbe = defaultProbe): void => { + registry.register(new RocprofAdapter(probe)) + } + + /** + * Intel domain-pack hook: register VTune on pack activation. + */ + export const registerIntelAdapters = (registry: Registry, probe: BinaryProbe = defaultProbe): void => { + registry.register(new VtuneAdapter(probe)) + } +} diff --git a/packages/deepagent-code/src/profile/adapters/ncu.ts b/packages/deepagent-code/src/profile/adapters/ncu.ts new file mode 100644 index 00000000..fdd3b73a --- /dev/null +++ b/packages/deepagent-code/src/profile/adapters/ncu.ts @@ -0,0 +1,355 @@ +import * as Log from "@deepagent-code/core/util/log" +import { which } from "@deepagent-code/core/util/which" +import { PAP } from "@/profile/pap" +import { Vocabulary } from "@/profile/vocabulary" +import { RuntimeBase } from "@/runtime/base" + +const log = Log.create({ service: "profile.ncu" }) + +// —— binary probe (injectable, mirrors DebugAdapter.BinaryProbe) —————————————— + +export interface NcuBinaryProbe { + readonly locate: (command: string) => string | null +} + +export const defaultNcuProbe: NcuBinaryProbe = { locate: (cmd) => which(cmd) } +export const installedNcuProbe = (installed: Iterable): NcuBinaryProbe => { + const set = new Set(installed) + return { locate: (cmd) => (set.has(cmd) ? `/usr/local/bin/${cmd}` : null) } +} +export const missingNcuProbe: NcuBinaryProbe = { locate: () => null } + +// —— mapping ———————————————————————————————————————————————————————————————— + +/** + * ncu native metric names (from ncu --csv output). + * See §P1A-V 表1 and NVIDIA Nsight Compute Profiling Guide. + */ +const N = { + computeThroughput: "sm__throughput.avg.pct_of_peak_sustained_elapsed", + memoryThroughput: "gpu__compute_memory_throughput.avg.pct_of_peak_sustained_elapsed", + dramBandwidth: "gpu__dram_throughput.avg.pct_of_peak_sustained_elapsed", + l2Throughput: "lts__throughput.avg.pct_of_peak_sustained_elapsed", + occupancy: "sm__warps_active.avg.pct_of_peak_sustained_active", + // sm__pipe_fma_cycles_active is an approximation of vector ALU utilization (ncu has + // no single exact equivalent to rocprof VALUUtilization). + valuUtilization: "sm__pipe_fma_cycles_active.avg.pct_of_peak_sustained_active", + duration: "gpu__time_duration.sum", +} as const + +const AVAILABLE = Object.values(N) as string[] + +export const ncuMapping: PAP.MetricMapping = { + adapterId: "ncu", + domain: "gpu_kernel", + availableMetrics: AVAILABLE, + entries: [ + { neutral: "compute_throughput_pct", native: N.computeThroughput, semantic: "exact" }, + { neutral: "memory_throughput_pct", native: N.memoryThroughput, semantic: "exact" }, + { neutral: "dram_bandwidth_pct", native: N.dramBandwidth, semantic: "exact" }, + { neutral: "l2_throughput_pct", native: N.l2Throughput, semantic: "exact" }, + { neutral: "occupancy_pct", native: N.occupancy, semantic: "exact" }, + // sm__pipe_fma_cycles_active is approximate for valu_utilization: it measures FMA pipe + // activity, not all vector ALU paths. §P1A-V 映射原则 2. + { neutral: "valu_utilization_pct", native: N.valuUtilization, semantic: "approximate" }, + // ncu has NO direct scalar ALU busy metric — salu_busy_pct is AMD-native. §P1A-V 表1. + { neutral: "salu_busy_pct", native: null, reason: "metric_not_in_this_profiler", detail: "ncu has no scalar ALU busy metric; SALUBusy is AMD-native" }, + { neutral: "duration_ns", native: N.duration, semantic: "exact" }, + // compute_bound is PAP-derived: compute throughput > memory throughput by threshold. + { + neutral: "compute_bound", + native: [N.computeThroughput, N.memoryThroughput], + semantic: "exact", + derived: true, + formula: "compute_throughput_pct > memory_throughput_pct", + }, + ], +} + +// validate at module load (registration-time anti-套壳 gate) +const _mappingValidation = Vocabulary.validateMapping(ncuMapping) +if (!_mappingValidation.ok) { + log.warn("ncu mapping validation failed at load time", { issues: _mappingValidation.issues }) +} + +// —— CSV parsing helpers ———————————————————————————————————————————————————— + +/** + * Parse ncu --csv output. Each row is one metric for one kernel invocation. + * Columns (in order): ID, Process ID, Process Name, Host Name, Kernel Name, + * Kernel Time, Context, Stream, Section Name, Metric Name, Metric Unit, Metric Value. + * Returns a map: kernelName → { metricName → value }. + */ +export function parseNcuCsv(csv: string): Map> { + const result = new Map>() + const lines = csv.split(/\r?\n/).filter((l) => l.trim() && !l.startsWith('"ID"') && !l.startsWith("ID,")) + for (const line of lines) { + const cols = splitCsvRow(line) + if (cols.length < 12) continue + // columns: ID, PID, ProcName, Host, KernelName, KernelTime, Ctx, Stream, Section, MetricName, MetricUnit, MetricValue + const kernelName = cols[4]?.trim().replace(/^"|"$/g, "") ?? "" + const metricName = cols[9]?.trim().replace(/^"|"$/g, "") ?? "" + const metricValue = parseFloat(cols[11]?.trim().replace(/^"|"$/g, "") ?? "NaN") + if (!kernelName || !metricName || isNaN(metricValue)) continue + if (!result.has(kernelName)) result.set(kernelName, new Map()) + result.get(kernelName)!.set(metricName, metricValue) + } + return result +} + +/** Minimal CSV row splitter (handles quoted fields). */ +function splitCsvRow(row: string): string[] { + const cols: string[] = [] + let cur = "" + let inQuote = false + for (let i = 0; i < row.length; i++) { + const ch = row[i]! + if (ch === '"') { inQuote = !inQuote } + else if (ch === "," && !inQuote) { cols.push(cur); cur = "" } + else { cur += ch } + } + cols.push(cur) + return cols +} + +// —— adapter ———————————————————————————————————————————————————————————————— + +export class NcuAdapter implements PAP.ProfileAdapter { + readonly id = "ncu" + readonly vendor = "nvidia" as const + readonly domain = "gpu_kernel" as const + readonly privileges: readonly RuntimeBase.PrivilegeSpec[] = [ + { kind: "gpu_performance_counter", reason: "ncu needs GPU hardware performance counters (requires NVIDIA driver permission or admin)" }, + ] + readonly mapping = ncuMapping + + constructor(private readonly probe: NcuBinaryProbe = defaultNcuProbe) {} + + async collect(target: PAP.ProfileTarget): Promise { + const bin = this.probe.locate("ncu") + if (!bin) { + const msg = "ncu (NVIDIA Nsight Compute) is not installed or not on PATH. Install it via the NVIDIA CUDA Toolkit." + log.info(msg) + return Promise.reject(new Error(msg)) + } + const outPath = `/tmp/deepagent-ncu-${Date.now()}` + const args = [ + "--set", "full", + "--target-processes", "all", + "-o", outPath, + "--", + target.command, + ...(target.args ?? []), + ] + log.info("ncu collect", { command: bin, args }) + // Build the export command for re-deriving a CSV view. + const exportCommand = `${bin} --import ${outPath}.ncu-rep --csv` + + const { Process } = await import("@/util/process") + const result = await Process.run([bin, ...args], { cwd: target.cwd, nothrow: true }) + if (result.code !== 0) { + const msg = `ncu exited with code ${result.code}: ${result.stderr.toString().trim()}` + log.warn(msg) + return Promise.reject(new Error(msg)) + } + return { + path: `${outPath}.ncu-rep`, + format: "ncu-rep", + exportCommand, + } + } + + async parse(report: PAP.NativeReportRef): Promise { + // Re-export to CSV via `ncu --import ... --csv`, or read if already CSV. + let csvText: string + if (report.format === "csv") { + const fs = await import("fs/promises") + csvText = await fs.readFile(report.path, "utf8") + } else { + const bin = this.probe.locate("ncu") + if (!bin) { + return Promise.reject(new Error("ncu binary required to parse .ncu-rep; not found on PATH")) + } + const { Process } = await import("@/util/process") + const result = await Process.run([bin, "--import", report.path, "--csv"], { nothrow: true }) + if (result.code !== 0) { + return Promise.reject(new Error(`ncu --import failed (code ${result.code}): ${result.stderr.toString().trim()}`)) + } + csvText = result.stdout.toString() + } + + const kernelMap = parseNcuCsv(csvText) + const hotspots: PAP.RawHotspot[] = [] + for (const [kernelName, metrics] of kernelMap) { + const nativeMetrics: Record = {} + for (const [k, v] of metrics) nativeMetrics[k] = v + hotspots.push({ + name: kernelName, + kind: "kernel", + nativeMetrics, + // self_pct derived from sm__throughput or left undefined here (normalize stage fills it) + }) + } + + // Build a summary from the first (or aggregated) kernel's metrics. + const firstKernel = hotspots[0] + const nativeSummary: Record = firstKernel + ? { ...firstKernel.nativeMetrics } + : {} + + return { + adapterId: this.id, + vendor: this.vendor, + domain: this.domain, + target: { command: report.path }, + nativeSummary, + hotspots, + availableMetrics: AVAILABLE, + raw_report_ref: report, + } + } + + normalize(raw: PAP.RawProfile): PAP.NormalizedProfile { + const summary: Record = {} + + const getNative = (bag: Record, key: string): number | undefined => { + const v = bag[key] + if (v === undefined || v === "") return undefined + const n = Number(v) + return isNaN(n) ? undefined : n + } + + // Compute top-level summary from nativeSummary (first kernel or aggregated). + const ns = raw.nativeSummary + const computePct = getNative(ns, N.computeThroughput) + const memPct = getNative(ns, N.memoryThroughput) + const dramPct = getNative(ns, N.dramBandwidth) + const l2Pct = getNative(ns, N.l2Throughput) + const occPct = getNative(ns, N.occupancy) + const valuPct = getNative(ns, N.valuUtilization) + const durationRaw = getNative(ns, N.duration) + + summary["compute_throughput_pct"] = computePct !== undefined + ? PAP.present(computePct, "pct", { nativeMetric: N.computeThroughput, semantic: "exact" }) + : PAP.missing("not_collected") + + summary["memory_throughput_pct"] = memPct !== undefined + ? PAP.present(memPct, "pct", { nativeMetric: N.memoryThroughput, semantic: "exact" }) + : PAP.missing("not_collected") + + summary["dram_bandwidth_pct"] = dramPct !== undefined + ? PAP.present(dramPct, "pct", { nativeMetric: N.dramBandwidth, semantic: "exact" }) + : PAP.missing("not_collected") + + summary["l2_throughput_pct"] = l2Pct !== undefined + ? PAP.present(l2Pct, "pct", { nativeMetric: N.l2Throughput, semantic: "exact" }) + : PAP.missing("not_collected") + + summary["occupancy_pct"] = occPct !== undefined + ? PAP.present(occPct, "pct", { nativeMetric: N.occupancy, semantic: "exact" }) + : PAP.missing("not_collected") + + summary["valu_utilization_pct"] = valuPct !== undefined + ? PAP.present(valuPct, "pct", { + nativeMetric: N.valuUtilization, + semantic: "approximate", // FMA pipe ≠ all vector ALU paths + }) + : PAP.missing("not_collected") + + // salu_busy_pct: ncu has no scalar ALU busy metric — honest null. + summary["salu_busy_pct"] = PAP.missing("metric_not_in_this_profiler", "ncu has no scalar ALU busy metric; SALUBusy is AMD-native") + + // duration_ns: ncu reports in nanoseconds (gpu__time_duration.sum unit = ns). + summary["duration_ns"] = durationRaw !== undefined + ? PAP.present(durationRaw, "ns", { nativeMetric: N.duration, semantic: "exact" }) + : PAP.missing("not_collected") + + // compute_bound: PAP-derived boolean — compute throughput strictly exceeds memory. + if (computePct !== undefined && memPct !== undefined) { + summary["compute_bound"] = PAP.present(computePct > memPct, "bool", { + nativeMetric: [N.computeThroughput, N.memoryThroughput], + semantic: "exact", + derived: true, + formula: "compute_throughput_pct > memory_throughput_pct", + }) + } else { + summary["compute_bound"] = PAP.missing("not_collected", "compute or memory throughput metrics missing") + } + + // self_pct is a TIME share, so derive it from each kernel's duration relative + // to the sum of all kernel durations — NOT from compute throughput (which is a + // rate, not a time, and would mis-rank hotspots and mislabel the number). + // When durations are unavailable we leave self_pct at 0 (honest: "unranked") + // rather than substituting an unrelated metric. + const kernelDurations = raw.hotspots.map((h) => getNative(h.nativeMetrics, N.duration)) + const totalDurationNs = kernelDurations.reduce((sum, d) => sum + (d ?? 0), 0) + + // Per-kernel hotspots. + const hotspots: PAP.Hotspot[] = raw.hotspots.map((h, i) => { + const nm = h.nativeMetrics + const cPct = getNative(nm, N.computeThroughput) + const mPct = getNative(nm, N.memoryThroughput) + const dur = getNative(nm, N.duration) + const durForSelf = kernelDurations[i] + const selfPct = + h.self_pct ?? (totalDurationNs > 0 && durForSelf !== undefined ? (durForSelf / totalDurationNs) * 100 : 0) + const metrics: Record = { + compute_throughput_pct: cPct !== undefined + ? PAP.present(cPct, "pct", { nativeMetric: N.computeThroughput, semantic: "exact" }) + : PAP.missing("not_collected"), + memory_throughput_pct: mPct !== undefined + ? PAP.present(mPct, "pct", { nativeMetric: N.memoryThroughput, semantic: "exact" }) + : PAP.missing("not_collected"), + dram_bandwidth_pct: (() => { + const v = getNative(nm, N.dramBandwidth) + return v !== undefined ? PAP.present(v, "pct", { nativeMetric: N.dramBandwidth, semantic: "exact" }) : PAP.missing("not_collected") + })(), + l2_throughput_pct: (() => { + const v = getNative(nm, N.l2Throughput) + return v !== undefined ? PAP.present(v, "pct", { nativeMetric: N.l2Throughput, semantic: "exact" }) : PAP.missing("not_collected") + })(), + occupancy_pct: (() => { + const v = getNative(nm, N.occupancy) + return v !== undefined ? PAP.present(v, "pct", { nativeMetric: N.occupancy, semantic: "exact" }) : PAP.missing("not_collected") + })(), + valu_utilization_pct: (() => { + const v = getNative(nm, N.valuUtilization) + return v !== undefined ? PAP.present(v, "pct", { nativeMetric: N.valuUtilization, semantic: "approximate" }) : PAP.missing("not_collected") + })(), + salu_busy_pct: PAP.missing("metric_not_in_this_profiler", "ncu has no scalar ALU busy metric"), + duration_ns: dur !== undefined + ? PAP.present(dur, "ns", { nativeMetric: N.duration, semantic: "exact" }) + : PAP.missing("not_collected"), + compute_bound: (cPct !== undefined && mPct !== undefined) + ? PAP.present(cPct > mPct, "bool", { + nativeMetric: [N.computeThroughput, N.memoryThroughput], + semantic: "exact", + derived: true, + formula: "compute_throughput_pct > memory_throughput_pct", + }) + : PAP.missing("not_collected", "compute or memory throughput missing"), + } + return { + kernel: h.name, + file_line: h.file_line, + self_pct: selfPct, + total_pct: h.total_pct, + metrics, + } + }) + + return { + domain: this.domain, + vendor: this.vendor, + adapterId: this.id, + target: raw.target, + duration_ns: durationRaw ?? null, + hotspots, + summary, + raw_report_ref: raw.raw_report_ref, + } + } +} + +export const makeNcuAdapter = (probe: NcuBinaryProbe = defaultNcuProbe): PAP.ProfileAdapter => + new NcuAdapter(probe) diff --git a/packages/deepagent-code/src/profile/adapters/nsys.ts b/packages/deepagent-code/src/profile/adapters/nsys.ts new file mode 100644 index 00000000..81af3c4d --- /dev/null +++ b/packages/deepagent-code/src/profile/adapters/nsys.ts @@ -0,0 +1,432 @@ +import * as Log from "@deepagent-code/core/util/log" +import { which } from "@deepagent-code/core/util/which" +import { PAP } from "@/profile/pap" +import { Vocabulary } from "@/profile/vocabulary" +import { RuntimeBase } from "@/runtime/base" + +const log = Log.create({ service: "profile.nsys" }) + +// —— binary probe ———————————————————————————————————————————————————————————— + +export interface NsysBinaryProbe { + readonly locate: (command: string) => string | null +} + +export const defaultNsysProbe: NsysBinaryProbe = { locate: (cmd) => which(cmd) } +export const installedNsysProbe = (installed: Iterable): NsysBinaryProbe => { + const set = new Set(installed) + return { locate: (cmd) => (set.has(cmd) ? `/usr/local/bin/${cmd}` : null) } +} +export const missingNsysProbe: NsysBinaryProbe = { locate: () => null } + +// —— mapping ———————————————————————————————————————————————————————————————— + +/** + * nsys native metric names as used in the RawProfile nativeSummary. + * nsys exports three separate CSV reports; we aggregate them into one flat + * nativeSummary with synthetic neutral-ish keys before normalization. + * + * §P1A-V 表2: gpu_timeline domain has kernel_total_pct, mem_copy_pct, api_overhead_pct. + */ +const N = { + // gpukernsum report: top kernel time percent + kernelTimePct: "kernel_time_pct", + // gpumemtimesum report: memory copy time percent + memCopyTimePct: "mem_copy_time_pct", + // cudaapisum report: CUDA API overhead percent + apiOverheadPct: "api_overhead_pct", +} as const + +const AVAILABLE = Object.values(N) as string[] + +export const nsysMapping: PAP.MetricMapping = { + adapterId: "nsys", + domain: "gpu_timeline", + availableMetrics: AVAILABLE, + entries: [ + { neutral: "kernel_total_pct", native: N.kernelTimePct, semantic: "exact" }, + { neutral: "mem_copy_pct", native: N.memCopyTimePct, semantic: "exact" }, + // nsys stats exposes API time only as a per-report internal percentage, with no + // GPU/wall-total denominator we can access — so we honestly declare it null rather + // than fabricate a "share of total" number. §P1A-V 映射原则 5. + { + neutral: "api_overhead_pct", + native: null, + reason: "not_collected", + detail: "nsys stats reports API time only as a per-report normalized percentage; no valid GPU/wall-total denominator", + }, + ], +} + +const _mappingValidation = Vocabulary.validateMapping(nsysMapping) +if (!_mappingValidation.ok) { + log.warn("nsys mapping validation failed at load time", { issues: _mappingValidation.issues }) +} + +// —— CSV parsing helpers ———————————————————————————————————————————————————— + +/** + * Simplified CSV row splitter (handles quoted fields). + */ +function splitCsvRow(row: string): string[] { + const cols: string[] = [] + let cur = "" + let inQuote = false + for (let i = 0; i < row.length; i++) { + const ch = row[i]! + if (ch === '"') { inQuote = !inQuote } + else if (ch === "," && !inQuote) { cols.push(cur); cur = "" } + else { cur += ch } + } + cols.push(cur) + return cols +} + +function cleanField(s: string): string { + return s.trim().replace(/^"|"$/g, "") +} + +export interface NsysKernelRow { + name: string + timePct: number + totalTimeNs: number + instances: number +} + +export interface NsysMemRow { + operation: string + timePct: number + totalTimeNs: number +} + +export interface NsysApiRow { + name: string + timePct: number + totalTimeNs: number +} + +/** + * Parse `nsys stats --report gpukernsum --format csv` output. + * Columns: Time (%), Total Time (ns), Instances, Average (ns), Minimum (ns), Maximum (ns), Name + */ +export function parseGpukernsum(csv: string): NsysKernelRow[] { + const rows: NsysKernelRow[] = [] + const lines = csv.split(/\r?\n/).filter((l) => l.trim()) + let headerIdx = -1 + const headers: string[] = [] + for (let i = 0; i < lines.length; i++) { + const line = lines[i]! + if (line.toLowerCase().includes("time (%)") || line.toLowerCase().includes("time(%)")) { + headerIdx = i + headers.push(...splitCsvRow(line).map(cleanField).map((h) => h.toLowerCase())) + break + } + } + if (headerIdx < 0) return rows + const timeIdx = headers.findIndex((h) => h.includes("time") && h.includes("%")) + const totalIdx = headers.findIndex((h) => h.includes("total") && h.includes("time")) + const instIdx = headers.findIndex((h) => h.includes("instance")) + const nameIdx = headers.length - 1 // Name is last column + + for (let i = headerIdx + 1; i < lines.length; i++) { + const cols = splitCsvRow(lines[i]!).map(cleanField) + if (cols.length < 2) continue + const timePct = parseFloat(cols[timeIdx >= 0 ? timeIdx : 0] ?? "0") + const totalTimeNs = parseFloat((cols[totalIdx >= 0 ? totalIdx : 1] ?? "0").replace(/,/g, "")) + const instances = parseInt(cols[instIdx >= 0 ? instIdx : 2] ?? "1", 10) + const name = cols[nameIdx] ?? cols[cols.length - 1] ?? "" + if (!name || isNaN(timePct)) continue + rows.push({ name, timePct, totalTimeNs, instances }) + } + return rows +} + +/** + * Parse `nsys stats --report gpumemtimesum --format csv` output. + * Columns: Time (%), Total Time (ns), Count, Average (ns), Minimum (ns), Maximum (ns), Operation + */ +export function parseGpumemtimesum(csv: string): NsysMemRow[] { + const rows: NsysMemRow[] = [] + const lines = csv.split(/\r?\n/).filter((l) => l.trim()) + let headerIdx = -1 + const headers: string[] = [] + for (let i = 0; i < lines.length; i++) { + const line = lines[i]! + if (line.toLowerCase().includes("time (%)") || line.toLowerCase().includes("time(%)")) { + headerIdx = i + headers.push(...splitCsvRow(line).map(cleanField).map((h) => h.toLowerCase())) + break + } + } + if (headerIdx < 0) return rows + const timeIdx = headers.findIndex((h) => h.includes("time") && h.includes("%")) + const totalIdx = headers.findIndex((h) => h.includes("total") && h.includes("time")) + const nameIdx = headers.length - 1 + + for (let i = headerIdx + 1; i < lines.length; i++) { + const cols = splitCsvRow(lines[i]!).map(cleanField) + if (cols.length < 2) continue + const timePct = parseFloat(cols[timeIdx >= 0 ? timeIdx : 0] ?? "0") + const totalTimeNs = parseFloat((cols[totalIdx >= 0 ? totalIdx : 1] ?? "0").replace(/,/g, "")) + const operation = cols[nameIdx] ?? cols[cols.length - 1] ?? "" + if (!operation || isNaN(timePct)) continue + rows.push({ operation, timePct, totalTimeNs }) + } + return rows +} + +/** + * Parse `nsys stats --report cudaapisum --format csv` output. + * Columns: Time (%), Total Time (ns), Num Calls, Average (ns), Minimum (ns), Maximum (ns), Name + */ +export function parseCudaapisum(csv: string): NsysApiRow[] { + const rows: NsysApiRow[] = [] + const lines = csv.split(/\r?\n/).filter((l) => l.trim()) + let headerIdx = -1 + const headers: string[] = [] + for (let i = 0; i < lines.length; i++) { + const line = lines[i]! + if (line.toLowerCase().includes("time (%)") || line.toLowerCase().includes("time(%)")) { + headerIdx = i + headers.push(...splitCsvRow(line).map(cleanField).map((h) => h.toLowerCase())) + break + } + } + if (headerIdx < 0) return rows + const timeIdx = headers.findIndex((h) => h.includes("time") && h.includes("%")) + const totalIdx = headers.findIndex((h) => h.includes("total") && h.includes("time")) + const nameIdx = headers.length - 1 + + for (let i = headerIdx + 1; i < lines.length; i++) { + const cols = splitCsvRow(lines[i]!).map(cleanField) + if (cols.length < 2) continue + const timePct = parseFloat(cols[timeIdx >= 0 ? timeIdx : 0] ?? "0") + const totalTimeNs = parseFloat((cols[totalIdx >= 0 ? totalIdx : 1] ?? "0").replace(/,/g, "")) + const name = cols[nameIdx] ?? cols[cols.length - 1] ?? "" + if (!name || isNaN(timePct)) continue + rows.push({ name, timePct, totalTimeNs }) + } + return rows +} + +/** + * Multi-section fixture format for tests: + * Sections are delimited by lines like "=== REPORT: gpukernsum ===" etc. + * Used by parse() and directly in tests. + */ +export function parseNsysMultiSectionCsv(text: string): { + kernels: NsysKernelRow[] + memOps: NsysMemRow[] + apiCalls: NsysApiRow[] +} { + const sections = new Map() + let currentSection = "" + let buf: string[] = [] + for (const line of text.split(/\r?\n/)) { + const m = line.match(/^===\s*REPORT:\s*(\w+)\s*===/) + if (m) { + if (currentSection && buf.length) sections.set(currentSection, buf.join("\n")) + currentSection = m[1]! + buf = [] + } else { + buf.push(line) + } + } + if (currentSection && buf.length) sections.set(currentSection, buf.join("\n")) + + return { + kernels: parseGpukernsum(sections.get("gpukernsum") ?? ""), + memOps: parseGpumemtimesum(sections.get("gpumemtimesum") ?? ""), + apiCalls: parseCudaapisum(sections.get("cudaapisum") ?? ""), + } +} + +// —— adapter ———————————————————————————————————————————————————————————————— + +export class NsysAdapter implements PAP.ProfileAdapter { + readonly id = "nsys" + readonly vendor = "nvidia" as const + readonly domain = "gpu_timeline" as const + readonly privileges: readonly RuntimeBase.PrivilegeSpec[] = [ + { kind: "gpu_performance_counter", reason: "nsys needs GPU performance counter access for kernel tracing" }, + ] + readonly mapping = nsysMapping + + constructor(private readonly probe: NsysBinaryProbe = defaultNsysProbe) {} + + async collect(target: PAP.ProfileTarget): Promise { + const bin = this.probe.locate("nsys") + if (!bin) { + const msg = "nsys (NVIDIA Nsight Systems) is not installed or not on PATH. Install it via the NVIDIA CUDA Toolkit." + log.info(msg) + return Promise.reject(new Error(msg)) + } + const outPath = `/tmp/deepagent-nsys-${Date.now()}` + const args = [ + "profile", + "-o", outPath, + "--force-overwrite", "true", + "--", + target.command, + ...(target.args ?? []), + ] + log.info("nsys collect", { command: bin, args }) + const exportCommand = `${bin} stats --report gpukernsum,gpumemtimesum,cudaapisum --format csv -o stdout ${outPath}.nsys-rep` + + const { Process } = await import("@/util/process") + const result = await Process.run([bin, ...args], { cwd: target.cwd, nothrow: true }) + if (result.code !== 0) { + const msg = `nsys exited with code ${result.code}: ${result.stderr.toString().trim()}` + log.warn(msg) + return Promise.reject(new Error(msg)) + } + return { + path: `${outPath}.nsys-rep`, + format: "nsys-rep", + exportCommand, + } + } + + async parse(report: PAP.NativeReportRef): Promise { + let text: string + if (report.format === "csv" || report.format === "text") { + const fs = await import("fs/promises") + text = await fs.readFile(report.path, "utf8") + } else { + // nsys-rep: need nsys stats to export CSV + const bin = this.probe.locate("nsys") + if (!bin) { + return Promise.reject(new Error("nsys binary required to parse .nsys-rep; not found on PATH")) + } + const { Process } = await import("@/util/process") + // Run each report type and concatenate with section headers for our multi-section parser. + const sections: string[] = [] + for (const report_type of ["gpukernsum", "gpumemtimesum", "cudaapisum"]) { + const r = await Process.run([bin, "stats", "--report", report_type, "--format", "csv", "-o", "stdout", report.path], { nothrow: true }) + sections.push(`=== REPORT: ${report_type} ===\n${r.stdout.toString()}`) + } + text = sections.join("\n") + } + + const { kernels, memOps, apiCalls } = parseNsysMultiSectionCsv(text) + + // Build hotspots from kernel table. + const hotspots: PAP.RawHotspot[] = kernels.map((k) => ({ + name: k.name, + kind: "kernel" as const, + self_pct: k.timePct, + total_pct: k.timePct, + nativeMetrics: { + [N.kernelTimePct]: k.timePct, + total_time_ns: k.totalTimeNs, + instances: k.instances, + }, + })) + + // Summary aggregates top-level metrics. + // + // The per-report `Time (%)` columns are each normalized WITHIN their own report + // (kernels sum to ~100%, mem ops sum to ~100%, api calls sum to ~100%), so summing + // them across reports is meaningless — it made api_overhead_pct≈100% unconditionally + // and forced roofline to call almost everything "latency-bound". Instead we derive + // real GPU-time shares from the nanosecond totals nsys reports per row. + const kernelNs = kernels.reduce((s, r) => s + (Number.isFinite(r.totalTimeNs) ? r.totalTimeNs : 0), 0) + const memNs = memOps.reduce((s, r) => s + (Number.isFinite(r.totalTimeNs) ? r.totalTimeNs : 0), 0) + const apiNs = apiCalls.reduce((s, r) => s + (Number.isFinite(r.totalTimeNs) ? r.totalTimeNs : 0), 0) + // GPU-side wall time = time spent in kernels + memory copies. This is the correct + // denominator for the compute-vs-transfer split that roofline consumes. + const gpuNs = kernelNs + memNs + const kernelTotalPct = gpuNs > 0 ? (kernelNs / gpuNs) * 100 : kernels.length > 0 ? kernels[0]!.timePct : 0 + const memCopyPct = gpuNs > 0 ? (memNs / gpuNs) * 100 : 0 + + const nativeSummary: Record = { + [N.kernelTimePct]: kernelTotalPct, + [N.memCopyTimePct]: memCopyPct, + // api_overhead is host-side CUDA/HIP runtime time that overlaps GPU work; there is + // no correct "share of GPU total" denominator available from these three reports, + // so we keep the raw ns for provenance and let normalize() report it as honest null. + kernel_ns_total: kernelNs, + mem_ns_total: memNs, + api_ns_total: apiNs, + } + + return { + adapterId: this.id, + vendor: this.vendor, + domain: this.domain, + target: { command: report.path }, + nativeSummary, + hotspots, + availableMetrics: AVAILABLE, + raw_report_ref: report, + } + } + + normalize(raw: PAP.RawProfile): PAP.NormalizedProfile { + const getNative = (bag: Record, key: string): number | undefined => { + const v = bag[key] + if (v === undefined || v === "") return undefined + const n = Number(v) + return isNaN(n) ? undefined : n + } + + const ns = raw.nativeSummary + const kernelPct = getNative(ns, N.kernelTimePct) + const memCopyPct = getNative(ns, N.memCopyTimePct) + + const summary: Record = { + kernel_total_pct: kernelPct !== undefined + ? PAP.present(kernelPct, "pct", { + nativeMetric: N.kernelTimePct, + semantic: "exact", + derived: true, + formula: "kernel_ns_total / (kernel_ns_total + mem_ns_total) * 100", + }) + : PAP.missing("not_collected"), + mem_copy_pct: memCopyPct !== undefined + ? PAP.present(memCopyPct, "pct", { + nativeMetric: N.memCopyTimePct, + semantic: "exact", + derived: true, + formula: "mem_ns_total / (kernel_ns_total + mem_ns_total) * 100", + }) + : PAP.missing("not_collected"), + // Host-side CUDA/HIP API time overlaps GPU execution and nsys reports it only as a + // per-report internal percentage, not as a share of any GPU/wall total we can access + // here. Reporting a number would be fabricated; honest null + reason instead. + api_overhead_pct: PAP.missing( + "not_collected", + "api_overhead needs total wall time as denominator; nsys stats reports only per-report normalized percentages", + ), + } + + const hotspots: PAP.Hotspot[] = raw.hotspots.map((h) => { + const kPct = h.self_pct ?? getNative(h.nativeMetrics as Record, N.kernelTimePct) ?? 0 + return { + kernel: h.name, + file_line: h.file_line, + self_pct: kPct, + total_pct: h.total_pct, + metrics: { + kernel_total_pct: PAP.present(kPct, "pct", { nativeMetric: N.kernelTimePct, semantic: "exact" }), + mem_copy_pct: PAP.missing("not_applicable_to_domain", "per-kernel mem copy not available in nsys gpukernsum"), + api_overhead_pct: PAP.missing("not_applicable_to_domain", "per-kernel API overhead not in gpukernsum"), + }, + } + }) + + return { + domain: this.domain, + vendor: this.vendor, + adapterId: this.id, + target: raw.target, + duration_ns: null, + hotspots, + summary, + raw_report_ref: raw.raw_report_ref, + } + } +} + +export const makeNsysAdapter = (probe: NsysBinaryProbe = defaultNsysProbe): PAP.ProfileAdapter => + new NsysAdapter(probe) diff --git a/packages/deepagent-code/src/profile/adapters/perf.ts b/packages/deepagent-code/src/profile/adapters/perf.ts new file mode 100644 index 00000000..eaf3d3e7 --- /dev/null +++ b/packages/deepagent-code/src/profile/adapters/perf.ts @@ -0,0 +1,376 @@ +import * as Log from "@deepagent-code/core/util/log" +import { which } from "@deepagent-code/core/util/which" +import { PAP } from "@/profile/pap" +import { Vocabulary } from "@/profile/vocabulary" +import { RuntimeBase } from "@/runtime/base" + +const log = Log.create({ service: "profile.perf" }) + +// —— binary probe ———————————————————————————————————————————————————————————— + +export interface PerfBinaryProbe { + readonly locate: (command: string) => string | null +} + +export const defaultPerfProbe: PerfBinaryProbe = { locate: (cmd) => which(cmd) } +export const installedPerfProbe = (installed: Iterable): PerfBinaryProbe => { + const set = new Set(installed) + return { locate: (cmd) => (set.has(cmd) ? `/usr/bin/${cmd}` : null) } +} +export const missingPerfProbe: PerfBinaryProbe = { locate: () => null } + +// —— mapping ———————————————————————————————————————————————————————————————— + +/** + * Linux perf native event/column names. + * See §P1A-V 表3 and `perf list` / `perf stat` output. + * cpu_sampling domain: NO memory_bound_pct or dram_bound_pct (those are cpu_hotspot only). + */ +const N = { + overhead: "overhead", + cycles: "cycles", + instructions: "instructions", + cacheMisses: "cache-misses", + cacheReferences: "cache-references", + branchMisses: "branch-misses", + branches: "branches", +} as const + +const AVAILABLE = Object.values(N) as string[] + +export const perfMapping: PAP.MetricMapping = { + adapterId: "perf", + domain: "cpu_sampling", + availableMetrics: AVAILABLE, + entries: [ + { neutral: "self_pct", native: N.overhead, semantic: "exact" }, + // cpi: vocabulary says derived:false (it's a native concept), but perf computes it from + // cycles/instructions. We map both natives; formula goes in MetricProvenance on output. + { neutral: "cpi", native: [N.cycles, N.instructions], semantic: "exact" }, + // ipc: vocabulary says derived:true; must mark derived:true + provide formula. + { + neutral: "ipc", + native: [N.instructions, N.cycles], + semantic: "exact", + derived: true, + formula: "instructions / cycles", + }, + { neutral: "clockticks", native: N.cycles, semantic: "exact" }, + { neutral: "instructions_retired", native: N.instructions, semantic: "exact" }, + { neutral: "cache_miss_rate", native: [N.cacheMisses, N.cacheReferences], semantic: "exact" }, + { neutral: "branch_misprediction_pct", native: [N.branchMisses, N.branches], semantic: "exact" }, + // memory_bound_pct and dram_bound_pct are cpu_hotspot domain only — NOT applicable to cpu_sampling. + // (Vocabulary.metricsForDomain("cpu_sampling") does NOT include them, so we must NOT map them.) + ], +} + +const _mappingValidation = Vocabulary.validateMapping(perfMapping) +if (!_mappingValidation.ok) { + log.warn("perf mapping validation failed at load time", { issues: _mappingValidation.issues }) +} + +// —— text parsing helpers ———————————————————————————————————————————————————— + +export interface PerfSymbolRow { + symbol: string + object?: string + overheadPct: number +} + +export interface PerfStatRow { + event: string + count: number + unit?: string +} + +/** + * Parse `perf report --stdio -n` output. + * Lines of interest start with a number (overhead %) followed by columns. + * Format: " 62.50% bench bench [.] compute_kernel" + */ +export function parsePerfReport(text: string): PerfSymbolRow[] { + const rows: PerfSymbolRow[] = [] + for (const line of text.split(/\r?\n/)) { + const m = line.match(/^\s+([\d.]+)%\s+\S+\s+(\S+)\s+\[.\]\s+(.+)$/) + if (!m) continue + const overheadPct = parseFloat(m[1]!) + const object = m[2]! + const symbol = m[3]!.trim() + if (!symbol || isNaN(overheadPct)) continue + rows.push({ symbol, object, overheadPct }) + } + return rows +} + +/** + * Parse `perf stat` output lines. + * Format: " 2,000,000 cycles # 1.50 GHz" + * Returns a map of event name → count. + */ +export function parsePerfStat(text: string): Map { + const result = new Map() + for (const line of text.split(/\r?\n/)) { + // Skip comment/header lines + if (line.trim().startsWith("#") || line.trim().startsWith("Performance")) continue + // Match: optional leading spaces, number (with commas), whitespace, event name + const m = line.match(/^\s*([\d,]+)\s+(\S[\w\-:]+)/) + if (!m) continue + const count = parseFloat(m[1]!.replace(/,/g, "")) + const event = m[2]!.trim() + if (!isNaN(count)) result.set(event, count) + } + return result +} + +/** + * Multi-section fixture format for tests. + * Sections delimited by "=== SECTION: perf_report ===" and "=== SECTION: perf_stat ===". + */ +export function parsePerfMultiSection(text: string): { + reportRows: PerfSymbolRow[] + statCounts: Map +} { + const sections = new Map() + let currentSection = "" + let buf: string[] = [] + for (const line of text.split(/\r?\n/)) { + const m = line.match(/^===\s*SECTION:\s*(\w+)\s*===/) + if (m) { + if (currentSection && buf.length) sections.set(currentSection, buf.join("\n")) + currentSection = m[1]! + buf = [] + } else { + buf.push(line) + } + } + if (currentSection && buf.length) sections.set(currentSection, buf.join("\n")) + + return { + reportRows: parsePerfReport(sections.get("perf_report") ?? ""), + statCounts: parsePerfStat(sections.get("perf_stat") ?? ""), + } +} + +// —— adapter ———————————————————————————————————————————————————————————————— + +export class PerfAdapter implements PAP.ProfileAdapter { + readonly id = "perf" + readonly vendor = "cpu_generic" as const + readonly domain = "cpu_sampling" as const + readonly privileges: readonly RuntimeBase.PrivilegeSpec[] = [ + { kind: "perf_event_paranoid", reason: "Linux perf requires perf_event_paranoid <= 2 for CPU sampling", maxParanoid: 2 }, + ] + readonly mapping = perfMapping + + constructor(private readonly probe: PerfBinaryProbe = defaultPerfProbe) {} + + async collect(target: PAP.ProfileTarget): Promise { + const bin = this.probe.locate("perf") + if (!bin) { + const msg = "perf (Linux perf_events) is not installed or not on PATH. Install linux-perf or linux-tools-$(uname -r)." + log.info(msg) + return Promise.reject(new Error(msg)) + } + const outPath = `/tmp/deepagent-perf-${Date.now()}.data` + const args = [ + "record", + "-g", // call graph + "-e", "cycles,instructions,cache-misses,cache-references,branch-misses,branches", + "-o", outPath, + "--", + target.command, + ...(target.args ?? []), + ] + log.info("perf collect", { command: bin, args }) + const exportCommand = `${bin} report --stdio -n -i ${outPath}` + + const { Process } = await import("@/util/process") + const result = await Process.run([bin, ...args], { cwd: target.cwd, nothrow: true }) + if (result.code !== 0) { + const msg = `perf record exited with code ${result.code}: ${result.stderr.toString().trim()}` + log.warn(msg) + return Promise.reject(new Error(msg)) + } + return { + path: outPath, + format: "perf-data", + exportCommand, + } + } + + async parse(report: PAP.NativeReportRef): Promise { + let text: string + + if (report.format === "text") { + // Test fixture: multi-section text already exported. + const fs = await import("fs/promises") + text = await fs.readFile(report.path, "utf8") + } else if (report.format === "perf-data") { + const bin = this.probe.locate("perf") + if (!bin) { + return Promise.reject(new Error("perf binary required to parse perf.data; not found on PATH")) + } + const { Process } = await import("@/util/process") + // Export: `perf report --stdio -n` for symbol hotspots. + const reportResult = await Process.run([bin, "report", "--stdio", "-n", "-i", report.path], { nothrow: true }) + // Export: `perf stat --log-fd 1 -i` for aggregate event counts. + const statResult = await Process.run([bin, "stat", "-i", report.path], { nothrow: true }) + text = [ + "=== SECTION: perf_report ===", + reportResult.stdout.toString(), + "=== SECTION: perf_stat ===", + statResult.stdout.toString() + statResult.stderr.toString(), + ].join("\n") + } else { + return Promise.reject(new Error(`perf adapter cannot parse format: ${report.format}`)) + } + + const { reportRows, statCounts } = parsePerfMultiSection(text) + + const hotspots: PAP.RawHotspot[] = reportRows.map((r) => ({ + name: r.symbol, + kind: "symbol" as const, + self_pct: r.overheadPct, + nativeMetrics: { + [N.overhead]: r.overheadPct, + // Per-symbol cycles/instructions not available from `perf report --stdio` without -g parsing. + // They come from `perf stat` aggregate only. + }, + })) + + // Pull aggregate event counts from perf stat into nativeSummary. + const nativeSummary: Record = {} + for (const [event, count] of statCounts) { + nativeSummary[event] = count + } + + return { + adapterId: this.id, + vendor: this.vendor, + domain: this.domain, + target: { command: report.path }, + nativeSummary, + hotspots, + availableMetrics: AVAILABLE, + raw_report_ref: report, + } + } + + normalize(raw: PAP.RawProfile): PAP.NormalizedProfile { + const getNative = (bag: Record, key: string): number | undefined => { + const v = bag[key] + if (v === undefined || v === "") return undefined + const n = Number(v) + return isNaN(n) ? undefined : n + } + + const ns = raw.nativeSummary + const cycles = getNative(ns, N.cycles) + const instructions = getNative(ns, N.instructions) + const cacheMisses = getNative(ns, N.cacheMisses) + const cacheRefs = getNative(ns, N.cacheReferences) + const branchMisses = getNative(ns, N.branchMisses) + const branches = getNative(ns, N.branches) + + // cpi = cycles / instructions (computed, but vocab says derived:false). + const cpiVal = cycles !== undefined && instructions !== undefined && instructions > 0 + ? cycles / instructions + : undefined + + // ipc = instructions / cycles (PAP-derived, vocab says derived:true). + const ipcVal = instructions !== undefined && cycles !== undefined && cycles > 0 + ? instructions / cycles + : undefined + + // cache_miss_rate = cache-misses / cache-references (ratio 0–1). + const cacheMissRate = cacheMisses !== undefined && cacheRefs !== undefined && cacheRefs > 0 + ? cacheMisses / cacheRefs + : undefined + + // branch_misprediction_pct = branch-misses / branches * 100. + const branchMispredPct = branchMisses !== undefined && branches !== undefined && branches > 0 + ? (branchMisses / branches) * 100 + : undefined + + const summary: Record = { + self_pct: PAP.missing("not_applicable_to_domain", "top-level self_pct is per-symbol, not aggregated"), + + cpi: cpiVal !== undefined + ? PAP.present(cpiVal, "ratio", { + nativeMetric: [N.cycles, N.instructions], + semantic: "exact", + // cpi is not marked derived in vocab, but we compute it from primitives. + formula: "cycles / instructions", + }) + : PAP.missing("not_collected"), + + ipc: ipcVal !== undefined + ? PAP.present(ipcVal, "ratio", { + nativeMetric: [N.instructions, N.cycles], + semantic: "exact", + derived: true, + formula: "instructions / cycles", + }) + : PAP.missing("not_collected"), + + clockticks: cycles !== undefined + ? PAP.present(cycles, "count", { nativeMetric: N.cycles, semantic: "exact" }) + : PAP.missing("not_collected"), + + instructions_retired: instructions !== undefined + ? PAP.present(instructions, "count", { nativeMetric: N.instructions, semantic: "exact" }) + : PAP.missing("not_collected"), + + cache_miss_rate: cacheMissRate !== undefined + ? PAP.present(cacheMissRate, "ratio", { + nativeMetric: [N.cacheMisses, N.cacheReferences], + semantic: "exact", + formula: "cache-misses / cache-references", + }) + : PAP.missing("not_collected"), + + branch_misprediction_pct: branchMispredPct !== undefined + ? PAP.present(branchMispredPct, "pct", { + nativeMetric: [N.branchMisses, N.branches], + semantic: "exact", + formula: "(branch-misses / branches) * 100", + }) + : PAP.missing("not_collected"), + } + + // Per-hotspot normalization (symbols from perf report). + const hotspots: PAP.Hotspot[] = raw.hotspots.map((h) => { + const overhead = getNative(h.nativeMetrics as Record, N.overhead) ?? h.self_pct ?? 0 + return { + symbol: h.name, + file_line: h.file_line, + self_pct: overhead, + total_pct: h.total_pct, + metrics: { + self_pct: PAP.present(overhead, "pct", { nativeMetric: N.overhead, semantic: "exact" }), + // Per-symbol cycles/instructions not available from perf report without annotation. + cpi: PAP.missing("not_collected", "per-symbol cycles/instructions require `perf annotate`"), + ipc: PAP.missing("not_collected", "per-symbol IPC requires `perf annotate`"), + clockticks: PAP.missing("not_collected", "per-symbol cycle count requires `perf annotate`"), + instructions_retired: PAP.missing("not_collected", "per-symbol instruction count requires `perf annotate`"), + cache_miss_rate: PAP.missing("not_collected", "per-symbol cache miss rate requires `perf annotate`"), + branch_misprediction_pct: PAP.missing("not_collected", "per-symbol branch misprediction requires `perf annotate`"), + }, + } + }) + + return { + domain: this.domain, + vendor: this.vendor, + adapterId: this.id, + target: raw.target, + duration_ns: null, + hotspots, + summary, + raw_report_ref: raw.raw_report_ref, + } + } +} + +export const makePerfAdapter = (probe: PerfBinaryProbe = defaultPerfProbe): PAP.ProfileAdapter => + new PerfAdapter(probe) diff --git a/packages/deepagent-code/src/profile/adapters/rocprof.ts b/packages/deepagent-code/src/profile/adapters/rocprof.ts new file mode 100644 index 00000000..d6a37f29 --- /dev/null +++ b/packages/deepagent-code/src/profile/adapters/rocprof.ts @@ -0,0 +1,376 @@ +import * as Log from "@deepagent-code/core/util/log" +import { which } from "@deepagent-code/core/util/which" +import { PAP } from "@/profile/pap" +import { Vocabulary } from "@/profile/vocabulary" +import { RuntimeBase } from "@/runtime/base" + +const log = Log.create({ service: "profile.rocprof" }) + +// —— binary probe ———————————————————————————————————————————————————————————— + +export interface RocprofBinaryProbe { + readonly locate: (command: string) => string | null +} + +export const defaultRocprofProbe: RocprofBinaryProbe = { locate: (cmd) => which(cmd) } +export const installedRocprofProbe = (installed: Iterable): RocprofBinaryProbe => { + const set = new Set(installed) + return { locate: (cmd) => (set.has(cmd) ? `/usr/local/bin/${cmd}` : null) } +} +export const missingRocprofProbe: RocprofBinaryProbe = { locate: () => null } + +// —— mapping ———————————————————————————————————————————————————————————————— + +/** + * AMD rocprofv3 native metric names. + * See §P1A-V 表1 and AMD ROCprofiler-SDK docs. + */ +const N = { + gpuBusy: "GPUBusy", + memUnitBusy: "MemUnitBusy", + // L2CacheHit is a hit-rate (%), NOT throughput — semantic:"approximate" when mapped to + // l2_throughput_pct. §P1A-V 映射原则 2. + l2CacheHit: "L2CacheHit", + wavefronts: "Wavefronts", + valuUtilization: "VALUUtilization", + saluBusy: "SALUBusy", + beginNs: "BeginNs", + endNs: "EndNs", +} as const + +const AVAILABLE = Object.values(N) as string[] + +export const rocprofMapping: PAP.MetricMapping = { + adapterId: "rocprof", + domain: "gpu_kernel", + availableMetrics: AVAILABLE, + entries: [ + // GPUBusy is GPU-wide busy percent, not SM compute throughput — approximate mapping. + { neutral: "compute_throughput_pct", native: N.gpuBusy, semantic: "approximate" }, + // MemUnitBusy ≈ memory unit utilization — maps to memory_throughput_pct (approximate). + { neutral: "memory_throughput_pct", native: N.memUnitBusy, semantic: "approximate" }, + // rocprof lacks a direct DRAM bandwidth % metric; MemUnitBusy is the closest proxy. + { neutral: "dram_bandwidth_pct", native: N.memUnitBusy, semantic: "approximate" }, + // L2CacheHit is hit-rate, NOT throughput. §P1A-V 表1 footnote: semantic:"approximate". + { neutral: "l2_throughput_pct", native: N.l2CacheHit, semantic: "approximate" }, + // Wavefronts / theoretical_max gives occupancy — approximate (needs theoretical max). + { neutral: "occupancy_pct", native: N.wavefronts, semantic: "approximate" }, + // VALUUtilization is the vector ALU utilization — direct rocprof native metric. + { neutral: "valu_utilization_pct", native: N.valuUtilization, semantic: "exact" }, + // SALUBusy is AMD-native; ncu has no equivalent. + { neutral: "salu_busy_pct", native: N.saluBusy, semantic: "exact" }, + // duration_ns: kernel wall time = EndNs - BeginNs. + { neutral: "duration_ns", native: [N.beginNs, N.endNs], semantic: "exact" }, + // compute_bound: PAP-derived — GPUBusy > MemUnitBusy. + { + neutral: "compute_bound", + native: [N.gpuBusy, N.memUnitBusy], + semantic: "approximate", // both inputs are approximate mappings + derived: true, + formula: "GPUBusy > MemUnitBusy", + }, + ], +} + +const _mappingValidation = Vocabulary.validateMapping(rocprofMapping) +if (!_mappingValidation.ok) { + log.warn("rocprof mapping validation failed at load time", { issues: _mappingValidation.issues }) +} + +// —— CSV parsing helpers ———————————————————————————————————————————————————— + +function splitCsvRow(row: string): string[] { + const cols: string[] = [] + let cur = "" + let inQuote = false + for (let i = 0; i < row.length; i++) { + const ch = row[i]! + if (ch === '"') { inQuote = !inQuote } + else if (ch === "," && !inQuote) { cols.push(cur); cur = "" } + else { cur += ch } + } + cols.push(cur) + return cols +} + +function cleanField(s: string): string { + return s.trim().replace(/^"|"$/g, "") +} + +export interface RocprofKernelRow { + kernelName: string + gpuId: number + metrics: Record +} + +/** + * Parse rocprofv3 CSV output. + * Canonical columns include: Kernel_Name, gpu-id, GPUBusy, MemUnitBusy, + * VALUUtilization, SALUBusy, Wavefronts, L2CacheHit, BeginNs, EndNs. + */ +export function parseRocprofCsv(csv: string): RocprofKernelRow[] { + const rows: RocprofKernelRow[] = [] + const lines = csv.split(/\r?\n/).filter((l) => l.trim()) + if (lines.length < 2) return rows + + // Find header line. + let headerIdx = 0 + let headers: string[] = [] + for (let i = 0; i < lines.length; i++) { + const fields = splitCsvRow(lines[i]!).map(cleanField) + // Detect header by presence of "Kernel_Name" or "kernel_name". + if (fields.some((f) => f.toLowerCase() === "kernel_name")) { + headerIdx = i + headers = fields + break + } + } + if (!headers.length) return rows + + const idxKernelName = headers.findIndex((h) => h.toLowerCase() === "kernel_name") + const idxGpuId = headers.findIndex((h) => h.toLowerCase() === "gpu-id") + + for (let i = headerIdx + 1; i < lines.length; i++) { + const cols = splitCsvRow(lines[i]!).map(cleanField) + if (cols.length < headers.length) continue + const kernelName = cols[idxKernelName >= 0 ? idxKernelName : 0] ?? "" + if (!kernelName) continue + const gpuId = parseInt(cols[idxGpuId >= 0 ? idxGpuId : 1] ?? "0", 10) + const metrics: Record = {} + for (let j = 0; j < headers.length; j++) { + const h = headers[j]! + const v = parseFloat(cols[j] ?? "NaN") + if (!isNaN(v)) metrics[h] = v + } + rows.push({ kernelName, gpuId, metrics }) + } + return rows +} + +// —— adapter ———————————————————————————————————————————————————————————————— + +/** + * Theoretical maximum wavefronts per CU (depends on GPU architecture). + * Without querying the device, we use a reasonable default for modern AMD GPUs. + * Adapters should query `rocminfo` at registration for the real value. + */ +const DEFAULT_MAX_WAVEFRONTS_PER_CU = 40 + +export class RocprofAdapter implements PAP.ProfileAdapter { + readonly id = "rocprof" + readonly vendor = "amd" as const + readonly domain = "gpu_kernel" as const + readonly privileges: readonly RuntimeBase.PrivilegeSpec[] = [ + { kind: "rocm_profiling", reason: "rocprofv3 requires ROCm profiling access (rocm-smi permissions or root)" }, + ] + readonly mapping = rocprofMapping + + constructor( + private readonly probe: RocprofBinaryProbe = defaultRocprofProbe, + /** Theoretical max wavefronts per CU for occupancy calculation. */ + private readonly maxWavefrontsPerCu: number = DEFAULT_MAX_WAVEFRONTS_PER_CU, + ) {} + + async collect(target: PAP.ProfileTarget): Promise { + const bin = this.probe.locate("rocprofv3") + if (!bin) { + const msg = "rocprofv3 (AMD ROCprofiler-SDK) is not installed or not on PATH. Install via ROCm: `sudo apt install rocprofiler-sdk`." + log.info(msg) + return Promise.reject(new Error(msg)) + } + const outDir = `/tmp/deepagent-rocprof-${Date.now()}` + const metrics = [ + "GPUBusy", "MemUnitBusy", "VALUUtilization", "SALUBusy", "Wavefronts", + "L2CacheHit", + ] + const args = [ + "--kernel-trace", + "--hip-trace", + "--output-format", "csv", + "--output-directory", outDir, + "-M", metrics.join(","), + "--", + target.command, + ...(target.args ?? []), + ] + log.info("rocprofv3 collect", { command: bin, args }) + + const { Process } = await import("@/util/process") + const result = await Process.run([bin, ...args], { cwd: target.cwd, nothrow: true }) + if (result.code !== 0) { + const msg = `rocprofv3 exited with code ${result.code}: ${result.stderr.toString().trim()}` + log.warn(msg) + return Promise.reject(new Error(msg)) + } + return { + path: `${outDir}/results.csv`, + format: "csv", + } + } + + async parse(report: PAP.NativeReportRef): Promise { + const fs = await import("fs/promises") + const text = await fs.readFile(report.path, "utf8") + const rows = parseRocprofCsv(text) + + const hotspots: PAP.RawHotspot[] = rows.map((r) => ({ + name: r.kernelName, + kind: "kernel" as const, + nativeMetrics: r.metrics as Record, + })) + + // nativeSummary: aggregate across all kernels (take first as representative). + const nativeSummary: Record = + rows.length > 0 ? { ...rows[0]!.metrics } : {} + + return { + adapterId: this.id, + vendor: this.vendor, + domain: this.domain, + target: { command: report.path }, + nativeSummary, + hotspots, + availableMetrics: AVAILABLE, + raw_report_ref: report, + } + } + + normalize(raw: PAP.RawProfile): PAP.NormalizedProfile { + const getNative = (bag: Record, key: string): number | undefined => { + const v = bag[key] + if (v === undefined || v === "") return undefined + const n = Number(v) + return isNaN(n) ? undefined : n + } + + const normKernel = (nm: Record): Record => { + const gpuBusy = getNative(nm, N.gpuBusy) + const memUnitBusy = getNative(nm, N.memUnitBusy) + const l2CacheHit = getNative(nm, N.l2CacheHit) + const wavefronts = getNative(nm, N.wavefronts) + const valuUtil = getNative(nm, N.valuUtilization) + const saluBusy = getNative(nm, N.saluBusy) + const beginNs = getNative(nm, N.beginNs) + const endNs = getNative(nm, N.endNs) + + // Occupancy: Wavefronts / theoretical_max_per_CU → [0,100]%. + // This is an approximation without knowing the exact CU count and hardware limit. + const occupancyPct = + wavefronts !== undefined + ? Math.min(100, (wavefronts / this.maxWavefrontsPerCu) * 100) + : undefined + + const durNs = beginNs !== undefined && endNs !== undefined ? endNs - beginNs : undefined + + return { + // GPUBusy → compute_throughput_pct: approximate (GPU-wide busy ≠ SM compute throughput). + compute_throughput_pct: gpuBusy !== undefined + ? PAP.present(gpuBusy, "pct", { nativeMetric: N.gpuBusy, semantic: "approximate" }) + : PAP.missing("not_collected"), + + // MemUnitBusy → memory_throughput_pct: approximate. + memory_throughput_pct: memUnitBusy !== undefined + ? PAP.present(memUnitBusy, "pct", { nativeMetric: N.memUnitBusy, semantic: "approximate" }) + : PAP.missing("not_collected"), + + // MemUnitBusy → dram_bandwidth_pct: approximate (same metric, different intent). + dram_bandwidth_pct: memUnitBusy !== undefined + ? PAP.present(memUnitBusy, "pct", { nativeMetric: N.memUnitBusy, semantic: "approximate" }) + : PAP.missing("not_collected"), + + // L2CacheHit is a hit-rate (%), NOT throughput. Semantically approximate. + l2_throughput_pct: l2CacheHit !== undefined + ? PAP.present(l2CacheHit, "pct", { nativeMetric: N.l2CacheHit, semantic: "approximate" }) + : PAP.missing("not_collected"), + + // Wavefronts / theoretical max → occupancy %. + occupancy_pct: occupancyPct !== undefined + ? PAP.present(occupancyPct, "pct", { + nativeMetric: N.wavefronts, + semantic: "approximate", + derived: false, + conversion: `wavefronts / ${this.maxWavefrontsPerCu} * 100`, + }) + : PAP.missing("not_collected"), + + // VALUUtilization is exact. + valu_utilization_pct: valuUtil !== undefined + ? PAP.present(valuUtil, "pct", { nativeMetric: N.valuUtilization, semantic: "exact" }) + : PAP.missing("not_collected"), + + // SALUBusy is AMD-native; has no ncu equivalent. + salu_busy_pct: saluBusy !== undefined + ? PAP.present(saluBusy, "pct", { nativeMetric: N.saluBusy, semantic: "exact" }) + : PAP.missing("not_collected"), + + // duration_ns = EndNs - BeginNs. + duration_ns: durNs !== undefined + ? PAP.present(durNs, "ns", { + nativeMetric: [N.beginNs, N.endNs], + semantic: "exact", + conversion: "EndNs - BeginNs", + }) + : PAP.missing("not_collected"), + + // compute_bound: PAP-derived from GPUBusy > MemUnitBusy (both approximate). + compute_bound: gpuBusy !== undefined && memUnitBusy !== undefined + ? PAP.present(gpuBusy > memUnitBusy, "bool", { + nativeMetric: [N.gpuBusy, N.memUnitBusy], + semantic: "approximate", + derived: true, + formula: "GPUBusy > MemUnitBusy", + }) + : PAP.missing("not_collected", "GPUBusy or MemUnitBusy metrics missing"), + } + } + + const summaryMetrics = normKernel(raw.nativeSummary) + + // self_pct is a TIME share. Derive it from each kernel's (EndNs − BeginNs) + // duration relative to the sum across kernels. Kernels missing timestamps + // contribute 0 and stay unranked (honest) — the previous `? 0 : 0` dead ternary + // pinned every AMD kernel to 0, collapsing sort order and defeating diff. + const durations = raw.hotspots.map((h) => { + const nm = h.nativeMetrics as Record + const beginNs = Number(nm[N.beginNs] ?? NaN) + const endNs = Number(nm[N.endNs] ?? NaN) + return isNaN(beginNs) || isNaN(endNs) ? undefined : endNs - beginNs + }) + const totalDurationNs = durations.reduce((sum, d) => sum + (d ?? 0), 0) + + const hotspots: PAP.Hotspot[] = raw.hotspots.map((h, i) => { + const nm = h.nativeMetrics as Record + const dur = durations[i] + const selfPct = h.self_pct ?? (totalDurationNs > 0 && dur !== undefined ? (dur / totalDurationNs) * 100 : 0) + return { + kernel: h.name, + file_line: h.file_line, + self_pct: selfPct, + total_pct: h.total_pct, + metrics: normKernel(nm), + } + }) + + const durNs = (() => { + const begin = Number(raw.nativeSummary[N.beginNs] ?? NaN) + const end = Number(raw.nativeSummary[N.endNs] ?? NaN) + return isNaN(begin) || isNaN(end) ? null : end - begin + })() + + return { + domain: this.domain, + vendor: this.vendor, + adapterId: this.id, + target: raw.target, + duration_ns: durNs, + hotspots, + summary: summaryMetrics, + raw_report_ref: raw.raw_report_ref, + } + } +} + +export const makeRocprofAdapter = ( + probe: RocprofBinaryProbe = defaultRocprofProbe, + maxWavefrontsPerCu?: number, +): PAP.ProfileAdapter => new RocprofAdapter(probe, maxWavefrontsPerCu) diff --git a/packages/deepagent-code/src/profile/adapters/vtune.ts b/packages/deepagent-code/src/profile/adapters/vtune.ts new file mode 100644 index 00000000..73044b90 --- /dev/null +++ b/packages/deepagent-code/src/profile/adapters/vtune.ts @@ -0,0 +1,395 @@ +import * as Log from "@deepagent-code/core/util/log" +import { which } from "@deepagent-code/core/util/which" +import { PAP } from "@/profile/pap" +import { Vocabulary } from "@/profile/vocabulary" +import { RuntimeBase } from "@/runtime/base" + +const log = Log.create({ service: "profile.vtune" }) + +// —— binary probe ———————————————————————————————————————————————————————————— + +export interface VtuneBinaryProbe { + readonly locate: (command: string) => string | null +} + +export const defaultVtuneProbe: VtuneBinaryProbe = { locate: (cmd) => which(cmd) } +export const installedVtuneProbe = (installed: Iterable): VtuneBinaryProbe => { + const set = new Set(installed) + return { locate: (cmd) => (set.has(cmd) ? `/opt/intel/oneapi/vtune/latest/bin64/${cmd}` : null) } +} +export const missingVtuneProbe: VtuneBinaryProbe = { locate: () => null } + +// —— mapping ———————————————————————————————————————————————————————————————— + +/** + * Intel VTune native metric / CSV column names. + * See §P1A-V 表3 and Intel VTune CPU Metrics Reference. + * Column names match `vtune -report hotspots -format=csv` output. + */ +const N = { + cpuTimeSelf: "CPU Time:Self", + cpiRate: "CPI Rate", + clockticks: "Clockticks", + instructionsRetired: "Instructions Retired", + memoryBound: "Memory Bound", + dramBound: "DRAM Bound", + // VTune "Bad Speculation" metric = branch misprediction pipeline slots %. + badSpeculation: "Bad Speculation", + // VTune has multiple cache miss columns; "LLC Miss Count" is the primary one. + llcMissCount: "LLC Miss Count", + llcMissRatio: "LLC Miss Ratio", + // Function name column + functionName: "Function", + // Module/CPU time (total) for hotspot + cpuTimeTotal: "CPU Time", +} as const + +const AVAILABLE = Object.values(N) as string[] + +export const vtuneMapping: PAP.MetricMapping = { + adapterId: "vtune", + domain: "cpu_hotspot", + availableMetrics: AVAILABLE, + entries: [ + { neutral: "self_pct", native: N.cpuTimeSelf, semantic: "exact" }, + // CPI Rate is a direct VTune metric (not derived). + { neutral: "cpi", native: N.cpiRate, semantic: "exact" }, + // ipc = 1 / CPI Rate — PAP-derived, §P1A-V 表3. + { + neutral: "ipc", + native: N.cpiRate, + semantic: "exact", + derived: true, + formula: "1 / CPI Rate", + }, + { neutral: "clockticks", native: N.clockticks, semantic: "exact" }, + { neutral: "instructions_retired", native: N.instructionsRetired, semantic: "exact" }, + { neutral: "memory_bound_pct", native: N.memoryBound, semantic: "exact" }, + { neutral: "dram_bound_pct", native: N.dramBound, semantic: "exact" }, + // LLC Miss Ratio is the cache miss rate (misses / references). Approximate because + // VTune uses LLC misses, not all-level misses. We use exact here as it's the canonical + // VTune cache miss rate metric. + { neutral: "cache_miss_rate", native: N.llcMissRatio, semantic: "exact" }, + // Bad Speculation = branch misprediction rate in VTune topdown. + { neutral: "branch_misprediction_pct", native: N.badSpeculation, semantic: "exact" }, + ], +} + +const _mappingValidation = Vocabulary.validateMapping(vtuneMapping) +if (!_mappingValidation.ok) { + log.warn("vtune mapping validation failed at load time", { issues: _mappingValidation.issues }) +} + +// —— CSV parsing helpers ———————————————————————————————————————————————————— + +function splitCsvRow(row: string): string[] { + const cols: string[] = [] + let cur = "" + let inQuote = false + for (let i = 0; i < row.length; i++) { + const ch = row[i]! + if (ch === '"') { inQuote = !inQuote } + else if (ch === "," && !inQuote) { cols.push(cur); cur = "" } + else { cur += ch } + } + cols.push(cur) + return cols +} + +function cleanField(s: string): string { + return s.trim().replace(/^"|"$/g, "") +} + +/** + * Parse a percent string like "85.5%" or "85.5" → 85.5. + */ +function parsePct(s: string): number { + const cleaned = cleanField(s).replace(/%$/, "").replace(/,/g, "") + return parseFloat(cleaned) +} + +export interface VtuneHotspotRow { + functionName: string + cpuTimePct: number + cpuTimeSelfPct: number + cpiRate: number + clockticks: number + instructionsRetired: number + memoryBound: number + dramBound: number + llcMissRatio: number + badSpeculation: number + /** Raw fields map for any additional metrics. */ + raw: Record +} + +/** + * Parse `vtune -report hotspots -format=csv` output. + * Column names match VTune's CPU Metrics hotspot report. + */ +export function parseVtuneCsv(csv: string): VtuneHotspotRow[] { + const rows: VtuneHotspotRow[] = [] + const lines = csv.split(/\r?\n/).filter((l) => l.trim()) + if (lines.length < 2) return rows + + // Find header line (first non-empty, non-comment line). + let headerIdx = -1 + let headers: string[] = [] + for (let i = 0; i < lines.length; i++) { + const line = lines[i]!.trim() + if (line.startsWith("#") || line.startsWith("//")) continue + const fields = splitCsvRow(line).map(cleanField) + // Detect by presence of "Function" column. + if (fields.some((f) => f.toLowerCase() === "function" || f.toLowerCase() === "function (full)")) { + headerIdx = i + headers = fields + break + } + } + if (headerIdx < 0 || !headers.length) return rows + + const idx = (name: string): number => { + const lower = name.toLowerCase() + return headers.findIndex((h) => h.toLowerCase() === lower || h.toLowerCase().includes(lower.replace(/ /g, ""))) + } + + const iFn = idx("function") + const iTotal = idx("cpu time") + const iSelf = idx("cpu time:self") + const iCpi = idx("cpi rate") + const iClocks = idx("clockticks") + const iInstr = idx("instructions retired") + const iMemBound = idx("memory bound") + const iDramBound = idx("dram bound") + const iLlcMissRatio = idx("llc miss ratio") + const iBadSpec = idx("bad speculation") + + for (let i = headerIdx + 1; i < lines.length; i++) { + const cols = splitCsvRow(lines[i]!).map(cleanField) + if (cols.length < 2) continue + const functionName = cols[iFn >= 0 ? iFn : 0] ?? "" + if (!functionName) continue + + const raw: Record = {} + for (let j = 0; j < headers.length; j++) { + raw[headers[j]!] = cols[j] ?? "" + } + + rows.push({ + functionName, + cpuTimePct: parsePct(cols[iTotal >= 0 ? iTotal : 1] ?? "0"), + cpuTimeSelfPct: parsePct(cols[iSelf >= 0 ? iSelf : 2] ?? "0"), + cpiRate: parseFloat(cleanField(cols[iCpi >= 0 ? iCpi : 3] ?? "0")), + clockticks: parseFloat((cols[iClocks >= 0 ? iClocks : 4] ?? "0").replace(/,/g, "")), + instructionsRetired: parseFloat((cols[iInstr >= 0 ? iInstr : 5] ?? "0").replace(/,/g, "")), + memoryBound: parsePct(cols[iMemBound >= 0 ? iMemBound : 6] ?? "0"), + dramBound: parsePct(cols[iDramBound >= 0 ? iDramBound : 7] ?? "0"), + llcMissRatio: parsePct(cols[iLlcMissRatio >= 0 ? iLlcMissRatio : 8] ?? "0"), + badSpeculation: parsePct(cols[iBadSpec >= 0 ? iBadSpec : 9] ?? "0"), + raw, + }) + } + return rows +} + +// —— adapter ———————————————————————————————————————————————————————————————— + +export class VtuneAdapter implements PAP.ProfileAdapter { + readonly id = "vtune" + readonly vendor = "intel" as const + readonly domain = "cpu_hotspot" as const + readonly privileges: readonly RuntimeBase.PrivilegeSpec[] = [] + readonly mapping = vtuneMapping + + constructor(private readonly probe: VtuneBinaryProbe = defaultVtuneProbe) {} + + async collect(target: PAP.ProfileTarget): Promise { + const bin = this.probe.locate("vtune") + if (!bin) { + const msg = "vtune (Intel VTune Profiler) is not installed or not on PATH. Install Intel oneAPI Base Toolkit." + log.info(msg) + return Promise.reject(new Error(msg)) + } + const resultDir = `/tmp/deepagent-vtune-${Date.now()}` + const args = [ + "-collect", "hotspots", + "-knob", "sampling-mode=hw", + "-result-dir", resultDir, + "--", + target.command, + ...(target.args ?? []), + ] + log.info("vtune collect", { command: bin, args }) + const exportCommand = `${bin} -report hotspots -result-dir ${resultDir} -format csv -report-output ${resultDir}/hotspots.csv` + + const { Process } = await import("@/util/process") + const result = await Process.run([bin, ...args], { cwd: target.cwd, nothrow: true }) + if (result.code !== 0) { + const msg = `vtune exited with code ${result.code}: ${result.stderr.toString().trim()}` + log.warn(msg) + return Promise.reject(new Error(msg)) + } + return { + path: resultDir, + format: "csv", + exportCommand, + } + } + + async parse(report: PAP.NativeReportRef): Promise { + let csvText: string + if (report.format === "csv") { + const fs = await import("fs/promises") + // report.path may be a directory (vtune result dir) or a CSV file. + let filePath = report.path + try { + const stat = await fs.stat(filePath) + if (stat.isDirectory()) { + filePath = `${filePath}/hotspots.csv` + } + } catch { + // path might be a direct CSV file + } + csvText = await fs.readFile(filePath, "utf8") + } else { + return Promise.reject(new Error(`vtune adapter cannot parse format: ${report.format}`)) + } + + const rows = parseVtuneCsv(csvText) + const hotspots: PAP.RawHotspot[] = rows.map((r) => ({ + name: r.functionName, + kind: "symbol" as const, + self_pct: r.cpuTimeSelfPct, + total_pct: r.cpuTimePct, + nativeMetrics: { + [N.cpuTimeTotal]: r.cpuTimePct, + [N.cpuTimeSelf]: r.cpuTimeSelfPct, + [N.cpiRate]: r.cpiRate, + [N.clockticks]: r.clockticks, + [N.instructionsRetired]: r.instructionsRetired, + [N.memoryBound]: r.memoryBound, + [N.dramBound]: r.dramBound, + [N.llcMissRatio]: r.llcMissRatio, + [N.badSpeculation]: r.badSpeculation, + }, + })) + + // nativeSummary: aggregate (first row as representative, or rolled up top-level). + const nativeSummary: Record = + rows.length > 0 + ? { + [N.cpuTimeSelf]: rows[0]!.cpuTimeSelfPct, + [N.cpiRate]: rows[0]!.cpiRate, + [N.clockticks]: rows.reduce((s, r) => s + r.clockticks, 0), + [N.instructionsRetired]: rows.reduce((s, r) => s + r.instructionsRetired, 0), + [N.memoryBound]: rows[0]!.memoryBound, + [N.dramBound]: rows[0]!.dramBound, + [N.llcMissRatio]: rows[0]!.llcMissRatio, + [N.badSpeculation]: rows[0]!.badSpeculation, + } + : {} + + return { + adapterId: this.id, + vendor: this.vendor, + domain: this.domain, + target: { command: report.path }, + nativeSummary, + hotspots, + availableMetrics: AVAILABLE, + raw_report_ref: report, + } + } + + normalize(raw: PAP.RawProfile): PAP.NormalizedProfile { + const getNative = (bag: Record, key: string): number | undefined => { + const v = bag[key] + if (v === undefined || v === "") return undefined + const n = Number(v) + return isNaN(n) ? undefined : n + } + + const normFn = (nm: Record): Record => { + const selfPct = getNative(nm, N.cpuTimeSelf) + const cpiRate = getNative(nm, N.cpiRate) + const clocks = getNative(nm, N.clockticks) + const instr = getNative(nm, N.instructionsRetired) + const memBound = getNative(nm, N.memoryBound) + const dramBound = getNative(nm, N.dramBound) + const llcRatio = getNative(nm, N.llcMissRatio) + const badSpec = getNative(nm, N.badSpeculation) + + return { + self_pct: selfPct !== undefined + ? PAP.present(selfPct, "pct", { nativeMetric: N.cpuTimeSelf, semantic: "exact" }) + : PAP.missing("not_collected"), + + cpi: cpiRate !== undefined + ? PAP.present(cpiRate, "ratio", { nativeMetric: N.cpiRate, semantic: "exact" }) + : PAP.missing("not_collected"), + + // ipc = 1 / CPI Rate — PAP-derived. + ipc: cpiRate !== undefined && cpiRate > 0 + ? PAP.present(1 / cpiRate, "ratio", { + nativeMetric: N.cpiRate, + semantic: "exact", + derived: true, + formula: "1 / CPI Rate", + }) + : PAP.missing("not_collected"), + + clockticks: clocks !== undefined + ? PAP.present(clocks, "count", { nativeMetric: N.clockticks, semantic: "exact" }) + : PAP.missing("not_collected"), + + instructions_retired: instr !== undefined + ? PAP.present(instr, "count", { nativeMetric: N.instructionsRetired, semantic: "exact" }) + : PAP.missing("not_collected"), + + memory_bound_pct: memBound !== undefined + ? PAP.present(memBound, "pct", { nativeMetric: N.memoryBound, semantic: "exact" }) + : PAP.missing("not_collected"), + + dram_bound_pct: dramBound !== undefined + ? PAP.present(dramBound, "pct", { nativeMetric: N.dramBound, semantic: "exact" }) + : PAP.missing("not_collected"), + + // LLC Miss Ratio → cache_miss_rate (ratio 0–1 or already 0–100 depending on VTune version). + // VTune reports LLC Miss Ratio as 0–100%, we normalize to 0–1 ratio. + cache_miss_rate: llcRatio !== undefined + ? PAP.present(llcRatio > 1 ? llcRatio / 100 : llcRatio, "ratio", { + nativeMetric: N.llcMissRatio, + semantic: "exact", + ...(llcRatio > 1 ? { conversion: "LLC Miss Ratio / 100" } : {}), + }) + : PAP.missing("not_collected"), + + branch_misprediction_pct: badSpec !== undefined + ? PAP.present(badSpec, "pct", { nativeMetric: N.badSpeculation, semantic: "exact" }) + : PAP.missing("not_collected"), + } + } + + const hotspots: PAP.Hotspot[] = raw.hotspots.map((h) => ({ + symbol: h.name, + file_line: h.file_line, + self_pct: h.self_pct ?? 0, + total_pct: h.total_pct, + metrics: normFn(h.nativeMetrics as Record), + })) + + return { + domain: this.domain, + vendor: this.vendor, + adapterId: this.id, + target: raw.target, + duration_ns: null, + hotspots, + summary: normFn(raw.nativeSummary), + raw_report_ref: raw.raw_report_ref, + } + } +} + +export const makeVtuneAdapter = (probe: VtuneBinaryProbe = defaultVtuneProbe): PAP.ProfileAdapter => + new VtuneAdapter(probe) diff --git a/packages/deepagent-code/src/profile/index.ts b/packages/deepagent-code/src/profile/index.ts new file mode 100644 index 00000000..a011fa40 --- /dev/null +++ b/packages/deepagent-code/src/profile/index.ts @@ -0,0 +1,13 @@ +/** + * P1A (S1-v3.5): PAP — the Profile Adapter Protocol module barrel. + * + * - `PAP` — three-stage `ProfileAdapter` contract + `NormalizedProfile`/`RawProfile`/ + * `ProfileTarget`/`NativeReportRef`/`Hotspot`/`MetricValue` types + profile + * structural validation. + * - `Vocabulary` — the vendor-neutral metric vocabulary (tables 1/2/3) + `validateMapping` + * (registration-time completeness/honesty check) + `validateProfile` + * (vocabulary conformance). + */ +export * from "./pap" +export * from "./vocabulary" +export * from "./service" diff --git a/packages/deepagent-code/src/profile/pap.ts b/packages/deepagent-code/src/profile/pap.ts new file mode 100644 index 00000000..e084d0a4 --- /dev/null +++ b/packages/deepagent-code/src/profile/pap.ts @@ -0,0 +1,377 @@ +import { RuntimeBase } from "@/runtime/base" +import type { LSPResolve } from "@/lsp/resolve" + +/** + * P1A (S1-v3.5): PAP — the Profile Adapter Protocol. + * + * Unlike DAP (debug), profilers have NO common protocol: ncu emits `.ncu-rep`, + * nsys emits a SQLite `.nsys-rep`, rocprof emits rocpd/CSV, VTune a private DB, + * perf a `perf.data`. PAP is the layer we invent to unify them. Its soul is the + * vendor-neutral metric vocabulary (see `./vocabulary`): ncu's `sm__throughput`, + * rocprof's `GPUBusy` and VTune's `CPI Rate` must collapse onto ONE neutral name, + * otherwise PAP is just a thin wrapper ("套壳"). + * + * The protocol is three stages every adapter implements: + * 1. collect — build the CLI, run the program under the profiler, produce a + * native report (done inside R0 worktree isolation + privilege gate). + * 2. parse — read the native report (CSV/JSON/SQLite) into an intermediate + * `RawProfile` that still carries NATIVE metric names. + * 3. normalize — map native metric names onto the neutral vocabulary, producing a + * vendor-agnostic `NormalizedProfile`. + * + * This module is PURE protocol + types — it spawns nothing and runs no profiler. + * R0 (`RuntimeBase`) supplies privileges, isolation, and the output budget; adapters + * declare privileges with `RuntimeBase.PrivilegeSpec` and may carry a default + * `RuntimeBase.ResourceBudget` so large native reports spill to an artifact. + */ +export namespace PAP { + // —— enums ———————————————————————————————————————————————————————————————— + + export type Vendor = "nvidia" | "amd" | "intel" | "cpu_generic" + + /** + * The profiling domain. GPU splits into per-kernel (ncu/rocprof: a single + * kernel's compute/memory/occupancy) vs timeline (nsys: system timeline / API / + * transfers). CPU splits into sampling (perf) vs hotspot/µarch (VTune). A neutral + * metric only applies to the domains where it is meaningful — we never cross-fill + * a metric into a domain that cannot produce it. + */ + export type Domain = "gpu_kernel" | "gpu_timeline" | "cpu_sampling" | "cpu_hotspot" + + /** + * Normalized unit. §P1A-V "单位归一": bandwidth → `pct` or `gb_s` (explicit), all + * durations → `ns`, all ratios/percent → `pct` on a 0–100 scale, raw counts → + * `count`, dimensionless ratios (cpi/ipc/miss-rate) → `ratio`, booleans → `bool`. + */ + export type MetricUnit = "pct" | "gb_s" | "ns" | "count" | "ratio" | "bool" + + /** + * Relationship between the native metric and the neutral metric it maps to. + * `exact` = same quantity; `approximate` = related but NOT identical (e.g. AMD + * `L2CacheHit` hit-rate → `l2_throughput_pct` throughput — §P1A-V 映射原则 2). + * Derivation is tracked separately via `derived`. + */ + export type Semantic = "exact" | "approximate" + + /** + * Why a neutral metric has no value. §P1A-V 映射原则 5: missing is honest — a + * metric the machine/arch/profiler cannot produce is `null` + a reason, NEVER + * back-filled from a different metric and never fabricated. The listed literals + * are the canonical reasons; the open `string` tail allows adapter-specific notes. + */ + export type MissingReason = + | "not_supported_on_arch" + | "metric_not_in_this_profiler" + | "not_collected" + | "not_applicable_to_domain" + | (string & {}) + + // —— metric values —————————————————————————————————————————————————————————— + + /** Where a normalized value came from — kept for auditability (§P1A-V 映射原则 3). */ + export interface MetricProvenance { + /** The native metric name(s) this value was derived/mapped from. */ + nativeMetric: string | readonly string[] + /** `exact` or `approximate` (semantic difference made explicit). */ + semantic: Semantic + /** True when PAP computed this from other native metrics (e.g. `ipc`, `compute_bound`). */ + derived?: boolean + /** For derived metrics: the formula/source, so the value can be audited. */ + formula?: string + /** When the native value was bytes/counts, the conversion applied to reach `unit`. */ + conversion?: string + } + + /** A metric that has a real value. */ + export interface MetricPresent { + readonly value: number | boolean + readonly unit: MetricUnit + readonly provenance: MetricProvenance + } + + /** A metric with no value — honest null + machine-readable reason, never fabricated. */ + export interface MetricMissing { + readonly value: null + readonly reason: MissingReason + /** Optional human-readable detail. */ + readonly detail?: string + } + + export type MetricValue = MetricPresent | MetricMissing + + export const isPresent = (m: MetricValue): m is MetricPresent => m.value !== null + export const isMissing = (m: MetricValue): m is MetricMissing => m.value === null + + /** Construct a present metric value with provenance. */ + export const present = (value: number | boolean, unit: MetricUnit, provenance: MetricProvenance): MetricPresent => ({ + value, + unit, + provenance, + }) + + /** Construct an honest missing value (`null` + reason). Use this; never invent a number. */ + export const missing = (reason: MissingReason, detail?: string): MetricMissing => ({ + value: null, + reason, + ...(detail !== undefined ? { detail } : {}), + }) + + // —— hotspots & profile —————————————————————————————————————————————————————— + + /** A resolved source coordinate. Shape matches `LSPResolve.Candidate.{file,position}`. */ + export interface FileLine { + file: string + /** 1-based line for human display (LSP positions are 0-based; back-fill converts). */ + line: number + } + + /** + * One hotspot: a GPU `kernel` or a CPU `symbol`/function, with its share of time + * and its neutral metrics. `file_line` is OPTIONAL and back-fillable: P3A passes + * the kernel/symbol name through `LSPResolve.resolveSymbol` (a `Candidate.file` + + * `position.line`) to fill it. P1A only leaves the field + this note; it does not + * wire LSP. Until back-filled it is `undefined` (not attempted) or `null` (attempted, + * unresolved). + */ + export interface Hotspot { + /** CPU/function hotspot identity. At least one of `symbol`/`kernel` is set. */ + symbol?: string + /** GPU kernel hotspot identity. */ + kernel?: string + /** Source coordinate; back-filled via {@link LSPResolve.resolveSymbol} by P3A. */ + file_line?: FileLine | null + /** Self time as a percent of total (0–100). */ + self_pct: number + /** Inclusive/total time percent (0–100), when the profiler distinguishes it. */ + total_pct?: number + /** Neutral-vocabulary metrics for this hotspot: neutral name → value (present or null). */ + metrics: Record + } + + /** + * Back-fill helper for P3A: convert an `LSPResolve.Candidate` (0-based LSP position) + * into a hotspot `FileLine` (1-based display line). P1A defines the seam; P3A calls + * `LSPResolve.resolveSymbol(kernel|symbol)` and feeds the candidate here. This is the + * only point that couples PAP to LSP, and it is pure (no LSP wiring in this module). + */ + export const fileLineFromCandidate = (c: LSPResolve.Candidate): FileLine => ({ + file: c.file, + line: c.position.line + 1, + }) + + /** Reference to the native report on disk — spilled to an L5 artifact, never inlined. */ + export interface NativeReportRef { + /** Absolute path to the native report (`.ncu-rep`/`.nsys-rep`/rocpd/CSV/…). */ + path: string + format: "csv" | "json" | "sqlite" | "ncu-rep" | "nsys-rep" | "rocpd" | "perf-data" | "text" + /** Byte size, for the R0 output budget / artifact routing. */ + bytes?: number + /** Native exporter command that can re-derive a human view (e.g. `nsys stats …`). */ + exportCommand?: string + } + + /** What to profile. `focus` (symbol/kernel) drives `LSPResolve` back-fill in P3A. */ + export interface ProfileTarget { + /** Command/test/executable to profile. */ + command: string + args?: readonly string[] + cwd?: string + /** Symbol/kernel name to focus on (resolved via LSP for hotspot back-fill). */ + focus?: string + /** Requested domain; an adapter may pin its own. */ + domain?: Domain + /** Requested neutral metric names (PAP vocabulary); empty → adapter default set. */ + metrics?: readonly string[] + } + + /** + * Stage-2 output: the parsed native report. Still carries NATIVE metric names — + * normalization to the neutral vocabulary happens in stage 3. `availableMetrics` + * is the existence-check input (§P1A-V 映射原则 1): the metrics this machine's + * profiler actually exposed, used to trim "theoretical" mappings to "machine-available". + */ + export interface RawHotspot { + name: string + kind: "kernel" | "symbol" + file_line?: FileLine | null + self_pct?: number + total_pct?: number + /** Native metric name → raw value, as the profiler exported it. */ + nativeMetrics: Record + } + + export interface RawProfile { + adapterId: string + vendor: Vendor + domain: Domain + target: ProfileTarget + /** Top-level native metrics (roofline/occupancy summary), native names preserved. */ + nativeSummary: Record + hotspots: RawHotspot[] + raw_report_ref: NativeReportRef + /** Native metrics actually available on this machine (existence-check input). */ + availableMetrics?: readonly string[] + } + + /** + * Stage-3 output: the vendor-agnostic profile handed to the Agent / evidence layer. + * Every metric key is a NEUTRAL vocabulary name; no native vendor names leak here. + * Native report stays out of context — only `raw_report_ref` points to the artifact. + */ + export interface NormalizedProfile { + domain: Domain + vendor: Vendor + adapterId: string + target: ProfileTarget + /** Wall/kernel duration normalized to ns; `null` when the profiler did not report it. */ + duration_ns?: number | null + hotspots: Hotspot[] + /** Top-level neutral metrics (roofline/occupancy/etc.): neutral name → value. */ + summary: Record + raw_report_ref: NativeReportRef + } + + // —— neutral→native mapping (validated at adapter registration) —————————————— + + /** A neutral metric this adapter CAN produce, and how. */ + export interface MetricMapPresent { + neutral: string + native: string | readonly string[] + semantic: Semantic + /** True for PAP-computed metrics (`ipc`/`compute_bound`); requires `formula`. */ + derived?: boolean + formula?: string + conversion?: string + } + + /** A neutral metric this adapter CANNOT produce — declared null + reason at register time. */ + export interface MetricMapMissing { + neutral: string + native: null + reason: MissingReason + detail?: string + } + + export type MetricMapEntry = MetricMapPresent | MetricMapMissing + + export const isMappingPresent = (e: MetricMapEntry): e is MetricMapPresent => e.native !== null + export const isMappingMissing = (e: MetricMapEntry): e is MetricMapMissing => e.native === null + + /** + * An adapter's declared mapping from the neutral vocabulary onto its native metrics. + * Validated at registration by `Vocabulary.validateMapping` for completeness + + * existence + derived/missing honesty. + */ + export interface MetricMapping { + adapterId: string + domain: Domain + /** Native metrics actually available on this machine (existence check). */ + availableMetrics?: readonly string[] + entries: readonly MetricMapEntry[] + } + + // —— the adapter contract —————————————————————————————————————————————————— + + /** + * The PAP three-stage contract. Adding a new profiler = implement these three + * stages + fill `mapping`; nothing above this layer changes. Stages return + * `Promise` (matching the §P1A interface sketch) because the actual collect/parse + * are process/IO bound in P2A; `normalize` is pure but stays async-shaped for + * symmetry. Control-plane only: collect builds a CLI and runs the vendor tool — + * PAP never reimplements a profiler. + */ + export interface ProfileAdapter { + readonly id: string // "ncu" | "nsys" | "rocprof" | "vtune" | "perf" + readonly vendor: Vendor + readonly domain: Domain + /** Privileges this adapter needs; R0 gates them fail-closed. */ + readonly privileges: readonly RuntimeBase.PrivilegeSpec[] + /** Neutral→native mapping; validated at registration (anti-套壳 completeness). */ + readonly mapping: MetricMapping + /** Default output budget; large native reports spill to an artifact (R0). */ + readonly defaultBudget?: RuntimeBase.ResourceBudget + + /** Stage 1 — build CLI, run program under profiler, produce native report. */ + collect(target: ProfileTarget): Promise + /** Stage 2 — read native report (CSV/JSON/SQLite) into intermediate structure. */ + parse(report: NativeReportRef): Promise + /** Stage 3 — map native metric names onto the neutral vocabulary. */ + normalize(raw: RawProfile): NormalizedProfile + } + + // —— profile structural validation —————————————————————————————————————————— + + export interface ValidationResult { + ok: boolean + errors: string[] + warnings: string[] + } + + /** + * Validate that a `NormalizedProfile` is well-formed: required fields present, + * each hotspot identified (symbol|kernel) with a numeric `self_pct`, and every + * metric value is either a proper present-with-provenance value or an honest + * null-with-reason. Vocabulary conformance (neutral names + domain applicability) + * is checked by `Vocabulary.validateProfile`; this is the structural gate. + */ + export const validateProfile = (np: NormalizedProfile): ValidationResult => { + const errors: string[] = [] + const warnings: string[] = [] + const domains: readonly Domain[] = ["gpu_kernel", "gpu_timeline", "cpu_sampling", "cpu_hotspot"] + + if (!np.adapterId) errors.push("missing adapterId") + if (!domains.includes(np.domain)) errors.push(`invalid domain: ${String(np.domain)}`) + if (!np.target || !np.target.command) errors.push("missing target.command") + if (!np.raw_report_ref || !np.raw_report_ref.path) errors.push("missing raw_report_ref.path") + if (np.duration_ns !== undefined && np.duration_ns !== null && !(np.duration_ns >= 0)) + errors.push("duration_ns must be >= 0 or null") + + if (!Array.isArray(np.hotspots)) { + errors.push("hotspots must be an array") + } else { + np.hotspots.forEach((h, i) => { + if (!h.symbol && !h.kernel) errors.push(`hotspot[${i}] has neither symbol nor kernel`) + if (typeof h.self_pct !== "number") errors.push(`hotspot[${i}].self_pct must be a number`) + if (h.file_line !== undefined && h.file_line !== null) { + if (!h.file_line.file || typeof h.file_line.line !== "number") + errors.push(`hotspot[${i}].file_line must be {file,line} or null`) + } + validateMetricBag(h.metrics, `hotspot[${i}].metrics`, errors, warnings) + }) + } + + validateMetricBag(np.summary, "summary", errors, warnings) + return { ok: errors.length === 0, errors, warnings } + } + + const validateMetricBag = ( + bag: Record | undefined, + where: string, + errors: string[], + warnings: string[], + ): void => { + if (!bag || typeof bag !== "object") { + errors.push(`${where} must be an object`) + return + } + for (const [name, m] of Object.entries(bag)) { + if (m == null || typeof m !== "object") { + errors.push(`${where}.${name} is not a MetricValue`) + continue + } + if (isMissing(m)) { + if (!m.reason) errors.push(`${where}.${name} is null but has no reason (must be honest, not fabricated)`) + continue + } + // present + if (m.unit === undefined) errors.push(`${where}.${name} present value missing unit`) + if (!m.provenance || !m.provenance.nativeMetric) errors.push(`${where}.${name} present value missing provenance`) + else { + if (m.provenance.derived && !m.provenance.formula) + errors.push(`${where}.${name} is derived but records no formula`) + if (m.provenance.semantic === "approximate") + warnings.push(`${where}.${name} mapped with approximate semantics`) + } + } + } +} diff --git a/packages/deepagent-code/src/profile/service.ts b/packages/deepagent-code/src/profile/service.ts new file mode 100644 index 00000000..4f1f7c2d --- /dev/null +++ b/packages/deepagent-code/src/profile/service.ts @@ -0,0 +1,557 @@ +import path from "path" +import * as Log from "@deepagent-code/core/util/log" +import { PAP } from "@/profile/pap" + +const log = Log.create({ service: "profile.service" }) + +/** + * P4A (S1-v3.5): ProfileService — the profiling evidence closed-loop. + * + * Orchestrates the full collect→parse→normalize pipeline over a PAP adapter and + * writes the result as a PROFILE_RESULT.json evidence artifact + * (`evidence_kind:"profile"`), registered in agent-gateway.ts. + * + * Three entry points: + * - `run` — full pipeline + artifact write + optional before/after diff. + * - `roofline` — pure classifier: compute/memory/latency/balanced from neutral metrics. + * - `diff` — structured before/after diff of two NormalizedProfiles. + * + * Cross-vendor note: because all metrics use the neutral vocabulary, a NVIDIA (ncu) + * and an AMD (rocprof) profile of the same program can be compared through `diff`. + * Granularity differs (ncu exports per-kernel counter precision, rocprof aggregates + * some metrics differently), so some deltas will be `null` when a metric is missing + * on one side. The `cross_vendor` flag in DiffResult signals this to callers. + */ +export namespace ProfileService { + // —— roofline types ———————————————————————————————————————————————————————— + + export type Bound = "compute" | "memory" | "latency" | "balanced" + + export interface RooflineResult { + /** The dominant performance limiter. */ + readonly bound: Bound + /** + * Human-readable explanation referencing the specific metric values that drove + * the classification (e.g. "compute-bound (compute_throughput_pct=87%, + * memory_throughput_pct=42%)"). Derived from the neutral vocabulary — no vendor + * names leak here. + */ + readonly detail: string + /** Always true: this is a PAP-derived classification, not a native metric. */ + readonly derived: true + } + + // —— diff types ———————————————————————————————————————————————————————————— + + export interface MetricDiff { + before: number | null + after: number | null + /** after − before; null when either side has no value. */ + delta: number | null + } + + export interface HotspotDiff { + /** Identity key: `symbol` or `kernel` name. */ + name: string + status: "improved" | "worsened" | "unchanged" | "added" | "removed" + /** Self-time percent in the before profile (absent for "added"). */ + self_pct_before?: number + /** Self-time percent in the after profile (absent for "removed"). */ + self_pct_after?: number + /** + * self_pct_after − self_pct_before. Negative = hotspot shrank (improved), + * positive = hotspot grew (worsened). Absent when one side is missing. + */ + self_pct_delta?: number + /** Per-neutral-metric deltas for this hotspot. */ + metrics_diff: Record + } + + export interface DiffResult { + hotspots: HotspotDiff[] + summary_diff: Record + /** + * True when profileA.vendor !== profileB.vendor. Cross-vendor diffs are valid + * because both profiles use the neutral vocabulary; some metrics may be null + * on one side when a vendor does not provide them (honest null, not fabricated). + */ + cross_vendor: boolean + /** + * False when the two profiles are NOT directly comparable — currently when they + * live in different domains (e.g. gpu_kernel vs cpu_sampling): their metric sets + * and hotspot namespaces are disjoint, so a name-keyed diff produces spurious + * all-added/all-removed noise. Callers must not present a `comparable:false` diff + * as an apples-to-apples improvement/regression. + */ + comparable: boolean + vendor_a: string + vendor_b: string + domain_a: string + domain_b: string + /** Human-readable note, e.g. cross-vendor caveat or metric granularity difference. */ + note?: string + /** Non-fatal caveats, e.g. "same metric mapped exact on one side, approximate on the other". */ + warnings?: string[] + } + + // —— artifact shape ———————————————————————————————————————————————————————— + + /** The shape written to PROFILE_RESULT.json (evidence_kind:"profile"). */ + export interface ProfileArtifact { + evidence_kind: "profile" + generated_at: string + profile: PAP.NormalizedProfile + roofline: RooflineResult + diff?: DiffResult + } + + // —— run options & result —————————————————————————————————————————————————— + + export interface RunOptions { + /** + * Directory where PROFILE_RESULT.json will be written. Defaults to the OS + * temp directory when omitted (useful for tests that only check the returned + * shape and do not need a stable path). + */ + artifactDir?: string + /** + * Absolute path to a previous PROFILE_RESULT.json. When provided, `run` + * computes a structured diff against the new profile and attaches it to both + * the artifact and the return value. + */ + compare_to?: string + } + + export interface RunResult { + profile: PAP.NormalizedProfile + artifactPath: string + diff?: DiffResult + } + + // —— thresholds ———————————————————————————————————————————————————————————— + + // GPU kernel thresholds (0–100 scale matching PAP unit:"pct") + const GPU_COMPUTE_BOUND_THRESHOLD = 70 + const GPU_MEMORY_BOUND_THRESHOLD = 70 + const GPU_LATENCY_OCCUPANCY_MAX = 33 + + // CPU thresholds + const CPU_MEMORY_CACHE_MISS_THRESHOLD = 0.1 // ratio: > 10% miss rate → memory-bound + const CPU_COMPUTE_IPC_THRESHOLD = 2.0 // ipc > 2.0 → compute-bound + const CPU_COMPUTE_CACHE_MAX = 0.05 // cache_miss_rate < 5% (paired with high ipc) + const CPU_LATENCY_BRANCH_THRESHOLD = 10 // branch_misprediction_pct > 10% → latency + + // GPU timeline thresholds + const TIMELINE_MEMORY_COPY_THRESHOLD = 30 // mem_copy_pct > 30% → memory-bound + const TIMELINE_API_OVERHEAD_THRESHOLD = 40 // api_overhead_pct > 40% → latency + const TIMELINE_COMPUTE_KERNEL_THRESHOLD = 80 // kernel_total_pct > 80% → compute-bound + + // —— helpers ——————————————————————————————————————————————————————————————— + + /** Extract a numeric value from a MetricValue, or undefined if null/missing. */ + function numericMetric(bag: Record, key: string): number | undefined { + const m = bag[key] + if (!m) return undefined + if (PAP.isMissing(m)) return undefined + const v = m.value + if (typeof v !== "number") return undefined + return v + } + + /** Hotspot identity string: symbol takes priority, then kernel. */ + function hotspotName(h: PAP.Hotspot): string { + return h.symbol ?? h.kernel ?? "(unknown)" + } + + // —— roofline —————————————————————————————————————————————————————————————— + + /** + * Derive a roofline / bottleneck classification from a NormalizedProfile. + * + * Works for BOTH GPU (gpu_kernel, gpu_timeline) and CPU (cpu_sampling, cpu_hotspot) + * profiles via the neutral vocabulary. GPU: uses compute_throughput_pct, + * memory_throughput_pct, dram_bandwidth_pct, occupancy_pct. CPU: uses ipc, + * cache_miss_rate, memory_bound_pct, branch_misprediction_pct. + * + * Returns `bound:"balanced"` when no metric is clearly dominant — this is + * honest: "no single bottleneck identified from available metrics." + */ + export const roofline = (profile: PAP.NormalizedProfile): RooflineResult => { + const s = profile.summary + const domain = profile.domain + + if (domain === "gpu_kernel") return rooflineGpuKernel(s) + if (domain === "gpu_timeline") return rooflineGpuTimeline(s) + // cpu_sampling and cpu_hotspot + return rooflineCpu(s, profile.hotspots) + } + + function rooflineGpuKernel(summary: Record): RooflineResult { + const computePct = numericMetric(summary, "compute_throughput_pct") + const memPct = numericMetric(summary, "memory_throughput_pct") + const dramPct = numericMetric(summary, "dram_bandwidth_pct") + const occPct = numericMetric(summary, "occupancy_pct") + + // Priority order: latency (low occupancy) first — even a compute-heavy kernel + // running at 20% occupancy is latency-limited. Then check compute vs memory. + if (occPct !== undefined && occPct < GPU_LATENCY_OCCUPANCY_MAX) { + return { + bound: "latency", + detail: `latency-bound (occupancy_pct=${occPct.toFixed(1)}% < ${GPU_LATENCY_OCCUPANCY_MAX}%; low occupancy indicates latency-limited execution)`, + derived: true, + } + } + if (dramPct !== undefined && dramPct >= GPU_MEMORY_BOUND_THRESHOLD) { + const detail = buildGpuDetail({ computePct, memPct, dramPct, occPct }) + return { bound: "memory", detail: `memory-bound (${detail})`, derived: true } + } + if (memPct !== undefined && memPct >= GPU_MEMORY_BOUND_THRESHOLD && (computePct === undefined || computePct < GPU_COMPUTE_BOUND_THRESHOLD)) { + const detail = buildGpuDetail({ computePct, memPct, dramPct, occPct }) + return { bound: "memory", detail: `memory-bound (${detail})`, derived: true } + } + if (computePct !== undefined && computePct >= GPU_COMPUTE_BOUND_THRESHOLD) { + const detail = buildGpuDetail({ computePct, memPct, dramPct, occPct }) + return { bound: "compute", detail: `compute-bound (${detail})`, derived: true } + } + // No clear dominant limiter + const detail = buildGpuDetail({ computePct, memPct, dramPct, occPct }) + return { bound: "balanced", detail: `balanced (${detail || "no dominant bottleneck from available metrics"})`, derived: true } + } + + function buildGpuDetail(m: { + computePct?: number + memPct?: number + dramPct?: number + occPct?: number + }): string { + const parts: string[] = [] + if (m.computePct !== undefined) parts.push(`compute_throughput_pct=${m.computePct.toFixed(1)}%`) + if (m.memPct !== undefined) parts.push(`memory_throughput_pct=${m.memPct.toFixed(1)}%`) + if (m.dramPct !== undefined) parts.push(`dram_bandwidth_pct=${m.dramPct.toFixed(1)}%`) + if (m.occPct !== undefined) parts.push(`occupancy_pct=${m.occPct.toFixed(1)}%`) + return parts.join(", ") + } + + function rooflineGpuTimeline(summary: Record): RooflineResult { + const kernelPct = numericMetric(summary, "kernel_total_pct") + const memCopyPct = numericMetric(summary, "mem_copy_pct") + const apiPct = numericMetric(summary, "api_overhead_pct") + + if (memCopyPct !== undefined && memCopyPct >= TIMELINE_MEMORY_COPY_THRESHOLD) { + return { + bound: "memory", + detail: `memory-bound (mem_copy_pct=${memCopyPct.toFixed(1)}% indicates transfer-dominated workload)`, + derived: true, + } + } + if (apiPct !== undefined && apiPct >= TIMELINE_API_OVERHEAD_THRESHOLD) { + return { + bound: "latency", + detail: `latency-bound (api_overhead_pct=${apiPct.toFixed(1)}% indicates API-call latency dominates)`, + derived: true, + } + } + if (kernelPct !== undefined && kernelPct >= TIMELINE_COMPUTE_KERNEL_THRESHOLD) { + return { + bound: "compute", + detail: `compute-bound (kernel_total_pct=${kernelPct.toFixed(1)}% of GPU time in compute kernels)`, + derived: true, + } + } + const parts: string[] = [] + if (kernelPct !== undefined) parts.push(`kernel_total_pct=${kernelPct.toFixed(1)}%`) + if (memCopyPct !== undefined) parts.push(`mem_copy_pct=${memCopyPct.toFixed(1)}%`) + if (apiPct !== undefined) parts.push(`api_overhead_pct=${apiPct.toFixed(1)}%`) + return { + bound: "balanced", + detail: `balanced (${parts.join(", ") || "no dominant bottleneck from available metrics"})`, + derived: true, + } + } + + function rooflineCpu(summary: Record, hotspots: PAP.Hotspot[]): RooflineResult { + // Try summary first; fall back to aggregate from top hotspot + const ipc = numericMetric(summary, "ipc") ?? (hotspots[0] ? numericMetric(hotspots[0]!.metrics, "ipc") : undefined) + const cacheMiss = numericMetric(summary, "cache_miss_rate") ?? (hotspots[0] ? numericMetric(hotspots[0]!.metrics, "cache_miss_rate") : undefined) + const memBound = numericMetric(summary, "memory_bound_pct") + const dramBound = numericMetric(summary, "dram_bound_pct") + const branchMisp = numericMetric(summary, "branch_misprediction_pct") + + // Memory-bound: high cache miss or explicit memory-bound pipeline analysis + if (cacheMiss !== undefined && cacheMiss >= CPU_MEMORY_CACHE_MISS_THRESHOLD) { + const parts: string[] = [`cache_miss_rate=${(cacheMiss * 100).toFixed(1)}%`] + if (memBound !== undefined) parts.push(`memory_bound_pct=${memBound.toFixed(1)}%`) + if (dramBound !== undefined) parts.push(`dram_bound_pct=${dramBound.toFixed(1)}%`) + return { bound: "memory", detail: `memory-bound (${parts.join(", ")})`, derived: true } + } + if ((memBound !== undefined && memBound >= 40) || (dramBound !== undefined && dramBound >= 20)) { + const parts: string[] = [] + if (memBound !== undefined) parts.push(`memory_bound_pct=${memBound.toFixed(1)}%`) + if (dramBound !== undefined) parts.push(`dram_bound_pct=${dramBound.toFixed(1)}%`) + return { bound: "memory", detail: `memory-bound (${parts.join(", ")})`, derived: true } + } + + // Compute-bound: high IPC + low cache miss + if (ipc !== undefined && ipc >= CPU_COMPUTE_IPC_THRESHOLD && (cacheMiss === undefined || cacheMiss < CPU_COMPUTE_CACHE_MAX)) { + const parts = [`ipc=${ipc.toFixed(2)}`] + if (cacheMiss !== undefined) parts.push(`cache_miss_rate=${(cacheMiss * 100).toFixed(1)}%`) + return { bound: "compute", detail: `compute-bound (${parts.join(", ")})`, derived: true } + } + + // Latency-bound: high branch misprediction (pipeline stalls) or very low IPC without clear cause + if (branchMisp !== undefined && branchMisp >= CPU_LATENCY_BRANCH_THRESHOLD) { + const parts = [`branch_misprediction_pct=${branchMisp.toFixed(1)}%`] + if (ipc !== undefined) parts.push(`ipc=${ipc.toFixed(2)}`) + return { bound: "latency", detail: `latency-bound (${parts.join(", ")}; branch mispredictions cause pipeline stalls)`, derived: true } + } + + const parts: string[] = [] + if (ipc !== undefined) parts.push(`ipc=${ipc.toFixed(2)}`) + if (cacheMiss !== undefined) parts.push(`cache_miss_rate=${(cacheMiss * 100).toFixed(1)}%`) + if (branchMisp !== undefined) parts.push(`branch_misprediction_pct=${branchMisp.toFixed(1)}%`) + return { + bound: "balanced", + detail: `balanced (${parts.join(", ") || "no dominant bottleneck from available metrics"})`, + derived: true, + } + } + + // —— diff —————————————————————————————————————————————————————————————————— + + /** + * Produce a structured before/after diff of two NormalizedProfiles. + * + * Cross-vendor: because both profiles use the neutral vocabulary, a NVIDIA (ncu) + * and an AMD (rocprof) profile of the same program can be compared. Metric + * values that are null on one side (due to vendor metric gaps, not fabrication) + * produce MetricDiff.delta=null. The `cross_vendor` flag is set to make this + * visible to the caller. + * + * Improvement semantics: a hotspot is "improved" when its self_pct decreased by + * more than 1 percentage point (it consumed less time), "worsened" when it grew + * by more than 1 percentage point, and "unchanged" otherwise. Hotspots absent + * in profileA are "added"; absent in profileB are "removed". + */ + export const diff = (profileA: PAP.NormalizedProfile, profileB: PAP.NormalizedProfile): DiffResult => { + const cross_vendor = profileA.vendor !== profileB.vendor + const comparable = profileA.domain === profileB.domain + + // Cross-domain guard: gpu_kernel vs cpu_sampling (or any domain mismatch) have + // disjoint metric sets and hotspot namespaces. A name-keyed diff would report + // everything as added/removed with delta=null and mislabel it "directly comparable". + // Return early with an explicit not-comparable result rather than fabricate a diff. + if (!comparable) { + return { + hotspots: [], + summary_diff: {}, + cross_vendor, + comparable: false, + vendor_a: profileA.vendor, + vendor_b: profileB.vendor, + domain_a: profileA.domain, + domain_b: profileB.domain, + note: + `not_comparable(cross-domain): '${profileA.domain}' vs '${profileB.domain}'. ` + + `These domains have disjoint metric sets and hotspot namespaces, so a before/after ` + + `diff is not meaningful. Profile both runs with the same adapter/domain to compare.`, + } + } + + // Build lookup maps keyed by hotspot name + const mapA = new Map() + for (const h of profileA.hotspots) mapA.set(hotspotName(h), h) + const mapB = new Map() + for (const h of profileB.hotspots) mapB.set(hotspotName(h), h) + + const hotspots: HotspotDiff[] = [] + + // Hotspots in A: matched (updated) or removed + for (const [name, ha] of mapA) { + const hb = mapB.get(name) + if (!hb) { + hotspots.push({ name, status: "removed", self_pct_before: ha.self_pct, metrics_diff: {} }) + continue + } + const delta = hb.self_pct - ha.self_pct + let status: HotspotDiff["status"] = "unchanged" + if (delta < -1) status = "improved" + else if (delta > 1) status = "worsened" + + const metrics_diff = diffMetricBags(ha.metrics, hb.metrics) + hotspots.push({ + name, + status, + self_pct_before: ha.self_pct, + self_pct_after: hb.self_pct, + self_pct_delta: delta, + metrics_diff, + }) + } + + // Hotspots in B that are new + for (const [name, hb] of mapB) { + if (!mapA.has(name)) { + hotspots.push({ name, status: "added", self_pct_after: hb.self_pct, metrics_diff: {} }) + } + } + + // Sort: improved first, then unchanged, then worsened, added, removed + const ORDER: Record = { + improved: 0, + unchanged: 1, + worsened: 2, + added: 3, + removed: 4, + } + hotspots.sort((a, b) => ORDER[a.status] - ORDER[b.status]) + + const summary_diff = diffMetricBags(profileA.summary, profileB.summary) + + // Same-domain honesty check: a shared metric mapped `exact` on one side and + // `approximate` on the other (e.g. ncu-vs-rocprof compute_throughput_pct) means the + // numeric delta mixes semantics. Surface it as a warning rather than silently trusting it. + const warnings = collectSemanticWarnings(profileA, profileB) + + let note: string | undefined + if (cross_vendor) { + note = + `Cross-vendor comparison (${profileA.vendor} vs ${profileB.vendor}). ` + + `Both profiles use the neutral vocabulary so hotspot names and shared metrics are directly comparable. ` + + `Metrics absent on one vendor (null) produce delta=null — these are honest gaps, not fabrications.` + } + + return { + hotspots, + summary_diff, + cross_vendor, + comparable: true, + vendor_a: profileA.vendor, + vendor_b: profileB.vendor, + domain_a: profileA.domain, + domain_b: profileB.domain, + ...(note ? { note } : {}), + ...(warnings.length ? { warnings } : {}), + } + } + + /** + * Detect shared summary metrics whose mapping semantics differ between the two + * profiles (exact on one side, approximate on the other). The numeric delta of + * such a metric silently mixes an exact and an approximate quantity, so callers + * should treat it with the emitted caveat rather than as a clean measurement. + */ + function collectSemanticWarnings( + profileA: PAP.NormalizedProfile, + profileB: PAP.NormalizedProfile, + ): string[] { + const warnings: string[] = [] + const semanticOf = (m: PAP.MetricValue | undefined): PAP.Semantic | undefined => + m && PAP.isPresent(m) ? m.provenance.semantic : undefined + for (const key of Object.keys(profileA.summary)) { + const sa = semanticOf(profileA.summary[key]) + const sb = semanticOf(profileB.summary[key]) + if (sa && sb && sa !== sb) { + warnings.push( + `metric '${key}' is mapped '${sa}' on ${profileA.adapterId} but '${sb}' on ${profileB.adapterId}; ` + + `its delta mixes exact and approximate semantics (semantic_warning).`, + ) + } + } + return warnings + } + + function diffMetricBags( + bagA: Record, + bagB: Record, + ): Record { + const result: Record = {} + const keys = new Set([...Object.keys(bagA), ...Object.keys(bagB)]) + for (const key of keys) { + const a = bagA[key] + const b = bagB[key] + const va = a && PAP.isPresent(a) && typeof a.value === "number" ? a.value : null + const vb = b && PAP.isPresent(b) && typeof b.value === "number" ? b.value : null + const delta = va !== null && vb !== null ? vb - va : null + result[key] = { before: va, after: vb, delta } + } + return result + } + + // —— run ——————————————————————————————————————————————————————————————————— + + /** + * Run the full collect→parse→normalize pipeline using the given adapter, then: + * 1. Classify the output with `roofline`. + * 2. Optionally compute a before/after diff against `options.compare_to`. + * 3. Write PROFILE_RESULT.json to `options.artifactDir` (defaults to OS temp). + * + * The written artifact is registered in agent-gateway.ts with + * `evidence_kind:"profile"`, so it enters the document graph for plan/audit. + */ + export const run = async ( + adapter: PAP.ProfileAdapter, + target: PAP.ProfileTarget, + options?: RunOptions, + ): Promise => { + log.info("ProfileService.run start", { adapter: adapter.id, target: target.command }) + + // Stage 1: collect + const reportRef = await adapter.collect(target) + log.info("ProfileService collected", { adapter: adapter.id, path: reportRef.path }) + + // Stage 2: parse + const raw = await adapter.parse(reportRef) + log.info("ProfileService parsed", { adapter: adapter.id, hotspots: raw.hotspots.length }) + + // Stage 3: normalize + const profile = adapter.normalize(raw) + log.info("ProfileService normalized", { adapter: adapter.id, hotspots: profile.hotspots.length }) + + // Roofline classification + const rooflineResult = roofline(profile) + log.info("ProfileService roofline", { bound: rooflineResult.bound }) + + // Optional diff + let diffResult: DiffResult | undefined + if (options?.compare_to) { + try { + const fs = await import("fs/promises") + const raw = await fs.readFile(options.compare_to, "utf8") + const prev = JSON.parse(raw) as ProfileArtifact + if (prev.profile) { + diffResult = diff(prev.profile, profile) + log.info("ProfileService diff computed", { + improved: diffResult.hotspots.filter((h) => h.status === "improved").length, + worsened: diffResult.hotspots.filter((h) => h.status === "worsened").length, + cross_vendor: diffResult.cross_vendor, + }) + } + } catch (e) { + log.warn("ProfileService: failed to load compare_to; skipping diff", { path: options.compare_to, error: String(e) }) + } + } + + // Write artifact + const artifactDir = options?.artifactDir ?? (await import("os")).tmpdir() + const artifactPath = path.join(artifactDir, "PROFILE_RESULT.json") + + const artifact: ProfileArtifact = { + evidence_kind: "profile", + generated_at: new Date().toISOString(), + profile, + roofline: rooflineResult, + ...(diffResult ? { diff: diffResult } : {}), + } + + try { + const fs = await import("fs/promises") + await fs.mkdir(artifactDir, { recursive: true }) + await fs.writeFile(artifactPath, JSON.stringify(artifact, null, 2), "utf8") + log.info("ProfileService artifact written", { artifactPath }) + } catch (e) { + log.warn("ProfileService: failed to write artifact", { artifactPath, error: String(e) }) + } + + return { profile, artifactPath, ...(diffResult ? { diff: diffResult } : {}) } + } +} diff --git a/packages/deepagent-code/src/profile/vocabulary.ts b/packages/deepagent-code/src/profile/vocabulary.ts new file mode 100644 index 00000000..dd51efd5 --- /dev/null +++ b/packages/deepagent-code/src/profile/vocabulary.ts @@ -0,0 +1,370 @@ +import { PAP } from "./pap" + +/** + * P1A-V (S1-v3.5): the vendor-neutral metric vocabulary — PAP's soul. + * + * This is the contract table. Each neutral metric declares its meaning, the + * domains it applies to, its normalized unit, and whether it is `derived` (PAP + * computes it from native metrics rather than reading it directly). Adapters map + * their native metric names onto these neutral names; `validateMapping` enforces, + * at registration time, that a mapping is COMPLETE (covers every metric applicable + * to the adapter's domain), HONEST (missing → null + reason, never fabricated), + * EXISTENT (mapped natives are actually available on this machine), and AUDITABLE + * (derived metrics record a formula). Without this gate PAP degrades into N + * incomparable per-profiler wrappers ("套壳"). + * + * Metric names and the native columns referenced in comments are taken from the + * vendor docs cited in §P1A-V Sources (NVIDIA Nsight Compute/Systems, AMD + * rocprofv3, Intel VTune, Linux perf). + */ +export namespace Vocabulary { + /** Definition of one neutral metric in the vocabulary. */ + export interface MetricDef { + /** Neutral name — the key that appears in `NormalizedProfile` metric bags. */ + name: string + /** What the metric means (vendor-agnostic). */ + meaning: string + /** Domains this metric is applicable to; outside these it is `not_applicable_to_domain`. */ + domains: readonly PAP.Domain[] + /** Normalized unit. */ + unit: PAP.MetricUnit + /** True when PAP computes it from other native metrics (not a native metric itself). */ + derived: boolean + } + + // —— 表 1：GPU kernel 级（NVIDIA ncu ↔ AMD rocprof）———————————————————————————— + const GPU_KERNEL: readonly PAP.Domain[] = ["gpu_kernel"] + + export const TABLE_1_GPU_KERNEL: readonly MetricDef[] = [ + { + name: "compute_throughput_pct", + meaning: "Compute (SM/CU) throughput as a percent of peak sustained.", + domains: GPU_KERNEL, + unit: "pct", + derived: false, + }, // ncu sm__throughput.avg.pct_of_peak_sustained_elapsed ↔ rocprof GPUBusy (approx) + { + name: "memory_throughput_pct", + meaning: "Memory subsystem throughput as a percent of peak sustained.", + domains: GPU_KERNEL, + unit: "pct", + derived: false, + }, // ncu gpu__compute_memory_throughput... ↔ rocprof MemUnitBusy + { + name: "dram_bandwidth_pct", + meaning: "DRAM bandwidth utilization as a percent of peak.", + domains: GPU_KERNEL, + unit: "pct", + derived: false, + }, // ncu gpu__dram_throughput... ↔ rocprof MemUnitBusy / (FetchSize+WriteSize ÷ time ÷ peak) + { + name: "l2_throughput_pct", + meaning: "L2 cache throughput as a percent of peak. NB: AMD L2CacheHit is hit-rate (approximate).", + domains: GPU_KERNEL, + unit: "pct", + derived: false, + }, // ncu lts__throughput... ↔ rocprof L2CacheHit (semantic: approximate) + { + name: "occupancy_pct", + meaning: "Achieved occupancy: active warps/wavefronts as a percent of peak.", + domains: GPU_KERNEL, + unit: "pct", + derived: false, + }, // ncu sm__warps_active... ↔ rocprof Wavefronts / theoretical + { + name: "valu_utilization_pct", + meaning: "Vector ALU utilization percent.", + domains: GPU_KERNEL, + unit: "pct", + derived: false, + }, // ncu sm__pipe_fma_cycles_active... (approx) ↔ rocprof VALUUtilization + { + name: "salu_busy_pct", + meaning: "Scalar ALU busy percent (AMD-native; no direct NVIDIA counterpart).", + domains: GPU_KERNEL, + unit: "pct", + derived: false, + }, // ncu — (null) ↔ rocprof SALUBusy + { + name: "duration_ns", + meaning: "Kernel execution duration, normalized to nanoseconds.", + domains: GPU_KERNEL, + unit: "ns", + derived: false, + }, // ncu gpu__time_duration.sum ↔ rocpd kernel timestamp diff + { + name: "compute_bound", + meaning: "Derived: whether the kernel is compute-bound (compute throughput > memory by threshold).", + domains: GPU_KERNEL, + unit: "bool", + derived: true, + }, // PAP-derived from compute_throughput_pct vs memory_throughput_pct + ] + + // —— 表 2：GPU timeline 级（NVIDIA nsys ↔ AMD rocprof trace）———————————————————— + const GPU_TIMELINE: readonly PAP.Domain[] = ["gpu_timeline"] + + export const TABLE_2_GPU_TIMELINE: readonly MetricDef[] = [ + { + name: "kernel_total_pct", + meaning: "Share of total GPU time spent in a single kernel.", + domains: GPU_TIMELINE, + unit: "pct", + derived: false, + }, // nsys gpukernsum % column ↔ rocpd kernel-table aggregation + { + name: "mem_copy_pct", + meaning: "Share of time in H2D/D2H memory transfers.", + domains: GPU_TIMELINE, + unit: "pct", + derived: false, + }, // nsys gpumemtimesum ↔ rocprof --memory-copy-trace + { + name: "api_overhead_pct", + meaning: "Share of time in API-call overhead (CUDA/HIP runtime).", + domains: GPU_TIMELINE, + unit: "pct", + derived: false, + }, // nsys cudaapisum ↔ rocprof --hip-trace aggregation + ] + // NB: the hotspot-list metric (`hotspot[].kernel`, §P1A-V 表2 first row) is structural + // — it lives in `Hotspot.kernel`, not as a scalar metric — so it is not a MetricDef. + + // —— 表 3：CPU 级（Intel VTune ↔ Linux perf）————————————————————————————————————— + const CPU_ALL: readonly PAP.Domain[] = ["cpu_sampling", "cpu_hotspot"] + const CPU_HOTSPOT: readonly PAP.Domain[] = ["cpu_hotspot"] + + export const TABLE_3_CPU: readonly MetricDef[] = [ + { + name: "self_pct", + meaning: "Self time as a percent of total (per symbol/function).", + domains: CPU_ALL, + unit: "pct", + derived: false, + }, // VTune hotspots CPU Time % ↔ perf Overhead % (also surfaced structurally on Hotspot.self_pct) + { + name: "cpi", + meaning: "Cycles per instruction.", + domains: CPU_ALL, + unit: "ratio", + derived: false, + }, // VTune CPI Rate ↔ perf cycles/instructions (derived on perf) + { + name: "ipc", + meaning: "Derived: instructions per cycle (1/CPI).", + domains: CPU_ALL, + unit: "ratio", + derived: true, + }, // VTune 1/CPI Rate (derived) ↔ perf instructions/cycles + { + name: "clockticks", + meaning: "Clock cycles consumed.", + domains: CPU_ALL, + unit: "count", + derived: false, + }, // VTune Clockticks ↔ perf cycles PMU event + { + name: "instructions_retired", + meaning: "Retired instruction count.", + domains: CPU_ALL, + unit: "count", + derived: false, + }, // VTune Instructions Retired ↔ perf instructions PMU event + { + name: "memory_bound_pct", + meaning: "Percent of pipeline slots stalled on memory (topdown µarch analysis).", + domains: CPU_HOTSPOT, + unit: "pct", + derived: false, + }, // VTune Memory Bound ↔ perf — (null unless perf stat topdown) + { + name: "dram_bound_pct", + meaning: "Percent of pipeline slots bound on DRAM.", + domains: CPU_HOTSPOT, + unit: "pct", + derived: false, + }, // VTune DRAM Bound ↔ perf — (null) + { + name: "cache_miss_rate", + meaning: "Cache miss rate (misses / references).", + domains: CPU_ALL, + unit: "ratio", + derived: false, + }, // VTune *Cache Miss* ↔ perf cache-misses/cache-references + { + name: "branch_misprediction_pct", + meaning: "Branch misprediction rate.", + domains: CPU_ALL, + unit: "pct", + derived: false, + }, // VTune Bad Speculation ↔ perf branch-misses/branches + ] + + /** The full vocabulary, all tables flattened. */ + export const ALL: readonly MetricDef[] = [...TABLE_1_GPU_KERNEL, ...TABLE_2_GPU_TIMELINE, ...TABLE_3_CPU] + + const BY_NAME: ReadonlyMap = new Map(ALL.map((m) => [m.name, m])) + + export const get = (name: string): MetricDef | undefined => BY_NAME.get(name) + export const has = (name: string): boolean => BY_NAME.has(name) + + /** Neutral metrics applicable to a domain — the completeness target for that domain. */ + export const metricsForDomain = (domain: PAP.Domain): readonly MetricDef[] => + ALL.filter((m) => m.domains.includes(domain)) + + // —— mapping validation (run when an adapter registers) —————————————————————— + + export interface MappingIssue { + /** Neutral metric the issue is about (or "" for mapping-wide issues). */ + metric: string + kind: + | "unknown_metric" // mapping references a name not in the vocabulary + | "not_applicable_to_domain" // mapped a metric that doesn't apply to this domain + | "missing_coverage" // an applicable metric was neither mapped nor declared null + | "derived_without_formula" // derived metric mapped present but no formula recorded + | "derived_mismatch" // present mapping marks derived≠vocabulary, or native metric for non-derived absent + | "null_without_reason" // declared missing but no reason given + | "native_not_available" // mapped native metric isn't in this machine's availableMetrics + | "duplicate_entry" // the same neutral metric mapped twice + detail: string + } + + export interface MappingValidation { + ok: boolean + issues: MappingIssue[] + /** Neutral metrics this adapter produces a real value for. */ + present: string[] + /** Neutral metrics honestly declared null. */ + missing: string[] + } + + /** + * Validate an adapter's neutral→native mapping at registration. Enforces the five + * §P1A-V 映射原则: + * 1. existence — every mapped native metric must be in `availableMetrics` (when provided). + * 2. semantic — `approximate` is allowed; only structural problems are flagged here. + * 3. derived split — derived metrics need a formula and must match the vocabulary's + * `derived` flag; non-derived present mappings must name a native metric. + * 4. unit — units come from the vocabulary def, so they are consistent by construction. + * 5. honesty/completeness — every domain-applicable metric is either mapped present OR + * declared null + reason; nothing applicable may be silently omitted, and nothing + * may be fabricated. + */ + export const validateMapping = (mapping: PAP.MetricMapping): MappingValidation => { + const issues: MappingIssue[] = [] + const present: string[] = [] + const missing: string[] = [] + const seen = new Set() + const available = mapping.availableMetrics ? new Set(mapping.availableMetrics) : undefined + + for (const entry of mapping.entries) { + const def = get(entry.neutral) + if (!def) { + issues.push({ metric: entry.neutral, kind: "unknown_metric", detail: `'${entry.neutral}' is not in the vocabulary` }) + continue + } + if (seen.has(entry.neutral)) { + issues.push({ metric: entry.neutral, kind: "duplicate_entry", detail: `'${entry.neutral}' mapped more than once` }) + continue + } + seen.add(entry.neutral) + + if (!def.domains.includes(mapping.domain)) { + issues.push({ + metric: entry.neutral, + kind: "not_applicable_to_domain", + detail: `'${entry.neutral}' does not apply to domain '${mapping.domain}'`, + }) + continue + } + + if (PAP.isMappingMissing(entry)) { + if (!entry.reason) { + issues.push({ metric: entry.neutral, kind: "null_without_reason", detail: `null mapping for '${entry.neutral}' has no reason` }) + } else { + missing.push(entry.neutral) + } + continue + } + + // present mapping + if (def.derived) { + if (!entry.derived) { + issues.push({ + metric: entry.neutral, + kind: "derived_mismatch", + detail: `'${entry.neutral}' is derived in the vocabulary but the mapping doesn't mark derived:true`, + }) + } + if (!entry.formula) { + issues.push({ + metric: entry.neutral, + kind: "derived_without_formula", + detail: `derived metric '${entry.neutral}' must record a formula (auditability)`, + }) + } + // derived metrics may compose multiple natives; existence-check each named one below. + } else if (entry.derived) { + issues.push({ + metric: entry.neutral, + kind: "derived_mismatch", + detail: `'${entry.neutral}' is native in the vocabulary but the mapping marks derived:true`, + }) + } + + const natives = Array.isArray(entry.native) ? entry.native : [entry.native] + if (natives.length === 0 || natives.some((n) => !n)) { + issues.push({ metric: entry.neutral, kind: "derived_mismatch", detail: `'${entry.neutral}' present mapping names no native metric` }) + } + if (available) { + for (const n of natives) { + if (n && !available.has(n)) { + issues.push({ + metric: entry.neutral, + kind: "native_not_available", + detail: `native metric '${n}' for '${entry.neutral}' is not in this machine's availableMetrics`, + }) + } + } + } + present.push(entry.neutral) + } + + // Completeness: every domain-applicable metric must be covered (present or null). + for (const def of metricsForDomain(mapping.domain)) { + if (!seen.has(def.name)) { + issues.push({ + metric: def.name, + kind: "missing_coverage", + detail: `domain '${mapping.domain}' requires '${def.name}' to be mapped present or declared null+reason`, + }) + } + } + + return { ok: issues.length === 0, issues, present, missing } + } + + /** + * Vocabulary conformance check for a finished `NormalizedProfile`: every metric key + * (in summary + hotspots) must be a known neutral name and applicable to the profile's + * domain. Complements `PAP.validateProfile` (which checks structure/provenance). + */ + export const validateProfile = (np: PAP.NormalizedProfile): PAP.ValidationResult => { + const errors: string[] = [] + const warnings: string[] = [] + const checkBag = (bag: Record, where: string) => { + for (const name of Object.keys(bag)) { + const def = get(name) + if (!def) { + errors.push(`${where}.${name} is not a vocabulary metric`) + continue + } + if (!def.domains.includes(np.domain)) + warnings.push(`${where}.${name} is not applicable to domain '${np.domain}'`) + } + } + checkBag(np.summary, "summary") + np.hotspots.forEach((h, i) => checkBag(h.metrics, `hotspot[${i}].metrics`)) + return { ok: errors.length === 0, errors, warnings } + } +} diff --git a/packages/deepagent-code/src/provider/provider.ts b/packages/deepagent-code/src/provider/provider.ts index d816f674..1d869bbc 100644 --- a/packages/deepagent-code/src/provider/provider.ts +++ b/packages/deepagent-code/src/provider/provider.ts @@ -26,7 +26,8 @@ import { FSUtil } from "@deepagent-code/core/fs-util" import { isRecord } from "@/util/record" import { optionalOmitUndefined } from "@deepagent-code/core/schema" import { ProviderTransform } from "./transform" -import { ProviderV2 } from "@deepagent-code/core/provider" +import { ProviderV2, OFFICIAL_PROVIDER_ID_SET } from "@deepagent-code/core/provider" +import { SettingsStore } from "@/settings/store" import { ModelV2 } from "@deepagent-code/core/model" import { ModelStatus } from "./model-status" import { RuntimeFlags } from "@/effect/runtime-flags" @@ -44,6 +45,10 @@ import { const log = Log.create({ service: "provider" }) const OPENAI_HEADER_TIMEOUT_DEFAULT = 10_000 +const THIRD_PARTY_PROVIDER_CONFLICT_MESSAGE = + "Provider id conflicts with an official provider. Rename this third-party provider in your config." +const LEGACY_AUTH_KEY_MESSAGE = + "Saved API key is no longer used. Only official providers read keys from the key store. Re-add this as a third-party provider in your config and set the key under options.apiKey." function providerEnvKey(configuredEnv: string[], envs: Record) { const configured = configuredEnv.find((item) => envs[item]) @@ -1015,8 +1020,10 @@ export type Info = Types.DeepMutable> const DefaultModelIDs = Schema.Record(Schema.String, Schema.String) -// A non-fatal config-load problem (bad JSON or invalid fields in a config/provider file) surfaced to the UI -// so the user can tell *why* a provider was not imported. `source` is the offending file path. +// A non-fatal config-load problem surfaced to the UI so the user can tell *why* a provider was not +// imported. `source` is a human-readable locator for the offending input: a config/provider file path +// for parse/schema failures, or a `provider.` / `auth.` locator for provider-level problems +// (id conflicts, legacy auth-store keys). `kind` is the failure category. export const ConfigError = Schema.Struct({ source: Schema.String, kind: Schema.Literals(["json", "schema"]), @@ -1091,6 +1098,7 @@ export type Error = ModelNotFoundError | InitError | NoProvidersError | NoModels export interface Interface { readonly list: () => Effect.Effect> + readonly errors: () => Effect.Effect readonly getProvider: (providerID: ProviderV2.ID) => Effect.Effect readonly getModel: (providerID: ProviderV2.ID, modelID: ModelV2.ID) => Effect.Effect readonly getLanguage: (model: Model) => Effect.Effect @@ -1106,6 +1114,7 @@ interface State { models: Map providers: Record catalog: Record + errors: ConfigError[] sdk: Map modelLoaders: Record varsLoaders: Record @@ -1151,6 +1160,8 @@ function cost(c: ModelsDev.Model["cost"]): Model["cost"] { function inferredReasoning(providerID: string, apiID: string, modelID = apiID) { const provider = providerID.toLowerCase() const model = `${apiID} ${modelID}`.toLowerCase() + // Aligned with upstream: GLM-5.2 is a reasoning model across the whole Zhipu/Z.AI brand family + // (plain pay-as-you-go AND coding-plan), so its thinking tiers apply on every face. if (!["zai", "zhipuai"].some((id) => provider.includes(id))) return false return ["glm-5.2", "glm-5-2", "glm-5p2"].some((id) => model.includes(id)) } @@ -1285,9 +1296,18 @@ export const layer = Layer.effect( using _ = log.time("state") const bridge = yield* EffectBridge.make() const cfg = yield* config.get() + // Official providers ignore config.provider. entirely; their transport tuning + // (header/chunk/request timeouts, retries) is read straight from SettingsStore — the only + // place the connect dialog's advanced section persists it (never the config file). + const officialTransport = (yield* Effect.promise(() => SettingsStore.read())).providers ?? {} const modelsDev = yield* modelsDevSvc.get() const catalog = mapValues(modelsDev, fromModelsDevProvider) const database = mapValues(catalog, toPublicInfo) + // "Official" is a fixed, curated set (openai/deepseek/anthropic/zhipuai/xai/google) — NOT the + // whole models.dev catalog. Only these read credentials from the auth key store and reject + // config redefinition; every other catalog id is a normal third-party provider configurable + // via `provider.` in config (credentials from options.apiKey/env). + const officialProviderIDs = OFFICIAL_PROVIDER_ID_SET const providers: Record = {} as Record const languages = new Map() @@ -1332,6 +1352,7 @@ export const layer = Layer.effect( const enabled = cfg.enabled_providers ? new Set(cfg.enabled_providers) : null const envs = yield* env.all() const allAuths = yield* auth.all().pipe(Effect.orDie) + const errors: ConfigError[] = [] function isProviderAllowed(providerID: ProviderV2.ID): boolean { if (enabled && !enabled.has(providerID)) return false @@ -1366,15 +1387,44 @@ export const layer = Layer.effect( }) } - // extend database from config + function isOfficialProviderID(providerID: string) { + return officialProviderIDs.has(providerID) + } + + function providerConfigError( + providerID: string, + message: string, + scope: "provider" | "auth" = "provider", + ): ConfigError { + return { + source: `${scope}.${providerID}`, + kind: "schema", + message, + } + } + + // Configured providers are always third-party providers. They must not share ids with + // official catalog providers; otherwise a custom endpoint can silently hijack official + // provider semantics and auth. for (const [providerID, provider] of configProviders) { + // The hosted first-party gateway is credentialed via config (provider.deepagent-code. + // options.apiKey) but its catalog identity/models are fixed. Leave its catalog entry + // intact — the custom loader reads the config key — and never treat it as third-party. + if (providerID === "deepagent-code") continue + if (isOfficialProviderID(providerID)) { + errors.push(providerConfigError(providerID, THIRD_PARTY_PROVIDER_CONFLICT_MESSAGE)) + continue + } + // Non-official providers are third-party. If the id also exists in the catalog (e.g. + // mistral, cloudflare, nvidia), config MERGES onto the catalog entry so shipped models and + // loaders survive while config overrides name/options/models. A brand-new id starts empty. const existing = database[providerID] const parsed: Info = { id: ProviderV2.ID.make(providerID), name: provider.name ?? existing?.name ?? providerID, env: provider.env ?? existing?.env ?? [], options: mergeDeep(existing?.options ?? {}, provider.options ?? {}), - source: "config", + source: "custom", models: existing?.models ?? {}, } @@ -1459,10 +1509,13 @@ export const layer = Layer.effect( parsed.models[modelID] = parsedModel } database[providerID] = parsed + mergeProvider(ProviderV2.ID.make(providerID), { source: "custom" }) } - // load env + // Official providers use the auth/key store only. Env API keys are only honored for + // third-party providers declared in config via their `env` field. for (const [id, provider] of Object.entries(database)) { + if (isOfficialProviderID(id)) continue const providerID = ProviderV2.ID.make(id) if (!isProviderAllowed(providerID)) continue const envKey = providerEnvKey(provider.env, envs) @@ -1475,8 +1528,16 @@ export const layer = Layer.effect( } // load apikeys + // The auth/key store is read for official ids AND for shipped integrations that consume auth + // via a custom loader or plugin auth loader (digitalocean, azure, bedrock, gitlab, …). Any + // other id with a stored key is a leftover from the old flow — see the orphan warning below. + const credentialLoaderIDs = new Set([ + ...Object.keys(custom(dep)), + ...plugins.flatMap((p) => (p.auth ? [p.auth.provider] : [])), + ]) + const canUseKeyStore = (id: string) => isOfficialProviderID(id) || credentialLoaderIDs.has(id) const auths = Object.fromEntries( - Object.entries(allAuths).filter(([id]) => isProviderAllowed(ProviderV2.ID.make(id))), + Object.entries(allAuths).filter(([id]) => canUseKeyStore(id) && isProviderAllowed(ProviderV2.ID.make(id))), ) for (const [id, provider] of Object.entries(auths)) { const providerID = ProviderV2.ID.make(id) @@ -1489,6 +1550,15 @@ export const layer = Layer.effect( } } + // Warn about legacy key-store entries left behind by the old flow (where third-party keys were + // written to the auth store). Those keys are no longer read for a plain third-party provider, so + // the key silently does nothing until the user re-adds it in config under options.apiKey. + for (const [id, provider] of Object.entries(allAuths)) { + if (provider.type !== "api") continue + if (canUseKeyStore(id)) continue + errors.push(providerConfigError(id, LEGACY_AUTH_KEY_MESSAGE, "auth")) + } + // plugin auth loader - database now has entries for config providers for (const plugin of plugins) { if (!plugin.auth) continue @@ -1532,16 +1602,6 @@ export const layer = Layer.effect( } } - // load config - re-apply with updated data - for (const [id, provider] of configProviders) { - const providerID = ProviderV2.ID.make(id) - const partial: Partial = { source: "config" } - if (provider.env) partial.env = provider.env - if (provider.name) partial.name = provider.name - if (provider.options) partial.options = provider.options - mergeProvider(providerID, partial) - } - const gitlab = ProviderV2.ID.make("gitlab") if (discoveryLoaders[gitlab] && providers[gitlab] && isProviderAllowed(gitlab)) { yield* Effect.promise(async () => { @@ -1565,7 +1625,17 @@ export const layer = Layer.effect( continue } - const configProvider = cfg.provider?.[providerID] + const configProvider = isOfficialProviderID(providerID) ? undefined : cfg.provider?.[providerID] + + // Official providers: merge transport tuning from SettingsStore onto the loader/catalog + // defaults (settings win). maxRetries maps to the SDK option; the fetch-level timeouts are + // consumed by resolveSDK. Third-party providers get their transport from config.options. + if (isOfficialProviderID(providerID)) { + const transport = officialTransport[providerID] + if (transport && Object.keys(transport).length > 0) { + provider.options = { ...provider.options, ...transport } + } + } for (const [modelID, model] of Object.entries(provider.models)) { model.api.id = model.api.id ?? model.id ?? modelID @@ -1632,6 +1702,7 @@ export const layer = Layer.effect( models: languages, providers, catalog, + errors, sdk, modelLoaders, varsLoaders, @@ -1640,6 +1711,7 @@ export const layer = Layer.effect( ) const list = Effect.fn("Provider.list")(() => InstanceState.use(state, (s) => s.providers)) + const errors = Effect.fn("Provider.errors")(() => InstanceState.use(state, (s) => s.errors)) function deepagentModelAuthProviderID(model: Model) { if (model.providerID !== "deepagent") return @@ -1709,6 +1781,8 @@ export const layer = Layer.effect( const headerTimeout = options["headerTimeout"] delete options["chunkTimeout"] delete options["headerTimeout"] + // maxRetries is applied at the generate call (see session/llm.ts), not the SDK factory. + delete options["maxRetries"] options["fetch"] = async (input: any, init?: BunFetchRequestInit) => { const fetchFn = customFetch ?? fetch @@ -1970,7 +2044,7 @@ export const layer = Layer.effect( } }) - return Service.of({ list, getProvider, getModel, getLanguage, closest, getSmallModel, defaultModel }) + return Service.of({ list, errors, getProvider, getModel, getLanguage, closest, getSmallModel, defaultModel }) }), ) diff --git a/packages/deepagent-code/src/provider/transform.ts b/packages/deepagent-code/src/provider/transform.ts index dbab4fb9..115ddd5e 100644 --- a/packages/deepagent-code/src/provider/transform.ts +++ b/packages/deepagent-code/src/provider/transform.ts @@ -658,6 +658,8 @@ export function variants(model: Provider.Model): Record input.model.providerID.includes(id)) && + ["zai", "zhipuai"].some((id) => input.model.providerID.toLowerCase().includes(id)) && input.model.api.npm === "@ai-sdk/openai-compatible" ) { result["thinking"] = { diff --git a/packages/deepagent-code/src/runtime/base.ts b/packages/deepagent-code/src/runtime/base.ts new file mode 100644 index 00000000..5900a668 --- /dev/null +++ b/packages/deepagent-code/src/runtime/base.ts @@ -0,0 +1,341 @@ +import { Context, Effect, Layer } from "effect" +import path from "path" +import { Worktree } from "@/worktree" +import { InstanceState } from "@/effect/instance-state" +import { which } from "@deepagent-code/core/util/which" +import * as Log from "@deepagent-code/core/util/log" + +const log = Log.create({ service: "runtime.base" }) + +/** + * R0 (S1-v3.5): the runtime common base shared by DAP (debug) and PAP (profile). + * + * Both runtime layers are EXECUTION-class (they actually run the user's program), + * may need PRIVILEGES (GPU counters / perf_event_paranoid / ptrace), produce LARGE + * structured output, run in WORKTREE ISOLATION, and back-fill SYMBOLS. None of that + * should be written twice. This module is control-plane only — it never reimplements + * a debugger or profiler; it gates, isolates, budgets, and routes evidence. + * + * The four cross-cutting concerns (§R0 设计): + * 1. execution approval — once per session, reused for in-session sub-operations. + * 2. privilege gate — fail-closed; declared per adapter, never silently degraded. + * 3. worktree isolation — sessions run in a V3.3 (U3) worktree, auto-cleaned. + * 4. resource budget — timeout + output ceiling; over-limit truncates to artifact. + */ +export namespace RuntimeBase { + // —— privileges —————————————————————————————————————————————————————————— + + /** + * A privilege an adapter declares it needs. The gate is FAIL-CLOSED: if the + * environment does not satisfy a required privilege, the runtime reports + * "needs X, currently unavailable" and refuses — it never silently degrades + * and never attempts to elevate. + */ + export type PrivilegeKind = + | "gpu_performance_counter" // NVIDIA ncu / nsys GPU counters + | "perf_event_paranoid" // Linux perf_event_paranoid <= required level + | "ptrace" // GDB / lldb attach via ptrace_scope + | "cap_sys_admin" // some counters require CAP_SYS_ADMIN + | "rocm_profiling" // AMD rocprof profiling access + + export interface PrivilegeSpec { + kind: PrivilegeKind + /** Human-readable note shown when the privilege is missing. */ + reason: string + /** For perf_event_paranoid: the maximum acceptable value (e.g. 2). */ + maxParanoid?: number + } + + /** Outcome of checking one privilege against the live environment. */ + export interface PrivilegeCheck { + kind: PrivilegeKind + satisfied: boolean + /** Why it is unsatisfied (only set when satisfied=false). */ + detail?: string + } + + /** + * Probes the environment for one privilege. Pure detection — no side effects, + * no elevation. Probes are injected so tests can simulate any environment and + * so platform specifics stay out of the gate logic. + */ + export interface PrivilegeProbe { + readonly check: (spec: PrivilegeSpec) => Effect.Effect + } + + export class UnsatisfiedPrivilegeError extends Error { + readonly _tag = "RuntimeUnsatisfiedPrivilegeError" + readonly checks: PrivilegeCheck[] + constructor(checks: PrivilegeCheck[]) { + const missing = checks.filter((c) => !c.satisfied) + super( + `Required runtime privilege(s) unavailable: ${missing + .map((c) => `${c.kind}${c.detail ? ` (${c.detail})` : ""}`) + .join(", ")}. Not degrading and not elevating — resolve the privilege and retry.`, + ) + this.checks = checks + } + } + + // —— execution approval ———————————————————————————————————————————————————— + + /** + * Tracks which runtime sessions have already been approved, so the FIRST + * start of a session asks once and every in-session sub-operation (step / + * continue / inspect / collect) reuses that grant without re-prompting. + * Keyed by a caller-chosen session key (e.g. a debug/profile session id). + */ + export interface ApprovalTracker { + readonly approved: (sessionKey: string) => boolean + readonly markApproved: (sessionKey: string) => void + } + + // —— resource budget ———————————————————————————————————————————————————————— + + export interface ResourceBudget { + /** Hard wall-clock ceiling for a single collect/debug operation. */ + timeoutMs: number + /** Max bytes of output kept inline; the rest spills to an artifact. */ + maxInlineBytes: number + } + + export const DEFAULT_BUDGET: ResourceBudget = { + timeoutMs: 120_000, + maxInlineBytes: 24_000, + } + + /** Result of applying the output budget: a summary stays inline, the full body spills. */ + export interface BudgetedOutput { + inline: string + truncated: boolean + /** Full byte length before truncation. */ + fullBytes: number + } + + /** + * Applies the output budget. Profiler reports can reach hundreds of MB, so the + * runtime keeps only a head slice inline and signals truncation; the caller + * writes the full body to an artifact (L5) and surfaces only the summary. + */ + export const applyOutputBudget = (full: string, budget: ResourceBudget = DEFAULT_BUDGET): BudgetedOutput => { + const bytes = Buffer.byteLength(full, "utf8") + if (bytes <= budget.maxInlineBytes) return { inline: full, truncated: false, fullBytes: bytes } + // Slice on bytes, then decode back to a clean string (drop a possibly split tail char). + const head = Buffer.from(full, "utf8").subarray(0, budget.maxInlineBytes).toString("utf8") + return { + inline: `${head}\n… [truncated: ${bytes} bytes total, full report in artifact]`, + truncated: true, + fullBytes: bytes, + } + } + + // —— service ———————————————————————————————————————————————————————————————— + + export interface Interface { + /** + * Gate a runtime EXECUTION operation: approve once per session, then enforce + * the privilege gate fail-closed. Reuses the approval for in-session + * sub-operations. `ask` is the tool's `ctx.ask` bridge. + */ + readonly gate: (input: { + sessionKey: string + /** Privileges the chosen adapter declares it needs. */ + privileges: readonly PrivilegeSpec[] + /** Called only on the FIRST operation of a session; should drive ctx.ask. */ + requestApproval: () => Effect.Effect + }) => Effect.Effect + + /** + * Run a runtime body inside an isolated worktree (V3.3 U3). The worktree is + * created up-front and safe-removed on completion (clean → removed; dirty → + * left for inspection). Falls back to the main directory for non-git + * projects so the runtime still works, logging that isolation was skipped. + */ + readonly withIsolation: ( + input: { name?: string }, + body: (workdir: string) => Effect.Effect, + ) => Effect.Effect + + /** Check privileges without approving — used by tools to report capability up-front. */ + readonly checkPrivileges: (privileges: readonly PrivilegeSpec[]) => Effect.Effect + } + + export class Service extends Context.Service()("@deepagent-code/RuntimeBase") {} + + /** A no-op probe that reports every privilege satisfied — for tests / unprivileged dev. */ + export const allowAllProbe: PrivilegeProbe = { + check: (spec) => Effect.succeed({ kind: spec.kind, satisfied: true }), + } + + /** A probe that reports every privilege unavailable — for fail-closed tests. */ + export const denyAllProbe: PrivilegeProbe = { + check: (spec) => + Effect.succeed({ kind: spec.kind, satisfied: false, detail: spec.reason || "not available in this environment" }), + } + + /** + * Build the service from an injected privilege probe. The probe is the single + * seam for platform detection; the gate logic itself is platform-agnostic. + */ + export const make = (probe: PrivilegeProbe): Effect.Effect => + Effect.gen(function* () { + const worktree = yield* Worktree.Service + // Session approval state lives for the life of this service instance (one per + // instance/session scope), matching "approve once per session". + const approvals = new Set() + + const checkPrivileges: Interface["checkPrivileges"] = (privileges) => + Effect.forEach(privileges, (spec) => probe.check(spec)) + + const gate: Interface["gate"] = (input) => + Effect.gen(function* () { + // 1. Privilege gate first (fail-closed) — never prompt for approval on an + // operation we already know cannot run. + const checks = yield* checkPrivileges(input.privileges) + const missing = checks.filter((c) => !c.satisfied) + if (missing.length > 0) { + return yield* Effect.fail(new UnsatisfiedPrivilegeError(checks)) + } + // 2. Approval, once per session. + if (!approvals.has(input.sessionKey)) { + yield* input.requestApproval() + approvals.add(input.sessionKey) + } + }) + + const withIsolation: Interface["withIsolation"] = (input, body) => + Effect.gen(function* () { + const ctx = yield* InstanceState.context + // Non-git project → worktrees unsupported; run in the main dir but say so. + if (ctx.project.vcs !== "git") { + log.warn("runtime isolation skipped (non-git project); running in main directory") + return yield* body(ctx.directory) + } + const info = yield* worktree.create({ name: input.name }).pipe( + Effect.catch((e) => { + // Worktree creation failed — degrade to main dir rather than block the + // runtime entirely, but make the loss of isolation visible. + log.warn("runtime worktree creation failed; running in main directory", { error: String(e) }) + return Effect.succeed(undefined) + }), + ) + if (!info) return yield* body(ctx.directory) + return yield* body(info.directory).pipe( + Effect.ensuring( + // Clean → removed; dirty → kept (force=false) so the user can inspect side effects. + worktree.safeRemove({ directory: info.directory }).pipe(Effect.catch(() => Effect.void)), + ), + ) + }) + + return Service.of({ gate, withIsolation, checkPrivileges }) + }) + + /** + * Default platform privilege probe. Detection only — reads procfs / device nodes / + * env, never mutates state and never elevates. A privilege is `satisfied:true` only + * on a POSITIVE signal; anything unverifiable stays fail-closed with an accurate reason + * (so a fully-capable machine can actually pass the gate, but a machine we cannot verify + * never gets a false green). + */ + export const platformProbe: PrivilegeProbe = { + check: (spec) => + Effect.gen(function* () { + switch (spec.kind) { + case "perf_event_paranoid": { + const value = yield* readParanoid + if (value === undefined) + return { kind: spec.kind, satisfied: false, detail: "perf_event_paranoid unreadable" } + const max = spec.maxParanoid ?? 2 + return value <= max + ? { kind: spec.kind, satisfied: true } + : { kind: spec.kind, satisfied: false, detail: `perf_event_paranoid=${value} > ${max}` } + } + case "gpu_performance_counter": { + // Positive signal: an NVIDIA device node or the nvidia-smi tool is present. + const ok = (yield* anyPathExists(["/dev/nvidiactl", "/dev/nvidia0"])) || which("nvidia-smi") !== null + return ok + ? { kind: spec.kind, satisfied: true } + : { + kind: spec.kind, + satisfied: false, + detail: "no NVIDIA device node (/dev/nvidia*) or nvidia-smi found; GPU performance counters unavailable", + } + } + case "rocm_profiling": { + // Positive signal: the AMD KFD device node or a rocm-smi/rocminfo tool. + const ok = + (yield* anyPathExists(["/dev/kfd"])) || which("rocm-smi") !== null || which("rocminfo") !== null + return ok + ? { kind: spec.kind, satisfied: true } + : { + kind: spec.kind, + satisfied: false, + detail: "no AMD KFD device node (/dev/kfd) or rocm-smi/rocminfo found; ROCm profiling unavailable", + } + } + case "ptrace": { + // Linux yama ptrace_scope: 0 = unrestricted, 1 = child-only (still fine for + // launch-and-attach), 2/3 = admin/none. Absent file (non-Linux/no yama) → ptrace + // is generally permitted for a launched child, so treat "unreadable" as satisfied. + const scope = yield* readPtraceScope + if (scope === undefined) return { kind: spec.kind, satisfied: true } + return scope <= 1 + ? { kind: spec.kind, satisfied: true } + : { kind: spec.kind, satisfied: false, detail: `yama ptrace_scope=${scope} restricts attach (need <= 1)` } + } + // cap_sys_admin cannot be verified without attempting a privileged op; fail closed. + default: + return { kind: spec.kind, satisfied: false, detail: "privilege not verifiable in this environment" } + } + }), + } + + /** True if any of the given paths exists. Pure detection (fs.access), never mutates. */ + const anyPathExists = (paths: readonly string[]) => + Effect.promise(async () => { + const fs = await import("fs/promises") + for (const p of paths) { + try { + await fs.access(p) + return true + } catch { + // not present; keep checking + } + } + return false + }) + + const readPtraceScope = Effect.gen(function* () { + const raw = yield* Effect.tryPromise({ + try: async () => { + const fs = await import("fs/promises") + return await fs.readFile("/proc/sys/kernel/yama/ptrace_scope", "utf8") + }, + catch: () => undefined, + }).pipe(Effect.catch(() => Effect.succeed(undefined))) + if (raw === undefined) return undefined + const n = Number.parseInt(raw.trim(), 10) + return Number.isNaN(n) ? undefined : n + }) + + const readParanoid = Effect.gen(function* () { + const raw = yield* Effect.tryPromise({ + try: async () => { + const fs = await import("fs/promises") + return await fs.readFile(path.join("/proc/sys/kernel", "perf_event_paranoid"), "utf8") + }, + catch: () => undefined, + }).pipe(Effect.catch(() => Effect.succeed(undefined))) + if (raw === undefined) return undefined + const n = Number.parseInt(raw.trim(), 10) + return Number.isNaN(n) ? undefined : n + }) + + /** Default layer using the platform probe. */ + export const layer: Layer.Layer = Layer.effect(Service, make(platformProbe)) + + /** Test layer with an injectable probe (defaults to allow-all). */ + export const testLayer = (probe: PrivilegeProbe = allowAllProbe): Layer.Layer => + Layer.effect(Service, make(probe)) +} diff --git a/packages/deepagent-code/src/runtime/index.ts b/packages/deepagent-code/src/runtime/index.ts new file mode 100644 index 00000000..5e552b6b --- /dev/null +++ b/packages/deepagent-code/src/runtime/index.ts @@ -0,0 +1 @@ +export * from "./base" diff --git a/packages/deepagent-code/src/server/routes/instance/httpapi/handlers/provider.ts b/packages/deepagent-code/src/server/routes/instance/httpapi/handlers/provider.ts index 5e0a9196..3f0a8a92 100644 --- a/packages/deepagent-code/src/server/routes/instance/httpapi/handlers/provider.ts +++ b/packages/deepagent-code/src/server/routes/instance/httpapi/handlers/provider.ts @@ -54,7 +54,9 @@ export const providerHandlers = HttpApiBuilder.group(InstanceHttpApi, "provider" mapValues(filtered, (item) => Provider.fromModelsDevProvider(item)), connected, ) - const errors = yield* cfg.getErrors() + const configErrors = yield* cfg.getErrors() + const providerErrors = yield* provider.errors() + const errors = [...configErrors, ...providerErrors] return { all: Object.values(providers).map(Provider.toPublicInfo), default: Provider.defaultModelIDs(providers), diff --git a/packages/deepagent-code/src/session/deepagent-multiround.ts b/packages/deepagent-code/src/session/deepagent-multiround.ts index cd9697d0..5a3f53ca 100644 --- a/packages/deepagent-code/src/session/deepagent-multiround.ts +++ b/packages/deepagent-code/src/session/deepagent-multiround.ts @@ -303,8 +303,14 @@ export const maybeRunRounds = (ops: MultiRoundOps): Effect.Effect => const hardGate = AgentGateway.DeepAgentPlanController.hardGateEnabled(ops.agentMode) const plan = AgentGateway.DeepAgentSessionState.getPlan(ops.sessionID) const planExists = plan != null - const hasCompletionReport = - planExists && AgentGateway.DeepAgentPlanController.buildCompletionReport(plan).complete + const completionReport = planExists ? AgentGateway.DeepAgentPlanController.buildCompletionReport(plan) : null + const hasCompletionReport = completionReport?.complete === true + // U10: a plan that finished with a `blocked` step is NOT a clean "done" — finalize is allowed + // (blocked counts as resolved so the run never deadlocks), but it must route to needs_human so + // the operator sees WHY the plan could not be fully executed. This is the honest escape hatch + // that stops the model from marking a step falsely `done` to satisfy the gate. + const blockedSteps = completionReport?.blocked ?? [] + const hasBlocked = blockedSteps.length > 0 const stopDecision = StopHook.evaluate({ name: "stop", payload: { requiredValidationsRun, planStale, hardGate, planExists, hasCompletionReport }, @@ -312,7 +318,10 @@ export const maybeRunRounds = (ops: MultiRoundOps): Effect.Effect => const baseStatus = RoundReport.deriveStatus(report) // T3: a 🔴 triage exit (or exhausted narrowing) forces needs_human with the triage reason, so the // operator sees "not auto-fixable: " rather than a generic continue/done. - const status = redReason != null || stopDecision.decision === "block" || packChanged ? "needs_human" : baseStatus + const status = + redReason != null || stopDecision.decision === "block" || packChanged || hasBlocked + ? "needs_human" + : baseStatus const suggestion: NextRoundSuggestion = { status, body: redReason @@ -321,7 +330,9 @@ export const maybeRunRounds = (ops: MultiRoundOps): Effect.Effect => ? `Domain pack set changed mid-run (${ops.baselinePackSnapshotId} -> ${ops.packSnapshotId}); risk/scope may have shifted, human review required before continuing.` : stopDecision.decision === "block" ? `${stopDecision.blockReason}. Configured validations: ${ops.validationCommands.join(", ")}.` - : RoundReport.summarizeForSuggestion(report), + : hasBlocked + ? `Plan finished with blocked step(s) needing human input: ${blockedSteps.join("; ")}.` + : RoundReport.summarizeForSuggestion(report), } yield* ops.onMacroRound(suggestion, report) } diff --git a/packages/deepagent-code/src/session/llm.ts b/packages/deepagent-code/src/session/llm.ts index 1910b006..9d701584 100644 --- a/packages/deepagent-code/src/session/llm.ts +++ b/packages/deepagent-code/src/session/llm.ts @@ -6,7 +6,7 @@ import { Log } from "@deepagent-code/core/util/log" import { Global } from "@deepagent-code/core/global" import { Context, Effect, Layer } from "effect" import * as Stream from "effect/Stream" -import { streamText, wrapLanguageModel, type ModelMessage, type Tool } from "ai" +import { streamText, wrapLanguageModel, type ModelMessage, type Tool, APICallError } from "ai" import { type LLMEvent } from "@deepagent-code/llm" import { AgentGateway } from "@deepagent-code/core/agent-gateway" import { LLMClient, RequestExecutor, WebSocketExecutor } from "@deepagent-code/llm/route" @@ -130,6 +130,10 @@ const live: Layer.Layer< { concurrency: "unbounded" }, ) const info = input.model.providerID === "deepagent" ? (modelAuth ?? providerAuth) : providerAuth + // Official providers can configure a retry count via the connect dialog (SettingsStore → + // provider.options.maxRetries). When set it overrides the per-call default; otherwise the + // existing per-call retries (2 for a session turn, 0 for sub-calls) stands. + const providerMaxRetries = typeof item.options?.maxRetries === "number" ? item.options.maxRetries : undefined const isWorkflow = language instanceof GitLabWorkflowLanguageModel const prepared = yield* LLMRequestPrep.prepare({ @@ -311,8 +315,24 @@ const live: Layer.Layer< // Copilot returns the authoritative billed amount only in provider-specific response fields. includeRawChunks: input.model.providerID.includes("github-copilot"), onError(error) { + // AI SDK's APICallError carries `requestBodyValues` = the ENTIRE request body (system + // prompt + every message). Logging the raw error JSON.stringifies that into a single + // multi-hundred-KB line. Log only the salient fields (and a truncated responseBody) so a + // provider error — e.g. a 429 "insufficient balance" — stays a readable one-liner. + if (APICallError.isInstance(error)) { + const body = typeof error.responseBody === "string" ? error.responseBody : undefined + l.error("stream error", { + name: error.name, + url: error.url, + statusCode: error.statusCode, + isRetryable: error.isRetryable, + message: error.message, + responseBody: body && body.length > 1000 ? body.slice(0, 1000) + "…[truncated]" : body, + }) + return + } l.error("stream error", { - error, + error: error instanceof Error ? error.message : String(error), }) }, async experimental_repairToolCall(failed) { @@ -346,7 +366,7 @@ const live: Layer.Layer< maxOutputTokens: prepared.params.maxOutputTokens, abortSignal: input.abort, headers: prepared.headers, - maxRetries: input.retries ?? 0, + maxRetries: providerMaxRetries ?? input.retries ?? 0, messages: prepared.messages, model: wrapLanguageModel({ model: language, diff --git a/packages/deepagent-code/src/session/reminders.ts b/packages/deepagent-code/src/session/reminders.ts index f47afc7a..be004460 100644 --- a/packages/deepagent-code/src/session/reminders.ts +++ b/packages/deepagent-code/src/session/reminders.ts @@ -2,6 +2,7 @@ import path from "path" import { SessionV1 } from "@deepagent-code/core/v1/session" import { Effect } from "effect" import { Agent } from "@/agent/agent" +import { AgentGateway } from "@deepagent-code/core/agent-gateway" import { FSUtil } from "@deepagent-code/core/fs-util" import { InstanceState } from "@/effect/instance-state" import { RuntimeFlags } from "@/effect/runtime-flags" @@ -12,6 +13,41 @@ import PROMPT_PLAN from "./prompt/plan.txt" import BUILD_SWITCH from "./prompt/build-switch.txt" import PLAN_MODE from "./prompt/plan-mode.txt" +// U10 step-reporting: re-inject the model's own structured plan as an ephemeral synthetic reminder +// each turn (high+ only), so it can SEE its checklist and report against it — and, when it has made +// several edits without a status change, nudge it (soft) to report progress. Pushed as an ephemeral +// part (NOT persisted via updatePart), mirroring the plan-mode reminders, so it is constant-cost and +// does not accumulate across turns. The runtime never infers step completion; this only prompts the +// model to report, and the plan tool applies the report. +const applyPlanReport = (userMessage: SessionV1.WithParts): void => { + const sessionID = userMessage.info.sessionID + const agentMode = AgentGateway.snapshot().agentMode ?? "high" + // Lightweight modes (general/direct) never carry the plan machinery — no snapshot, no nudge. + if (AgentGateway.DeepAgentPlanController.isLightweightMode(agentMode)) return + const plan = AgentGateway.DeepAgentSessionState.getPlan(sessionID) + if (!plan) return + + const snapshot = AgentGateway.DeepAgentPlanController.renderPlanSnapshot(plan) + const mutations = AgentGateway.DeepAgentSessionState.mutationsSinceReport(sessionID) + const validationPassedSinceReport = AgentGateway.DeepAgentSessionState.validationPassedSinceReport(sessionID) + // U10 hybrid trigger: semantic (a validation just passed) is primary, mode-scaled count is the + // backstop. nudgeTrigger returns WHY it fired (or null) so the reminder can be phrased honestly. + const trigger = AgentGateway.DeepAgentPlanController.nudgeTrigger(plan, { + mutationsSinceReport: mutations, + validationPassedSinceReport, + mode: agentMode, + }) + const nudge = trigger ? `\n\n${AgentGateway.DeepAgentPlanController.PROGRESS_NUDGE(trigger, mutations)}` : "" + userMessage.parts.push({ + id: PartID.ascending(), + messageID: userMessage.info.id, + sessionID, + type: "text", + text: `\n${snapshot}${nudge}\n`, + synthetic: true, + }) +} + export const apply = Effect.fn("SessionReminders.apply")(function* (input: { messages: SessionV1.WithParts[] agent: Agent.Info @@ -23,6 +59,9 @@ export const apply = Effect.fn("SessionReminders.apply")(function* (input: { const userMessage = input.messages.findLast((msg) => msg.info.role === "user") if (!userMessage) return input.messages + // U10: PlanController snapshot + progress nudge, independent of experimental plan mode. + applyPlanReport(userMessage) + if (!flags.experimentalPlanMode) { if (input.agent.name === "plan") { userMessage.parts.push({ diff --git a/packages/deepagent-code/src/session/tools.ts b/packages/deepagent-code/src/session/tools.ts index 4ad0e2de..ceb6bd8b 100644 --- a/packages/deepagent-code/src/session/tools.ts +++ b/packages/deepagent-code/src/session/tools.ts @@ -171,6 +171,12 @@ export const resolve = Effect.fn("SessionTools.resolve")(function* (input: { return { title: "Plan update required", output: reason, metadata: {} } } const result = yield* item.execute(args, ctx) + // U10: count a successful mutating tool call toward the progress-nudge budget. Only + // mutating tools (edit/write/patch/shell) count; the counter resets when the model next + // changes a plan step's status. No-op when there is no plan. + if (AgentGateway.DeepAgentPlanController.isMutatingTool(item.id)) { + AgentGateway.DeepAgentSessionState.recordMutation(ctx.sessionID) + } const output = { ...result, attachments: result.attachments?.map((attachment) => ({ diff --git a/packages/deepagent-code/src/settings/store.ts b/packages/deepagent-code/src/settings/store.ts new file mode 100644 index 00000000..dd34dbae --- /dev/null +++ b/packages/deepagent-code/src/settings/store.ts @@ -0,0 +1,181 @@ +import fsNode from "fs/promises" +import path from "path" +import { Global } from "@deepagent-code/core/global" +import { OFFICIAL_PROVIDER_ID_SET } from "@deepagent-code/core/provider-official" + +/** + * First-party settings store — the single home for settings that must NOT live in the + * user-editable config file (`deepagent-code.jsonc`, which is reserved for third-party + * providers). Two families live here: + * + * 1. `deepagent` — first-party runtime settings (prompt/wish/agent-mode/self-learning + + * gateway knobs) that used to piggyback on `provider.deepagent.options`. + * 2. `providers` — per-official-provider transport tuning (header/chunk/request timeouts, + * retries). Official providers deliberately ignore `config.provider.`, + * so their transport settings can only be edited here (via the connect + * dialog's advanced section) — never through the config file. + * + * Stored at `~/.deepagent/code/settings.json` (same root as `account.json`), mode 0600, + * atomic write. Read is cached in-memory and invalidated on write. This module is + * backend-only; the renderer never imports it (it reads/writes through the config overlay). + */ +export namespace SettingsStore { + export type PromptMode = "direct" | "wish" + export type AgentMode = "general" | "high" | "xhigh" | "max" | "ultra" + export type SelfLearning = "manual" | "auto" + + export interface DeepAgentSettings { + promptMode?: PromptMode + wishModel?: string + agentMode?: AgentMode + selfLearning?: SelfLearning + runsDir?: string + allowProviderExecutedTools?: boolean + allowProviderExecutedToolNames?: string[] + } + + /** Transport tuning for a single official provider. Mirrors the transport keys the provider + * loader strips from `options` and applies as fetch-level abort controllers. */ + export interface TransportSettings { + headerTimeout?: number | false + chunkTimeout?: number + timeout?: number | false + maxRetries?: number + } + + export interface Settings { + deepagent?: DeepAgentSettings + /** Keyed by official provider id (openai/zhipuai/zai/…). */ + providers?: Record + } + + const FILE = () => path.join(Global.Path.data, "settings.json") + + // Cache is keyed by resolved file path so a mid-process home switch (TEST_HOME / DEEPAGENT_CODE_HOME + // in tests) doesn't serve a stale other-home cache. + let cache: { path: string; value: Settings } | undefined + + const isRecord = (v: unknown): v is Record => + typeof v === "object" && v !== null && !Array.isArray(v) + + const str = (v: unknown): string | undefined => (typeof v === "string" && v.length > 0 ? v : undefined) + const bool = (v: unknown): boolean | undefined => (typeof v === "boolean" ? v : undefined) + const posInt = (v: unknown): number | undefined => + typeof v === "number" && Number.isInteger(v) && v > 0 ? v : undefined + const timeout = (v: unknown): number | false | undefined => (v === false ? false : posInt(v)) + const strArray = (v: unknown): string[] | undefined => + Array.isArray(v) ? v.filter((i): i is string => typeof i === "string" && i.length > 0) : undefined + + const promptMode = (v: unknown): PromptMode | undefined => (v === "direct" || v === "wish" ? v : undefined) + const agentMode = (v: unknown): AgentMode | undefined => + v === "general" || v === "high" || v === "xhigh" || v === "max" || v === "ultra" ? v : undefined + const selfLearning = (v: unknown): SelfLearning | undefined => (v === "manual" || v === "auto" ? v : undefined) + + function normalizeDeepAgent(input: unknown): DeepAgentSettings | undefined { + if (!isRecord(input)) return undefined + const out: DeepAgentSettings = {} + const pm = promptMode(input.promptMode) + if (pm) out.promptMode = pm + const wm = str(input.wishModel) + if (wm) out.wishModel = wm + const am = agentMode(input.agentMode) + if (am) out.agentMode = am + const sl = selfLearning(input.selfLearning) + if (sl) out.selfLearning = sl + const rd = str(input.runsDir) + if (rd) out.runsDir = rd + const apet = bool(input.allowProviderExecutedTools) + if (apet !== undefined) out.allowProviderExecutedTools = apet + const names = strArray(input.allowProviderExecutedToolNames) + if (names) out.allowProviderExecutedToolNames = names + return Object.keys(out).length > 0 ? out : undefined + } + + function normalizeTransport(input: unknown): TransportSettings | undefined { + if (!isRecord(input)) return undefined + const out: TransportSettings = {} + const ht = timeout(input.headerTimeout) + if (ht !== undefined) out.headerTimeout = ht + const ct = posInt(input.chunkTimeout) + if (ct !== undefined) out.chunkTimeout = ct + const to = timeout(input.timeout) + if (to !== undefined) out.timeout = to + const mr = posInt(input.maxRetries) + if (mr !== undefined) out.maxRetries = mr + return Object.keys(out).length > 0 ? out : undefined + } + + function normalize(input: unknown): Settings { + if (!isRecord(input)) return {} + const out: Settings = {} + const da = normalizeDeepAgent(input.deepagent) + if (da) out.deepagent = da + if (isRecord(input.providers)) { + const providers: Record = {} + for (const [id, value] of Object.entries(input.providers)) { + // Only keep transport settings for real official providers; drop anything else so a stale + // or hand-edited id can never leak into the provider loader. + if (!OFFICIAL_PROVIDER_ID_SET.has(id)) continue + const t = normalizeTransport(value) + if (t) providers[id] = t + } + if (Object.keys(providers).length > 0) out.providers = providers + } + return out + } + + /** Read + validate the settings file. Cached in-memory; missing/broken file → empty settings. */ + export async function read(): Promise { + const file = FILE() + if (cache && cache.path === file) return cache.value + const value = await fsNode + .readFile(file, "utf8") + .then((text) => normalize(JSON.parse(text))) + .catch(() => ({}) as Settings) + cache = { path: file, value } + return value + } + + async function write(value: Settings): Promise { + const file = FILE() + await fsNode.mkdir(path.dirname(file), { recursive: true }).catch(() => {}) + const tmp = `${file}.${process.pid}.${Date.now()}.tmp` + await fsNode.writeFile(tmp, JSON.stringify(value, null, 2), { mode: 0o600 }) + await fsNode.rename(tmp, file) + cache = { path: file, value } + } + + /** Drop the in-memory cache (tests / after an external mutation). */ + export function invalidate(): void { + cache = undefined + } + + /** Merge a partial patch (per family) into the stored settings and persist. Reports whether the + * persisted value actually changed so callers can skip disposing running instances on no-op writes. */ + export async function update(patch: { + deepagent?: DeepAgentSettings + providers?: Record + }): Promise<{ settings: Settings; changed: boolean }> { + const current = await read() + const next: Settings = { ...current } + if (patch.deepagent) { + next.deepagent = normalizeDeepAgent({ ...(current.deepagent ?? {}), ...patch.deepagent }) + } + if (patch.providers) { + const merged: Record = { ...(current.providers ?? {}) } + for (const [id, value] of Object.entries(patch.providers)) { + if (!OFFICIAL_PROVIDER_ID_SET.has(id)) continue + const t = normalizeTransport({ ...(merged[id] ?? {}), ...value }) + if (t) merged[id] = t + else delete merged[id] + } + next.providers = Object.keys(merged).length > 0 ? merged : undefined + } + // Strip empty families so the file stays tidy. + if (next.deepagent && Object.keys(next.deepagent).length === 0) delete next.deepagent + if (next.providers && Object.keys(next.providers).length === 0) delete next.providers + const changed = JSON.stringify(next) !== JSON.stringify(current) + if (changed) await write(next) + return { settings: next, changed } + } +} diff --git a/packages/deepagent-code/src/tool/debug.ts b/packages/deepagent-code/src/tool/debug.ts new file mode 100644 index 00000000..a7921543 --- /dev/null +++ b/packages/deepagent-code/src/tool/debug.ts @@ -0,0 +1,358 @@ +import { Effect, Schema } from "effect" +import * as Tool from "./tool" +import path from "path" +import { LSP } from "@/lsp/lsp" +import { LSPResolve } from "@/lsp/resolve" +import { DebugAdapter } from "@/debug/adapter" +import { DebugService } from "@/debug/service" +import { RuntimeBase } from "@/runtime/base" +import { InstanceState } from "@/effect/instance-state" +import DESCRIPTION from "./debug.txt" +import * as Log from "@deepagent-code/core/util/log" +import { Identifier } from "@/id/id" + +const log = Log.create({ service: "tool.debug" }) + +/** + * D3 (S1-v3.5): the `debug` Agent tool — symbol-driven DAP entry point. + * + * Agents address code by symbol name + intent; coordinates are resolved + * internally (LSPResolve) and hidden, matching the code_intel philosophy. + * + * Control-plane only: this tool orchestrates a debug session but implements no + * debugging itself. It routes EVERY operation through `DebugService` (D1: the + * finite session state machine + EventV2 bridge + adapter-process lifecycle) and + * `RuntimeBase` (R0: fail-closed privilege gate, approve-once, worktree isolation). + * There is no local session Map and no local approval Set — the service owns + * session state (with a finalizer that tears down orphaned adapter processes) and + * R0 owns approval/privilege state (one instance per session). + * + * D4 evidence: the serializable `SessionState` snapshot is available in the tool + * result metadata (and registered as DEBUG_SESSION.json, evidence_kind:"debug_session", + * in agent-gateway.ts) — no live handles ever leak into it. + */ + +const intents = ["start", "break_at", "step", "continue", "stack", "inspect", "eval", "stop"] as const +type Intent = (typeof intents)[number] + +const stepKinds = ["next", "stepIn", "stepOut"] as const + +export const Parameters = Schema.Struct({ + intent: Schema.Literals(intents).annotate({ + description: "What to do: start a debug session, set a breakpoint, step, continue, inspect stack/vars, eval an expression, or stop.", + }), + target: Schema.optional(Schema.String).annotate({ + description: "For intent:start — the command or test to run under the debugger, e.g. 'python -m pytest test_foo.py'.", + }), + symbol: Schema.optional(Schema.String).annotate({ + description: "For intent:break_at — symbol name to break at (resolved via LSP, no raw line numbers needed).", + }), + condition: Schema.optional(Schema.String).annotate({ + description: "For intent:break_at — optional conditional expression for the breakpoint.", + }), + expression: Schema.optional(Schema.String).annotate({ + description: "For intent:eval — expression to evaluate in the current frame.", + }), + frame: Schema.optional(Schema.Int.check(Schema.isGreaterThanOrEqualTo(0))).annotate({ + description: "For intent:inspect/eval — stack frame index (0 = innermost). Default: 0.", + }), + language: Schema.optional(Schema.String).annotate({ + description: "For intent:start — programming language to select the adapter, e.g. 'python'. Auto-detected from target when omitted.", + }), + session_id: Schema.optional(Schema.String).annotate({ + description: "Multi-session: identifier for this debug session. Auto-generated when omitted.", + }), + step_kind: Schema.optional(Schema.Literals(stepKinds)).annotate({ + description: "For intent:step — 'next' (step over, default), 'stepIn', or 'stepOut'.", + }), +}) + +type Params = Schema.Schema.Type + +/** Pick a display language from the target command (best-effort heuristic). */ +function inferLanguage(target: string): string { + // Order + word boundaries matter: the old `includes("go ")` matched the "go r" in + // "car`go r`un" and shadowed Rust. Check the most specific signals first and anchor + // each keyword on a word/extension boundary so substrings don't cross-match. + if (/\bcargo\b|\brust\b|\brustc\b|\.rs\b/.test(target)) return "rust" + if (/\bpython[0-9.]*\b|\bpytest\b|\.py\b/.test(target)) return "python" + if (/\.(c|cpp|cc|cxx|h|hpp)\b/.test(target)) return "cpp" + if (/\bgo\b|\bdlv\b|\.go\b/.test(target)) return "go" + if (/\bswift\b|\.swift\b/.test(target)) return "swift" + return "unknown" +} + +function renderFrames(frames: any[]): string { + if (!frames.length) return "No stack frames." + return frames + .slice(0, 10) + .map((f: any, i: number) => { + const src = f.source?.name ?? f.source?.path ?? "?" + const line = f.line ?? "?" + return ` Frame #${i}: ${f.name ?? "?"} at ${src}:${line}` + }) + .join("\n") +} + +function renderVariables(vars: any[], label: string): string { + if (!vars.length) return `No variables in ${label}.` + const lines = vars.slice(0, 20).map((v: any) => ` ${v.name ?? "?"}: ${String(v.value ?? "?").slice(0, 120)}`) + const extra = vars.length > 20 ? `\n … ${vars.length - 20} more (see DEBUG_SESSION.json evidence)` : "" + return lines.join("\n") + extra +} + +export const DebugTool = Tool.define( + "debug", + Effect.gen(function* () { + // Consume the D1/R0 infrastructure directly (registry layer provides both). + const lsp = yield* LSP.Service + const debug = yield* DebugService.Service + const base = yield* RuntimeBase.Service + const adapterRegistry = DebugAdapter.make() + + /** + * Resolve the session id to operate on. Explicit `session_id` wins; otherwise + * reuse the most-recently-updated live session (matches debug.txt: "omit to use + * the first/only live session"). Returns undefined when none exists. + */ + const resolveSessionId = (explicit: string | undefined) => + Effect.gen(function* () { + if (explicit) return explicit + const sessions = yield* debug.list() + if (sessions.length === 0) return undefined + const latest = [...sessions].sort((a, b) => b.updatedAt - a.updatedAt)[0]! + return latest.id + }) + + return { + description: DESCRIPTION, + parameters: Parameters, + execute: (args: Params, ctx: Tool.Context): Effect.Effect => + Effect.gen(function* () { + const instance = yield* InstanceState.context + + // ── start ───────────────────────────────────────────────────────────── + if (args.intent === "start") { + if (!args.target) + return { title: "debug: error", metadata: {}, output: "`target` is required for intent:start." } + const target = args.target + + const language = args.language ?? inferLanguage(target) + const resolution = adapterRegistry.resolve(language) + if (!resolution.available) { + return { + title: "debug: adapter unavailable", + metadata: { available: false }, + output: resolution.message, + } + } + + // A caller-chosen id, or a fresh ascending one for a brand-new session. + const sessionId = args.session_id ?? Identifier.ascending("tool") + + // Run the launch inside an isolated worktree (R0 U3). DebugService.start + // performs the R0 gate (privilege fail-closed → approve-once) internally, + // spawns the adapter, and drives launch → initialized → configurationDone. + const state = yield* base.withIsolation({ name: `debug-${resolution.spec.id}` }, (workdir) => + debug.start({ + spec: resolution.spec, + sessionId, + // Pass the target as the launch program so the debuggee is actually + // launched (not just an initialize handshake) — the fix for C4. + launch: { program: target, cwd: workdir }, + cwd: workdir, + requestApproval: () => + ctx.ask({ + permission: "debug", + patterns: [target], + always: [], + metadata: { intent: "start", target, sessionId, isolated: workdir }, + }), + }), + ) + log.info("debug session started", { sessionId, adapter: resolution.spec.id }) + + return { + title: `debug: session started (${sessionId})`, + metadata: { sessionId, adapter: resolution.spec.id, status: state.status, session: state }, + output: `Debug session ${sessionId} started.\nAdapter: ${resolution.spec.id}\nTarget: ${target}\nStatus: ${state.status}\n\nUse intent:break_at (symbol name) to set breakpoints, then intent:continue to run.`, + } + } + + // ── resolve the target session for all non-start intents ────────────── + const sessionId = yield* resolveSessionId(args.session_id) + if (!sessionId) { + return { + title: "debug: no session", + metadata: {}, + output: "No active debug session. Use intent:start first.", + } + } + const current = yield* debug.get(sessionId) + if (!current) { + return { + title: "debug: no session", + metadata: {}, + output: `No active debug session '${sessionId}'. Use intent:start first.`, + } + } + + // ── break_at ────────────────────────────────────────────────────────── + if (args.intent === "break_at") { + if (!args.symbol) + return { title: "debug: error", metadata: {}, output: "`symbol` is required for intent:break_at." } + + // Symbol resolution via LSP (L2 resolveSymbol) — no raw line numbers. + const resolved = yield* LSPResolve.resolveSymbol({ lsp, symbol: args.symbol }).pipe( + Effect.catch(() => Effect.succeed({ type: "not_found" as const })), + ) + if (resolved.type === "not_found") { + return { + title: "debug: symbol not found", + metadata: { sessionId }, + output: `Symbol '${args.symbol}' not found via LSP. Is an LSP server active for this file type?`, + } + } + if (resolved.type === "ambiguous") { + const list = resolved.candidates + .map( + (c) => + ` ${c.kindLabel} ${c.name} @ ${path.relative(instance.directory, c.file)}:${c.position.line + 1}`, + ) + .join("\n") + return { + title: "debug: ambiguous symbol", + metadata: { sessionId }, + output: `Symbol '${args.symbol}' is ambiguous:\n${list}\nRe-issue with a more specific file or kind.`, + } + } + + const line = resolved.candidate.position.line + 1 + const state = yield* debug.setBreakpoints({ + sessionId, + source: resolved.candidate.file, + breakpoints: [{ line, ...(args.condition ? { condition: args.condition } : {}) }], + }) + return { + title: `debug: breakpoint set at ${args.symbol}`, + metadata: { sessionId, symbol: args.symbol, file: resolved.candidate.file, line, session: state }, + output: `Breakpoint set at symbol '${args.symbol}' → ${path.relative(instance.directory, resolved.candidate.file)}:${line}${args.condition ? ` (condition: ${args.condition})` : ""}.`, + } + } + + // ── continue ────────────────────────────────────────────────────────── + if (args.intent === "continue") { + const state = yield* debug.continue(sessionId) + return { + title: "debug: continue", + metadata: { sessionId, session: state }, + output: `Session ${sessionId}: resumed (status: ${state.status}).`, + } + } + + // ── step ────────────────────────────────────────────────────────────── + if (args.intent === "step") { + const kind = args.step_kind ?? "next" + const state = yield* debug.step(sessionId, kind) + return { + title: `debug: step (${kind})`, + metadata: { sessionId, session: state }, + output: `Step (${kind}) done (status: ${state.status}).`, + } + } + + // ── stack ───────────────────────────────────────────────────────────── + if (args.intent === "stack") { + const frames = yield* debug.stackTrace(sessionId) + return { + title: `debug: stack (${frames.length} frames)`, + metadata: { sessionId, frames }, + output: `Call stack:\n${renderFrames(frames)}`, + } + } + + // ── inspect ─────────────────────────────────────────────────────────── + if (args.intent === "inspect") { + const frameId = args.frame ?? 0 + const frames = yield* debug.stackTrace(sessionId) + const frame = frames[frameId] + if (!frame) + return { + title: "debug: inspect", + metadata: { sessionId }, + output: `Frame #${frameId} not found (${frames.length} total).`, + } + const scopes = yield* debug.scopes(sessionId, frame.id) + const parts: string[] = [ + `Frame #${frameId} (${frame.name ?? "?"} at ${frame.source?.path ?? "?"}:${frame.line ?? "?"})`, + ] + for (const scope of scopes.slice(0, 3)) { + if (typeof scope.variablesReference !== "number") continue + const vars = yield* debug.variables(sessionId, scope.variablesReference) + const budget = RuntimeBase.applyOutputBudget(JSON.stringify(vars, null, 2)) + parts.push( + `[${scope.name ?? "scope"}]${budget.truncated ? ` (${budget.fullBytes} bytes → DEBUG_SESSION.json)` : ""}\n${renderVariables(vars, scope.name)}`, + ) + } + return { + title: `debug: inspect frame #${frameId}`, + metadata: { sessionId, frameId, scopes }, + output: parts.join("\n\n"), + } + } + + // ── eval ────────────────────────────────────────────────────────────── + if (args.intent === "eval") { + if (!args.expression) + return { title: "debug: error", metadata: { sessionId }, output: "`expression` is required for intent:eval." } + + // Side-effecting evals (function calls) need additional confirmation. + const mightMutate = /\w\s*\(/.test(args.expression) + if (mightMutate) { + yield* ctx.ask({ + permission: "debug_eval", + patterns: [args.expression], + always: [], + metadata: { expression: args.expression, sessionId, note: "expression may have side effects" }, + }) + } + const result = yield* debug.evaluate({ + sessionId, + expression: args.expression, + frameId: args.frame, + context: "repl", + }) + const value = (result as any)?.result ?? JSON.stringify(result) + return { + title: `debug: eval ${args.expression}`, + metadata: { sessionId, result }, + output: `${args.expression} = ${value}`, + } + } + + // ── stop ────────────────────────────────────────────────────────────── + if (args.intent === "stop") { + const state = yield* debug.terminate(sessionId) + return { + title: "debug: session stopped", + metadata: { sessionId, status: state.status, session: state, evidence: "DEBUG_SESSION.json" }, + output: `Debug session ${sessionId} terminated.\nSession state (evidence_kind:"debug_session") is in the tool result metadata / DEBUG_SESSION.json.`, + } + } + + return { title: "debug: unknown intent", metadata: {}, output: `Unknown intent '${args.intent}'.` } + }).pipe( + // DAP/session/privilege failures degrade gracefully (never a Die that kills the + // turn). DebugService maps privilege + adapter errors to Error, so a single catch + // covers "needs X privilege", DAP timeouts, and adapter spawn failures alike. + Effect.catch((err) => + Effect.succeed({ + title: "debug: error", + metadata: {}, + output: err instanceof Error ? err.message : String(err), + } as Tool.ExecuteResult), + ), + ), + } + }), +) diff --git a/packages/deepagent-code/src/tool/debug.txt b/packages/deepagent-code/src/tool/debug.txt new file mode 100644 index 00000000..042d2295 --- /dev/null +++ b/packages/deepagent-code/src/tool/debug.txt @@ -0,0 +1,26 @@ +You are a debug tool powered by the Debug Adapter Protocol (DAP). Use `debug` to investigate runtime failures, inspect variable state, and pinpoint where code breaks under specific inputs — cases where static `code_intel` cannot help because the answer depends on actual execution. + +## When to use `debug` vs `code_intel` +- `code_intel`: static structure — where is a function defined, what calls it, what type is a variable at compile time. +- `debug`: runtime truth — why does it return `None`, what is the actual value of `x` at line 42, which frame threw the exception. + +## Symbol-name contract +The `debug` tool is **symbol-driven**: supply the name of the function or method you want to break at (`symbol:"my_func"`), not a raw line number. The tool resolves the symbol to a coordinate internally via LSP. Provide `session_id` for multi-session scenarios; omit to use the first (or only) live session. + +## Intents + +| Intent | When to use | +|---|---| +| `start` | Launch the program under the debugger. Provide `target` (command/test). Asks for approval once — subsequent in-session ops reuse the grant. | +| `break_at` | Set a breakpoint at a symbol name (`symbol:"foo"`). Optional: `condition` for a conditional breakpoint. | +| `step` | Single-step the program. Options: `"next"` (step over), `"stepIn"` (step into), `"stepOut"` (step out). | +| `continue` | Resume execution until the next breakpoint or program end. | +| `stack` | Inspect the call stack at the current stop. Returns numbered frames with file/line. | +| `inspect` | List local variables and their values for the current (or specified) `frame`. | +| `eval` | Evaluate an expression in the current frame (`expression:"x * 2"`). Expressions that may have side effects require an additional confirmation. | +| `stop` | Terminate the debug session and clean up. | + +## Tips +- Start a session with `start`, set breakpoints with `break_at`, then use `continue` to run to the first hit. +- After a `stack`, use `inspect` with a specific `frame` index to examine a particular call's locals. +- The inline output is a human-readable summary. The full serializable session state (status, breakpoints, thread, stack/variable trees) is returned in the tool result metadata under `session`, and is the `DEBUG_SESSION.json` evidence (evidence_kind:"debug_session") — read it from the tool result, not from a file you have to open. diff --git a/packages/deepagent-code/src/tool/plan-write.ts b/packages/deepagent-code/src/tool/plan-write.ts index fb9cb327..4dd8189a 100644 --- a/packages/deepagent-code/src/tool/plan-write.ts +++ b/packages/deepagent-code/src/tool/plan-write.ts @@ -14,6 +14,7 @@ const PlanStepEvent = Schema.Struct({ status: Schema.String, acceptance: Schema.optional(Schema.NullOr(Schema.String)), assigned_agent: Schema.optional(Schema.NullOr(Schema.String)), + note: Schema.optional(Schema.NullOr(Schema.String)), }) export const PlanEvent = { Updated: EventV2.define({ @@ -26,6 +27,9 @@ export const PlanEvent = { steps: Schema.Array(PlanStepEvent), done: Schema.Number, total: Schema.Number, + // U10: runtime-computed status transitions this write produced ("Title: from→to"). Lets the UI + // and logs show WHAT changed, derived from before/after — not from the model's prose. + changes: Schema.optional(Schema.Array(Schema.String)), }, }), } @@ -38,12 +42,15 @@ export const PlanEvent = { const PlanStep = Schema.Struct({ step_id: Schema.optional(Schema.String).annotate({ description: "Stable id; omit to auto-assign" }), title: Schema.String.annotate({ description: "What this step does" }), - status: Schema.String.annotate({ description: "pending | active | done | cancelled" }), + status: Schema.String.annotate({ description: "pending | active | done | cancelled | blocked" }), // No NullOr: a nested optional(NullOr(...)) emits a double-nested anyOf whose inner // {type:null} survives normalize() and is rejected by some third-party providers (no-reply). // Optional already covers "absent"; buildPlanFromInput coerces missing -> null. acceptance: Schema.optional(Schema.String).annotate({ description: "How you know this step is done" }), assigned_agent: Schema.optional(Schema.String).annotate({ description: "Subagent type to delegate to" }), + note: Schema.optional(Schema.String).annotate({ + description: "Short note; REQUIRED when status is 'blocked' — say why you are stuck", + }), }) export const Parameters = Schema.Struct({ @@ -74,7 +81,7 @@ export const PlanTool = Tool.define AgentGateway.DeepAgentPlanController.formatStepChange(c)) + // U10: soft advisory — a step declared `done` whose acceptance criterion has no passing + // validation on record is flagged (not blocked): the model may be marking done prematurely. + const acceptanceWarnings = plan.steps + .filter( + (s) => + s.status === "done" && + s.acceptance != null && + s.acceptance.trim() !== "" && + (s.evidence == null || s.evidence.length === 0), + ) + .map((s) => `"${s.title}" is done but its acceptance ("${s.acceptance}") has no recorded validation`) // U2: publish the live plan so the app's persistent plan panel updates immediately. yield* events .publish(PlanEvent.Updated, { @@ -101,19 +129,34 @@ export const PlanTool = Tool.define { - const mark = s.status === "done" ? "x" : s.status === "cancelled" ? "-" : s.status === "active" ? ">" : " " - return `[${mark}] ${s.title}` + const mark = + s.status === "done" + ? "x" + : s.status === "cancelled" + ? "-" + : s.status === "blocked" + ? "!" + : s.status === "active" + ? ">" + : " " + const suffix = s.status === "blocked" && s.note ? ` — blocked: ${s.note}` : "" + return `[${mark}] ${s.title}${suffix}` }) + const changeSummary = changeLines.length > 0 ? `\n\nChanges: ${changeLines.join("; ")}` : "" + const warnSummary = + acceptanceWarnings.length > 0 ? `\n\n⚠ ${acceptanceWarnings.join("; ")}. Verify before finalizing.` : "" return { title: `Plan: ${done}/${total} steps`, - output: `Goal: ${plan.goal}\n${lines.join("\n")}`, + output: `Goal: ${plan.goal}\n${lines.join("\n")}${changeSummary}${warnSummary}`, metadata: { plan_id: plan.plan_id, goal: plan.goal, done, total }, } }), diff --git a/packages/deepagent-code/src/tool/plan-write.txt b/packages/deepagent-code/src/tool/plan-write.txt index 76bd1ef6..36bf2ec1 100644 --- a/packages/deepagent-code/src/tool/plan-write.txt +++ b/packages/deepagent-code/src/tool/plan-write.txt @@ -1,11 +1,21 @@ Create or update your working plan for the current task. Use this BEFORE making file changes on a non-trivial task, and again whenever the situation changes (a step finished, a new requirement arrived, a test failed, or you discovered the plan was wrong). +Report as you go — do not batch. After you FINISH a step, call this tool immediately: mark that step `done` and set the next one `active`. Completing several steps and updating the plan only once at the end is not allowed; the runtime tracks how many changes you make between plan updates and will remind you to report. + The plan is shown to the user as a live checklist and is enforced by the runtime: when the runtime detects that reality no longer matches your plan (a new user instruction, a failed tool call, a failed validation, repeated no-progress, or a domain-pack change), it marks the plan stale and SOFT-BLOCKS further file edits until you call this tool again to update the plan. Reading, searching, and diagnosis are always allowed while stale — so inspect first, then update the plan, then continue. Call this tool with: - goal: one sentence describing what "done" means for this task. -- steps: an ordered list of concrete steps. Each step has a title, a status (pending | active | done | cancelled), and optionally an acceptance criterion (how you'll know the step is done) and an assigned_agent (a subagent type to delegate the step to). +- steps: an ordered list of concrete steps. Each step has a title, a status, and optionally an acceptance criterion (how you'll know the step is done), an assigned_agent (a subagent type to delegate the step to), and a note. - assumptions (optional): facts you are relying on that, if wrong, would change the plan. - active_step_id (optional): the step you are currently working on. If you omit it, the runtime uses the step whose status is "active". -Keep the plan small and honest. Mark a step "done" only when its work is actually complete (and, for high-strength modes, when its acceptance check has passed). Mark a step "cancelled" rather than deleting it, so the user sees what changed and why. +Step status is one of: +- pending — not started yet. +- active — currently being worked on (exactly the step your edits belong to). +- done — work is actually complete (and, for high-strength modes, its acceptance check has passed). The runtime attaches the latest validation result as evidence. +- cancelled — no longer needed. Mark cancelled rather than deleting, so the user sees what changed and why. +- blocked — you cannot finish this step (missing access, external dependency, ambiguous requirement). REQUIRED: set `note` explaining the blocker. A blocked step does not deadlock finishing, but it routes the run to human review so the operator sees why the plan could not be fully executed. + +Keep the plan small and honest. Never mark a step `done` to get past a gate — if you are stuck, mark it `blocked` with a note instead. + diff --git a/packages/deepagent-code/src/tool/profile.ts b/packages/deepagent-code/src/tool/profile.ts new file mode 100644 index 00000000..08025ea4 --- /dev/null +++ b/packages/deepagent-code/src/tool/profile.ts @@ -0,0 +1,323 @@ +import { Effect, Schema } from "effect" +import * as Tool from "./tool" +import * as Log from "@deepagent-code/core/util/log" +import { LSP } from "@/lsp/lsp" +import { LSPResolve } from "@/lsp/resolve" +import { PAP } from "@/profile/pap" +import { ProfileService } from "@/profile/service" +import { ProfileAdapterRegistry } from "@/profile/adapters/index" +import { RuntimeBase } from "@/runtime/base" +import { InstanceState } from "@/effect/instance-state" +import { which } from "@deepagent-code/core/util/which" +import DESCRIPTION from "./profile.txt" + +// P3A (S1-v3.5): the Agent-facing profile tool. Symbol/region-driven performance +// profiling entry point. Builds on P1A (PAP protocol), P2A (profiler adapters), +// P4A (ProfileService evidence loop), and R0 (runtime base). +// +// This tool is control-plane only. It routes through R0's fail-closed privilege gate +// + approve-once + worktree isolation (RuntimeBase.Service), then delegates the actual +// collect→parse→normalize→roofline→artifact pipeline to ProfileService.run. It never +// re-implements the pipeline inline and never bypasses the privilege gate. + +const log = Log.create({ service: "tool.profile" }) + +const TOP_N = 10 + +export const Parameters = Schema.Struct({ + target: Schema.String.annotate({ + description: "The command/test/executable to profile, e.g. `python train.py` or `./bench`.", + }), + adapter: Schema.optional(Schema.String).annotate({ + description: + "Profiler adapter id: ncu | nsys | rocprof | vtune | perf. Omit for auto-selection by env heuristics.", + }), + focus: Schema.optional(Schema.String).annotate({ + description: + "Symbol or kernel name to highlight, e.g. `train_step` or `compute_kernel`. Resolved via LSP to back-fill file:line.", + }), + domain: Schema.optional( + Schema.Literals(["gpu_kernel", "gpu_timeline", "cpu_sampling", "cpu_hotspot"]), + ).annotate({ + description: "Profiling domain. Inferred from adapter when omitted.", + }), + metrics: Schema.optional(Schema.Array(Schema.String)).annotate({ + description: + "Neutral PAP metric names to request, e.g. ['cpi','ipc']. Leave empty for adapter default set.", + }), + compare_to: Schema.optional(Schema.String).annotate({ + description: + "Absolute path to a previous PROFILE_RESULT.json. When given, the tool produces a before/after diff (improved/worsened hotspots) against the new run.", + }), +}) + +export type ProfileParams = Schema.Schema.Type + +/** + * Shared metadata shape — both the "not available" and "success" branches must + * return a structurally compatible object so TypeScript can unify the union. + */ +export interface ProfileMetadata { + adapterId: string + available: boolean + message?: string + domain?: PAP.Domain + vendor?: PAP.Vendor + hotspots?: PAP.Hotspot[] + summary?: Record + raw_report_ref?: PAP.NativeReportRef + truncated?: boolean + focus?: string | null + focusFileLine?: PAP.FileLine | null + /** Path to the written PROFILE_RESULT.json evidence artifact (P4A closed loop). */ + artifactPath?: string + /** Roofline / bottleneck classification derived from the neutral metrics. */ + roofline?: ProfileService.RooflineResult + /** Before/after diff when `compare_to` was provided. */ + diff?: ProfileService.DiffResult + /** True when the fail-closed privilege gate refused the run (missing GPU/perf/ROCm privilege). */ + privilege_blocked?: boolean +} + +/** + * Auto-select adapter id from environment heuristics. + * Explicit `adapter` param always overrides. Pure — testable without Effect. + */ +export function autoSelectAdapterId(explicitAdapter?: string): string { + if (explicitAdapter) return explicitAdapter + if (process.env["CUDA_VISIBLE_DEVICES"] !== undefined) return "ncu" + if (process.env["ROCM_HOME"] !== undefined || process.env["HIP_VISIBLE_DEVICES"] !== undefined) return "rocprof" + if (process.env["VTUNE_PROFILING_DIR"] !== undefined || which("vtune") !== null) return "vtune" + return "perf" +} + +/** Render one hotspot line. Exported for unit tests. */ +export function renderHotspot(h: PAP.Hotspot, isFocused: boolean): string { + const name = h.kernel ?? h.symbol ?? "?" + const loc = h.file_line ? `${h.file_line.file}:${h.file_line.line}` : "" + const metricParts: string[] = [`self: ${h.self_pct.toFixed(1)}%`] + + const cpi = h.metrics["cpi"] + if (cpi && PAP.isPresent(cpi)) metricParts.push(` cpi: ${Number(cpi.value).toFixed(1)}`) + const ipc = h.metrics["ipc"] + if (ipc && PAP.isPresent(ipc)) metricParts.push(` ipc: ${Number(ipc.value).toFixed(2)}`) + + const focusMarker = isFocused ? "* " : " " + const nameCol = name.padEnd(20) + const locCol = loc ? `${loc.padEnd(30)}` : "".padEnd(30) + return `${focusMarker}${nameCol} ${locCol} ${metricParts.join("")}` +} + +/** Render summary key=value pairs. Exported for unit tests. */ +export function renderSummary(summary: Record): string { + const parts: string[] = [] + for (const [k, v] of Object.entries(summary)) { + if (PAP.isPresent(v)) { + const val = typeof v.value === "boolean" ? String(v.value) : Number(v.value).toFixed(2) + parts.push(`${k}=${val}`) + } + } + return parts.join(" ") +} + +/** + * Build the formatted profile output from a NormalizedProfile. Exported for tests. + * focus/focusFileLine control highlighting; adapterId/target go into the header. + */ +export function buildProfileOutput(params: { + adapterId: string + target: string + normalized: PAP.NormalizedProfile + focus?: string + focusFileLine?: PAP.FileLine | null + /** Absolute path to the written PROFILE_RESULT.json evidence artifact. */ + artifactPath?: string +}): string { + const { adapterId, target, normalized, focus, focusFileLine, artifactPath } = params + const sorted = [...normalized.hotspots].sort((a, b) => b.self_pct - a.self_pct).slice(0, TOP_N) + + const lines: string[] = [] + lines.push(`profile: ${adapterId} ${normalized.domain} on \`${target}\``) + if (focus) { + const loc = focusFileLine ? `${focusFileLine.file}:${focusFileLine.line}` : "(symbol not found via LSP)" + lines.push(`focus: ${focus} (${loc})`) + } + lines.push("top hotspots:") + for (const h of sorted) { + const isFocused = !!(focus && (h.kernel === focus || h.symbol === focus)) + lines.push(renderHotspot(h, isFocused)) + } + const summaryStr = renderSummary(normalized.summary) + if (summaryStr) lines.push(`summary: ${summaryStr}`) + // Evidence lives in the written PROFILE_RESULT.json artifact (evidence_kind:"profile"). + lines.push( + artifactPath + ? `evidence: PROFILE_RESULT.json written to ${artifactPath} (full report + roofline; evidence_kind:"profile")` + : `evidence: full report in the tool result metadata (roofline + hotspots + summary)`, + ) + return lines.join("\n") +} + +export const ProfileTool = Tool.define( + "profile", + Effect.gen(function* () { + const lsp = yield* LSP.Service + // R0 runtime base: fail-closed privilege gate + approve-once + worktree isolation. + // Shared across debug/profile (one approval-state per session). + const base = yield* RuntimeBase.Service + + return { + description: DESCRIPTION, + parameters: Parameters, + execute: (args: ProfileParams, ctx: Tool.Context): Effect.Effect => + Effect.gen(function* () { + const instance = yield* InstanceState.context + const adapterId = autoSelectAdapterId(args.adapter) + + log.info("profile tool invoked", { adapterId, target: args.target, focus: args.focus }) + + // Build adapter registry with the default binary probe. + const registry = ProfileAdapterRegistry.make() + const resolution = registry.resolveById(adapterId) + if (!resolution.available) { + const meta: ProfileMetadata = { + adapterId, + available: false, + message: resolution.message, + } + return { + title: `profile: ${adapterId} not available`, + output: resolution.message, + metadata: meta, + } + } + + const adapter = resolution.adapter + const sessionKey = `profile:${ctx.sessionID}:${adapterId}` + + // Run the whole profiling operation inside an isolated worktree (R0 withIsolation): + // the profiled program executes there and side effects are contained + auto-cleaned. + // The evidence artifact is written to the MAIN tree (instance.directory) so it + // survives worktree teardown and stays referenceable as PROFILE_RESULT.json. + return yield* base + .withIsolation({ name: `profile-${adapterId}` }, (workdir) => + Effect.gen(function* () { + // R0 gate: privilege fail-closed FIRST, then approve-once-per-session. + // Adapter-declared privileges (gpu_performance_counter / perf_event_paranoid / + // rocm_profiling) are enforced here — no silent degradation, no elevation. + yield* base.gate({ + sessionKey, + privileges: adapter.privileges, + requestApproval: () => + ctx.ask({ + permission: "execute", + patterns: [args.target], + always: [], + metadata: { adapter: adapterId, target: args.target, isolated: workdir }, + }), + }) + + const target: PAP.ProfileTarget = { + command: args.target, + cwd: workdir, + focus: args.focus, + domain: args.domain as PAP.Domain | undefined, + metrics: args.metrics, + } + + // Delegate the full collect→parse→normalize→roofline→artifact(+diff) + // pipeline to ProfileService.run — the single writer of PROFILE_RESULT.json. + const runResult = yield* Effect.tryPromise({ + try: () => + ProfileService.run(adapter, target, { + artifactDir: instance.directory, + ...(args.compare_to ? { compare_to: args.compare_to } : {}), + }), + catch: (e) => new Error(`profile run failed: ${String(e)}`), + }) + + const normalized = runResult.profile + + // Focus: resolve symbol name → file:line via LSP and back-fill matching hotspot. + let focusFileLine: PAP.FileLine | null = null + if (args.focus) { + const resolved = yield* LSPResolve.resolveSymbol({ lsp, symbol: args.focus }).pipe( + Effect.catch(() => Effect.succeed({ type: "not_found" as const })), + ) + if (resolved.type === "resolved") { + focusFileLine = PAP.fileLineFromCandidate(resolved.candidate) + for (const h of normalized.hotspots) { + const name = h.kernel ?? h.symbol + if (name === args.focus) { + ;(h as any).file_line = focusFileLine + } + } + } + } + + const roofline = ProfileService.roofline(normalized) + + const fullOutput = buildProfileOutput({ + adapterId, + target: args.target, + normalized, + focus: args.focus, + focusFileLine, + artifactPath: runResult.artifactPath, + }) + const budgeted = RuntimeBase.applyOutputBudget(fullOutput, adapter.defaultBudget) + + const topHotspots = [...normalized.hotspots].sort((a, b) => b.self_pct - a.self_pct).slice(0, TOP_N) + + const meta: ProfileMetadata = { + adapterId, + available: true, + domain: normalized.domain, + vendor: normalized.vendor, + hotspots: topHotspots, + summary: normalized.summary, + raw_report_ref: normalized.raw_report_ref, + truncated: budgeted.truncated, + focus: args.focus ?? null, + focusFileLine, + artifactPath: runResult.artifactPath, + roofline, + ...(runResult.diff ? { diff: runResult.diff } : {}), + } + + return { + title: `profile: ${adapterId} on ${args.target}`, + output: budgeted.inline, + metadata: meta, + } + }), + ) + .pipe( + // Fail-closed privilege gate + any collect/parse failure → graceful, + // model-readable error (never a Die). UnsatisfiedPrivilegeError is flagged + // so the caller can distinguish "missing GPU/perf/ROCm privilege" from a crash. + Effect.catch((err) => + Effect.succeed( + err instanceof RuntimeBase.UnsatisfiedPrivilegeError + ? { + title: `profile: ${adapterId} privilege unavailable`, + output: err.message, + metadata: { + adapterId, + available: false, + privilege_blocked: true, + message: err.message, + } as ProfileMetadata, + } + : { + title: `profile: ${adapterId} failed`, + output: err instanceof Error ? err.message : String(err), + metadata: { adapterId, available: false, message: String(err) } as ProfileMetadata, + }, + ), + ), + ) + }), + } + }), +) diff --git a/packages/deepagent-code/src/tool/profile.txt b/packages/deepagent-code/src/tool/profile.txt new file mode 100644 index 00000000..3bd0a2aa --- /dev/null +++ b/packages/deepagent-code/src/tool/profile.txt @@ -0,0 +1,42 @@ +Profile a running program and surface performance hotspots — symbol-level CPU functions or GPU kernels — with vendor-neutral metrics (PAP vocabulary). + +WHEN TO USE profile vs code_intel: +- code_intel: STATIC analysis — symbol definitions, references, call graphs, diagnostics. No execution. Use when you need to understand code structure or find where a function is defined. +- profile: RUNTIME measurement — which functions/kernels consume the most CPU/GPU time. Requires executing the program. Use when you need to find performance bottlenecks or measure hotspot self-time. + +ADAPTER AUTO-SELECTION (override with the adapter param): +- CUDA_VISIBLE_DEVICES set in env → ncu (NVIDIA Nsight Compute, GPU kernel-level metrics) +- ROCM_HOME or HIP_VISIBLE_DEVICES set → rocprof (AMD ROCprofiler-SDK) +- VTUNE_PROFILING_DIR set or vtune found on PATH → vtune (Intel VTune, CPU µarch analysis) +- otherwise → perf (Linux perf sampling — available anywhere perf is installed) + +Available adapter ids: ncu, nsys, rocprof, vtune, perf + +VENDOR-NEUTRAL METRICS (PAP vocabulary): +All profiler output is mapped to a shared vocabulary so metrics are comparable across hardware: +- GPU kernel level: compute_throughput_pct, memory_throughput_pct, occupancy_pct, duration_ns +- CPU level: self_pct, cpi (cycles/instruction), ipc (instructions/cycle), cache_miss_rate, branch_misprediction_pct +Metrics the profiler cannot produce on the current hardware are reported as null + reason — never fabricated. + +FOCUS PARAMETER: +Provide focus: to highlight a specific function or GPU kernel in the output. +- The symbol is resolved via LSP (same as code_intel) to back-fill a file:line coordinate. +- The matching hotspot is starred (*) in the top-hotspots table. +- Useful when you already know which function is slow and want to see its metrics clearly. + +OUTPUT FORMAT: + profile: perf cpu_sampling on `python train.py` + focus: train_step (src/model.py:42) + top hotspots: + * train_step src/model.py:42 self: 38.0% cpi: 2.1 + matmul torch/... self: 22.0% cpi: 1.8 + summary: ipc=0.48 cache_miss_rate=0.12 + evidence: PROFILE_RESULT.json written to (full report + roofline; evidence_kind:"profile") + +Returns up to 10 hotspots by self_pct. The full result — normalized profile, roofline classification, and (when compare_to is given) a before/after diff — is written to a PROFILE_RESULT.json evidence artifact whose path is reported in the output and in the tool result metadata (`artifactPath`). The bulky native report (ncu-rep / nsys-rep / rocpd / perf.data) stays on disk as a `raw_report_ref`, never inlined into context. + +BEFORE/AFTER DIFF: +Pass compare_to: to get a structured diff (which hotspots improved/worsened). Diffs across different domains (e.g. gpu_kernel vs cpu_sampling) are reported as not_comparable rather than fabricated. + +APPROVAL: +Profiling executes the target program. Execution approval is requested once per session; in-session sub-operations (e.g. repeated profiles of the same target) reuse the grant without re-prompting. Adapters requiring hardware privileges (GPU perf counters, perf_event_paranoid, ROCm access) will report a clear error if the environment does not satisfy the requirement — the tool never silently degrades or attempts privilege escalation. diff --git a/packages/deepagent-code/src/tool/registry.ts b/packages/deepagent-code/src/tool/registry.ts index 3baafaf3..f912ae22 100644 --- a/packages/deepagent-code/src/tool/registry.ts +++ b/packages/deepagent-code/src/tool/registry.ts @@ -27,6 +27,13 @@ import { WebSearchTool } from "./websearch" import * as Log from "@deepagent-code/core/util/log" import { LspTool } from "./lsp" import { CodeIntelTool } from "./code_intel" +import { ProfileTool } from "./profile" +import { DebugTool } from "./debug" +import { DebugService } from "@/debug/service" +import { RuntimeBase } from "@/runtime/base" +import { Worktree } from "@/worktree" +import { InstanceStore } from "@/project/instance-store" +import { InstanceBootstrap } from "@/project/bootstrap-service" import * as Truncate from "./truncate" import { ApplyPatchTool } from "./apply_patch" import { Glob } from "@deepagent-code/core/util/glob" @@ -108,6 +115,8 @@ export const layer: Layer.Layer< | Truncate.Service | RuntimeFlags.Service | Database.Service + | DebugService.Service + | RuntimeBase.Service > = Layer.effect( Service, Effect.gen(function* () { @@ -135,6 +144,8 @@ export const layer: Layer.Layer< const patchtool = yield* ApplyPatchTool const skilltool = yield* SkillTool const codeintel = yield* CodeIntelTool + const profiletool = yield* ProfileTool + const debugtool = yield* DebugTool const agent = yield* Agent.Service const state = yield* InstanceState.make( @@ -253,6 +264,8 @@ export const layer: Layer.Layer< question: Tool.init(question), lsp: Tool.init(lsptool), code_intel: Tool.init(codeintel), + profile: Tool.init(profiletool), + debug: Tool.init(debugtool), plan: Tool.init(plan), planwrite: Tool.init(planwrite), }) @@ -277,6 +290,8 @@ export const layer: Layer.Layer< tool.planwrite, ...(flags.experimentalLspTool ? [tool.lsp] : []), ...(flags.codeIntelTool ? [tool.code_intel] : []), + ...(flags.profileTool ? [tool.profile] : []), + ...(flags.debugTool ? [tool.debug] : []), ...(flags.experimentalPlanMode && flags.client === "cli" ? [tool.plan] : []), ], task: tool.task, @@ -367,30 +382,62 @@ export const layer: Layer.Layer< }), ) +/** + * InstanceStore backed by a NO-OP InstanceBootstrap — used only to satisfy the + * Worktree dependency for debug/profile `withIsolation`. The real InstanceBootstrap + * (FFF warm + eager config.get + service init) is provided by the app-runtime at the + * top level; wiring it here would eagerly freeze config.directories() at instance + * creation and race tools that read files written after the instance starts. + */ +const noopBootstrapInstanceStore = InstanceStore.defaultLayer.pipe( + Layer.provide(Layer.succeed(InstanceBootstrap.Service, InstanceBootstrap.Service.of({ run: Effect.void }))), +) + export const defaultLayer = Layer.suspend(() => - layer - .pipe( - Layer.provide(Config.defaultLayer), - Layer.provide(Plugin.defaultLayer), - Layer.provide(Question.defaultLayer), - Layer.provide(Todo.defaultLayer), - Layer.provide(Skill.defaultLayer), - Layer.provide(Agent.defaultLayer), - Layer.provide(Session.defaultLayer), - Layer.provide(BackgroundJob.defaultLayer), - Layer.provide(Provider.defaultLayer), - Layer.provide(Reference.defaultLayer), - Layer.provide(LSP.defaultLayer), - Layer.provide(Instruction.defaultLayer), - Layer.provide(FSUtil.defaultLayer), - Layer.provide(EventV2Bridge.defaultLayer), - Layer.provide(FetchHttpClient.layer), - Layer.provide(Format.defaultLayer), - Layer.provide(CrossSpawnSpawner.defaultLayer), - Layer.provide(Search.defaultLayer), - Layer.provide(Truncate.defaultLayer), - ) - .pipe(Layer.provide(Database.defaultLayer), Layer.provide(RuntimeFlags.defaultLayer)), + layer.pipe( + // Ordered dependency chain (must stay explicit so instances are SHARED): + // DebugService.layer needs RuntimeBase.Service + EventV2Bridge.Service; RuntimeBase.layer + // needs Worktree.Service. Providing them outermost-last means the EventV2Bridge in the + // merged block below is the SAME instance DebugService publishes debug.* events onto, and + // RuntimeBase is shared between the profile tool's gate and DebugService's gate. + Layer.provide(DebugService.layer), + Layer.provide(RuntimeBase.layer), + // Worktree here is used only by debug/profile withIsolation (create/safeRemove). It must + // NOT pull in InstanceLayer's real InstanceBootstrap: that boostrap eagerly runs config.get() + // (+ FFF warm) at instance creation, which would freeze config.directories() before a tool + // (e.g. skill scanning) sees files written after instance start. A no-op bootstrap satisfies + // the InstanceStore tag without that eager side effect. In production the app-runtime provides + // the real InstanceLayer at the top level for actual instance init; this sealed one only backs + // worktree create/remove. + Layer.provide(Worktree.appLayer.pipe(Layer.provide(noopBootstrapInstanceStore))), + // All remaining requirements are self-contained default layers with no ordering needs; + // merge them into one provide (Layer.suspend's pipe caps at 20 chained args). + Layer.provide( + Layer.mergeAll( + Config.defaultLayer, + Plugin.defaultLayer, + Question.defaultLayer, + Todo.defaultLayer, + Skill.defaultLayer, + Agent.defaultLayer, + Session.defaultLayer, + BackgroundJob.defaultLayer, + Provider.defaultLayer, + Reference.defaultLayer, + LSP.defaultLayer, + Instruction.defaultLayer, + FSUtil.defaultLayer, + EventV2Bridge.defaultLayer, + FetchHttpClient.layer, + Format.defaultLayer, + CrossSpawnSpawner.defaultLayer, + Search.defaultLayer, + Truncate.defaultLayer, + Database.defaultLayer, + RuntimeFlags.defaultLayer, + ), + ), + ), ) function isZodType(value: unknown): value is z.ZodType { diff --git a/packages/deepagent-code/test/deepagent/dap-client-initialize-launch-stop.test.ts b/packages/deepagent-code/test/deepagent/dap-client-initialize-launch-stop.test.ts new file mode 100644 index 00000000..86a2e671 --- /dev/null +++ b/packages/deepagent-code/test/deepagent/dap-client-initialize-launch-stop.test.ts @@ -0,0 +1,71 @@ +import { describe, expect } from "bun:test" +import path from "path" +import { Effect } from "effect" +import { DapClient } from "@/debug/client" +import type { AdapterSpec } from "@/debug/types" +import { TestInstance } from "../fixture/fixture" +import { it } from "../lib/effect" + +// D1 (S1-v3.5): DAP client — initialize handshake + launch + receive a `stopped` +// event. Drives the fake adapter directly (no DebugService), proving the client +// speaks DAP framing over stdio and routes events. + +const fakeAdapterPath = path.join(__dirname, "../fixture/debug/fake-dap-adapter.js") + +const fakeSpec = (): AdapterSpec => ({ + id: "fake", + languages: ["python"], + command: process.execPath, + args: [fakeAdapterPath], + privileges: [], + transport: "stdio", +}) + +describe("DAP client: initialize + launch + stop", () => { + it.instance("initializes, launches, and receives a stopped event", () => + Effect.gen(function* () { + const dir = (yield* TestInstance).directory + const client = yield* Effect.promise(() => DapClient.create({ spec: fakeSpec(), cwd: dir })) + + // initialize handshake captured adapter capabilities. + expect(client.adapterID).toBe("fake") + expect(client.capabilities.supportsConfigurationDoneRequest).toBe(true) + + // Subscribe BEFORE launch so we catch the stopped event after configurationDone. + const stopped = new Promise((resolve) => { + const off = client.onEvent((event) => { + if (event.event === "stopped") { + off() + resolve(event.body) + } + }) + }) + + yield* Effect.promise(() => client.launch({ program: "/repro/main.py" })) + yield* Effect.promise(() => client.configurationDone()) + + const body = yield* Effect.promise(() => + Promise.race([ + stopped, + new Promise((_, reject) => setTimeout(() => reject(new Error("no stopped event")), 5000)), + ]), + ) + expect(body.reason).toBe("breakpoint") + expect(body.threadId).toBe(1) + + yield* Effect.promise(() => client.shutdown()) + }), + ) + + it.instance("rejects a non-stdio transport (no silent downgrade)", () => + Effect.gen(function* () { + const exit = yield* Effect.promise(() => + DapClient.create({ spec: { ...fakeSpec(), transport: "socket" }, cwd: "." }).then( + () => "ok" as const, + (e) => e as Error, + ), + ) + expect(exit).not.toBe("ok") + }), + ) +}) diff --git a/packages/deepagent-code/test/deepagent/dap-multi-session-isolation.test.ts b/packages/deepagent-code/test/deepagent/dap-multi-session-isolation.test.ts new file mode 100644 index 00000000..3784e5c6 --- /dev/null +++ b/packages/deepagent-code/test/deepagent/dap-multi-session-isolation.test.ts @@ -0,0 +1,112 @@ +import { afterEach, describe, expect } from "bun:test" +import path from "path" +import { Effect, Layer } from "effect" +import { FSUtil } from "@deepagent-code/core/fs-util" +import { CrossSpawnSpawner } from "@deepagent-code/core/cross-spawn-spawner" +import { EventV2Bridge } from "@/event-v2-bridge" +import { RuntimeBase } from "@/runtime/base" +import { DebugService } from "@/debug/service" +import type { AdapterSpec } from "@/debug/types" +import { Git } from "@/git" +import { Worktree } from "@/worktree" +import { disposeAllInstances } from "../fixture/fixture" +import { testEffect } from "../lib/effect" + +// D1 (S1-v3.5): two concurrent debug sessions, each its own adapter process, with +// independent serializable state. Stepping one must not perturb the other. + +const fakeAdapterPath = path.join(__dirname, "../fixture/debug/fake-dap-adapter.js") + +const fakeSpec = (): AdapterSpec => ({ + id: "fake", + languages: ["python"], + command: process.execPath, + args: [fakeAdapterPath], + privileges: [], + transport: "stdio", +}) + +const debugLayer = Layer.mergeAll( + DebugService.layer.pipe( + Layer.provide(RuntimeBase.testLayer(RuntimeBase.allowAllProbe).pipe(Layer.provide(Worktree.defaultLayer))), + Layer.provide(EventV2Bridge.defaultLayer), + ), + Worktree.defaultLayer, + FSUtil.defaultLayer, + CrossSpawnSpawner.defaultLayer, + Git.defaultLayer, +) + +const waitForStatus = (debug: DebugService.Interface, sessionId: string, status: string) => + Effect.gen(function* () { + for (let i = 0; i < 100; i++) { + const s = yield* debug.get(sessionId) + if (s?.status === status) return s + yield* Effect.sleep("20 millis") + } + return yield* Effect.fail(new Error(`session ${sessionId} never reached "${status}"`)) + }) + +describe("DAP multi-session isolation", () => { + afterEach(() => disposeAllInstances()) + + const it = testEffect(debugLayer) + + it.instance( + "two concurrent sessions have independent adapter processes + state", + () => + Effect.gen(function* () { + const debug = yield* DebugService.Service + + yield* debug.start({ spec: fakeSpec(), sessionId: "a", launch: { program: "/repro/a.py" } }) + yield* debug.start({ spec: fakeSpec(), sessionId: "b", launch: { program: "/repro/b.py" } }) + + const a0 = yield* waitForStatus(debug, "a", "stopped") + const b0 = yield* waitForStatus(debug, "b", "stopped") + expect(a0.stoppedReason).toBe("breakpoint") + expect(b0.stoppedReason).toBe("breakpoint") + + // list() reports both, independently. + const all = yield* debug.list() + expect(all.map((s) => s.id).sort()).toEqual(["a", "b"]) + + // Different breakpoints on each session — must not bleed across. + yield* debug.setBreakpoints({ sessionId: "a", source: "/repro/a.py", breakpoints: [{ line: 1 }] }) + yield* debug.setBreakpoints({ sessionId: "b", source: "/repro/b.py", breakpoints: [{ line: 99 }] }) + const a1 = yield* debug.get("a") + const b1 = yield* debug.get("b") + expect(a1?.breakpoints[0].lines).toEqual([1]) + expect(b1?.breakpoints[0].lines).toEqual([99]) + + // Continue A to completion; B must remain stopped. + yield* debug.continue("a") + yield* waitForStatus(debug, "a", "terminated").pipe( + Effect.catch(() => waitForStatus(debug, "a", "exited")), + ) + const bStill = yield* debug.get("b") + expect(bStill?.status).toBe("stopped") + + // Terminate A; B still present and independent. + yield* debug.terminate("a") + const afterTerminate = yield* debug.list() + expect(afterTerminate.map((s) => s.id)).toEqual(["b"]) + + yield* debug.terminate("b") + expect((yield* debug.list()).length).toBe(0) + }), + { git: true }, + ) + + it.instance( + "starting a session id that already exists is rejected", + () => + Effect.gen(function* () { + const debug = yield* DebugService.Service + yield* debug.start({ spec: fakeSpec(), sessionId: "dup", launch: {} }) + const exit = yield* debug.start({ spec: fakeSpec(), sessionId: "dup", launch: {} }).pipe(Effect.exit) + expect(exit._tag).toBe("Failure") + yield* debug.terminate("dup") + }), + { git: true }, + ) +}) diff --git a/packages/deepagent-code/test/deepagent/dap-session-state-machine.test.ts b/packages/deepagent-code/test/deepagent/dap-session-state-machine.test.ts new file mode 100644 index 00000000..139fcf86 --- /dev/null +++ b/packages/deepagent-code/test/deepagent/dap-session-state-machine.test.ts @@ -0,0 +1,153 @@ +import { afterEach, describe, expect } from "bun:test" +import path from "path" +import { Effect, Layer } from "effect" +import { FSUtil } from "@deepagent-code/core/fs-util" +import { CrossSpawnSpawner } from "@deepagent-code/core/cross-spawn-spawner" +import { EventV2Bridge } from "@/event-v2-bridge" +import { RuntimeBase } from "@/runtime/base" +import { DebugService } from "@/debug/service" +import type { AdapterSpec } from "@/debug/types" +import { Git } from "@/git" +import { Worktree } from "@/worktree" +import { disposeAllInstances } from "../fixture/fixture" +import { testEffect } from "../lib/effect" + +// D1 (S1-v3.5): DebugService session state machine. Drives a full session through +// launch → breakpoint → stop → step → continue → terminate and asserts the +// serializable state transitions are correct. + +const fakeAdapterPath = path.join(__dirname, "../fixture/debug/fake-dap-adapter.js") + +const fakeSpec = (): AdapterSpec => ({ + id: "fake", + languages: ["python"], + command: process.execPath, + args: [fakeAdapterPath], + privileges: [], + transport: "stdio", +}) + +const debugLayer = (probe: RuntimeBase.PrivilegeProbe = RuntimeBase.allowAllProbe) => + Layer.mergeAll( + DebugService.layer.pipe( + Layer.provide(RuntimeBase.testLayer(probe).pipe(Layer.provide(Worktree.defaultLayer))), + Layer.provide(EventV2Bridge.defaultLayer), + ), + Worktree.defaultLayer, + FSUtil.defaultLayer, + CrossSpawnSpawner.defaultLayer, + Git.defaultLayer, + ) + +// Wait until a session reaches an expected status (events arrive async). +const waitForStatus = (debug: DebugService.Interface, sessionId: string, status: string) => + Effect.gen(function* () { + for (let i = 0; i < 100; i++) { + const s = yield* debug.get(sessionId) + if (s?.status === status) return s + yield* Effect.sleep("20 millis") + } + return yield* Effect.fail(new Error(`session never reached status "${status}"`)) + }) + +describe("DAP session state machine", () => { + afterEach(() => disposeAllInstances()) + + const it = testEffect(debugLayer()) + + it.instance( + "drives launch → breakpoint → stop → step → continue → terminate", + () => + Effect.gen(function* () { + const debug = yield* DebugService.Service + const sessionId = "sm-1" + + const started = yield* debug.start({ + spec: fakeSpec(), + sessionId, + launch: { program: "/repro/main.py" }, + }) + expect(started.id).toBe(sessionId) + expect(started.adapterId).toBe("fake") + // After launch+configurationDone the fake adapter hits a breakpoint. + const stopped = yield* waitForStatus(debug, sessionId, "stopped") + expect(stopped.status).toBe("stopped") + expect(stopped.stoppedReason).toBe("breakpoint") + expect(stopped.threadId).toBe(1) + + // Set a breakpoint (recorded in serializable state). + const withBp = yield* debug.setBreakpoints({ + sessionId, + source: "/repro/main.py", + breakpoints: [{ line: 10 }, { line: 20 }], + }) + expect(withBp.breakpoints.length).toBe(1) + expect(withBp.breakpoints[0].source).toBe("/repro/main.py") + expect(withBp.breakpoints[0].lines).toEqual([10, 20]) + + // Inspect stack / scopes / variables / eval — all delegated to adapter. + const frames = yield* debug.stackTrace(sessionId) + expect(frames.length).toBe(2) + expect(frames[0].name).toBe("main") + const scopes = yield* debug.scopes(sessionId, frames[0].id) + expect(scopes[0].name).toBe("Locals") + const vars = yield* debug.variables(sessionId, scopes[0].variablesReference) + expect(vars.find((v: any) => v.name === "x")?.value).toBe("42") + const evaln = yield* debug.evaluate({ sessionId, expression: "x + 1", frameId: frames[0].id }) + expect(evaln.result).toContain("x + 1") + + // Step → fake adapter pauses again with reason "step". + yield* debug.step(sessionId, "next") + const stepped = yield* waitForStatus(debug, sessionId, "stopped") + expect(stepped.stoppedReason).toBe("step") + + // Continue → program runs to completion → terminated/exited. + yield* debug.continue(sessionId) + const ended = yield* waitForStatus(debug, sessionId, "terminated").pipe( + Effect.catch(() => waitForStatus(debug, sessionId, "exited")), + ) + expect(["terminated", "exited"]).toContain(ended.status) + + // Explicit terminate removes the session. + yield* debug.terminate(sessionId) + const gone = yield* debug.get(sessionId) + expect(gone).toBeUndefined() + }), + { git: true }, + ) + + it.instance( + "step before a stop fails (state machine guards thread)", + () => + Effect.gen(function* () { + const debug = yield* DebugService.Service + // No session at all → stepping fails. + const exit = yield* debug.step("nope", "next").pipe(Effect.exit) + expect(exit._tag).toBe("Failure") + }), + { git: true }, + ) + + describe("privilege gate fail-closed at start", () => { + const denyIt = testEffect(debugLayer(RuntimeBase.denyAllProbe)) + denyIt.instance( + "refuses to start when a required privilege is unavailable", + () => + Effect.gen(function* () { + const debug = yield* DebugService.Service + const exit = yield* debug + .start({ + spec: { ...fakeSpec(), privileges: [{ kind: "ptrace", reason: "lldb needs ptrace" }] }, + sessionId: "priv-1", + launch: {}, + }) + .pipe(Effect.exit) + expect(exit._tag).toBe("Failure") + // Session must not have been created. + const s = yield* debug.get("priv-1") + expect(s).toBeUndefined() + }), + { git: true }, + ) + }) +}) diff --git a/packages/deepagent-code/test/deepagent/debug-adapter-base-set.test.ts b/packages/deepagent-code/test/deepagent/debug-adapter-base-set.test.ts new file mode 100644 index 00000000..abb7c037 --- /dev/null +++ b/packages/deepagent-code/test/deepagent/debug-adapter-base-set.test.ts @@ -0,0 +1,98 @@ +import { describe, expect, it } from "bun:test" +import { DebugAdapter } from "@/debug/adapter" +import type { AdapterSpec } from "@/debug/types" + +// D2 (S1-v3.5): the base set (debugpy / delve / lldb) is discoverable and each +// produces a valid AdapterSpec. We mock the existence probe (mirroring how R0 +// injects its privilege probe) so the test never depends on a real binary. + +// A probe reporting every base-set binary as installed. +const allInstalled = DebugAdapter.installedProbe([ + "python3", + "python", + "dlv", + "lldb-dap", + "lldb-vscode", +]) + +const isValidSpec = (spec: AdapterSpec) => { + expect(typeof spec.id).toBe("string") + expect(spec.id.length).toBeGreaterThan(0) + expect(Array.isArray(spec.languages)).toBe(true) + expect(spec.languages.length).toBeGreaterThan(0) + expect(typeof spec.command).toBe("string") + expect(spec.command.length).toBeGreaterThan(0) + expect(Array.isArray(spec.args)).toBe(true) + expect(Array.isArray(spec.privileges)).toBe(true) + expect(spec.transport).toBe("stdio") +} + +describe("D2 debug-adapter base set", () => { + it("registers debugpy / delve / lldb out of the box", () => { + const registry = DebugAdapter.make(allInstalled) + expect(registry.has("debugpy")).toBe(true) + expect(registry.has("delve")).toBe(true) + expect(registry.has("lldb")).toBe(true) + // GDB is a domain-pack adapter, not part of the base set. + expect(registry.has("gdb")).toBe(false) + }) + + it("resolves a base adapter by id into a valid AdapterSpec", () => { + const registry = DebugAdapter.make(allInstalled) + for (const id of ["debugpy", "delve", "lldb"]) { + const res = registry.resolveById(id) + expect(res.available).toBe(true) + if (res.available) { + expect(res.spec.id).toBe(id) + isValidSpec(res.spec) + } + } + }) + + it("resolves an adapter by language", () => { + const registry = DebugAdapter.make(allInstalled) + const py = registry.resolve("python") + expect(py.available).toBe(true) + if (py.available) expect(py.spec.id).toBe("debugpy") + + const go = registry.resolve("go") + expect(go.available).toBe(true) + if (go.available) expect(go.spec.id).toBe("delve") + + // lldb serves several systems languages; lookup is case-insensitive. + for (const lang of ["c", "cpp", "rust", "swift", "CPP"]) { + const res = registry.resolve(lang) + expect(res.available).toBe(true) + if (res.available) expect(res.spec.id).toBe("lldb") + } + }) + + it("declares the ptrace privilege on lldb (handed to R0's gate)", () => { + const registry = DebugAdapter.make(allInstalled) + const res = registry.resolveById("lldb") + expect(res.available).toBe(true) + if (res.available) { + expect(res.spec.privileges.some((p) => p.kind === "ptrace")).toBe(true) + } + // Pure-Python debugging needs no OS privilege. + const py = registry.resolveById("debugpy") + if (py.available) expect(py.spec.privileges.length).toBe(0) + }) + + it("builds debugpy as `python -m debugpy.adapter`", () => { + const registry = DebugAdapter.make(allInstalled) + const res = registry.resolveById("debugpy") + expect(res.available).toBe(true) + if (res.available) { + expect(res.spec.command).toContain("python") + expect(res.spec.args).toEqual(["-m", "debugpy.adapter"]) + } + }) + + it("builds delve as `dlv dap`", () => { + const registry = DebugAdapter.make(allInstalled) + const res = registry.resolveById("delve") + expect(res.available).toBe(true) + if (res.available) expect(res.spec.args).toEqual(["dap"]) + }) +}) diff --git a/packages/deepagent-code/test/deepagent/debug-adapter-domain-pack-gdb.test.ts b/packages/deepagent-code/test/deepagent/debug-adapter-domain-pack-gdb.test.ts new file mode 100644 index 00000000..85870f3e --- /dev/null +++ b/packages/deepagent-code/test/deepagent/debug-adapter-domain-pack-gdb.test.ts @@ -0,0 +1,52 @@ +import { describe, expect, it } from "bun:test" +import { DebugAdapter } from "@/debug/adapter" + +// D2 (S1-v3.5): GDB is contributed by the native/systems-programming domain +// pack — it must be available only when the pack has registered it, and absent +// otherwise. Core (the base set) stays clean. Probe is injected so the binary is +// treated as installed without touching the real system. + +const installed = DebugAdapter.installedProbe(["gdb", "python3", "dlv", "lldb-dap"]) + +describe("D2 debug-adapter domain-pack GDB", () => { + it("does not expose GDB before the domain pack registers it", () => { + const registry = DebugAdapter.make(installed) + expect(registry.has("gdb")).toBe(false) + const res = registry.resolveById("gdb") + expect(res.available).toBe(false) + if (!res.available) expect(res.message).toContain("No debug adapter registered") + }) + + it("exposes GDB once the domain-pack hook registers it", () => { + const registry = DebugAdapter.make(installed) + DebugAdapter.registerGdb(registry) + expect(registry.has("gdb")).toBe(true) + + const res = registry.resolveById("gdb") + expect(res.available).toBe(true) + if (res.available) { + expect(res.spec.id).toBe("gdb") + expect(res.spec.command).toContain("gdb") + expect(res.spec.args).toEqual(["--interpreter=dap"]) + // GDB attaches via ptrace → declares the privilege for R0's gate. + expect(res.spec.privileges.some((p) => p.kind === "ptrace")).toBe(true) + } + }) + + it("supports the generic register() hook (a pack can add any adapter)", () => { + const registry = DebugAdapter.make(installed) + registry.register(DebugAdapter.GDB) + expect(registry.has("gdb")).toBe(true) + // C/C++ now resolves to lldb (base, registered first) and gdb is also listed. + expect(registry.listForLanguage("cpp").map((a) => a.id)).toContain("gdb") + }) + + it("hides GDB again when the pack deactivates (unregister)", () => { + const registry = DebugAdapter.make(installed) + DebugAdapter.registerGdb(registry) + expect(registry.has("gdb")).toBe(true) + registry.unregister("gdb") + expect(registry.has("gdb")).toBe(false) + expect(registry.resolveById("gdb").available).toBe(false) + }) +}) diff --git a/packages/deepagent-code/test/deepagent/debug-adapter-missing-graceful.test.ts b/packages/deepagent-code/test/deepagent/debug-adapter-missing-graceful.test.ts new file mode 100644 index 00000000..801433fe --- /dev/null +++ b/packages/deepagent-code/test/deepagent/debug-adapter-missing-graceful.test.ts @@ -0,0 +1,56 @@ +import { describe, expect, it } from "bun:test" +import { DebugAdapter } from "@/debug/adapter" + +// D2 (S1-v3.5): when an adapter binary is missing, the registry reports a clear +// "please install X" message and NEVER throws Die — mirroring how lsp/server.ts +// returns undefined and logs "please install …" for a missing server. + +describe("D2 debug-adapter graceful missing", () => { + it("reports a clear install message instead of throwing when a binary is absent", () => { + const registry = DebugAdapter.make(DebugAdapter.missingProbe) + // The adapter is still registered (declared), it's just not installed. + expect(registry.has("debugpy")).toBe(true) + + // resolveById must not throw — it returns a graceful result. + let res: ReturnType | undefined + expect(() => { + res = registry.resolveById("debugpy") + }).not.toThrow() + expect(res!.available).toBe(false) + if (res && !res.available) { + expect(res.adapterId).toBe("debugpy") + expect(res.message).toContain("not available") + expect(res.message.toLowerCase()).toContain("install") + } + }) + + it("resolves-by-language gracefully when the binary is missing", () => { + const registry = DebugAdapter.make(DebugAdapter.missingProbe) + let res: ReturnType | undefined + expect(() => { + res = registry.resolve("go") + }).not.toThrow() + expect(res!.available).toBe(false) + if (res && !res.available) { + expect(res.message.toLowerCase()).toContain("delve") + } + }) + + it("carries the per-adapter install hint for each base adapter", () => { + const registry = DebugAdapter.make(DebugAdapter.missingProbe) + const debugpy = registry.resolveById("debugpy") + if (!debugpy.available) expect(debugpy.message).toContain("debugpy") + const delve = registry.resolveById("delve") + if (!delve.available) expect(delve.message).toContain("dlv") + const lldb = registry.resolveById("lldb") + if (!lldb.available) expect(lldb.message.toLowerCase()).toContain("lldb") + }) + + it("a partially-installed environment resolves only what exists", () => { + // Only python is installed: debugpy resolves, delve/lldb are gracefully missing. + const registry = DebugAdapter.make(DebugAdapter.installedProbe(["python3"])) + expect(registry.resolveById("debugpy").available).toBe(true) + expect(registry.resolveById("delve").available).toBe(false) + expect(registry.resolveById("lldb").available).toBe(false) + }) +}) diff --git a/packages/deepagent-code/test/deepagent/debug-tool-d3-d4.test.ts b/packages/deepagent-code/test/deepagent/debug-tool-d3-d4.test.ts new file mode 100644 index 00000000..0f1c7b69 --- /dev/null +++ b/packages/deepagent-code/test/deepagent/debug-tool-d3-d4.test.ts @@ -0,0 +1,121 @@ +import { describe, expect } from "bun:test" +import { Effect, Layer } from "effect" +import { FSUtil } from "@deepagent-code/core/fs-util" +import { CrossSpawnSpawner } from "@deepagent-code/core/cross-spawn-spawner" +import { Git } from "../../src/git" +import { Worktree } from "../../src/worktree" +import { LSP } from "../../src/lsp/lsp" +import { Config } from "../../src/config/config" +import { RuntimeFlags } from "../../src/effect/runtime-flags" +import { EventV2Bridge } from "../../src/event-v2-bridge" +import { RuntimeBase } from "../../src/runtime/base" +import { afterEach } from "bun:test" +import { disposeAllInstances } from "../fixture/fixture" +import { testEffect } from "../lib/effect" + +// D3/D4 (S1-v3.5): the debug tool is symbol-driven (no raw line numbers). +// This file covers the STATIC contract of the tool (exports, parameter schema, +// evidence-artifact registration). The dynamic behaviour — that execute() actually +// routes through DebugService + the R0 gate, launches the debuggee, and reuses the +// live session — is covered by real execute() tests in `debug-tool-d3-execute.test.ts`. +// (The old approve-once and D4 tests here asserted local closures / grepped source +// and never called the tool; they were false confidence and have been removed in +// favour of the real execute tests.) + +// Minimal layer for the static-contract tests: no DAP adapter needed. +const testLayer = Layer.mergeAll( + FSUtil.defaultLayer, + CrossSpawnSpawner.defaultLayer, + Git.defaultLayer, + Worktree.defaultLayer, + RuntimeBase.testLayer(RuntimeBase.allowAllProbe).pipe(Layer.provide(Worktree.defaultLayer)), + LSP.layer.pipe( + Layer.provide(Config.defaultLayer), + Layer.provide(RuntimeFlags.layer({})), + Layer.provide(EventV2Bridge.defaultLayer), + ), +) + +const it = testEffect(testLayer) + +describe("D3 debug tool", () => { + afterEach(() => disposeAllInstances()) + + describe("output budget → artifact truncation (D4)", () => { + it.instance( + "large variable tree triggers budget and returns truncated flag", + () => + Effect.gen(function* () { + // RuntimeBase.applyOutputBudget is the shared budget logic (tested in R0 tests). + // Here we verify the budget parameters used by the debug tool are sensible. + const bigOutput = "x".repeat(30_000) + const result = RuntimeBase.applyOutputBudget(bigOutput, RuntimeBase.DEFAULT_BUDGET) + expect(result.truncated).toBe(true) + expect(result.fullBytes).toBeGreaterThan(24_000) + expect(result.inline).toContain("truncated") + + const small = RuntimeBase.applyOutputBudget("hello world", RuntimeBase.DEFAULT_BUDGET) + expect(small.truncated).toBe(false) + expect(small.inline).toBe("hello world") + }), + { git: true }, + ) + }) + + describe("D3 debug tool exports", () => { + it.instance( + "DebugTool is a valid Tool.Info with id='debug'", + () => + Effect.gen(function* () { + // Import and check the tool's id and parameter schema. + const { DebugTool, Parameters } = yield* Effect.promise(() => import("../../src/tool/debug")) + expect(DebugTool.id).toBe("debug") + // Parameters schema should include the eight intents. + const intents = Parameters.fields.intent.literals + expect(intents).toContain("start") + expect(intents).toContain("break_at") + expect(intents).toContain("stack") + expect(intents).toContain("eval") + expect(intents).toContain("stop") + }), + { git: true }, + ) + }) + + describe("symbol-driven breakpoint (acceptance criterion a)", () => { + it.instance( + "symbol name → LSP resolve → file+line, no raw line numbers needed", + () => + Effect.gen(function* () { + // The debug tool calls LSPResolve.resolveSymbol internally. + // We verify the resolve module is used (not a raw line number API). + const { LSPResolve } = yield* Effect.promise(() => import("../../src/lsp/resolve")) + expect(typeof LSPResolve.resolveSymbol).toBe("function") + // The tool's Parameters schema doesn't expose a raw 'line' field. + const { Parameters } = yield* Effect.promise(() => import("../../src/tool/debug")) + const fieldNames = Object.keys(Parameters.fields) + expect(fieldNames).not.toContain("line") + expect(fieldNames).toContain("symbol") + }), + { git: true }, + ) + }) + + describe("D4 evidence artifact registration", () => { + it.instance( + "DEBUG_SESSION.json / PROFILE_RESULT.json artifacts are registered in agent-gateway.ts", + () => + Effect.gen(function* () { + // Verify the D4/P4A artifacts are registered in the gateway (evidence kinds). + const fs = yield* FSUtil.Service + const gatewayPath = "/Users/xiuranli/code/agent/deepagent-code/packages/core/src/agent-gateway.ts" + const content = yield* fs.readFileStringSafe(gatewayPath) + expect(content).toContain("DEBUG_SESSION.json") + expect(content).toContain("debug_session") + expect(content).toContain("PROFILE_RESULT.json") + expect(content).toContain('"profile"') + }), + { git: true }, + ) + }) +}) diff --git a/packages/deepagent-code/test/deepagent/debug-tool-d3-execute.test.ts b/packages/deepagent-code/test/deepagent/debug-tool-d3-execute.test.ts new file mode 100644 index 00000000..ce5a73c8 --- /dev/null +++ b/packages/deepagent-code/test/deepagent/debug-tool-d3-execute.test.ts @@ -0,0 +1,205 @@ +import { afterEach, beforeAll, afterAll, describe, expect } from "bun:test" +import { Effect, Layer } from "effect" +import path from "path" +import os from "os" +import * as fs from "fs/promises" +import { FSUtil } from "@deepagent-code/core/fs-util" +import { CrossSpawnSpawner } from "@deepagent-code/core/cross-spawn-spawner" +import { Git } from "@/git" +import { Worktree } from "@/worktree" +import { LSP } from "@/lsp/lsp" +import { Config } from "@/config/config" +import { RuntimeFlags } from "@/effect/runtime-flags" +import { EventV2Bridge } from "@/event-v2-bridge" +import { RuntimeBase } from "@/runtime/base" +import { DebugService } from "@/debug/service" +import * as Truncate from "@/tool/truncate" +import { Agent } from "@/agent/agent" +import { Tool } from "@/tool/tool" +import { DebugTool } from "@/tool/debug" +import { disposeAllInstances } from "../fixture/fixture" +import { testEffect } from "../lib/effect" +import { InstanceStore } from "@/project/instance-store" +import { MessageID, SessionID } from "@/session/schema" + +// D3 (S1-v3.5) — REAL DebugTool.execute behaviour tests. +// +// These replace the old "false confidence" tests (a local Set approval assertion +// that never called the tool, a grep-the-source D4 test). They drive the actual +// DebugTool.execute and prove the tool now: +// (1) routes intent:start through DebugService (D1 state machine) + R0 gate/isolation, +// actually launching the debuggee — not a bare initialize handshake (C3/C4/C6), +// (2) reuses the live session when session_id is omitted (M10 fix), +// (3) fails closed on a missing privilege via the R0 gate (#4), +// (4) degrades gracefully (no Die) on no-session / unavailable-adapter. +// +// A fake `python3` on PATH runs the fake DAP adapter fixture, so the debugpy adapter +// resolves and DapClient talks a real DAP session end-to-end. + +const fakeAdapterPath = path.join(__dirname, "../fixture/debug/fake-dap-adapter.js") + +let fakeBinDir: string +let originalPath: string | undefined + +beforeAll(async () => { + fakeBinDir = await fs.mkdtemp(path.join(os.tmpdir(), "deepagent-fakepy-")) + // A fake `python3` that ignores `-m debugpy.adapter` and just runs the fake DAP + // adapter over stdio (cross-platform: the runner has no real debugpy). + const script = `#!/usr/bin/env node +require(${JSON.stringify(fakeAdapterPath)}) +` + const pyPath = path.join(fakeBinDir, "python3") + await fs.writeFile(pyPath, script, { mode: 0o755 }) + await fs.chmod(pyPath, 0o755) + originalPath = process.env.PATH + process.env.PATH = `${fakeBinDir}${path.delimiter}${originalPath ?? ""}` +}) + +afterAll(async () => { + process.env.PATH = originalPath + await fs.rm(fakeBinDir, { recursive: true, force: true }).catch(() => {}) +}) + +const toolLayer = (probe: RuntimeBase.PrivilegeProbe = RuntimeBase.allowAllProbe) => + Layer.mergeAll( + LSP.defaultLayer, + DebugService.layer.pipe( + Layer.provide(RuntimeBase.testLayer(probe).pipe(Layer.provide(Worktree.defaultLayer))), + Layer.provide(EventV2Bridge.defaultLayer), + ), + RuntimeBase.testLayer(probe).pipe(Layer.provide(Worktree.defaultLayer)), + Worktree.defaultLayer, + Truncate.defaultLayer, + Agent.defaultLayer, + FSUtil.defaultLayer, + CrossSpawnSpawner.defaultLayer, + Git.defaultLayer, + Config.defaultLayer, + RuntimeFlags.layer({}), + EventV2Bridge.defaultLayer, + ) + +type AskCall = { permission: string; patterns: readonly string[] } + +const makeCtx = (asks: AskCall[]): Tool.Context => ({ + sessionID: SessionID.make("ses_test"), + messageID: MessageID.make("msg_test"), + agent: "build", + abort: new AbortController().signal, + messages: [], + metadata: () => Effect.void, + ask: (req) => + Effect.sync(() => { + asks.push({ permission: req.permission, patterns: req.patterns }) + }), +}) + +describe("D3 DebugTool.execute — real tool path", () => { + afterEach(() => disposeAllInstances()) + + const it = testEffect(toolLayer()) + + it.instance( + "intent:start launches the debuggee via DebugService and records a live session", + () => + Effect.gen(function* () { + const def = yield* Tool.init(yield* DebugTool) + const debug = yield* DebugService.Service + const asks: AskCall[] = [] + + const result = yield* def.execute( + { intent: "start", target: "python -m pytest test_foo.py", session_id: "s1" }, + makeCtx(asks), + ) + + // Reached DebugService.start (not the "adapter unavailable" early return): + // the fake python3/debugpy resolved and the session is tracked by the SERVICE, + // not a local Map (C3). The session state proves launch happened (C4). + expect(result.title).toContain("session started") + const live = yield* debug.get("s1") + expect(live).toBeDefined() + expect(live!.adapterId).toBe("debugpy") + // R0 approve-once gate fired exactly one debug approval (C6). + expect(asks.filter((a) => a.permission === "debug").length).toBe(1) + + yield* debug.terminate("s1").pipe(Effect.catch(() => Effect.void)) + }), + { git: true }, + ) + + it.instance( + "intent:stop with omitted session_id reuses the latest live session (M10)", + () => + Effect.gen(function* () { + const def = yield* Tool.init(yield* DebugTool) + const debug = yield* DebugService.Service + const asks: AskCall[] = [] + + // Start WITH an id. + yield* def.execute({ intent: "start", target: "python app.py", session_id: "reuse-1" }, makeCtx(asks)) + expect(yield* debug.get("reuse-1")).toBeDefined() + + // Stop WITHOUT an id → must resolve to the live session, not mint a new one + // and report "no session" (the old bug where each omit made a fresh id). + const stopResult = yield* def.execute({ intent: "stop" }, makeCtx(asks)) + expect(stopResult.title).toContain("stopped") + expect(yield* debug.get("reuse-1")).toBeUndefined() + }), + { git: true }, + ) + + it.instance( + "non-start intent with no live session degrades gracefully (no Die)", + () => + Effect.gen(function* () { + const def = yield* Tool.init(yield* DebugTool) + const result = yield* def.execute({ intent: "continue" }, makeCtx([])) + expect(result.title).toContain("no session") + expect(result.output).toContain("intent:start") + }), + { git: true }, + ) + + it.instance( + "unknown language → adapter unavailable (graceful, no Die)", + () => + Effect.gen(function* () { + const def = yield* Tool.init(yield* DebugTool) + const asks: AskCall[] = [] + const result = yield* def.execute( + { intent: "start", target: "./mystery-binary", language: "brainfuck", session_id: "x" }, + makeCtx(asks), + ) + expect(result.title).toContain("adapter unavailable") + // No approval prompt when there's no adapter to run. + expect(asks.length).toBe(0) + }), + { git: true }, + ) +}) + +describe("D3 DebugTool.execute — fail-closed privilege gate (#4)", () => { + afterEach(() => disposeAllInstances()) + + const denyIt = testEffect(toolLayer(RuntimeBase.denyAllProbe)) + + denyIt.instance( + "a ptrace-requiring adapter is refused when the privilege is unavailable", + () => + Effect.gen(function* () { + const def = yield* Tool.init(yield* DebugTool) + const debug = yield* DebugService.Service + // C/C++/Rust resolve to lldb, which declares the `ptrace` privilege. With + // denyAllProbe the R0 gate refuses BEFORE the adapter is spawned. + // (lldb-dap may not be installed either; both paths are graceful, non-Die.) + const result = yield* def.execute( + { intent: "start", target: "cargo run", session_id: "priv-1" }, + makeCtx([]), + ) + expect(result.title).toContain("debug:") + // Either way, no live session was created. + expect(yield* debug.get("priv-1")).toBeUndefined() + }), + { git: true }, + ) +}) diff --git a/packages/deepagent-code/test/deepagent/mcp-secret-env-expansion.test.ts b/packages/deepagent-code/test/deepagent/mcp-secret-env-expansion.test.ts new file mode 100644 index 00000000..c4d35646 --- /dev/null +++ b/packages/deepagent-code/test/deepagent/mcp-secret-env-expansion.test.ts @@ -0,0 +1,61 @@ +import { describe, expect, test } from "bun:test" +import { Effect } from "effect" +import { SecretStore } from "@/mcp/secret-store" + +// M-CRED (S1-v3.5): `${VAR}` / `${VAR:-default}` env expansion (Step 1, the low-cost +// transition that mirrors claude-code). Resolution happens at connect time from the +// process environment; a missing var WARNS (by name) but does not block — it expands to +// "" so the connection path keeps going. + +describe("M-CRED env expansion", () => { + test("expands a plain ${VAR} from the environment", () => { + const { value, missing } = SecretStore.expandEnvRefs("Bearer ${TOKEN}", { TOKEN: "ghp_real" }) + expect(value).toBe("Bearer ghp_real") + expect(missing).toEqual([]) + }) + + test("uses the :-default when the var is unset or empty", () => { + expect(SecretStore.expandEnvRefs("${HOST:-localhost}", {}).value).toBe("localhost") + expect(SecretStore.expandEnvRefs("${HOST:-localhost}", { HOST: "" }).value).toBe("localhost") + // Set, non-empty → the env value wins over the default. + expect(SecretStore.expandEnvRefs("${HOST:-localhost}", { HOST: "db.internal" }).value).toBe("db.internal") + }) + + test("missing var with no default warns (reported in `missing`) but does not block — expands to ''", () => { + const { value, missing } = SecretStore.expandEnvRefs("postgres://${DB_USER}@h/db", {}) + // Does not throw; the missing var simply becomes empty and is surfaced for a warning. + expect(value).toBe("postgres://@h/db") + expect(missing).toEqual(["DB_USER"]) + }) + + test("expands multiple references in one value", () => { + const { value, missing } = SecretStore.expandEnvRefs("${A}/${B:-z}/${C}", { A: "1", C: "3" }) + expect(value).toBe("1/z/3") + expect(missing).toEqual([]) // B had a default, A and C were present + }) + + test("classifies references vs plaintext", () => { + expect(SecretStore.containsEnvRef("${X}")).toBe(true) + expect(SecretStore.containsEnvRef("plain")).toBe(false) + expect(SecretStore.isHandle("secret://acct")).toBe(true) + expect(SecretStore.isReference("${X}")).toBe(true) + expect(SecretStore.isReference("secret://acct")).toBe(true) + expect(SecretStore.isReference("postgres://u:p@h/db")).toBe(false) + }) + + test("resolveValue passes a literal through unchanged and expands a ${VAR}", async () => { + const store = SecretStore.make(SecretStore.inMemoryBackend()) + const literal = await Effect.runPromise(SecretStore.resolveValue("just-a-literal", store, {})) + expect(literal).toBe("just-a-literal") + const expanded = await Effect.runPromise(SecretStore.resolveValue("Bearer ${T}", store, { T: "tok" })) + expect(expanded).toBe("Bearer tok") + }) + + test("resolveRecord drops nothing for env refs but warns on missing; keeps the partial value", async () => { + const store = SecretStore.make(SecretStore.inMemoryBackend()) + const out = await Effect.runPromise( + SecretStore.resolveRecord({ A: "${A}", B: "lit" }, store, { A: "av" }), + ) + expect(out).toEqual({ A: "av", B: "lit" }) + }) +}) diff --git a/packages/deepagent-code/test/deepagent/mcp-secret-keychain-roundtrip.test.ts b/packages/deepagent-code/test/deepagent/mcp-secret-keychain-roundtrip.test.ts new file mode 100644 index 00000000..3cb92378 --- /dev/null +++ b/packages/deepagent-code/test/deepagent/mcp-secret-keychain-roundtrip.test.ts @@ -0,0 +1,67 @@ +import { describe, expect, test } from "bun:test" +import { Effect } from "effect" +import { SecretStore } from "@/mcp/secret-store" + +// M-CRED (S1-v3.5) acceptance (b): put → resolve roundtrip with an INJECTED backend, so the +// test never touches the real OS keychain. The store wraps any Backend (macOS Keychain / +// libsecret / DPAPI / file fallback) behind the same put/resolve contract; here we inject an +// in-memory backend to prove the contract. + +describe("M-CRED keychain roundtrip (mock backend)", () => { + test("put returns a secret:// handle; resolve returns the stored value", async () => { + const store = SecretStore.make(SecretStore.inMemoryBackend("mock-keychain")) + const handle = await Effect.runPromise(store.put("mcp:pg:env:DATABASE_URI", "postgres://u:p@h/db")) + expect(handle).toBe("secret://mcp:pg:env:DATABASE_URI") + const value = await Effect.runPromise(store.resolve(handle)) + expect(value).toBe("postgres://u:p@h/db") + }) + + test("resolve of an unknown handle returns undefined (caller drops the value)", async () => { + const store = SecretStore.make(SecretStore.inMemoryBackend()) + const value = await Effect.runPromise(store.resolve("secret://does-not-exist")) + expect(value).toBeUndefined() + }) + + test("remove deletes the secret", async () => { + const store = SecretStore.make(SecretStore.inMemoryBackend()) + const handle = await Effect.runPromise(store.put("acct", "v")) + await Effect.runPromise(store.remove(handle)) + expect(await Effect.runPromise(store.resolve(handle))).toBeUndefined() + }) + + test("an injected failing backend surfaces as undefined on resolve (never throws into connect path)", async () => { + const flaky: SecretStore.Backend = { + id: "flaky", + available: async () => true, + put: async () => {}, + get: async () => { + throw new Error("keychain unlock prompt cancelled") + }, + remove: async () => {}, + } + const store = SecretStore.make(flaky) + const value = await Effect.runPromise(store.resolve("secret://x")) + expect(value).toBeUndefined() + }) + + test("resolveValue resolves a handle through the injected store", async () => { + const backend = SecretStore.inMemoryBackend() + await backend.put("acct", "real-secret") + const store = SecretStore.make(backend) + const resolved = await Effect.runPromise( + SecretStore.resolveValue(SecretStore.makeHandle("acct"), store, {}), + ) + expect(resolved).toBe("real-secret") + }) + + test("testLayer provides an injectable in-memory backend", async () => { + const program = Effect.gen(function* () { + const store = yield* SecretStore.Service + const handle = yield* store.put("k", "s") + return yield* store.resolve(handle) + }) + const backend = SecretStore.inMemoryBackend() + const result = await Effect.runPromise(program.pipe(Effect.provide(SecretStore.testLayer(backend)))) + expect(result).toBe("s") + }) +}) diff --git a/packages/deepagent-code/test/deepagent/mcp-secret-migration.test.ts b/packages/deepagent-code/test/deepagent/mcp-secret-migration.test.ts new file mode 100644 index 00000000..d372b00a --- /dev/null +++ b/packages/deepagent-code/test/deepagent/mcp-secret-migration.test.ts @@ -0,0 +1,140 @@ +import { describe, expect, test } from "bun:test" +import { Effect } from "effect" +import { ConfigMCPV1 } from "@deepagent-code/core/v1/config/mcp" +import { SecretStore } from "@/mcp/secret-store" + +// M-CRED (S1-v3.5) acceptance (d): existing PLAINTEXT secrets in cfg.mcp are migrated into the +// secret store and replaced with `secret://` handles — transactionally (put+verify before erase), +// so a partial failure never loses a credential. Already-referenced values are left alone. + +const secretKeys = new Set(["DATABASE_URI", "GITHUB_PERSONAL_ACCESS_TOKEN"]) + +describe("M-CRED migration", () => { + test("migrates a plaintext env secret to a handle; the store holds the real value", async () => { + const mcp: Record = { + "postgres-readonly": { + type: "local", + command: ["postgres-mcp", "--access-mode=restricted"], + environment: { DATABASE_URI: "postgres://u:secret@h/db" }, + enabled: true, + }, + } + const backend = SecretStore.inMemoryBackend() + const store = SecretStore.make(backend) + const outcome = await Effect.runPromise(SecretStore.migratePlaintextSecrets(mcp, store, { secretEnvKeys: secretKeys })) + + expect(outcome.changed).toBe(true) + expect(outcome.moved.length).toBe(1) + const newConfig = outcome.config["postgres-readonly"] + if (newConfig.type !== "local") throw new Error("expected local") + // Config now holds a handle, not the plaintext. + expect(SecretStore.isHandle(newConfig.environment!.DATABASE_URI)).toBe(true) + expect(JSON.stringify(outcome.config)).not.toContain("secret@h") + // The real value is retrievable from the store via the handle. + const resolved = await Effect.runPromise(store.resolve(newConfig.environment!.DATABASE_URI)) + expect(resolved).toBe("postgres://u:secret@h/db") + }) + + test("migrates a plaintext Authorization header to a handle", async () => { + const mcp: Record = { + github: { type: "remote", url: "https://api.example/mcp", headers: { Authorization: "Bearer ghp_plain" }, enabled: true }, + } + const store = SecretStore.make(SecretStore.inMemoryBackend()) + const outcome = await Effect.runPromise(SecretStore.migratePlaintextSecrets(mcp, store)) + const cfg = outcome.config.github + if (cfg.type !== "remote") throw new Error("expected remote") + expect(SecretStore.isHandle(cfg.headers!.Authorization)).toBe(true) + expect(JSON.stringify(outcome.config)).not.toContain("ghp_plain") + }) + + test("leaves existing ${VAR} references and handles untouched (idempotent)", async () => { + const mcp: Record = { + a: { type: "local", command: ["x"], environment: { DATABASE_URI: "${DB}" }, enabled: true }, + b: { type: "remote", url: "u", headers: { Authorization: "secret://acct" }, enabled: true }, + } + const store = SecretStore.make(SecretStore.inMemoryBackend()) + const outcome = await Effect.runPromise(SecretStore.migratePlaintextSecrets(mcp, store, { secretEnvKeys: secretKeys })) + expect(outcome.changed).toBe(false) + expect(outcome.moved.length).toBe(0) + expect(outcome.config).toEqual(mcp) + }) + + test("TRANSACTIONAL: a backend put failure preserves THAT plaintext and never drops the credential", async () => { + // A backend that fails to store anything → migration must NOT erase the plaintext. + const failing: SecretStore.Backend = { + id: "failing", + available: async () => true, + put: async () => { + throw new Error("keychain write denied") + }, + get: async () => undefined, + remove: async () => {}, + } + const store = SecretStore.make(failing) + const mcp: Record = { + "postgres-readonly": { + type: "local", + command: ["postgres-mcp"], + environment: { DATABASE_URI: "postgres://u:keepme@h/db" }, + enabled: true, + }, + } + const outcome = await Effect.runPromise(SecretStore.migratePlaintextSecrets(mcp, store, { secretEnvKeys: secretKeys })) + expect(outcome.changed).toBe(false) + expect(outcome.failures.length).toBe(1) + const cfg = outcome.config["postgres-readonly"] + if (cfg.type !== "local") throw new Error("expected local") + // The credential is STILL in the config — not lost. + expect(cfg.environment!.DATABASE_URI).toBe("postgres://u:keepme@h/db") + }) + + test("TRANSACTIONAL: a verify mismatch preserves the plaintext (no silent loss)", async () => { + // Backend that "accepts" the put but returns a wrong value on read-back. + const corrupting: SecretStore.Backend = { + id: "corrupting", + available: async () => true, + put: async () => {}, + get: async () => "WRONG", + remove: async () => {}, + } + const store = SecretStore.make(corrupting) + const mcp: Record = { + pg: { type: "local", command: ["x"], environment: { DATABASE_URI: "postgres://u:keepme@h/db" }, enabled: true }, + } + const outcome = await Effect.runPromise(SecretStore.migratePlaintextSecrets(mcp, store, { secretEnvKeys: secretKeys })) + expect(outcome.failures.length).toBe(1) + const cfg = outcome.config.pg + if (cfg.type !== "local") throw new Error("expected local") + expect(cfg.environment!.DATABASE_URI).toBe("postgres://u:keepme@h/db") + }) + + test("PARTIAL: one server migrates while another fails — migrated stays migrated, failed stays plaintext", async () => { + // Backend that succeeds for the first account and fails for the second. + const calls: string[] = [] + const map = new Map() + const selective: SecretStore.Backend = { + id: "selective", + available: async () => true, + put: async (account, secret) => { + calls.push(account) + if (account.includes(":b:") || account.includes("server-b")) throw new Error("denied for b") + map.set(account, secret) + }, + get: async (account) => map.get(account), + remove: async () => {}, + } + const store = SecretStore.make(selective) + const mcp: Record = { + "server-a": { type: "local", command: ["x"], environment: { DATABASE_URI: "postgres://a:secret@h/db" }, enabled: true }, + "server-b": { type: "local", command: ["y"], environment: { DATABASE_URI: "postgres://b:secret@h/db" }, enabled: true }, + } + const outcome = await Effect.runPromise(SecretStore.migratePlaintextSecrets(mcp, store, { secretEnvKeys: secretKeys })) + expect(outcome.moved.length).toBe(1) + expect(outcome.failures.length).toBe(1) + const a = outcome.config["server-a"] + const b = outcome.config["server-b"] + if (a.type !== "local" || b.type !== "local") throw new Error("expected local") + expect(SecretStore.isHandle(a.environment!.DATABASE_URI)).toBe(true) + expect(b.environment!.DATABASE_URI).toBe("postgres://b:secret@h/db") // preserved + }) +}) diff --git a/packages/deepagent-code/test/deepagent/mcp-secret-no-keyring-fallback.test.ts b/packages/deepagent-code/test/deepagent/mcp-secret-no-keyring-fallback.test.ts new file mode 100644 index 00000000..f922482c --- /dev/null +++ b/packages/deepagent-code/test/deepagent/mcp-secret-no-keyring-fallback.test.ts @@ -0,0 +1,50 @@ +import { describe, expect, test } from "bun:test" +import { Effect } from "effect" +import fs from "fs" +import os from "os" +import path from "path" +import { SecretStore } from "@/mcp/secret-store" + +// M-CRED (S1-v3.5) acceptance (c): with NO OS keyring available (headless / CI / container, +// no daemon), the store falls back to a `chmod 0600` local credentials file — NOT to the +// project config repo (fail-safe, never fail-open). This test drives the file backend +// directly with a temp path so it never writes the real data dir. + +const tmpFile = () => path.join(fs.mkdtempSync(path.join(os.tmpdir(), "mcp-secret-")), "mcp-secrets.json") + +describe("M-CRED no-keyring fallback", () => { + test("selectBackend degrades to the file backend when no native keyring is available", async () => { + // libsecret + DPAPI report unavailable; on macOS we still exercise the file backend + // path directly below. selectBackend is fail-safe by contract. + const fileBackend = SecretStore.fileBackend(tmpFile()) + expect(fileBackend.id).toBe("file") + const store = SecretStore.make(fileBackend) + expect(store.isFallback).toBe(true) + }) + + test("file backend persists the secret and writes a 0600 file (owner-only)", async () => { + const file = tmpFile() + const store = SecretStore.make(SecretStore.fileBackend(file)) + const handle = await Effect.runPromise(store.put("acct", "topsecret")) + expect(await Effect.runPromise(store.resolve(handle))).toBe("topsecret") + + expect(fs.existsSync(file)).toBe(true) + // POSIX mode check (skip the assertion on platforms without mode bits, e.g. win32). + if (process.platform !== "win32") { + const mode = fs.statSync(file).mode & 0o777 + expect(mode).toBe(0o600) + } + }) + + test("the fallback file lives under the data dir, NOT the project config repo", () => { + const where = SecretStore.defaultFilePath() + // Must not be a project-local config file that could be committed. + expect(where).not.toContain(".deepagent-code") + expect(path.basename(where)).toBe("mcp-secrets.json") + }) + + test("a missing fallback file resolves to undefined rather than throwing", async () => { + const store = SecretStore.make(SecretStore.fileBackend(tmpFile())) + expect(await Effect.runPromise(store.resolve("secret://nope"))).toBeUndefined() + }) +}) diff --git a/packages/deepagent-code/test/deepagent/mcp-secret-not-in-config.test.ts b/packages/deepagent-code/test/deepagent/mcp-secret-not-in-config.test.ts new file mode 100644 index 00000000..40c8444d --- /dev/null +++ b/packages/deepagent-code/test/deepagent/mcp-secret-not-in-config.test.ts @@ -0,0 +1,56 @@ +import { describe, expect, test } from "bun:test" +import { McpCatalog } from "@/mcp/catalog" +import { SecretStore } from "@/mcp/secret-store" + +// M-CRED (S1-v3.5) acceptance (a): after enabling a `secret:true` credential, the +// instantiated config carries NO plaintext value — only a `${KEY}` env reference (or a +// caller-supplied `${VAR}` ref / `secret://` handle). The real value is resolved at +// connect time and never lands in cfg.mcp. + +describe("M-CRED secret not in config", () => { + test("postgres connection string never appears in config; env holds a ${KEY} ref", () => { + const pg = McpCatalog.find("postgres-readonly")! + const secret = "postgres://admin:hunter2@db.internal:5432/prod" + const { config } = McpCatalog.instantiate(pg, { params: {}, credentialRefs: { DATABASE_URI: secret } }) + if (config.type !== "local") throw new Error("expected local config") + const serialized = JSON.stringify(config) + expect(serialized).not.toContain(secret) + expect(serialized).not.toContain("hunter2") + expect(config.environment?.DATABASE_URI).toBe("${DATABASE_URI}") + expect(SecretStore.isReference(config.environment!.DATABASE_URI)).toBe(true) + }) + + test("github PAT never appears in config; header holds a ${KEY} ref", () => { + const github = McpCatalog.find("github")! + const pat = "ghp_supersecretvalue123" + const { config } = McpCatalog.instantiate(github, { + params: {}, + credentialRefs: { GITHUB_PERSONAL_ACCESS_TOKEN: pat }, + }) + if (config.type !== "remote") throw new Error("expected remote config") + expect(JSON.stringify(config)).not.toContain(pat) + expect(config.headers?.Authorization).toBe("Bearer ${GITHUB_PERSONAL_ACCESS_TOKEN}") + }) + + test("a caller-supplied ${VAR} reference is preserved verbatim (not re-wrapped)", () => { + const pg = McpCatalog.find("postgres-readonly")! + const { config } = McpCatalog.instantiate(pg, { + params: {}, + credentialRefs: { DATABASE_URI: "${MY_DB_URI}" }, + }) + if (config.type !== "local") throw new Error("expected local config") + expect(config.environment?.DATABASE_URI).toBe("${MY_DB_URI}") + }) + + test("a caller-supplied secret:// handle is preserved verbatim", () => { + const pg = McpCatalog.find("postgres-readonly")! + const handle = SecretStore.makeHandle("mcp:postgres-readonly:environment:DATABASE_URI") + const { config } = McpCatalog.instantiate(pg, { + params: {}, + credentialRefs: { DATABASE_URI: handle }, + }) + if (config.type !== "local") throw new Error("expected local config") + expect(config.environment?.DATABASE_URI).toBe(handle) + expect(SecretStore.isHandle(config.environment!.DATABASE_URI)).toBe(true) + }) +}) diff --git a/packages/deepagent-code/test/deepagent/multiround.test.ts b/packages/deepagent-code/test/deepagent/multiround.test.ts index 254a53d2..8228615f 100644 --- a/packages/deepagent-code/test/deepagent/multiround.test.ts +++ b/packages/deepagent-code/test/deepagent/multiround.test.ts @@ -360,6 +360,39 @@ describe("A3 macro-round suggestion ({status,body}, objective)", () => { ) expect(emitted?.status).toBe("needs_human") }) + + test("U10: a completed plan with a blocked step -> needs_human, body names the blocker", async () => { + const sessionID = setup() + // A plan whose steps are all resolved (done + blocked): completion report is `complete` so the + // hard-gate finalize check passes, but the blocked step must still route to human review. + AgentGateway.DeepAgentSessionState.setPlan(sessionID, { + plan_id: "plan_blocked", + session_id: sessionID, + goal: "ship the feature", + assumptions: [], + steps: [ + { step_id: "s1", title: "build", status: "done" }, + { step_id: "s2", title: "deploy to prod", status: "blocked", note: "no prod credentials" }, + ], + active_step_id: null, + created_at: new Date().toISOString(), + }) + let emitted: { status: string; body: string } | undefined + await Effect.runPromise( + maybeRunRounds( + ops(sessionID, { + runValidation: () => Effect.succeed([vr("npm test", true)]), + onMacroRound: (s) => + Effect.sync(() => { + emitted = s + }), + }), + ), + ) + expect(emitted?.status).toBe("needs_human") + expect(emitted?.body).toContain("deploy to prod") + expect(emitted?.body).toContain("no prod credentials") + }) }) // T3 (S1-v3.4): three-light triage routing in the microbatch loop. diff --git a/packages/deepagent-code/test/deepagent/pap-cross-vendor-comparable.test.ts b/packages/deepagent-code/test/deepagent/pap-cross-vendor-comparable.test.ts new file mode 100644 index 00000000..2df75059 --- /dev/null +++ b/packages/deepagent-code/test/deepagent/pap-cross-vendor-comparable.test.ts @@ -0,0 +1,178 @@ +import { describe, it, expect } from "bun:test" +import { PAP } from "@/profile/pap" +import { Vocabulary } from "@/profile/vocabulary" + +// P1A acceptance (b): two adapters from different vendors both normalize to the +// SAME neutral hotspot[] shape and comparable, vendor-neutral metrics. If this +// holds, PAP is not a 套壳 — a consumer can rank/compare without knowing the vendor. + +// --- ncu-like (NVIDIA, gpu_kernel) ----------------------------------------- +const ncuLike: PAP.ProfileAdapter = { + id: "ncu-like", + vendor: "nvidia", + domain: "gpu_kernel", + privileges: [{ kind: "gpu_performance_counter", reason: "ncu needs GPU counters" }], + mapping: { + adapterId: "ncu-like", + domain: "gpu_kernel", + entries: [ + { neutral: "compute_throughput_pct", native: "sm__throughput.avg.pct_of_peak_sustained_elapsed", semantic: "exact" }, + { neutral: "memory_throughput_pct", native: "gpu__compute_memory_throughput.avg.pct_of_peak_sustained_elapsed", semantic: "exact" }, + { neutral: "dram_bandwidth_pct", native: "gpu__dram_throughput.avg.pct_of_peak_sustained_elapsed", semantic: "exact" }, + { neutral: "l2_throughput_pct", native: "lts__throughput.avg.pct_of_peak_sustained_elapsed", semantic: "exact" }, + { neutral: "occupancy_pct", native: "sm__warps_active.avg.pct_of_peak_sustained_active", semantic: "exact" }, + { neutral: "valu_utilization_pct", native: "sm__pipe_fma_cycles_active.avg.pct_of_peak_sustained_elapsed", semantic: "approximate" }, + { neutral: "salu_busy_pct", native: null, reason: "metric_not_in_this_profiler" }, + { neutral: "duration_ns", native: "gpu__time_duration.sum", semantic: "exact" }, + { neutral: "compute_bound", native: ["sm__throughput...", "gpu__compute_memory_throughput..."], semantic: "exact", derived: true, formula: "compute>memory+10" }, + ], + }, + async collect() { + return { path: "/tmp/r.ncu-rep", format: "ncu-rep" as const } + }, + async parse(ref) { + return { + adapterId: "ncu-like", + vendor: "nvidia", + domain: "gpu_kernel", + target: { command: "matmul" }, + nativeSummary: {}, + hotspots: [{ name: "sgemm_kernel", kind: "kernel", total_pct: 80, self_pct: 80, nativeMetrics: {} }], + raw_report_ref: ref, + } + }, + normalize(raw) { + return { + domain: "gpu_kernel", + vendor: "nvidia", + adapterId: "ncu-like", + target: raw.target, + duration_ns: 900_000, + hotspots: [ + { + kernel: "sgemm_kernel", + self_pct: 80, + total_pct: 80, + metrics: { + compute_throughput_pct: PAP.present(72, "pct", { nativeMetric: "sm__throughput", semantic: "exact" }), + occupancy_pct: PAP.present(55, "pct", { nativeMetric: "sm__warps_active", semantic: "exact" }), + salu_busy_pct: PAP.missing("metric_not_in_this_profiler"), + }, + }, + ], + summary: { occupancy_pct: PAP.present(55, "pct", { nativeMetric: "sm__warps_active", semantic: "exact" }) }, + raw_report_ref: raw.raw_report_ref, + } + }, +} + +// --- rocprof-like (AMD, gpu_kernel) ---------------------------------------- +const rocprofLike: PAP.ProfileAdapter = { + id: "rocprof-like", + vendor: "amd", + domain: "gpu_kernel", + privileges: [{ kind: "rocm_profiling", reason: "rocprof needs ROCm profiling access" }], + mapping: { + adapterId: "rocprof-like", + domain: "gpu_kernel", + entries: [ + { neutral: "compute_throughput_pct", native: "GPUBusy", semantic: "approximate" }, + { neutral: "memory_throughput_pct", native: "MemUnitBusy", semantic: "exact" }, + { neutral: "dram_bandwidth_pct", native: ["FetchSize", "WriteSize"], semantic: "approximate" }, + // AMD L2CacheHit is a hit-RATE, neutral l2_throughput_pct is THROUGHPUT — explicitly approximate. + { neutral: "l2_throughput_pct", native: "L2CacheHit", semantic: "approximate" }, + { neutral: "occupancy_pct", native: "Wavefronts", semantic: "approximate" }, + { neutral: "valu_utilization_pct", native: "VALUUtilization", semantic: "exact" }, + { neutral: "salu_busy_pct", native: "SALUBusy", semantic: "exact" }, + { neutral: "duration_ns", native: "rocpd.kernel.ts", semantic: "exact" }, + { neutral: "compute_bound", native: ["GPUBusy", "MemUnitBusy"], semantic: "approximate", derived: true, formula: "GPUBusy>MemUnitBusy+10" }, + ], + }, + async collect() { + return { path: "/tmp/r.rocpd", format: "rocpd" as const } + }, + async parse(ref) { + return { + adapterId: "rocprof-like", + vendor: "amd", + domain: "gpu_kernel", + target: { command: "matmul" }, + nativeSummary: {}, + hotspots: [{ name: "Cijk_gemm", kind: "kernel", total_pct: 78, self_pct: 78, nativeMetrics: {} }], + raw_report_ref: ref, + } + }, + normalize(raw) { + return { + domain: "gpu_kernel", + vendor: "amd", + adapterId: "rocprof-like", + target: raw.target, + duration_ns: 1_050_000, + hotspots: [ + { + kernel: "Cijk_gemm", + self_pct: 78, + total_pct: 78, + metrics: { + // GPUBusy → compute_throughput_pct is approximate (semantic flagged honestly). + compute_throughput_pct: PAP.present(68, "pct", { nativeMetric: "GPUBusy", semantic: "approximate" }), + occupancy_pct: PAP.present(60, "pct", { nativeMetric: "Wavefronts", semantic: "approximate" }), + salu_busy_pct: PAP.present(12, "pct", { nativeMetric: "SALUBusy", semantic: "exact" }), + }, + }, + ], + summary: { occupancy_pct: PAP.present(60, "pct", { nativeMetric: "Wavefronts", semantic: "approximate" }) }, + raw_report_ref: raw.raw_report_ref, + } + }, +} + +const run = async (a: PAP.ProfileAdapter) => a.normalize(await a.parse(await a.collect({ command: "matmul" }))) + +describe("PAP cross-vendor comparability", () => { + it("both vendors normalize to a valid, vocabulary-conformant profile", async () => { + for (const a of [ncuLike, rocprofLike]) { + const np = await run(a) + expect(PAP.validateProfile(np).errors).toEqual([]) + expect(Vocabulary.validateProfile(np).errors).toEqual([]) + } + }) + + it("produces the SAME neutral hotspot[] shape and comparable metric keys", async () => { + const nv = await run(ncuLike) + const amd = await run(rocprofLike) + + // Same neutral structure: one kernel hotspot each, identified by `kernel`, with self_pct. + expect(nv.hotspots[0]!.kernel).toBeDefined() + expect(amd.hotspots[0]!.kernel).toBeDefined() + expect(typeof nv.hotspots[0]!.self_pct).toBe("number") + expect(typeof amd.hotspots[0]!.self_pct).toBe("number") + + // Comparable metric: occupancy_pct exists on both, same neutral key + unit, comparable values. + const nvOcc = nv.hotspots[0]!.metrics["occupancy_pct"]! + const amdOcc = amd.hotspots[0]!.metrics["occupancy_pct"]! + expect(PAP.isPresent(nvOcc) && PAP.isPresent(amdOcc)).toBe(true) + if (PAP.isPresent(nvOcc) && PAP.isPresent(amdOcc)) { + expect(nvOcc.unit).toBe(amdOcc.unit) + // A vendor-agnostic consumer can compare them directly. + expect(amdOcc.value as number).toBeGreaterThan(nvOcc.value as number) + } + + // duration_ns is normalized to the same unit (ns) across vendors → comparable. + expect(typeof nv.duration_ns).toBe("number") + expect(typeof amd.duration_ns).toBe("number") + }) + + it("flags semantic differences explicitly (AMD GPUBusy→compute is approximate)", async () => { + const amd = await run(rocprofLike) + const ct = amd.hotspots[0]!.metrics["compute_throughput_pct"]! + expect(PAP.isPresent(ct)).toBe(true) + if (PAP.isPresent(ct)) expect(ct.provenance.semantic).toBe("approximate") + }) + + it("both mappings pass registration validation", () => { + expect(Vocabulary.validateMapping(ncuLike.mapping).ok).toBe(true) + expect(Vocabulary.validateMapping(rocprofLike.mapping).ok).toBe(true) + }) +}) diff --git a/packages/deepagent-code/test/deepagent/pap-missing-metric-is-null.test.ts b/packages/deepagent-code/test/deepagent/pap-missing-metric-is-null.test.ts new file mode 100644 index 00000000..ac9f851f --- /dev/null +++ b/packages/deepagent-code/test/deepagent/pap-missing-metric-is-null.test.ts @@ -0,0 +1,130 @@ +import { describe, it, expect } from "bun:test" +import { PAP } from "@/profile/pap" +import { Vocabulary } from "@/profile/vocabulary" + +// P1A acceptance (c): a metric the (fake) profiler lacks is `null` with a reason — +// never fabricated, never back-filled from a different metric. + +// perf cannot produce topdown µarch metrics without `perf stat topdown`; here the +// fake perf exposes only sampling events, so memory_bound_pct / dram_bound_pct are +// honestly absent. (cpu_hotspot domain is where those apply.) +const perfLike: PAP.ProfileAdapter = { + id: "perf-like", + vendor: "cpu_generic", + domain: "cpu_hotspot", + privileges: [{ kind: "perf_event_paranoid", reason: "perf needs perf_event_paranoid", maxParanoid: 2 }], + mapping: { + adapterId: "perf-like", + domain: "cpu_hotspot", + availableMetrics: ["overhead", "cycles", "instructions", "cache-misses", "cache-references", "branch-misses", "branches"], + entries: [ + { neutral: "self_pct", native: "overhead", semantic: "exact" }, + { neutral: "cpi", native: ["cycles", "instructions"], semantic: "exact" }, + { neutral: "ipc", native: ["instructions", "cycles"], semantic: "exact", derived: true, formula: "instructions / cycles" }, + { neutral: "clockticks", native: "cycles", semantic: "exact" }, + { neutral: "instructions_retired", native: "instructions", semantic: "exact" }, + { neutral: "cache_miss_rate", native: ["cache-misses", "cache-references"], semantic: "exact" }, + { neutral: "branch_misprediction_pct", native: ["branch-misses", "branches"], semantic: "exact" }, + // honest nulls: perf (sampling only) cannot produce topdown pipeline-slot metrics. + { neutral: "memory_bound_pct", native: null, reason: "metric_not_in_this_profiler", detail: "needs perf stat topdown" }, + { neutral: "dram_bound_pct", native: null, reason: "metric_not_in_this_profiler" }, + ], + }, + async collect() { + return { path: "/tmp/perf.data", format: "perf-data" as const } + }, + async parse(ref) { + return { + adapterId: "perf-like", + vendor: "cpu_generic", + domain: "cpu_hotspot", + target: { command: "app" }, + nativeSummary: {}, + hotspots: [{ name: "hot_fn", kind: "symbol", self_pct: 90, nativeMetrics: { cycles: 1000, instructions: 1500 } }], + raw_report_ref: ref, + } + }, + normalize(raw) { + const h = raw.hotspots[0]! + const cycles = Number(h.nativeMetrics["cycles"]) + const instructions = Number(h.nativeMetrics["instructions"]) + return { + domain: "cpu_hotspot", + vendor: "cpu_generic", + adapterId: "perf-like", + target: raw.target, + hotspots: [ + { + symbol: "hot_fn", + self_pct: 90, + metrics: { + self_pct: PAP.present(90, "pct", { nativeMetric: "overhead", semantic: "exact" }), + ipc: PAP.present(instructions / cycles, "ratio", { + nativeMetric: ["instructions", "cycles"], + semantic: "exact", + derived: true, + formula: "instructions / cycles", + }), + // the metrics perf can't produce: honest null + reason, NOT a fabricated number. + memory_bound_pct: PAP.missing("metric_not_in_this_profiler", "needs perf stat topdown"), + dram_bound_pct: PAP.missing("not_supported_on_arch"), + }, + }, + ], + summary: { + memory_bound_pct: PAP.missing("metric_not_in_this_profiler"), + }, + raw_report_ref: raw.raw_report_ref, + } + }, +} + +describe("PAP missing metric is honest null", () => { + it("a metric the profiler lacks is null + reason, never a number", async () => { + const np = perfLike.normalize(await perfLike.parse(await perfLike.collect({ command: "app" }))) + const mb = np.hotspots[0]!.metrics["memory_bound_pct"]! + expect(PAP.isMissing(mb)).toBe(true) + expect(mb.value).toBeNull() + if (PAP.isMissing(mb)) { + expect(mb.reason).toBe("metric_not_in_this_profiler") + expect(mb.detail).toContain("topdown") + } + // ipc, in contrast, IS present (derived) — null is only for the genuinely absent. + expect(PAP.isPresent(np.hotspots[0]!.metrics["ipc"]!)).toBe(true) + }) + + it("the profile still validates with honest nulls present", async () => { + const np = perfLike.normalize(await perfLike.parse(await perfLike.collect({ command: "app" }))) + expect(PAP.validateProfile(np).errors).toEqual([]) + expect(Vocabulary.validateProfile(np).errors).toEqual([]) + }) + + it("a null without a reason is rejected by structural validation", () => { + const bad: PAP.NormalizedProfile = { + domain: "cpu_hotspot", + vendor: "cpu_generic", + adapterId: "perf-like", + target: { command: "app" }, + hotspots: [ + { + symbol: "x", + self_pct: 1, + // a null with an empty reason = dishonest omission; must be flagged. + metrics: { memory_bound_pct: { value: null, reason: "" } as PAP.MetricValue }, + }, + ], + summary: {}, + raw_report_ref: { path: "/tmp/x", format: "perf-data" }, + } + const v = PAP.validateProfile(bad) + expect(v.ok).toBe(false) + expect(v.errors.some((e) => e.includes("no reason"))).toBe(true) + }) + + it("the mapping with honest nulls passes registration validation", () => { + const v = Vocabulary.validateMapping(perfLike.mapping) + expect(v.issues).toEqual([]) + expect(v.missing).toContain("memory_bound_pct") + expect(v.missing).toContain("dram_bound_pct") + }) +}) diff --git a/packages/deepagent-code/test/deepagent/pap-protocol-three-stage.test.ts b/packages/deepagent-code/test/deepagent/pap-protocol-three-stage.test.ts new file mode 100644 index 00000000..92a90c12 --- /dev/null +++ b/packages/deepagent-code/test/deepagent/pap-protocol-three-stage.test.ts @@ -0,0 +1,128 @@ +import { describe, it, expect } from "bun:test" +import { PAP } from "@/profile/pap" +import { Vocabulary } from "@/profile/vocabulary" + +// P1A: a fake in-memory adapter implementing collect→parse→normalize produces a +// valid NormalizedProfile. No process spawning — the "native report" is in-memory. + +// A complete cpu_sampling mapping (perf-like): every domain-applicable metric is +// either mapped present or honestly declared null. +const perfLikeMapping = (): PAP.MetricMapping => ({ + adapterId: "fake-perf", + domain: "cpu_sampling", + availableMetrics: ["overhead", "cycles", "instructions", "cache-misses", "cache-references", "branch-misses", "branches"], + entries: [ + { neutral: "self_pct", native: "overhead", semantic: "exact" }, + { neutral: "cpi", native: ["cycles", "instructions"], semantic: "exact", derived: false }, + { neutral: "ipc", native: ["instructions", "cycles"], semantic: "exact", derived: true, formula: "instructions / cycles" }, + { neutral: "clockticks", native: "cycles", semantic: "exact" }, + { neutral: "instructions_retired", native: "instructions", semantic: "exact" }, + { neutral: "cache_miss_rate", native: ["cache-misses", "cache-references"], semantic: "exact" }, + { neutral: "branch_misprediction_pct", native: ["branch-misses", "branches"], semantic: "exact" }, + ], +}) + +class FakePerfAdapter implements PAP.ProfileAdapter { + readonly id = "fake-perf" + readonly vendor = "cpu_generic" as const + readonly domain = "cpu_sampling" as const + readonly privileges = [{ kind: "perf_event_paranoid" as const, reason: "perf needs perf_event_paranoid", maxParanoid: 2 }] + readonly mapping = perfLikeMapping() + + async collect(target: PAP.ProfileTarget): Promise { + return { path: `/tmp/${target.command}.perf.data`, format: "perf-data", bytes: 4096, exportCommand: "perf script" } + } + + async parse(report: PAP.NativeReportRef): Promise { + return { + adapterId: this.id, + vendor: this.vendor, + domain: this.domain, + target: { command: "bench" }, + nativeSummary: {}, + availableMetrics: this.mapping.availableMetrics!, + hotspots: [ + { name: "compute", kind: "symbol", self_pct: 62.5, nativeMetrics: { overhead: 62.5, cycles: 2000, instructions: 1000 } }, + { name: "io_wait", kind: "symbol", self_pct: 20.0, nativeMetrics: { overhead: 20.0, cycles: 800, instructions: 200 } }, + ], + raw_report_ref: report, + } + } + + normalize(raw: PAP.RawProfile): PAP.NormalizedProfile { + const hotspots: PAP.Hotspot[] = raw.hotspots.map((h) => { + const cycles = Number(h.nativeMetrics["cycles"] ?? 0) + const instructions = Number(h.nativeMetrics["instructions"] ?? 0) + return { + symbol: h.name, + file_line: undefined, // P3A back-fills via LSPResolve + self_pct: h.self_pct ?? 0, + metrics: { + self_pct: PAP.present(h.self_pct ?? 0, "pct", { nativeMetric: "overhead", semantic: "exact" }), + cpi: PAP.present(cycles / instructions, "ratio", { nativeMetric: ["cycles", "instructions"], semantic: "exact" }), + ipc: PAP.present(instructions / cycles, "ratio", { + nativeMetric: ["instructions", "cycles"], + semantic: "exact", + derived: true, + formula: "instructions / cycles", + }), + clockticks: PAP.present(cycles, "count", { nativeMetric: "cycles", semantic: "exact" }), + instructions_retired: PAP.present(instructions, "count", { nativeMetric: "instructions", semantic: "exact" }), + cache_miss_rate: PAP.missing("not_collected", "cache events not requested in this run"), + branch_misprediction_pct: PAP.missing("not_collected"), + }, + } + }) + return { + domain: this.domain, + vendor: this.vendor, + adapterId: this.id, + target: raw.target, + duration_ns: 1_500_000, + hotspots, + summary: { + self_pct: PAP.present(100, "pct", { nativeMetric: "overhead", semantic: "exact" }), + }, + raw_report_ref: raw.raw_report_ref, + } + } +} + +describe("PAP three-stage protocol", () => { + it("collect → parse → normalize yields a structurally valid NormalizedProfile", async () => { + const adapter = new FakePerfAdapter() + const ref = await adapter.collect({ command: "bench" }) + expect(ref.format).toBe("perf-data") + + const raw = await adapter.parse(ref) + expect(raw.hotspots.length).toBe(2) + // stage-2 still carries native names + expect(Object.keys(raw.hotspots[0]!.nativeMetrics)).toContain("cycles") + + const np = adapter.normalize(raw) + const structural = PAP.validateProfile(np) + expect(structural.errors).toEqual([]) + expect(structural.ok).toBe(true) + + const conformance = Vocabulary.validateProfile(np) + expect(conformance.errors).toEqual([]) + + // neutral names only — no native leak + expect(Object.keys(np.hotspots[0]!.metrics)).toContain("ipc") + expect(Object.keys(np.hotspots[0]!.metrics)).not.toContain("cycles") + }) + + it("the adapter's mapping passes registration-time validation", () => { + const v = Vocabulary.validateMapping(new FakePerfAdapter().mapping) + expect(v.issues).toEqual([]) + expect(v.ok).toBe(true) + expect(v.present).toContain("ipc") + }) + + it("native report stays a ref (spills to artifact), not inlined", async () => { + const adapter = new FakePerfAdapter() + const np = adapter.normalize(await adapter.parse(await adapter.collect({ command: "bench" }))) + expect(np.raw_report_ref.path).toContain(".perf.data") + expect(np.raw_report_ref.bytes).toBeGreaterThan(0) + }) +}) diff --git a/packages/deepagent-code/test/deepagent/pap-vocabulary-mapping-completeness.test.ts b/packages/deepagent-code/test/deepagent/pap-vocabulary-mapping-completeness.test.ts new file mode 100644 index 00000000..f5aa5e7d --- /dev/null +++ b/packages/deepagent-code/test/deepagent/pap-vocabulary-mapping-completeness.test.ts @@ -0,0 +1,100 @@ +import { describe, it, expect } from "bun:test" +import { PAP } from "@/profile/pap" +import { Vocabulary } from "@/profile/vocabulary" + +// P1A: the registration-time mapping validator accepts a complete mapping and +// flags incomplete / invalid ones. This is the anti-套壳 gate. + +const completeGpuKernelMapping = (): PAP.MetricMapping => ({ + adapterId: "ncu-like", + domain: "gpu_kernel", + availableMetrics: [ + "sm__throughput.avg.pct_of_peak_sustained_elapsed", + "gpu__compute_memory_throughput.avg.pct_of_peak_sustained_elapsed", + "gpu__dram_throughput.avg.pct_of_peak_sustained_elapsed", + "lts__throughput.avg.pct_of_peak_sustained_elapsed", + "sm__warps_active.avg.pct_of_peak_sustained_active", + "sm__pipe_fma_cycles_active.avg.pct_of_peak_sustained_elapsed", + "gpu__time_duration.sum", + ], + entries: [ + { neutral: "compute_throughput_pct", native: "sm__throughput.avg.pct_of_peak_sustained_elapsed", semantic: "exact" }, + { neutral: "memory_throughput_pct", native: "gpu__compute_memory_throughput.avg.pct_of_peak_sustained_elapsed", semantic: "exact" }, + { neutral: "dram_bandwidth_pct", native: "gpu__dram_throughput.avg.pct_of_peak_sustained_elapsed", semantic: "exact" }, + { neutral: "l2_throughput_pct", native: "lts__throughput.avg.pct_of_peak_sustained_elapsed", semantic: "exact" }, + { neutral: "occupancy_pct", native: "sm__warps_active.avg.pct_of_peak_sustained_active", semantic: "exact" }, + { neutral: "valu_utilization_pct", native: "sm__pipe_fma_cycles_active.avg.pct_of_peak_sustained_elapsed", semantic: "approximate" }, + // ncu has no scalar-ALU counter → honest null, not fabricated. + { neutral: "salu_busy_pct", native: null, reason: "metric_not_in_this_profiler", detail: "ncu has no SALU counter" }, + { neutral: "duration_ns", native: "gpu__time_duration.sum", semantic: "exact" }, + { + neutral: "compute_bound", + native: ["sm__throughput.avg.pct_of_peak_sustained_elapsed", "gpu__compute_memory_throughput.avg.pct_of_peak_sustained_elapsed"], + semantic: "exact", + derived: true, + formula: "compute_throughput_pct > memory_throughput_pct + 10", + }, + ], +}) + +describe("PAP mapping completeness validation", () => { + it("accepts a complete, honest gpu_kernel mapping", () => { + const v = Vocabulary.validateMapping(completeGpuKernelMapping()) + expect(v.issues).toEqual([]) + expect(v.ok).toBe(true) + expect(v.present).toContain("compute_throughput_pct") + expect(v.missing).toContain("salu_busy_pct") + }) + + it("flags missing coverage when an applicable metric is omitted", () => { + const m = completeGpuKernelMapping() + m.entries = m.entries.filter((e) => e.neutral !== "occupancy_pct") + const v = Vocabulary.validateMapping(m) + expect(v.ok).toBe(false) + expect(v.issues.some((i) => i.kind === "missing_coverage" && i.metric === "occupancy_pct")).toBe(true) + }) + + it("flags a derived metric mapped without a formula (auditability)", () => { + const m = completeGpuKernelMapping() + m.entries = m.entries.map((e) => + e.neutral === "compute_bound" && PAP.isMappingPresent(e) ? { ...e, formula: undefined } : e, + ) + const v = Vocabulary.validateMapping(m) + expect(v.ok).toBe(false) + expect(v.issues.some((i) => i.kind === "derived_without_formula")).toBe(true) + }) + + it("flags a null mapping with no reason (honesty requires a reason)", () => { + const m = completeGpuKernelMapping() + m.entries = m.entries.map((e) => + e.neutral === "salu_busy_pct" ? ({ neutral: "salu_busy_pct", native: null, reason: "" } as PAP.MetricMapEntry) : e, + ) + const v = Vocabulary.validateMapping(m) + expect(v.ok).toBe(false) + expect(v.issues.some((i) => i.kind === "null_without_reason")).toBe(true) + }) + + it("flags a metric not applicable to the declared domain", () => { + const m = completeGpuKernelMapping() + m.entries = [...m.entries, { neutral: "cpi", native: "CPI Rate", semantic: "exact" }] + const v = Vocabulary.validateMapping(m) + expect(v.ok).toBe(false) + expect(v.issues.some((i) => i.kind === "not_applicable_to_domain" && i.metric === "cpi")).toBe(true) + }) + + it("flags an unknown (fabricated) neutral metric name", () => { + const m = completeGpuKernelMapping() + m.entries = [...m.entries, { neutral: "made_up_metric", native: "foo", semantic: "exact" }] + const v = Vocabulary.validateMapping(m) + expect(v.ok).toBe(false) + expect(v.issues.some((i) => i.kind === "unknown_metric")).toBe(true) + }) + + it("flags a mapped native metric not available on this machine (existence check)", () => { + const m = completeGpuKernelMapping() + m.availableMetrics = m.availableMetrics!.filter((n) => n !== "gpu__time_duration.sum") + const v = Vocabulary.validateMapping(m) + expect(v.ok).toBe(false) + expect(v.issues.some((i) => i.kind === "native_not_available" && i.metric === "duration_ns")).toBe(true) + }) +}) diff --git a/packages/deepagent-code/test/deepagent/profile-adapter-missing-hardware-graceful.test.ts b/packages/deepagent-code/test/deepagent/profile-adapter-missing-hardware-graceful.test.ts new file mode 100644 index 00000000..fc62b3aa --- /dev/null +++ b/packages/deepagent-code/test/deepagent/profile-adapter-missing-hardware-graceful.test.ts @@ -0,0 +1,276 @@ +import { describe, it, expect } from "bun:test" +import { PAP } from "@/profile/pap" +import { ProfileAdapterRegistry } from "@/profile/adapters/index" +import { NcuAdapter, missingNcuProbe } from "@/profile/adapters/ncu" +import { NsysAdapter, missingNsysProbe } from "@/profile/adapters/nsys" +import { RocprofAdapter, missingRocprofProbe } from "@/profile/adapters/rocprof" +import { VtuneAdapter, missingVtuneProbe } from "@/profile/adapters/vtune" +import { PerfAdapter, missingPerfProbe } from "@/profile/adapters/perf" + +/** + * P2A graceful-missing tests. + * + * When a profiler binary is not installed (or no matching hardware is present), + * adapters MUST: + * - Reject collect() with a clear Error message (not a Die/thrown panic). + * - NEVER throw an unhandled exception. + * - The registry must return { available: false, message } (not throw). + * + * §P2A spec requirement (c): "No corresponding hardware / tool not installed → + * graceful prompt, never throw Die." + */ +describe("profile adapter graceful-missing: no GPU / tool not installed", () => { + // —— ncu —— + describe("ncu adapter (NVIDIA Nsight Compute)", () => { + it("collect() rejects with a clear message when ncu binary is missing", async () => { + const adapter = new NcuAdapter(missingNcuProbe) + const target: PAP.ProfileTarget = { command: "./matmul" } + let error: Error | undefined + try { + await adapter.collect(target) + } catch (e) { + error = e as Error + } + expect(error).toBeDefined() + expect(error).toBeInstanceOf(Error) + // Must mention what is missing — not a cryptic Die. + expect(error!.message).toContain("ncu") + expect(error!.message.toLowerCase()).toContain("not installed") + }) + }) + + // —— nsys —— + describe("nsys adapter (NVIDIA Nsight Systems)", () => { + it("collect() rejects with a clear message when nsys binary is missing", async () => { + const adapter = new NsysAdapter(missingNsysProbe) + const target: PAP.ProfileTarget = { command: "./cuda_app" } + let error: Error | undefined + try { + await adapter.collect(target) + } catch (e) { + error = e as Error + } + expect(error).toBeDefined() + expect(error).toBeInstanceOf(Error) + expect(error!.message).toContain("nsys") + expect(error!.message.toLowerCase()).toContain("not installed") + }) + }) + + // —— rocprof —— + describe("rocprof adapter (AMD rocprofv3)", () => { + it("collect() rejects with a clear message when rocprofv3 binary is missing", async () => { + const adapter = new RocprofAdapter(missingRocprofProbe) + const target: PAP.ProfileTarget = { command: "./hip_app" } + let error: Error | undefined + try { + await adapter.collect(target) + } catch (e) { + error = e as Error + } + expect(error).toBeDefined() + expect(error).toBeInstanceOf(Error) + expect(error!.message).toContain("rocprofv3") + expect(error!.message.toLowerCase()).toContain("not installed") + }) + }) + + // —— vtune —— + describe("vtune adapter (Intel VTune)", () => { + it("collect() rejects with a clear message when vtune binary is missing", async () => { + const adapter = new VtuneAdapter(missingVtuneProbe) + const target: PAP.ProfileTarget = { command: "./my_app" } + let error: Error | undefined + try { + await adapter.collect(target) + } catch (e) { + error = e as Error + } + expect(error).toBeDefined() + expect(error).toBeInstanceOf(Error) + expect(error!.message).toContain("vtune") + expect(error!.message.toLowerCase()).toContain("not installed") + }) + }) + + // —— perf —— + describe("perf adapter (Linux perf)", () => { + it("collect() rejects with a clear message when perf binary is missing", async () => { + const adapter = new PerfAdapter(missingPerfProbe) + const target: PAP.ProfileTarget = { command: "./bench" } + let error: Error | undefined + try { + await adapter.collect(target) + } catch (e) { + error = e as Error + } + expect(error).toBeDefined() + expect(error).toBeInstanceOf(Error) + expect(error!.message).toContain("perf") + expect(error!.message.toLowerCase()).toContain("not installed") + }) + }) + + // —— registry: all binaries missing —— + describe("ProfileAdapterRegistry with all binaries missing", () => { + const registry = ProfileAdapterRegistry.make(ProfileAdapterRegistry.missingProbe) + + it("resolveById('ncu') returns { available: false } with install guidance", () => { + const result = registry.resolveById("ncu") + expect(result.available).toBe(false) + if (!result.available) { + expect(result.message).toBeDefined() + expect(result.message.length).toBeGreaterThan(0) + // Should mention the adapter and how to install. + expect(result.message.toLowerCase()).toMatch(/ncu|nvidia|nsight/) + } + }) + + it("resolveById('nsys') returns { available: false } with message", () => { + const result = registry.resolveById("nsys") + expect(result.available).toBe(false) + if (!result.available) { + expect(result.message).toMatch(/nsys|nvidia/i) + } + }) + + it("resolveById('rocprof') returns { available: false } with message", () => { + const result = registry.resolveById("rocprof") + expect(result.available).toBe(false) + if (!result.available) { + expect(result.message).toMatch(/rocprof|amd|rocm/i) + } + }) + + it("resolveById('vtune') returns { available: false } with message", () => { + const result = registry.resolveById("vtune") + expect(result.available).toBe(false) + if (!result.available) { + expect(result.message).toMatch(/vtune|intel/i) + } + }) + + it("resolveById('perf') returns { available: false } with message", () => { + const result = registry.resolveById("perf") + expect(result.available).toBe(false) + if (!result.available) { + expect(result.message).toMatch(/perf/i) + } + }) + + it("resolve({ vendor: 'nvidia', domain: 'gpu_kernel' }) returns { available: false } (no GPU)", () => { + const result = registry.resolve({ vendor: "nvidia", domain: "gpu_kernel" }) + expect(result.available).toBe(false) + if (!result.available) { + expect(result.message.length).toBeGreaterThan(0) + } + }) + + it("resolve({ domain: 'cpu_sampling' }) returns { available: false } (perf not installed)", () => { + const result = registry.resolve({ domain: "cpu_sampling" }) + expect(result.available).toBe(false) + }) + + it("available() returns empty array when all binaries are missing", () => { + expect(registry.available()).toHaveLength(0) + }) + + it("resolveById('unknown') returns { available: false } gracefully", () => { + const result = registry.resolveById("unknown-profiler") + expect(result.available).toBe(false) + if (!result.available) { + expect(result.message).toContain("unknown-profiler") + } + }) + + it("no exception is thrown for any resolution attempt", () => { + // All of these must be graceful — no throws. + expect(() => registry.resolveById("ncu")).not.toThrow() + expect(() => registry.resolveById("nsys")).not.toThrow() + expect(() => registry.resolveById("rocprof")).not.toThrow() + expect(() => registry.resolveById("vtune")).not.toThrow() + expect(() => registry.resolveById("perf")).not.toThrow() + expect(() => registry.resolve({ vendor: "nvidia", domain: "gpu_kernel" })).not.toThrow() + expect(() => registry.resolve({ vendor: "amd" })).not.toThrow() + expect(() => registry.resolve({ domain: "cpu_hotspot" })).not.toThrow() + }) + }) + + // —— registry: selected binary installed —— + describe("ProfileAdapterRegistry with only 'perf' installed", () => { + const probe = ProfileAdapterRegistry.installedProbe(["perf"]) + const registry = ProfileAdapterRegistry.make(probe) + + it("resolveById('perf') returns { available: true }", () => { + const result = registry.resolveById("perf") + expect(result.available).toBe(true) + if (result.available) { + expect(result.adapter.id).toBe("perf") + } + }) + + it("resolveById('ncu') returns { available: false } (binary not installed)", () => { + const result = registry.resolveById("ncu") + expect(result.available).toBe(false) + }) + + it("resolve({ domain: 'cpu_sampling' }) returns the perf adapter", () => { + const result = registry.resolve({ domain: "cpu_sampling" }) + expect(result.available).toBe(true) + if (result.available) { + expect(result.adapter.id).toBe("perf") + expect(result.adapter.domain).toBe("cpu_sampling") + } + }) + + it("resolve({ vendor: 'nvidia' }) returns { available: false } (no NVIDIA tools)", () => { + const result = registry.resolve({ vendor: "nvidia" }) + expect(result.available).toBe(false) + }) + + it("available() lists only perf", () => { + const avail = registry.available() + expect(avail).toHaveLength(1) + expect(avail[0]!.id).toBe("perf") + }) + }) + + // —— privilege declarations —— + describe("privilege declarations for R0 fail-closed gate", () => { + it("ncu declares gpu_performance_counter privilege", () => { + const adapter = new NcuAdapter(missingNcuProbe) + expect(adapter.privileges.some((p) => p.kind === "gpu_performance_counter")).toBe(true) + }) + + it("nsys declares gpu_performance_counter privilege", () => { + const adapter = new NsysAdapter(missingNsysProbe) + expect(adapter.privileges.some((p) => p.kind === "gpu_performance_counter")).toBe(true) + }) + + it("rocprof declares rocm_profiling privilege", () => { + const adapter = new RocprofAdapter(missingRocprofProbe) + expect(adapter.privileges.some((p) => p.kind === "rocm_profiling")).toBe(true) + }) + + it("vtune declares no special privilege (userspace profiling)", () => { + const adapter = new VtuneAdapter(missingVtuneProbe) + // VTune hardware mode may need some privilege, but basic hotspot sampling + // is user-space. No R0 privilege declared. + expect(adapter.privileges).toHaveLength(0) + }) + + it("perf declares perf_event_paranoid privilege", () => { + const adapter = new PerfAdapter(missingPerfProbe) + const spec = adapter.privileges.find((p) => p.kind === "perf_event_paranoid") + expect(spec).toBeDefined() + expect(spec!.maxParanoid).toBeDefined() + expect(spec!.maxParanoid).toBeLessThanOrEqual(2) + }) + + it("registry.privilegesFor('ncu') returns ncu privileges", () => { + const registry = ProfileAdapterRegistry.make(ProfileAdapterRegistry.missingProbe) + const privs = registry.privilegesFor("ncu") + expect(privs.some((p) => p.kind === "gpu_performance_counter")).toBe(true) + }) + }) +}) diff --git a/packages/deepagent-code/test/deepagent/profile-adapter-ncu-normalize.test.ts b/packages/deepagent-code/test/deepagent/profile-adapter-ncu-normalize.test.ts new file mode 100644 index 00000000..504acfb9 --- /dev/null +++ b/packages/deepagent-code/test/deepagent/profile-adapter-ncu-normalize.test.ts @@ -0,0 +1,236 @@ +import { describe, it, expect, beforeAll, afterAll } from "bun:test" +import { writeFile, mkdtemp, rm } from "fs/promises" +import { join } from "path" +import { tmpdir } from "os" +import { PAP } from "@/profile/pap" +import { Vocabulary } from "@/profile/vocabulary" +import { NcuAdapter, ncuMapping, parseNcuCsv, installedNcuProbe } from "@/profile/adapters/ncu" + +// Representative ncu --csv fixture (real column order from NVIDIA Nsight Compute CLI). +// Columns: ID, Process ID, Process Name, Host Name, Kernel Name, Kernel Time, +// Context, Stream, Section Name, Metric Name, Metric Unit, Metric Value +// Kernel names that contain C++ template/argument commas MUST be quoted in CSV. +// Real ncu --csv output quotes any field containing commas. +const NCU_FIXTURE_CSV = `"ID","Process ID","Process Name","Host Name","Kernel Name","Kernel Time","Context","Stream","Section Name","Metric Name","Metric Unit","Metric Value" +0,12345,./matmul,localhost,"void matmul_kernel(float* A, float* B, float* C, int N)",1000000,1,7,"GPU Speed Of Light Throughput",sm__throughput.avg.pct_of_peak_sustained_elapsed,%,85.5 +0,12345,./matmul,localhost,"void matmul_kernel(float* A, float* B, float* C, int N)",1000000,1,7,"Memory Workload Analysis",gpu__compute_memory_throughput.avg.pct_of_peak_sustained_elapsed,%,72.3 +0,12345,./matmul,localhost,"void matmul_kernel(float* A, float* B, float* C, int N)",1000000,1,7,"Memory Workload Analysis",gpu__dram_throughput.avg.pct_of_peak_sustained_elapsed,%,68.1 +0,12345,./matmul,localhost,"void matmul_kernel(float* A, float* B, float* C, int N)",1000000,1,7,"Memory Workload Analysis",lts__throughput.avg.pct_of_peak_sustained_elapsed,%,75.4 +0,12345,./matmul,localhost,"void matmul_kernel(float* A, float* B, float* C, int N)",1000000,1,7,Occupancy,sm__warps_active.avg.pct_of_peak_sustained_active,%,55.2 +0,12345,./matmul,localhost,"void matmul_kernel(float* A, float* B, float* C, int N)",1000000,1,7,"Compute Workload Analysis",sm__pipe_fma_cycles_active.avg.pct_of_peak_sustained_active,%,60.8 +0,12345,./matmul,localhost,"void matmul_kernel(float* A, float* B, float* C, int N)",1000000,1,7,"GPU Speed Of Light Throughput",gpu__time_duration.sum,ns,1000000 +1,12345,./matmul,localhost,vectorAdd_kernel,500000,1,7,"GPU Speed Of Light Throughput",sm__throughput.avg.pct_of_peak_sustained_elapsed,%,45.2 +1,12345,./matmul,localhost,vectorAdd_kernel,500000,1,7,"Memory Workload Analysis",gpu__compute_memory_throughput.avg.pct_of_peak_sustained_elapsed,%,88.9 +1,12345,./matmul,localhost,vectorAdd_kernel,500000,1,7,"Memory Workload Analysis",gpu__dram_throughput.avg.pct_of_peak_sustained_elapsed,%,82.1 +1,12345,./matmul,localhost,vectorAdd_kernel,500000,1,7,"Memory Workload Analysis",lts__throughput.avg.pct_of_peak_sustained_elapsed,%,85.0 +1,12345,./matmul,localhost,vectorAdd_kernel,500000,1,7,Occupancy,sm__warps_active.avg.pct_of_peak_sustained_active,%,72.5 +1,12345,./matmul,localhost,vectorAdd_kernel,500000,1,7,"Compute Workload Analysis",sm__pipe_fma_cycles_active.avg.pct_of_peak_sustained_active,%,40.1 +1,12345,./matmul,localhost,vectorAdd_kernel,500000,1,7,"GPU Speed Of Light Throughput",gpu__time_duration.sum,ns,500000 +` + +let tmpDir: string +let fixturePath: string + +beforeAll(async () => { + tmpDir = await mkdtemp(join(tmpdir(), "deepagent-test-ncu-")) + fixturePath = join(tmpDir, "ncu-fixture.csv") + await writeFile(fixturePath, NCU_FIXTURE_CSV, "utf8") +}) + +afterAll(async () => { + await rm(tmpDir, { recursive: true, force: true }) +}) + +describe("ncu adapter — CSV parsing", () => { + it("parseNcuCsv extracts kernel metrics correctly", () => { + const kernelMap = parseNcuCsv(NCU_FIXTURE_CSV) + expect(kernelMap.size).toBe(2) + const matmul = kernelMap.get("void matmul_kernel(float* A, float* B, float* C, int N)") + expect(matmul).toBeDefined() + expect(matmul!.get("sm__throughput.avg.pct_of_peak_sustained_elapsed")).toBeCloseTo(85.5, 3) + expect(matmul!.get("gpu__dram_throughput.avg.pct_of_peak_sustained_elapsed")).toBeCloseTo(68.1, 3) + expect(matmul!.get("sm__warps_active.avg.pct_of_peak_sustained_active")).toBeCloseTo(55.2, 3) + expect(matmul!.get("gpu__time_duration.sum")).toBe(1000000) + }) +}) + +describe("ncu adapter — mapping validation", () => { + it("ncuMapping passes Vocabulary.validateMapping (anti-套壳 gate)", () => { + const result = Vocabulary.validateMapping(ncuMapping) + expect(result.ok).toBe(true) + expect(result.issues).toEqual([]) + }) + + it("mapping declares salu_busy_pct as null (ncu has no scalar ALU metric)", () => { + const saluEntry = ncuMapping.entries.find((e) => e.neutral === "salu_busy_pct") + expect(saluEntry).toBeDefined() + expect(saluEntry!.native).toBeNull() + expect((saluEntry as any).reason).toBe("metric_not_in_this_profiler") + }) + + it("mapping marks compute_bound as derived with formula", () => { + const entry = ncuMapping.entries.find((e) => e.neutral === "compute_bound") + expect(entry).toBeDefined() + expect((entry as any).derived).toBe(true) + expect((entry as any).formula).toContain("compute_throughput_pct") + }) + + it("mapping marks valu_utilization_pct as approximate", () => { + const entry = ncuMapping.entries.find((e) => e.neutral === "valu_utilization_pct") + expect(entry).toBeDefined() + expect((entry as any).semantic).toBe("approximate") + }) +}) + +describe("ncu adapter — parse→normalize pipeline", () => { + it("parse() reads CSV and returns a RawProfile with kernel hotspots", async () => { + const adapter = new NcuAdapter(installedNcuProbe(["ncu"])) + const ref: PAP.NativeReportRef = { path: fixturePath, format: "csv" } + const raw = await adapter.parse(ref) + + expect(raw.adapterId).toBe("ncu") + expect(raw.domain).toBe("gpu_kernel") + expect(raw.vendor).toBe("nvidia") + expect(raw.hotspots.length).toBe(2) + // Stage 2 preserves native names. + expect(Object.keys(raw.hotspots[0]!.nativeMetrics)).toContain("sm__throughput.avg.pct_of_peak_sustained_elapsed") + expect(Object.keys(raw.hotspots[0]!.nativeMetrics)).not.toContain("compute_throughput_pct") + }) + + it("normalize() maps to neutral metrics — no native names leak", async () => { + const adapter = new NcuAdapter(installedNcuProbe(["ncu"])) + const ref: PAP.NativeReportRef = { path: fixturePath, format: "csv" } + const raw = await adapter.parse(ref) + const np = adapter.normalize(raw) + + expect(np.adapterId).toBe("ncu") + expect(np.domain).toBe("gpu_kernel") + // Neutral names present. + expect(np.summary["compute_throughput_pct"]).toBeDefined() + expect(np.summary["memory_throughput_pct"]).toBeDefined() + expect(np.summary["dram_bandwidth_pct"]).toBeDefined() + expect(np.summary["l2_throughput_pct"]).toBeDefined() + expect(np.summary["occupancy_pct"]).toBeDefined() + expect(np.summary["valu_utilization_pct"]).toBeDefined() + expect(np.summary["salu_busy_pct"]).toBeDefined() + expect(np.summary["compute_bound"]).toBeDefined() + // No native names. + expect(np.summary["sm__throughput.avg.pct_of_peak_sustained_elapsed"]).toBeUndefined() + }) + + it("normalize() produces correct values (compute_throughput_pct = 85.5)", async () => { + const adapter = new NcuAdapter(installedNcuProbe(["ncu"])) + const ref: PAP.NativeReportRef = { path: fixturePath, format: "csv" } + const raw = await adapter.parse(ref) + const np = adapter.normalize(raw) + + const ct = np.summary["compute_throughput_pct"]! + expect(PAP.isPresent(ct)).toBe(true) + if (PAP.isPresent(ct)) { + expect(ct.value).toBeCloseTo(85.5, 3) + expect(ct.unit).toBe("pct") + expect(ct.provenance.semantic).toBe("exact") + } + }) + + it("normalize() marks salu_busy_pct as missing with correct reason", async () => { + const adapter = new NcuAdapter(installedNcuProbe(["ncu"])) + const ref: PAP.NativeReportRef = { path: fixturePath, format: "csv" } + const raw = await adapter.parse(ref) + const np = adapter.normalize(raw) + + const salu = np.summary["salu_busy_pct"]! + expect(PAP.isMissing(salu)).toBe(true) + if (PAP.isMissing(salu)) { + expect(salu.reason).toBe("metric_not_in_this_profiler") + } + }) + + it("normalize() marks valu_utilization_pct as approximate", async () => { + const adapter = new NcuAdapter(installedNcuProbe(["ncu"])) + const ref: PAP.NativeReportRef = { path: fixturePath, format: "csv" } + const raw = await adapter.parse(ref) + const np = adapter.normalize(raw) + + const valu = np.summary["valu_utilization_pct"]! + expect(PAP.isPresent(valu)).toBe(true) + if (PAP.isPresent(valu)) { + expect(valu.provenance.semantic).toBe("approximate") + } + }) + + it("normalize() compute_bound is derived=true with formula", async () => { + const adapter = new NcuAdapter(installedNcuProbe(["ncu"])) + const ref: PAP.NativeReportRef = { path: fixturePath, format: "csv" } + const raw = await adapter.parse(ref) + const np = adapter.normalize(raw) + + const cb = np.summary["compute_bound"]! + expect(PAP.isPresent(cb)).toBe(true) + if (PAP.isPresent(cb)) { + // matmul: compute=85.5 > memory=72.3 → compute-bound=true + expect(cb.value).toBe(true) + expect(cb.provenance.derived).toBe(true) + expect(cb.provenance.formula).toBeDefined() + } + }) + + it("normalize() duration_ns matches native value (1000000 ns)", async () => { + const adapter = new NcuAdapter(installedNcuProbe(["ncu"])) + const ref: PAP.NativeReportRef = { path: fixturePath, format: "csv" } + const raw = await adapter.parse(ref) + const np = adapter.normalize(raw) + + const dur = np.summary["duration_ns"]! + expect(PAP.isPresent(dur)).toBe(true) + if (PAP.isPresent(dur)) { + expect(dur.value).toBe(1000000) + expect(dur.unit).toBe("ns") + } + expect(np.duration_ns).toBe(1000000) + }) + + it("normalize() hotspots carry correct kernel names and per-kernel metrics", async () => { + const adapter = new NcuAdapter(installedNcuProbe(["ncu"])) + const ref: PAP.NativeReportRef = { path: fixturePath, format: "csv" } + const raw = await adapter.parse(ref) + const np = adapter.normalize(raw) + + expect(np.hotspots.length).toBe(2) + const matmulHotspot = np.hotspots.find((h) => h.kernel?.includes("matmul")) + expect(matmulHotspot).toBeDefined() + expect(matmulHotspot!.metrics["compute_throughput_pct"]).toBeDefined() + expect(matmulHotspot!.metrics["salu_busy_pct"]).toBeDefined() + // salu_busy_pct is missing in hotspot too. + expect(PAP.isMissing(matmulHotspot!.metrics["salu_busy_pct"]!)).toBe(true) + + // vectorAdd is memory-bound (compute=45.2 < memory=88.9). + const vecAddHotspot = np.hotspots.find((h) => h.kernel?.includes("vectorAdd")) + expect(vecAddHotspot).toBeDefined() + const vecCb = vecAddHotspot!.metrics["compute_bound"]! + if (PAP.isPresent(vecCb)) { + expect(vecCb.value).toBe(false) // memory-bound + } + }) + + it("NormalizedProfile passes PAP.validateProfile structural check", async () => { + const adapter = new NcuAdapter(installedNcuProbe(["ncu"])) + const ref: PAP.NativeReportRef = { path: fixturePath, format: "csv" } + const raw = await adapter.parse(ref) + const np = adapter.normalize(raw) + + const structural = PAP.validateProfile(np) + expect(structural.errors).toEqual([]) + expect(structural.ok).toBe(true) + }) + + it("NormalizedProfile passes Vocabulary.validateProfile conformance check", async () => { + const adapter = new NcuAdapter(installedNcuProbe(["ncu"])) + const ref: PAP.NativeReportRef = { path: fixturePath, format: "csv" } + const raw = await adapter.parse(ref) + const np = adapter.normalize(raw) + + const conformance = Vocabulary.validateProfile(np) + expect(conformance.errors).toEqual([]) + }) +}) diff --git a/packages/deepagent-code/test/deepagent/profile-adapter-nsys-normalize.test.ts b/packages/deepagent-code/test/deepagent/profile-adapter-nsys-normalize.test.ts new file mode 100644 index 00000000..54fb41ef --- /dev/null +++ b/packages/deepagent-code/test/deepagent/profile-adapter-nsys-normalize.test.ts @@ -0,0 +1,184 @@ +import { describe, it, expect, beforeAll, afterAll } from "bun:test" +import { writeFile, mkdtemp, rm } from "fs/promises" +import { join } from "path" +import { tmpdir } from "os" +import { PAP } from "@/profile/pap" +import { Vocabulary } from "@/profile/vocabulary" +import { NsysAdapter, nsysMapping, parseNsysMultiSectionCsv, parseGpukernsum, installedNsysProbe } from "@/profile/adapters/nsys" + +// Representative nsys stats CSV fixture in our multi-section format. +// Each section matches what `nsys stats --report --format csv` emits. +const NSYS_FIXTURE = `=== REPORT: gpukernsum === +Time (%),Total Time (ns),Instances,Average (ns),Minimum (ns),Maximum (ns),Name +62.5,1250000,100,12500,10000,20000,void matmul_kernel(float*,float*,float*,int) +15.3,306000,50,6120,5000,8000,void vectorAdd_kernel(float*,float*,float*,int) +10.2,204000,200,1020,800,1500,void transpose_kernel(float*,float*,int) +=== REPORT: gpumemtimesum === +Time (%),Total Time (ns),Count,Average (ns),Minimum (ns),Maximum (ns),Operation +8.5,170000,200,850,600,1200,CUDA Memcpy HtoD +3.5,70000,100,700,500,900,CUDA Memcpy DtoH +=== REPORT: cudaapisum === +Time (%),Total Time (ns),Num Calls,Average (ns),Minimum (ns),Maximum (ns),Name +3.2,64000,1000,64,50,200,cudaLaunchKernel +0.8,16000,400,40,30,80,cudaMemcpy +` + +let tmpDir: string +let fixturePath: string + +beforeAll(async () => { + tmpDir = await mkdtemp(join(tmpdir(), "deepagent-test-nsys-")) + fixturePath = join(tmpDir, "nsys-fixture.txt") + await writeFile(fixturePath, NSYS_FIXTURE, "utf8") +}) + +afterAll(async () => { + await rm(tmpDir, { recursive: true, force: true }) +}) + +describe("nsys adapter — CSV parsing", () => { + it("parseNsysMultiSectionCsv parses all three report sections", () => { + const { kernels, memOps, apiCalls } = parseNsysMultiSectionCsv(NSYS_FIXTURE) + expect(kernels.length).toBe(3) + expect(memOps.length).toBe(2) + expect(apiCalls.length).toBe(2) + }) + + it("gpukernsum: top kernel timePct is correct", () => { + const { kernels } = parseNsysMultiSectionCsv(NSYS_FIXTURE) + expect(kernels[0]!.name).toContain("matmul_kernel") + expect(kernels[0]!.timePct).toBeCloseTo(62.5, 3) + expect(kernels[0]!.totalTimeNs).toBe(1250000) + }) + + it("gpumemtimesum: memory copy total percent is aggregated", () => { + const { memOps } = parseNsysMultiSectionCsv(NSYS_FIXTURE) + const totalPct = memOps.reduce((s, r) => s + r.timePct, 0) + expect(totalPct).toBeCloseTo(12.0, 3) + }) + + it("cudaapisum: API overhead percent is aggregated", () => { + const { apiCalls } = parseNsysMultiSectionCsv(NSYS_FIXTURE) + const totalPct = apiCalls.reduce((s, r) => s + r.timePct, 0) + expect(totalPct).toBeCloseTo(4.0, 3) + }) +}) + +describe("nsys adapter — mapping validation", () => { + it("nsysMapping passes Vocabulary.validateMapping", () => { + const result = Vocabulary.validateMapping(nsysMapping) + expect(result.ok).toBe(true) + expect(result.issues).toEqual([]) + }) + + it("mapping covers all three gpu_timeline metrics (api_overhead honestly null)", () => { + const result = Vocabulary.validateMapping(nsysMapping) + expect(result.present).toContain("kernel_total_pct") + expect(result.present).toContain("mem_copy_pct") + // api_overhead_pct is declared null+reason (no valid GPU-total denominator from nsys stats), + // so it is covered via the `missing` set, not `present`. §P1A-V 映射原则 5. + expect(result.missing).toContain("api_overhead_pct") + }) +}) + +describe("nsys adapter — parse→normalize pipeline", () => { + it("parse() returns RawProfile with hotspots from gpukernsum", async () => { + const adapter = new NsysAdapter(installedNsysProbe(["nsys"])) + const ref: PAP.NativeReportRef = { path: fixturePath, format: "text" } + const raw = await adapter.parse(ref) + + expect(raw.adapterId).toBe("nsys") + expect(raw.domain).toBe("gpu_timeline") + expect(raw.vendor).toBe("nvidia") + expect(raw.hotspots.length).toBe(3) + // Stage 2 carries native keys + raw ns totals used to derive GPU-time shares. + expect(Object.keys(raw.nativeSummary)).toContain("kernel_time_pct") + expect(Object.keys(raw.nativeSummary)).toContain("mem_copy_time_pct") + expect(Object.keys(raw.nativeSummary)).toContain("kernel_ns_total") + expect(Object.keys(raw.nativeSummary)).toContain("mem_ns_total") + expect(Object.keys(raw.nativeSummary)).toContain("api_ns_total") + }) + + it("normalize() produces neutral metrics with correct values", async () => { + const adapter = new NsysAdapter(installedNsysProbe(["nsys"])) + const ref: PAP.NativeReportRef = { path: fixturePath, format: "text" } + const raw = await adapter.parse(ref) + const np = adapter.normalize(raw) + + expect(np.adapterId).toBe("nsys") + expect(np.domain).toBe("gpu_timeline") + + // kernel_total_pct = kernel_ns / (kernel_ns + mem_ns) — the share of GPU-side + // time spent in compute kernels. kernelNs=1,760,000, memNs=240,000 → 88.0%. + const kPct = np.summary["kernel_total_pct"]! + expect(PAP.isPresent(kPct)).toBe(true) + if (PAP.isPresent(kPct)) { + expect(kPct.value).toBeCloseTo(88.0, 3) + expect(kPct.unit).toBe("pct") + expect(kPct.provenance.semantic).toBe("exact") + } + + // mem_copy_pct = mem_ns / (kernel_ns + mem_ns) = 240,000 / 2,000,000 = 12.0%. + const mPct = np.summary["mem_copy_pct"]! + expect(PAP.isPresent(mPct)).toBe(true) + if (PAP.isPresent(mPct)) { + expect(mPct.value).toBeCloseTo(12.0, 3) + } + + // api_overhead_pct is honestly null — nsys stats gives no valid GPU/wall-total + // denominator, so we never fabricate a "share of total" percentage. + const aPct = np.summary["api_overhead_pct"]! + expect(PAP.isMissing(aPct)).toBe(true) + if (PAP.isMissing(aPct)) { + expect(aPct.reason).toBeTruthy() + } + }) + + it("normalize() hotspots carry kernel names and kernel_total_pct", async () => { + const adapter = new NsysAdapter(installedNsysProbe(["nsys"])) + const ref: PAP.NativeReportRef = { path: fixturePath, format: "text" } + const raw = await adapter.parse(ref) + const np = adapter.normalize(raw) + + expect(np.hotspots.length).toBe(3) + const matmulHotspot = np.hotspots.find((h) => h.kernel?.includes("matmul")) + expect(matmulHotspot).toBeDefined() + const kPct = matmulHotspot!.metrics["kernel_total_pct"]! + expect(PAP.isPresent(kPct)).toBe(true) + if (PAP.isPresent(kPct)) { + expect(kPct.value).toBeCloseTo(62.5, 3) + } + }) + + it("normalize() no native metric names leak into NormalizedProfile", async () => { + const adapter = new NsysAdapter(installedNsysProbe(["nsys"])) + const ref: PAP.NativeReportRef = { path: fixturePath, format: "text" } + const raw = await adapter.parse(ref) + const np = adapter.normalize(raw) + + // Native key "kernel_time_pct" should not appear in summary. + expect(np.summary["kernel_time_pct"]).toBeUndefined() + expect(np.summary["mem_copy_time_pct"]).toBeUndefined() + }) + + it("NormalizedProfile passes PAP.validateProfile structural check", async () => { + const adapter = new NsysAdapter(installedNsysProbe(["nsys"])) + const ref: PAP.NativeReportRef = { path: fixturePath, format: "text" } + const raw = await adapter.parse(ref) + const np = adapter.normalize(raw) + + const structural = PAP.validateProfile(np) + expect(structural.errors).toEqual([]) + expect(structural.ok).toBe(true) + }) + + it("NormalizedProfile passes Vocabulary.validateProfile conformance check", async () => { + const adapter = new NsysAdapter(installedNsysProbe(["nsys"])) + const ref: PAP.NativeReportRef = { path: fixturePath, format: "text" } + const raw = await adapter.parse(ref) + const np = adapter.normalize(raw) + + const conformance = Vocabulary.validateProfile(np) + expect(conformance.errors).toEqual([]) + }) +}) diff --git a/packages/deepagent-code/test/deepagent/profile-adapter-perf-normalize.test.ts b/packages/deepagent-code/test/deepagent/profile-adapter-perf-normalize.test.ts new file mode 100644 index 00000000..9f0463c0 --- /dev/null +++ b/packages/deepagent-code/test/deepagent/profile-adapter-perf-normalize.test.ts @@ -0,0 +1,248 @@ +import { describe, it, expect, beforeAll, afterAll } from "bun:test" +import { writeFile, mkdtemp, rm } from "fs/promises" +import { join } from "path" +import { tmpdir } from "os" +import { PAP } from "@/profile/pap" +import { Vocabulary } from "@/profile/vocabulary" +import { PerfAdapter, perfMapping, parsePerfReport, parsePerfStat, parsePerfMultiSection, installedPerfProbe } from "@/profile/adapters/perf" + +// Representative perf multi-section fixture. +// Section perf_report: `perf report --stdio -n` format. +// Section perf_stat: `perf stat` format. +const PERF_FIXTURE = `=== SECTION: perf_report === +# Overhead Command Shared Object Symbol + 62.50% bench bench [.] compute_kernel + 20.00% bench libc.so [.] memcpy + 5.30% bench bench [.] io_thread_main + 3.20% bench [kernel] [k] copy_user_generic_string + 2.10% bench bench [.] sort_inplace +=== SECTION: perf_stat === + Performance counter stats for './bench': + + 2,000,000 cycles # 1.500 GHz + 1,000,000 instructions # 0.50 insn per cycle + 50,000 cache-misses # 50.000 % of all cache refs + 100,000 cache-references + 10,000 branch-misses # 5.000 % of all branches + 200,000 branches + + 0.001334 seconds time elapsed +` + +let tmpDir: string +let fixturePath: string + +beforeAll(async () => { + tmpDir = await mkdtemp(join(tmpdir(), "deepagent-test-perf-")) + fixturePath = join(tmpDir, "perf-fixture.txt") + await writeFile(fixturePath, PERF_FIXTURE, "utf8") +}) + +afterAll(async () => { + await rm(tmpDir, { recursive: true, force: true }) +}) + +describe("perf adapter — text parsing", () => { + it("parsePerfReport extracts symbol rows from perf report --stdio", () => { + const { reportRows } = parsePerfMultiSection(PERF_FIXTURE) + expect(reportRows.length).toBe(5) + expect(reportRows[0]!.symbol).toBe("compute_kernel") + expect(reportRows[0]!.overheadPct).toBeCloseTo(62.5, 3) + expect(reportRows[1]!.symbol).toBe("memcpy") + expect(reportRows[1]!.overheadPct).toBeCloseTo(20.0, 3) + }) + + it("parsePerfStat extracts event counts from perf stat", () => { + const { statCounts } = parsePerfMultiSection(PERF_FIXTURE) + expect(statCounts.get("cycles")).toBe(2000000) + expect(statCounts.get("instructions")).toBe(1000000) + expect(statCounts.get("cache-misses")).toBe(50000) + expect(statCounts.get("cache-references")).toBe(100000) + expect(statCounts.get("branch-misses")).toBe(10000) + expect(statCounts.get("branches")).toBe(200000) + }) +}) + +describe("perf adapter — mapping validation", () => { + it("perfMapping passes Vocabulary.validateMapping (anti-套壳 gate)", () => { + const result = Vocabulary.validateMapping(perfMapping) + expect(result.ok).toBe(true) + expect(result.issues).toEqual([]) + }) + + it("mapping covers all cpu_sampling metrics (memory_bound_pct/dram_bound_pct excluded — cpu_hotspot only)", () => { + const result = Vocabulary.validateMapping(perfMapping) + const samplingMetrics = Vocabulary.metricsForDomain("cpu_sampling").map((m) => m.name) + // All cpu_sampling domain metrics should be covered. + for (const m of samplingMetrics) { + expect(result.present.concat(result.missing)).toContain(m) + } + // cpu_sampling does NOT include memory_bound_pct or dram_bound_pct. + expect(samplingMetrics).not.toContain("memory_bound_pct") + expect(samplingMetrics).not.toContain("dram_bound_pct") + }) + + it("mapping marks ipc as derived with formula", () => { + const entry = perfMapping.entries.find((e) => e.neutral === "ipc") + expect(entry).toBeDefined() + expect((entry as any).derived).toBe(true) + expect((entry as any).formula).toBe("instructions / cycles") + }) + + it("mapping marks cpi as NOT derived (vocab: derived:false)", () => { + const entry = perfMapping.entries.find((e) => e.neutral === "cpi") + expect(entry).toBeDefined() + expect((entry as any).derived).toBeFalsy() + expect((entry as any).native).toContain("cycles") + expect((entry as any).native).toContain("instructions") + }) +}) + +describe("perf adapter — parse→normalize pipeline", () => { + it("parse() reads fixture and returns RawProfile with symbol hotspots", async () => { + const adapter = new PerfAdapter(installedPerfProbe(["perf"])) + const ref: PAP.NativeReportRef = { path: fixturePath, format: "text" } + const raw = await adapter.parse(ref) + + expect(raw.adapterId).toBe("perf") + expect(raw.domain).toBe("cpu_sampling") + expect(raw.vendor).toBe("cpu_generic") + expect(raw.hotspots.length).toBe(5) + // Stage 2 preserves native names. + expect(Object.keys(raw.nativeSummary)).toContain("cycles") + expect(Object.keys(raw.nativeSummary)).toContain("instructions") + // No neutral names in stage 2. + expect(Object.keys(raw.nativeSummary)).not.toContain("ipc") + }) + + it("normalize() hotspots map overhead% to self_pct", async () => { + const adapter = new PerfAdapter(installedPerfProbe(["perf"])) + const ref: PAP.NativeReportRef = { path: fixturePath, format: "text" } + const raw = await adapter.parse(ref) + const np = adapter.normalize(raw) + + expect(np.hotspots.length).toBe(5) + const compute = np.hotspots.find((h) => h.symbol === "compute_kernel")! + expect(compute.self_pct).toBeCloseTo(62.5, 3) + const selfPct = compute.metrics["self_pct"]! + expect(PAP.isPresent(selfPct)).toBe(true) + if (PAP.isPresent(selfPct)) { + expect(selfPct.value).toBeCloseTo(62.5, 3) + expect(selfPct.unit).toBe("pct") + expect(selfPct.provenance.semantic).toBe("exact") + } + }) + + it("normalize() summary: cpi = cycles / instructions = 2.0", async () => { + const adapter = new PerfAdapter(installedPerfProbe(["perf"])) + const ref: PAP.NativeReportRef = { path: fixturePath, format: "text" } + const raw = await adapter.parse(ref) + const np = adapter.normalize(raw) + + // cycles=2,000,000; instructions=1,000,000 → cpi=2.0 + const cpi = np.summary["cpi"]! + expect(PAP.isPresent(cpi)).toBe(true) + if (PAP.isPresent(cpi)) { + expect(cpi.value).toBeCloseTo(2.0, 5) + expect(cpi.unit).toBe("ratio") + // cpi is computed from cycles/instructions but vocab says derived:false. + expect(cpi.provenance.nativeMetric).toContain("cycles") + } + }) + + it("normalize() summary: ipc = instructions / cycles = 0.5 (derived, with formula)", async () => { + const adapter = new PerfAdapter(installedPerfProbe(["perf"])) + const ref: PAP.NativeReportRef = { path: fixturePath, format: "text" } + const raw = await adapter.parse(ref) + const np = adapter.normalize(raw) + + // ipc = 1,000,000 / 2,000,000 = 0.5 + const ipc = np.summary["ipc"]! + expect(PAP.isPresent(ipc)).toBe(true) + if (PAP.isPresent(ipc)) { + expect(ipc.value).toBeCloseTo(0.5, 5) + expect(ipc.unit).toBe("ratio") + expect(ipc.provenance.derived).toBe(true) + expect(ipc.provenance.formula).toBe("instructions / cycles") + } + }) + + it("normalize() summary: cache_miss_rate = cache-misses / cache-references = 0.5", async () => { + const adapter = new PerfAdapter(installedPerfProbe(["perf"])) + const ref: PAP.NativeReportRef = { path: fixturePath, format: "text" } + const raw = await adapter.parse(ref) + const np = adapter.normalize(raw) + + // cache-misses=50,000; cache-references=100,000 → miss_rate=0.5 + const cmr = np.summary["cache_miss_rate"]! + expect(PAP.isPresent(cmr)).toBe(true) + if (PAP.isPresent(cmr)) { + expect(cmr.value).toBeCloseTo(0.5, 5) + expect(cmr.unit).toBe("ratio") + } + }) + + it("normalize() summary: branch_misprediction_pct = branch-misses/branches*100 = 5%", async () => { + const adapter = new PerfAdapter(installedPerfProbe(["perf"])) + const ref: PAP.NativeReportRef = { path: fixturePath, format: "text" } + const raw = await adapter.parse(ref) + const np = adapter.normalize(raw) + + // branch-misses=10,000; branches=200,000 → 5% + const bmp = np.summary["branch_misprediction_pct"]! + expect(PAP.isPresent(bmp)).toBe(true) + if (PAP.isPresent(bmp)) { + expect(bmp.value).toBeCloseTo(5.0, 5) + expect(bmp.unit).toBe("pct") + } + }) + + it("normalize() per-symbol cpi/ipc are honestly null (require perf annotate)", async () => { + const adapter = new PerfAdapter(installedPerfProbe(["perf"])) + const ref: PAP.NativeReportRef = { path: fixturePath, format: "text" } + const raw = await adapter.parse(ref) + const np = adapter.normalize(raw) + + const compute = np.hotspots.find((h) => h.symbol === "compute_kernel")! + const perSymCpi = compute.metrics["cpi"]! + expect(PAP.isMissing(perSymCpi)).toBe(true) + if (PAP.isMissing(perSymCpi)) { + expect(perSymCpi.reason).toBe("not_collected") + } + const perSymIpc = compute.metrics["ipc"]! + expect(PAP.isMissing(perSymIpc)).toBe(true) + }) + + it("normalize() no native metric names leak", async () => { + const adapter = new PerfAdapter(installedPerfProbe(["perf"])) + const ref: PAP.NativeReportRef = { path: fixturePath, format: "text" } + const raw = await adapter.parse(ref) + const np = adapter.normalize(raw) + + expect(np.summary["cycles"]).toBeUndefined() + expect(np.summary["instructions"]).toBeUndefined() + expect(np.summary["cache-misses"]).toBeUndefined() + expect(np.summary["overhead"]).toBeUndefined() + }) + + it("NormalizedProfile passes PAP.validateProfile structural check", async () => { + const adapter = new PerfAdapter(installedPerfProbe(["perf"])) + const ref: PAP.NativeReportRef = { path: fixturePath, format: "text" } + const raw = await adapter.parse(ref) + const np = adapter.normalize(raw) + + const structural = PAP.validateProfile(np) + expect(structural.errors).toEqual([]) + expect(structural.ok).toBe(true) + }) + + it("NormalizedProfile passes Vocabulary.validateProfile conformance check", async () => { + const adapter = new PerfAdapter(installedPerfProbe(["perf"])) + const ref: PAP.NativeReportRef = { path: fixturePath, format: "text" } + const raw = await adapter.parse(ref) + const np = adapter.normalize(raw) + + const conformance = Vocabulary.validateProfile(np) + expect(conformance.errors).toEqual([]) + }) +}) diff --git a/packages/deepagent-code/test/deepagent/profile-adapter-rocprof-normalize.test.ts b/packages/deepagent-code/test/deepagent/profile-adapter-rocprof-normalize.test.ts new file mode 100644 index 00000000..229e0748 --- /dev/null +++ b/packages/deepagent-code/test/deepagent/profile-adapter-rocprof-normalize.test.ts @@ -0,0 +1,219 @@ +import { describe, it, expect, beforeAll, afterAll } from "bun:test" +import { writeFile, mkdtemp, rm } from "fs/promises" +import { join } from "path" +import { tmpdir } from "os" +import { PAP } from "@/profile/pap" +import { Vocabulary } from "@/profile/vocabulary" +import { RocprofAdapter, rocprofMapping, parseRocprofCsv, installedRocprofProbe } from "@/profile/adapters/rocprof" + +// Representative rocprofv3 CSV fixture. +// Columns: Kernel_Name, gpu-id, queue-id, queue-index, pid, tid, grd, wgr, lds, scr, +// arch_vgpr, accum_vgpr, phys_vgpr, phys_sgpr, sig, obj, +// GPUBusy, MemUnitBusy, VALUUtilization, SALUBusy, Wavefronts, L2CacheHit, +// BeginNs, EndNs +const ROCPROF_FIXTURE_CSV = `Kernel_Name,gpu-id,queue-id,queue-index,pid,tid,grd,wgr,lds,scr,arch_vgpr,accum_vgpr,phys_vgpr,phys_sgpr,sig,obj,GPUBusy,MemUnitBusy,VALUUtilization,SALUBusy,Wavefronts,L2CacheHit,BeginNs,EndNs +rocblas_gemm_kernel,0,0,0,12345,67890,262144,256,0,0,32,0,32,16,0,0,88.5,65.3,78.2,12.5,4096,82.3,1000000,1050000 +hip_vector_add,0,0,1,12345,67890,65536,64,0,0,16,0,16,8,0,0,45.2,88.9,32.1,8.3,1024,91.5,1060000,1085000 +rocblas_gemm_kernel,0,0,2,12345,67890,262144,256,0,0,32,0,32,16,0,0,90.1,62.8,81.5,13.2,4096,80.1,1090000,1140000 +` + +let tmpDir: string +let fixturePath: string + +beforeAll(async () => { + tmpDir = await mkdtemp(join(tmpdir(), "deepagent-test-rocprof-")) + fixturePath = join(tmpDir, "rocprof-fixture.csv") + await writeFile(fixturePath, ROCPROF_FIXTURE_CSV, "utf8") +}) + +afterAll(async () => { + await rm(tmpDir, { recursive: true, force: true }) +}) + +describe("rocprof adapter — CSV parsing", () => { + it("parseRocprofCsv extracts kernel rows correctly", () => { + const rows = parseRocprofCsv(ROCPROF_FIXTURE_CSV) + expect(rows.length).toBe(3) + expect(rows[0]!.kernelName).toBe("rocblas_gemm_kernel") + expect(rows[0]!.metrics["GPUBusy"]).toBeCloseTo(88.5, 3) + expect(rows[0]!.metrics["MemUnitBusy"]).toBeCloseTo(65.3, 3) + expect(rows[0]!.metrics["VALUUtilization"]).toBeCloseTo(78.2, 3) + expect(rows[0]!.metrics["SALUBusy"]).toBeCloseTo(12.5, 3) + expect(rows[0]!.metrics["Wavefronts"]).toBe(4096) + expect(rows[0]!.metrics["L2CacheHit"]).toBeCloseTo(82.3, 3) + expect(rows[0]!.metrics["BeginNs"]).toBe(1000000) + expect(rows[0]!.metrics["EndNs"]).toBe(1050000) + }) +}) + +describe("rocprof adapter — mapping validation", () => { + it("rocprofMapping passes Vocabulary.validateMapping (anti-套壳 gate)", () => { + const result = Vocabulary.validateMapping(rocprofMapping) + expect(result.ok).toBe(true) + expect(result.issues).toEqual([]) + }) + + it("mapping marks GPUBusy→compute_throughput_pct as approximate", () => { + const entry = rocprofMapping.entries.find((e) => e.neutral === "compute_throughput_pct") + expect(entry).toBeDefined() + expect((entry as any).native).toBe("GPUBusy") + expect((entry as any).semantic).toBe("approximate") + }) + + it("mapping marks L2CacheHit→l2_throughput_pct as approximate (hit-rate ≠ throughput)", () => { + const entry = rocprofMapping.entries.find((e) => e.neutral === "l2_throughput_pct") + expect(entry).toBeDefined() + expect((entry as any).native).toBe("L2CacheHit") + expect((entry as any).semantic).toBe("approximate") + }) + + it("mapping marks salu_busy_pct as present (AMD-native metric)", () => { + const entry = rocprofMapping.entries.find((e) => e.neutral === "salu_busy_pct") + expect(entry).toBeDefined() + expect((entry as any).native).toBe("SALUBusy") + }) + + it("mapping marks compute_bound as derived with formula", () => { + const entry = rocprofMapping.entries.find((e) => e.neutral === "compute_bound") + expect(entry).toBeDefined() + expect((entry as any).derived).toBe(true) + expect((entry as any).formula).toContain("GPUBusy") + expect((entry as any).semantic).toBe("approximate") + }) + + it("mapping declares duration_ns from BeginNs+EndNs", () => { + const entry = rocprofMapping.entries.find((e) => e.neutral === "duration_ns") + expect(entry).toBeDefined() + expect((entry as any).native).toContain("BeginNs") + expect((entry as any).native).toContain("EndNs") + }) +}) + +describe("rocprof adapter — parse→normalize pipeline", () => { + it("parse() reads CSV and returns RawProfile with kernel hotspots", async () => { + const adapter = new RocprofAdapter(installedRocprofProbe(["rocprofv3"])) + const ref: PAP.NativeReportRef = { path: fixturePath, format: "csv" } + const raw = await adapter.parse(ref) + + expect(raw.adapterId).toBe("rocprof") + expect(raw.domain).toBe("gpu_kernel") + expect(raw.vendor).toBe("amd") + expect(raw.hotspots.length).toBe(3) + // Stage 2 preserves native names. + expect(Object.keys(raw.hotspots[0]!.nativeMetrics)).toContain("GPUBusy") + expect(Object.keys(raw.hotspots[0]!.nativeMetrics)).not.toContain("compute_throughput_pct") + }) + + it("normalize() maps GPUBusy to compute_throughput_pct with approximate provenance", async () => { + const adapter = new RocprofAdapter(installedRocprofProbe(["rocprofv3"])) + const ref: PAP.NativeReportRef = { path: fixturePath, format: "csv" } + const raw = await adapter.parse(ref) + const np = adapter.normalize(raw) + + const ct = np.summary["compute_throughput_pct"]! + expect(PAP.isPresent(ct)).toBe(true) + if (PAP.isPresent(ct)) { + expect(ct.value).toBeCloseTo(88.5, 3) + expect(ct.unit).toBe("pct") + expect(ct.provenance.semantic).toBe("approximate") // GPUBusy ≠ SM compute throughput + expect(ct.provenance.nativeMetric).toBe("GPUBusy") + } + }) + + it("normalize() maps L2CacheHit to l2_throughput_pct as approximate", async () => { + const adapter = new RocprofAdapter(installedRocprofProbe(["rocprofv3"])) + const ref: PAP.NativeReportRef = { path: fixturePath, format: "csv" } + const raw = await adapter.parse(ref) + const np = adapter.normalize(raw) + + const l2 = np.summary["l2_throughput_pct"]! + expect(PAP.isPresent(l2)).toBe(true) + if (PAP.isPresent(l2)) { + expect(l2.value).toBeCloseTo(82.3, 3) + // MUST be approximate: L2CacheHit is hit-rate, not throughput. + expect(l2.provenance.semantic).toBe("approximate") + } + }) + + it("normalize() maps SALUBusy to salu_busy_pct with exact provenance (AMD-native)", async () => { + const adapter = new RocprofAdapter(installedRocprofProbe(["rocprofv3"])) + const ref: PAP.NativeReportRef = { path: fixturePath, format: "csv" } + const raw = await adapter.parse(ref) + const np = adapter.normalize(raw) + + const salu = np.summary["salu_busy_pct"]! + expect(PAP.isPresent(salu)).toBe(true) + if (PAP.isPresent(salu)) { + expect(salu.value).toBeCloseTo(12.5, 3) + expect(salu.provenance.semantic).toBe("exact") + expect(salu.provenance.nativeMetric).toBe("SALUBusy") + } + }) + + it("normalize() duration_ns = EndNs - BeginNs = 50000", async () => { + const adapter = new RocprofAdapter(installedRocprofProbe(["rocprofv3"])) + const ref: PAP.NativeReportRef = { path: fixturePath, format: "csv" } + const raw = await adapter.parse(ref) + const np = adapter.normalize(raw) + + const dur = np.summary["duration_ns"]! + expect(PAP.isPresent(dur)).toBe(true) + if (PAP.isPresent(dur)) { + expect(dur.value).toBe(50000) // 1050000 - 1000000 + expect(dur.unit).toBe("ns") + } + }) + + it("normalize() compute_bound is derived with approximate semantics", async () => { + const adapter = new RocprofAdapter(installedRocprofProbe(["rocprofv3"])) + const ref: PAP.NativeReportRef = { path: fixturePath, format: "csv" } + const raw = await adapter.parse(ref) + const np = adapter.normalize(raw) + + const cb = np.summary["compute_bound"]! + expect(PAP.isPresent(cb)).toBe(true) + if (PAP.isPresent(cb)) { + // GPUBusy=88.5 > MemUnitBusy=65.3 → true + expect(cb.value).toBe(true) + expect(cb.provenance.derived).toBe(true) + expect(cb.provenance.semantic).toBe("approximate") + expect(cb.provenance.formula).toBeDefined() + } + }) + + it("normalize() hotspots include salu_busy_pct (AMD-exclusive metric)", async () => { + const adapter = new RocprofAdapter(installedRocprofProbe(["rocprofv3"])) + const ref: PAP.NativeReportRef = { path: fixturePath, format: "csv" } + const raw = await adapter.parse(ref) + const np = adapter.normalize(raw) + + const gemm = np.hotspots.find((h) => h.kernel?.includes("gemm")) + expect(gemm).toBeDefined() + const saluInHotspot = gemm!.metrics["salu_busy_pct"]! + expect(PAP.isPresent(saluInHotspot)).toBe(true) + if (PAP.isPresent(saluInHotspot)) { + expect(saluInHotspot.value).toBeCloseTo(12.5, 3) + } + }) + + it("NormalizedProfile passes PAP.validateProfile structural check", async () => { + const adapter = new RocprofAdapter(installedRocprofProbe(["rocprofv3"])) + const ref: PAP.NativeReportRef = { path: fixturePath, format: "csv" } + const raw = await adapter.parse(ref) + const np = adapter.normalize(raw) + + const structural = PAP.validateProfile(np) + expect(structural.errors).toEqual([]) + expect(structural.ok).toBe(true) + }) + + it("NormalizedProfile passes Vocabulary.validateProfile conformance check", async () => { + const adapter = new RocprofAdapter(installedRocprofProbe(["rocprofv3"])) + const ref: PAP.NativeReportRef = { path: fixturePath, format: "csv" } + const raw = await adapter.parse(ref) + const np = adapter.normalize(raw) + + const conformance = Vocabulary.validateProfile(np) + expect(conformance.errors).toEqual([]) + }) +}) diff --git a/packages/deepagent-code/test/deepagent/profile-adapter-vtune-normalize.test.ts b/packages/deepagent-code/test/deepagent/profile-adapter-vtune-normalize.test.ts new file mode 100644 index 00000000..6821c4ff --- /dev/null +++ b/packages/deepagent-code/test/deepagent/profile-adapter-vtune-normalize.test.ts @@ -0,0 +1,215 @@ +import { describe, it, expect, beforeAll, afterAll } from "bun:test" +import { writeFile, mkdtemp, rm } from "fs/promises" +import { join } from "path" +import { tmpdir } from "os" +import { PAP } from "@/profile/pap" +import { Vocabulary } from "@/profile/vocabulary" +import { VtuneAdapter, vtuneMapping, parseVtuneCsv, installedVtuneProbe } from "@/profile/adapters/vtune" + +// Representative `vtune -report hotspots -format=csv` fixture. +// Column names match Intel VTune CPU Metrics Reference. +const VTUNE_FIXTURE_CSV = `Function,CPU Time,CPU Time:Self,CPI Rate,Clockticks,Instructions Retired,Memory Bound,DRAM Bound,LLC Miss Ratio,Bad Speculation +compute_matrix,80.0%,75.0%,3.2,2560000,800000,40.1%,15.2%,0.08,2.1% +io_thread,12.5%,10.0%,1.8,900000,500000,18.5%,5.3%,0.03,1.2% +main,5.0%,4.0%,2.1,210000,100000,12.3%,3.1%,0.01,0.5% +sort_helper,2.5%,2.5%,4.5,562500,125000,55.2%,22.8%,0.15,3.8% +` + +let tmpDir: string +let fixturePath: string + +beforeAll(async () => { + tmpDir = await mkdtemp(join(tmpdir(), "deepagent-test-vtune-")) + fixturePath = join(tmpDir, "vtune-fixture.csv") + await writeFile(fixturePath, VTUNE_FIXTURE_CSV, "utf8") +}) + +afterAll(async () => { + await rm(tmpDir, { recursive: true, force: true }) +}) + +describe("vtune adapter — CSV parsing", () => { + it("parseVtuneCsv extracts function rows correctly", () => { + const rows = parseVtuneCsv(VTUNE_FIXTURE_CSV) + expect(rows.length).toBe(4) + expect(rows[0]!.functionName).toBe("compute_matrix") + expect(rows[0]!.cpuTimePct).toBeCloseTo(80.0, 3) + expect(rows[0]!.cpuTimeSelfPct).toBeCloseTo(75.0, 3) + expect(rows[0]!.cpiRate).toBeCloseTo(3.2, 3) + expect(rows[0]!.clockticks).toBe(2560000) + expect(rows[0]!.instructionsRetired).toBe(800000) + expect(rows[0]!.memoryBound).toBeCloseTo(40.1, 3) + expect(rows[0]!.dramBound).toBeCloseTo(15.2, 3) + expect(rows[0]!.llcMissRatio).toBeCloseTo(0.08, 4) + expect(rows[0]!.badSpeculation).toBeCloseTo(2.1, 3) + }) +}) + +describe("vtune adapter — mapping validation", () => { + it("vtuneMapping passes Vocabulary.validateMapping (anti-套壳 gate)", () => { + const result = Vocabulary.validateMapping(vtuneMapping) + expect(result.ok).toBe(true) + expect(result.issues).toEqual([]) + }) + + it("mapping covers all cpu_hotspot metrics", () => { + const result = Vocabulary.validateMapping(vtuneMapping) + // cpu_hotspot domain has self_pct, cpi, ipc, clockticks, instructions_retired, + // memory_bound_pct, dram_bound_pct, cache_miss_rate, branch_misprediction_pct + const domainMetrics = Vocabulary.metricsForDomain("cpu_hotspot").map((m) => m.name) + for (const m of domainMetrics) { + expect(result.present.concat(result.missing)).toContain(m) + } + expect(result.missing).toHaveLength(0) // vtune covers all + }) + + it("mapping marks ipc as derived (1/CPI) with formula", () => { + const entry = vtuneMapping.entries.find((e) => e.neutral === "ipc") + expect(entry).toBeDefined() + expect((entry as any).derived).toBe(true) + expect((entry as any).formula).toContain("CPI Rate") + }) + + it("mapping marks cpi as NOT derived (VTune provides CPI Rate natively)", () => { + const entry = vtuneMapping.entries.find((e) => e.neutral === "cpi") + expect(entry).toBeDefined() + expect((entry as any).derived).toBeFalsy() + expect((entry as any).native).toBe("CPI Rate") + }) +}) + +describe("vtune adapter — parse→normalize pipeline", () => { + it("parse() reads CSV and returns RawProfile with function hotspots", async () => { + const adapter = new VtuneAdapter(installedVtuneProbe(["vtune"])) + const ref: PAP.NativeReportRef = { path: fixturePath, format: "csv" } + const raw = await adapter.parse(ref) + + expect(raw.adapterId).toBe("vtune") + expect(raw.domain).toBe("cpu_hotspot") + expect(raw.vendor).toBe("intel") + expect(raw.hotspots.length).toBe(4) + // Stage 2 preserves native names. + expect(Object.keys(raw.hotspots[0]!.nativeMetrics)).toContain("CPI Rate") + expect(Object.keys(raw.hotspots[0]!.nativeMetrics)).not.toContain("cpi") + }) + + it("normalize() maps CPI Rate → cpi with exact provenance", async () => { + const adapter = new VtuneAdapter(installedVtuneProbe(["vtune"])) + const ref: PAP.NativeReportRef = { path: fixturePath, format: "csv" } + const raw = await adapter.parse(ref) + const np = adapter.normalize(raw) + + const compute = np.hotspots.find((h) => h.symbol === "compute_matrix")! + const cpi = compute.metrics["cpi"]! + expect(PAP.isPresent(cpi)).toBe(true) + if (PAP.isPresent(cpi)) { + expect(cpi.value).toBeCloseTo(3.2, 3) + expect(cpi.unit).toBe("ratio") + expect(cpi.provenance.semantic).toBe("exact") + expect(cpi.provenance.nativeMetric).toBe("CPI Rate") + } + }) + + it("normalize() ipc = 1 / CPI Rate (derived, with formula)", async () => { + const adapter = new VtuneAdapter(installedVtuneProbe(["vtune"])) + const ref: PAP.NativeReportRef = { path: fixturePath, format: "csv" } + const raw = await adapter.parse(ref) + const np = adapter.normalize(raw) + + const compute = np.hotspots.find((h) => h.symbol === "compute_matrix")! + const ipc = compute.metrics["ipc"]! + expect(PAP.isPresent(ipc)).toBe(true) + if (PAP.isPresent(ipc)) { + // ipc = 1 / 3.2 ≈ 0.3125 + expect(ipc.value).toBeCloseTo(1 / 3.2, 5) + expect(ipc.unit).toBe("ratio") + expect(ipc.provenance.derived).toBe(true) + expect(ipc.provenance.formula).toBe("1 / CPI Rate") + } + }) + + it("normalize() memory_bound_pct and dram_bound_pct are present (cpu_hotspot exclusive)", async () => { + const adapter = new VtuneAdapter(installedVtuneProbe(["vtune"])) + const ref: PAP.NativeReportRef = { path: fixturePath, format: "csv" } + const raw = await adapter.parse(ref) + const np = adapter.normalize(raw) + + const sortHotspot = np.hotspots.find((h) => h.symbol === "sort_helper")! + const memBound = sortHotspot.metrics["memory_bound_pct"]! + expect(PAP.isPresent(memBound)).toBe(true) + if (PAP.isPresent(memBound)) { + expect(memBound.value).toBeCloseTo(55.2, 3) + expect(memBound.unit).toBe("pct") + } + + const dramBound = sortHotspot.metrics["dram_bound_pct"]! + expect(PAP.isPresent(dramBound)).toBe(true) + if (PAP.isPresent(dramBound)) { + expect(dramBound.value).toBeCloseTo(22.8, 3) + } + }) + + it("normalize() cache_miss_rate from LLC Miss Ratio (ratio 0-1)", async () => { + const adapter = new VtuneAdapter(installedVtuneProbe(["vtune"])) + const ref: PAP.NativeReportRef = { path: fixturePath, format: "csv" } + const raw = await adapter.parse(ref) + const np = adapter.normalize(raw) + + const compute = np.hotspots.find((h) => h.symbol === "compute_matrix")! + const cmr = compute.metrics["cache_miss_rate"]! + expect(PAP.isPresent(cmr)).toBe(true) + if (PAP.isPresent(cmr)) { + // 0.08 is already 0-1, should stay as-is. + expect(cmr.value).toBeCloseTo(0.08, 4) + expect(cmr.unit).toBe("ratio") + } + }) + + it("normalize() branch_misprediction_pct from Bad Speculation", async () => { + const adapter = new VtuneAdapter(installedVtuneProbe(["vtune"])) + const ref: PAP.NativeReportRef = { path: fixturePath, format: "csv" } + const raw = await adapter.parse(ref) + const np = adapter.normalize(raw) + + const compute = np.hotspots.find((h) => h.symbol === "compute_matrix")! + const bmp = compute.metrics["branch_misprediction_pct"]! + expect(PAP.isPresent(bmp)).toBe(true) + if (PAP.isPresent(bmp)) { + expect(bmp.value).toBeCloseTo(2.1, 3) + expect(bmp.unit).toBe("pct") + } + }) + + it("normalize() no native metric names leak", async () => { + const adapter = new VtuneAdapter(installedVtuneProbe(["vtune"])) + const ref: PAP.NativeReportRef = { path: fixturePath, format: "csv" } + const raw = await adapter.parse(ref) + const np = adapter.normalize(raw) + + const compute = np.hotspots[0]! + expect(compute.metrics["CPI Rate"]).toBeUndefined() + expect(compute.metrics["Memory Bound"]).toBeUndefined() + expect(compute.metrics["Bad Speculation"]).toBeUndefined() + }) + + it("NormalizedProfile passes PAP.validateProfile structural check", async () => { + const adapter = new VtuneAdapter(installedVtuneProbe(["vtune"])) + const ref: PAP.NativeReportRef = { path: fixturePath, format: "csv" } + const raw = await adapter.parse(ref) + const np = adapter.normalize(raw) + + const structural = PAP.validateProfile(np) + expect(structural.errors).toEqual([]) + expect(structural.ok).toBe(true) + }) + + it("NormalizedProfile passes Vocabulary.validateProfile conformance check", async () => { + const adapter = new VtuneAdapter(installedVtuneProbe(["vtune"])) + const ref: PAP.NativeReportRef = { path: fixturePath, format: "csv" } + const raw = await adapter.parse(ref) + const np = adapter.normalize(raw) + + const conformance = Vocabulary.validateProfile(np) + expect(conformance.errors).toEqual([]) + }) +}) diff --git a/packages/deepagent-code/test/deepagent/profile-before-after-diff.test.ts b/packages/deepagent-code/test/deepagent/profile-before-after-diff.test.ts new file mode 100644 index 00000000..7c809a39 --- /dev/null +++ b/packages/deepagent-code/test/deepagent/profile-before-after-diff.test.ts @@ -0,0 +1,267 @@ +import { describe, it, expect } from "bun:test" +import { PAP } from "@/profile/pap" +import { ProfileService } from "@/profile/service" + +// P4A (S1-v3.5): ProfileService.diff shows which hotspots improved/worsened +// between two profiling runs. Also validates cross-vendor diff capability: since +// both profiles use the neutral vocabulary, NVIDIA and AMD results are comparable. + +// ——— helpers ———————————————————————————————————————————————————————————————— + +function makeHotspot( + name: string, + isKernel: boolean, + selfPct: number, + metrics: Record, +): PAP.Hotspot { + const bag: Record = {} + for (const [k, v] of Object.entries(metrics)) { + bag[k] = PAP.present(v, "pct", { nativeMetric: k, semantic: "exact" }) + } + return { + ...(isKernel ? { kernel: name } : { symbol: name }), + self_pct: selfPct, + metrics: bag, + } +} + +function makeProfile( + vendor: PAP.Vendor, + domain: PAP.Domain, + hotspots: PAP.Hotspot[], + summary?: Record, +): PAP.NormalizedProfile { + return { + domain, + vendor, + adapterId: vendor === "nvidia" ? "fake-ncu" : vendor === "amd" ? "fake-rocprof" : "fake-perf", + target: { command: "bench" }, + duration_ns: 100_000, + hotspots, + summary: summary ?? {}, + raw_report_ref: { path: "/tmp/bench.rep", format: vendor === "nvidia" ? "ncu-rep" : vendor === "amd" ? "rocpd" : "perf-data" }, + } +} + +// ——— same-vendor diff ———————————————————————————————————————————————————————— + +describe("ProfileService.diff — before/after optimization (same vendor)", () => { + // Before: matmul_kernel hogs 72% and is memory-bound (DRAM=91%), + // reduce_kernel is 20%. + const before = makeProfile("nvidia", "gpu_kernel", [ + makeHotspot("matmul_kernel", true, 72.5, { + compute_throughput_pct: 30, + dram_bandwidth_pct: 91, + occupancy_pct: 65, + }), + makeHotspot("reduce_kernel", true, 20.1, { + compute_throughput_pct: 50, + dram_bandwidth_pct: 55, + occupancy_pct: 70, + }), + ]) + + // After optimisation: matmul_kernel now 40% (improved), reduce_kernel 25% (worsened slightly), + // new vector_kernel 15% (added). old_helper_kernel (removed). + const after = makeProfile("nvidia", "gpu_kernel", [ + makeHotspot("matmul_kernel", true, 40.0, { + compute_throughput_pct: 82, + dram_bandwidth_pct: 45, + occupancy_pct: 80, + }), + makeHotspot("reduce_kernel", true, 25.0, { + compute_throughput_pct: 48, + dram_bandwidth_pct: 58, + occupancy_pct: 68, + }), + makeHotspot("vector_kernel", true, 15.0, { + compute_throughput_pct: 75, + dram_bandwidth_pct: 40, + occupancy_pct: 78, + }), + ]) + + it("improved hotspot is correctly identified", () => { + const d = ProfileService.diff(before, after) + const matmul = d.hotspots.find((h) => h.name === "matmul_kernel") + expect(matmul).toBeDefined() + expect(matmul!.status).toBe("improved") + expect(matmul!.self_pct_before).toBe(72.5) + expect(matmul!.self_pct_after).toBe(40.0) + expect(matmul!.self_pct_delta).toBeCloseTo(-32.5, 5) + }) + + it("worsened hotspot is correctly identified", () => { + const d = ProfileService.diff(before, after) + const reduce = d.hotspots.find((h) => h.name === "reduce_kernel") + expect(reduce).toBeDefined() + expect(reduce!.status).toBe("worsened") + expect(reduce!.self_pct_before).toBe(20.1) + expect(reduce!.self_pct_after).toBe(25.0) + expect(reduce!.self_pct_delta).toBeCloseTo(4.9, 2) + }) + + it("added hotspot (new in after) is detected", () => { + const d = ProfileService.diff(before, after) + const added = d.hotspots.find((h) => h.name === "vector_kernel") + expect(added).toBeDefined() + expect(added!.status).toBe("added") + expect(added!.self_pct_after).toBe(15.0) + expect(added!.self_pct_before).toBeUndefined() + }) + + it("removed hotspot (in before, absent in after) is detected", () => { + // Add a hotspot only in "before" to verify removal detection + const beforeWithExtra = makeProfile("nvidia", "gpu_kernel", [ + ...before.hotspots, + makeHotspot("old_helper_kernel", true, 5.0, { compute_throughput_pct: 20 }), + ]) + const d = ProfileService.diff(beforeWithExtra, after) + const removed = d.hotspots.find((h) => h.name === "old_helper_kernel") + expect(removed).toBeDefined() + expect(removed!.status).toBe("removed") + expect(removed!.self_pct_before).toBe(5.0) + expect(removed!.self_pct_after).toBeUndefined() + }) + + it("per-metric deltas show how metrics changed (e.g. DRAM bandwidth improved)", () => { + const d = ProfileService.diff(before, after) + const matmul = d.hotspots.find((h) => h.name === "matmul_kernel")! + const dramDiff = matmul.metrics_diff["dram_bandwidth_pct"] + expect(dramDiff).toBeDefined() + expect(dramDiff!.before).toBe(91) + expect(dramDiff!.after).toBe(45) + expect(dramDiff!.delta).toBeCloseTo(-46, 5) // negative = bandwidth pressure reduced + }) + + it("improved hotspots sort before worsened in the result", () => { + const d = ProfileService.diff(before, after) + const statuses = d.hotspots.map((h) => h.status) + const firstWorsened = statuses.indexOf("worsened") + const lastImproved = statuses.lastIndexOf("improved") + // All improved must come before any worsened + expect(lastImproved).toBeLessThan(firstWorsened) + }) + + it("cross_vendor is false for same-vendor comparison", () => { + const d = ProfileService.diff(before, after) + expect(d.cross_vendor).toBe(false) + expect(d.vendor_a).toBe("nvidia") + expect(d.vendor_b).toBe("nvidia") + }) +}) + +// ——— cross-vendor diff —————————————————————————————————————————————————————— + +describe("ProfileService.diff — cross-vendor (NVIDIA ncu vs AMD rocprof)", () => { + // Same program profiled on NVIDIA (before migration) and AMD (after migration). + // Shared neutral metrics are comparable; vendor-specific metrics will have delta=null. + const nvidiaProd = makeProfile("nvidia", "gpu_kernel", [ + makeHotspot("matmul_kernel", true, 68.0, { + compute_throughput_pct: 85, + dram_bandwidth_pct: 35, + occupancy_pct: 72, + // salu_busy_pct NOT present (ncu doesn't have it) + }), + ]) + + const amdProd = makeProfile("amd", "gpu_kernel", [ + makeHotspot("matmul_kernel", true, 71.0, { + compute_throughput_pct: 78, + dram_bandwidth_pct: 40, + occupancy_pct: 68, + salu_busy_pct: 22, // AMD-native metric, missing on NVIDIA side + }), + ]) + + it("cross_vendor flag is set and a note is included", () => { + const d = ProfileService.diff(nvidiaProd, amdProd) + expect(d.cross_vendor).toBe(true) + expect(d.vendor_a).toBe("nvidia") + expect(d.vendor_b).toBe("amd") + expect(d.note).toBeDefined() + expect(d.note).toContain("nvidia") + expect(d.note).toContain("amd") + }) + + it("shared neutral metrics (compute_throughput_pct) produce a real delta", () => { + const d = ProfileService.diff(nvidiaProd, amdProd) + const matmul = d.hotspots.find((h) => h.name === "matmul_kernel")! + const computeDiff = matmul.metrics_diff["compute_throughput_pct"] + expect(computeDiff).toBeDefined() + expect(computeDiff!.before).toBe(85) + expect(computeDiff!.after).toBe(78) + expect(computeDiff!.delta).toBeCloseTo(-7, 5) + }) + + it("AMD-only metric (salu_busy_pct) has delta=null (honest gap, not fabricated)", () => { + const d = ProfileService.diff(nvidiaProd, amdProd) + const matmul = d.hotspots.find((h) => h.name === "matmul_kernel")! + // salu_busy_pct is present in AMD but missing from NVIDIA side + const saluDiff = matmul.metrics_diff["salu_busy_pct"] + if (saluDiff) { + // If the key appears, delta must be null since one side is missing + expect(saluDiff.delta).toBeNull() + expect(saluDiff.before).toBeNull() // NVIDIA didn't report it + } + // It's also acceptable for the key to be absent from NVIDIA's metrics bag + // Either way, no fabricated value is present + }) + + it("summary diff is also populated for cross-vendor comparison", () => { + const nvidiaWithSummary = { + ...nvidiaProd, + summary: { compute_throughput_pct: PAP.present(85, "pct", { nativeMetric: "sm__throughput", semantic: "exact" }) }, + } + const amdWithSummary = { + ...amdProd, + summary: { compute_throughput_pct: PAP.present(78, "pct", { nativeMetric: "GPUBusy", semantic: "approximate" }) }, + } + const d = ProfileService.diff(nvidiaWithSummary, amdWithSummary) + expect(d.summary_diff["compute_throughput_pct"]).toBeDefined() + expect(d.summary_diff["compute_throughput_pct"]!.before).toBe(85) + expect(d.summary_diff["compute_throughput_pct"]!.after).toBe(78) + expect(d.summary_diff["compute_throughput_pct"]!.delta).toBeCloseTo(-7, 5) + }) +}) + +// ——— CPU before/after diff —————————————————————————————————————————————————— + +describe("ProfileService.diff — CPU before/after", () => { + const before = makeProfile("cpu_generic", "cpu_sampling", [ + makeHotspot("compress_block", false, 45.0, { ipc: 0.8, cache_miss_rate: 0.22 }), + makeHotspot("hash_compute", false, 30.0, { ipc: 2.1, cache_miss_rate: 0.03 }), + ]) + + const after = makeProfile("cpu_generic", "cpu_sampling", [ + // compress_block now much faster due to cache-friendly access + makeHotspot("compress_block", false, 18.0, { ipc: 1.9, cache_miss_rate: 0.04 }), + makeHotspot("hash_compute", false, 32.0, { ipc: 2.0, cache_miss_rate: 0.03 }), + ]) + + it("CPU hotspot improvement after cache-friendly rewrite is detected", () => { + const d = ProfileService.diff(before, after) + const compress = d.hotspots.find((h) => h.name === "compress_block")! + expect(compress.status).toBe("improved") + expect(compress.self_pct_delta).toBeCloseTo(-27, 1) + }) + + it("CPU metric delta shows cache_miss_rate improved", () => { + const d = ProfileService.diff(before, after) + const compress = d.hotspots.find((h) => h.name === "compress_block")! + const missDiff = compress.metrics_diff["cache_miss_rate"] + expect(missDiff).toBeDefined() + expect(missDiff!.before).toBe(0.22) + expect(missDiff!.after).toBe(0.04) + expect(missDiff!.delta).toBeCloseTo(-0.18, 5) + }) + + it("diff result has correct vendor/domain metadata", () => { + const d = ProfileService.diff(before, after) + expect(d.cross_vendor).toBe(false) + expect(d.vendor_a).toBe("cpu_generic") + expect(d.vendor_b).toBe("cpu_generic") + expect(d.domain_a).toBe("cpu_sampling") + expect(d.domain_b).toBe("cpu_sampling") + }) +}) diff --git a/packages/deepagent-code/test/deepagent/profile-evidence-artifact-in-graph.test.ts b/packages/deepagent-code/test/deepagent/profile-evidence-artifact-in-graph.test.ts new file mode 100644 index 00000000..3181b490 --- /dev/null +++ b/packages/deepagent-code/test/deepagent/profile-evidence-artifact-in-graph.test.ts @@ -0,0 +1,191 @@ +import { describe, it, expect, afterAll } from "bun:test" +import os from "os" +import path from "path" +import * as fs from "fs/promises" +import { PAP } from "@/profile/pap" +import { ProfileService } from "@/profile/service" + +// P4A (S1-v3.5): ProfileService.run writes a PROFILE_RESULT.json evidence +// artifact (evidence_kind:"profile") and returns the NormalizedProfile + path. +// This test uses a fake in-memory adapter — no process spawning needed. + +// ——— fake adapter (same pattern as pap-protocol-three-stage.test.ts) ———————— + +class FakeGpuAdapter implements PAP.ProfileAdapter { + readonly id = "fake-ncu" + readonly vendor = "nvidia" as const + readonly domain = "gpu_kernel" as const + readonly privileges = [{ kind: "gpu_performance_counter" as const, reason: "test" }] + readonly mapping: PAP.MetricMapping = { + adapterId: "fake-ncu", + domain: "gpu_kernel", + availableMetrics: ["sm__throughput", "gpu__dram_throughput", "sm__warps_active", "gpu__time_duration"], + entries: [ + { neutral: "compute_throughput_pct", native: "sm__throughput", semantic: "exact" }, + { neutral: "memory_throughput_pct", native: "sm__throughput", semantic: "approximate" }, + { neutral: "dram_bandwidth_pct", native: "gpu__dram_throughput", semantic: "exact" }, + { neutral: "l2_throughput_pct", native: null, reason: "not_collected" }, + { neutral: "occupancy_pct", native: "sm__warps_active", semantic: "exact" }, + { neutral: "valu_utilization_pct", native: null, reason: "not_collected" }, + { neutral: "salu_busy_pct", native: null, reason: "metric_not_in_this_profiler", detail: "ncu has no SALU metric" }, + { neutral: "duration_ns", native: "gpu__time_duration", semantic: "exact" }, + { + neutral: "compute_bound", + native: ["sm__throughput", "gpu__dram_throughput"], + semantic: "exact", + derived: true, + formula: "compute_throughput_pct > memory_throughput_pct", + }, + ], + } + + async collect(target: PAP.ProfileTarget): Promise { + return { path: `/tmp/fake-${target.command}.ncu-rep`, format: "ncu-rep", bytes: 1024 } + } + + async parse(report: PAP.NativeReportRef): Promise { + return { + adapterId: this.id, + vendor: this.vendor, + domain: this.domain, + target: { command: "test-app" }, + nativeSummary: { + sm__throughput: 87, + gpu__dram_throughput: 42, + sm__warps_active: 75, + gpu__time_duration: 50_000, + }, + hotspots: [ + { + name: "matmul_kernel", + kind: "kernel", + self_pct: 72.5, + nativeMetrics: { sm__throughput: 87, gpu__dram_throughput: 42, gpu__time_duration: 36_000 }, + }, + { + name: "reduce_kernel", + kind: "kernel", + self_pct: 20.1, + nativeMetrics: { sm__throughput: 45, gpu__dram_throughput: 91, gpu__time_duration: 10_000 }, + }, + ], + availableMetrics: this.mapping.availableMetrics, + raw_report_ref: report, + } + } + + normalize(raw: PAP.RawProfile): PAP.NormalizedProfile { + const toMetrics = (nm: Record) => { + const get = (k: string) => { const v = nm[k]; return v !== undefined ? Number(v) : undefined } + const compute = get("sm__throughput") + const dram = get("gpu__dram_throughput") + const occ = get("sm__warps_active") + const dur = get("gpu__time_duration") + return { + compute_throughput_pct: compute !== undefined ? PAP.present(compute, "pct", { nativeMetric: "sm__throughput", semantic: "exact" }) : PAP.missing("not_collected"), + memory_throughput_pct: compute !== undefined ? PAP.present(compute, "pct", { nativeMetric: "sm__throughput", semantic: "approximate" }) : PAP.missing("not_collected"), + dram_bandwidth_pct: dram !== undefined ? PAP.present(dram, "pct", { nativeMetric: "gpu__dram_throughput", semantic: "exact" }) : PAP.missing("not_collected"), + l2_throughput_pct: PAP.missing("not_collected"), + occupancy_pct: occ !== undefined ? PAP.present(occ, "pct", { nativeMetric: "sm__warps_active", semantic: "exact" }) : PAP.missing("not_collected"), + valu_utilization_pct: PAP.missing("not_collected"), + salu_busy_pct: PAP.missing("metric_not_in_this_profiler", "ncu has no SALU metric"), + duration_ns: dur !== undefined ? PAP.present(dur, "ns", { nativeMetric: "gpu__time_duration", semantic: "exact" }) : PAP.missing("not_collected"), + compute_bound: (compute !== undefined && dram !== undefined) ? PAP.present(compute > dram, "bool", { + nativeMetric: ["sm__throughput", "gpu__dram_throughput"], semantic: "exact", derived: true, + formula: "compute_throughput_pct > memory_throughput_pct", + }) : PAP.missing("not_collected", "metrics missing"), + } + } + + const ns = raw.nativeSummary + return { + domain: this.domain, + vendor: this.vendor, + adapterId: this.id, + target: raw.target, + duration_ns: 50_000, + hotspots: raw.hotspots.map((h) => ({ + kernel: h.name, + self_pct: h.self_pct ?? 0, + metrics: toMetrics(h.nativeMetrics), + })), + summary: toMetrics(ns), + raw_report_ref: raw.raw_report_ref, + } + } +} + +// ——— tests —————————————————————————————————————————————————————————————————— + +describe("P4A profile evidence artifact", () => { + const artifactDir = path.join(os.tmpdir(), `deepagent-p4a-test-${Date.now()}`) + afterAll(async () => { await fs.rm(artifactDir, { recursive: true, force: true }).catch(() => {}) }) + + it("ProfileService.run returns a valid NormalizedProfile", async () => { + const adapter = new FakeGpuAdapter() + const result = await ProfileService.run(adapter, { command: "test-app" }, { artifactDir }) + const { profile } = result + + expect(profile.adapterId).toBe("fake-ncu") + expect(profile.domain).toBe("gpu_kernel") + expect(profile.vendor).toBe("nvidia") + expect(profile.hotspots.length).toBe(2) + expect(profile.hotspots[0]!.kernel).toBe("matmul_kernel") + expect(profile.hotspots[0]!.self_pct).toBe(72.5) + }) + + it("ProfileService.run returns an artifactPath pointing to PROFILE_RESULT.json", async () => { + const adapter = new FakeGpuAdapter() + const result = await ProfileService.run(adapter, { command: "test-app" }, { artifactDir }) + expect(result.artifactPath).toBe(path.join(artifactDir, "PROFILE_RESULT.json")) + }) + + it("PROFILE_RESULT.json has evidence_kind:profile and correct shape", async () => { + const adapter = new FakeGpuAdapter() + await ProfileService.run(adapter, { command: "test-app" }, { artifactDir }) + + const raw = await fs.readFile(path.join(artifactDir, "PROFILE_RESULT.json"), "utf8") + const artifact = JSON.parse(raw) as ProfileService.ProfileArtifact + + expect(artifact.evidence_kind).toBe("profile") + expect(typeof artifact.generated_at).toBe("string") + expect(artifact.profile.adapterId).toBe("fake-ncu") + expect(artifact.roofline).toBeDefined() + expect(["compute", "memory", "latency", "balanced"]).toContain(artifact.roofline.bound) + expect(artifact.roofline.derived).toBe(true) + expect(typeof artifact.roofline.detail).toBe("string") + expect(artifact.roofline.detail.length).toBeGreaterThan(0) + }) + + it("PROFILE_RESULT.json hotspots contain neutral metric names (no native leak)", async () => { + const adapter = new FakeGpuAdapter() + await ProfileService.run(adapter, { command: "test-app" }, { artifactDir }) + + const raw = await fs.readFile(path.join(artifactDir, "PROFILE_RESULT.json"), "utf8") + const artifact = JSON.parse(raw) as ProfileService.ProfileArtifact + const hotspot = artifact.profile.hotspots[0]! + const metricKeys = Object.keys(hotspot.metrics) + + // Must have neutral names + expect(metricKeys).toContain("compute_throughput_pct") + expect(metricKeys).toContain("occupancy_pct") + // Must NOT have native names + expect(metricKeys).not.toContain("sm__throughput") + expect(metricKeys).not.toContain("gpu__dram_throughput") + }) + + it("raw_report_ref stays as a path reference, not inlined into the artifact", async () => { + const adapter = new FakeGpuAdapter() + await ProfileService.run(adapter, { command: "test-app" }, { artifactDir }) + + const raw = await fs.readFile(path.join(artifactDir, "PROFILE_RESULT.json"), "utf8") + const artifact = JSON.parse(raw) as ProfileService.ProfileArtifact + + // Native report is a ref, not an inline blob + expect(artifact.profile.raw_report_ref.path).toBeTruthy() + expect(artifact.profile.raw_report_ref.format).toBe("ncu-rep") + // The artifact JSON should not contain the raw report bytes inline + // (size sanity: no huge embedded blob) + expect(raw.length).toBeLessThan(100_000) + }) +}) diff --git a/packages/deepagent-code/test/deepagent/profile-roofline-summary.test.ts b/packages/deepagent-code/test/deepagent/profile-roofline-summary.test.ts new file mode 100644 index 00000000..c3358046 --- /dev/null +++ b/packages/deepagent-code/test/deepagent/profile-roofline-summary.test.ts @@ -0,0 +1,285 @@ +import { describe, it, expect } from "bun:test" +import { PAP } from "@/profile/pap" +import { ProfileService } from "@/profile/service" + +// P4A (S1-v3.5): ProfileService.roofline classifies a NormalizedProfile into +// compute/memory/latency/balanced using only neutral vocabulary metrics. +// Works for BOTH GPU (gpu_kernel, gpu_timeline) and CPU (cpu_sampling, cpu_hotspot) +// profiles — the neutral vocabulary is the unifying layer. + +// ——— helpers ———————————————————————————————————————————————————————————————— + +function makeSummary(metrics: Record): Record { + const bag: Record = {} + for (const [key, val] of Object.entries(metrics)) { + if (val === null) { + bag[key] = PAP.missing("not_collected") + } else { + // provenance just needs to satisfy structural validation; exact native name + // doesn't matter for roofline classification. + bag[key] = PAP.present(val, "pct", { nativeMetric: key, semantic: "exact" }) + } + } + return bag +} + +function makeSummaryRatio(metrics: Record): Record { + const bag: Record = {} + for (const [key, val] of Object.entries(metrics)) { + if (val === null) { + bag[key] = PAP.missing("not_collected") + } else { + bag[key] = PAP.present(val, "ratio", { nativeMetric: key, semantic: "exact" }) + } + } + return bag +} + +function fakeGpuKernelProfile(summary: Record): PAP.NormalizedProfile { + return { + domain: "gpu_kernel", + vendor: "nvidia", + adapterId: "fake-ncu", + target: { command: "bench" }, + duration_ns: 10_000, + hotspots: [], + summary, + raw_report_ref: { path: "/tmp/bench.ncu-rep", format: "ncu-rep" }, + } +} + +function fakeGpuTimelineProfile(summary: Record): PAP.NormalizedProfile { + return { + domain: "gpu_timeline", + vendor: "nvidia", + adapterId: "fake-nsys", + target: { command: "bench" }, + duration_ns: 100_000, + hotspots: [], + summary, + raw_report_ref: { path: "/tmp/bench.nsys-rep", format: "nsys-rep" }, + } +} + +function fakeCpuProfile( + domain: PAP.Domain, + summary: Record, +): PAP.NormalizedProfile { + return { + domain, + vendor: "cpu_generic", + adapterId: "fake-perf", + target: { command: "bench" }, + duration_ns: 2_000_000, + hotspots: [], + summary, + raw_report_ref: { path: "/tmp/bench.perf.data", format: "perf-data" }, + } +} + +// ——— GPU kernel scenarios —————————————————————————————————————————————————— + +describe("ProfileService.roofline — GPU kernel", () => { + it("compute-bound: high compute throughput, moderate memory throughput, good occupancy", () => { + const profile = fakeGpuKernelProfile(makeSummary({ + compute_throughput_pct: 87, + memory_throughput_pct: 42, + dram_bandwidth_pct: 38, + occupancy_pct: 75, + })) + const r = ProfileService.roofline(profile) + expect(r.bound).toBe("compute") + expect(r.derived).toBe(true) + expect(r.detail).toContain("compute-bound") + expect(r.detail).toContain("compute_throughput_pct=87.0%") + expect(r.detail).toContain("memory_throughput_pct=42.0%") + }) + + it("memory-bound: high DRAM bandwidth utilization", () => { + const profile = fakeGpuKernelProfile(makeSummary({ + compute_throughput_pct: 30, + memory_throughput_pct: 60, + dram_bandwidth_pct: 91, + occupancy_pct: 70, + })) + const r = ProfileService.roofline(profile) + expect(r.bound).toBe("memory") + expect(r.derived).toBe(true) + expect(r.detail).toContain("memory-bound") + expect(r.detail).toContain("dram_bandwidth_pct=91.0%") + }) + + it("memory-bound: high memory throughput even without DRAM metric", () => { + const profile = fakeGpuKernelProfile(makeSummary({ + compute_throughput_pct: 40, + memory_throughput_pct: 82, + dram_bandwidth_pct: null, // not available on this profiler + occupancy_pct: 65, + })) + const r = ProfileService.roofline(profile) + expect(r.bound).toBe("memory") + expect(r.detail).toContain("memory-bound") + }) + + it("latency-bound: low occupancy regardless of compute/memory metrics", () => { + const profile = fakeGpuKernelProfile(makeSummary({ + compute_throughput_pct: 65, + memory_throughput_pct: 55, + dram_bandwidth_pct: 50, + occupancy_pct: 28, + })) + const r = ProfileService.roofline(profile) + expect(r.bound).toBe("latency") + expect(r.derived).toBe(true) + expect(r.detail).toContain("latency-bound") + expect(r.detail).toContain("occupancy_pct=28.0%") + }) + + it("balanced: no metric exceeds thresholds", () => { + const profile = fakeGpuKernelProfile(makeSummary({ + compute_throughput_pct: 45, + memory_throughput_pct: 48, + dram_bandwidth_pct: 40, + occupancy_pct: 60, + })) + const r = ProfileService.roofline(profile) + expect(r.bound).toBe("balanced") + expect(r.derived).toBe(true) + expect(r.detail).toContain("balanced") + }) + + it("still classifies when some metrics are null (not_collected)", () => { + // Only compute_throughput_pct present, others missing + const summary: Record = { + compute_throughput_pct: PAP.present(88, "pct", { nativeMetric: "sm__throughput", semantic: "exact" }), + memory_throughput_pct: PAP.missing("not_collected"), + dram_bandwidth_pct: PAP.missing("not_collected"), + occupancy_pct: PAP.missing("not_collected"), + } + const profile = fakeGpuKernelProfile(summary) + const r = ProfileService.roofline(profile) + // With only compute_throughput_pct=88 and no occupancy to disqualify it, + // should classify as compute-bound + expect(r.bound).toBe("compute") + expect(r.derived).toBe(true) + }) +}) + +// ——— GPU timeline scenarios —————————————————————————————————————————————————— + +describe("ProfileService.roofline — GPU timeline", () => { + it("memory-bound: high memory copy percent", () => { + const profile = fakeGpuTimelineProfile(makeSummary({ + kernel_total_pct: 30, + mem_copy_pct: 55, + api_overhead_pct: 15, + })) + const r = ProfileService.roofline(profile) + expect(r.bound).toBe("memory") + expect(r.detail).toContain("mem_copy_pct=55.0%") + }) + + it("compute-bound: high kernel total percent", () => { + const profile = fakeGpuTimelineProfile(makeSummary({ + kernel_total_pct: 85, + mem_copy_pct: 10, + api_overhead_pct: 5, + })) + const r = ProfileService.roofline(profile) + expect(r.bound).toBe("compute") + expect(r.detail).toContain("kernel_total_pct=85.0%") + }) + + it("latency-bound: high API overhead", () => { + const profile = fakeGpuTimelineProfile(makeSummary({ + kernel_total_pct: 20, + mem_copy_pct: 15, + api_overhead_pct: 60, + })) + const r = ProfileService.roofline(profile) + expect(r.bound).toBe("latency") + expect(r.detail).toContain("api_overhead_pct=60.0%") + }) + + it("balanced: no dominant factor", () => { + const profile = fakeGpuTimelineProfile(makeSummary({ + kernel_total_pct: 40, + mem_copy_pct: 20, + api_overhead_pct: 15, + })) + const r = ProfileService.roofline(profile) + expect(r.bound).toBe("balanced") + }) +}) + +// ——— CPU scenarios ——————————————————————————————————————————————————————————— + +describe("ProfileService.roofline — CPU (cpu_sampling)", () => { + it("compute-bound: high IPC, low cache miss rate", () => { + // IPC is a ratio, not pct — use separate helper + const summary: Record = { + ipc: PAP.present(2.8, "ratio", { nativeMetric: "ipc", semantic: "exact", derived: true, formula: "instructions/cycles" }), + cache_miss_rate: PAP.present(0.02, "ratio", { nativeMetric: "cache_miss_rate", semantic: "exact" }), + branch_misprediction_pct: PAP.present(2.0, "pct", { nativeMetric: "branch_misprediction_pct", semantic: "exact" }), + } + const profile = fakeCpuProfile("cpu_sampling", summary) + const r = ProfileService.roofline(profile) + expect(r.bound).toBe("compute") + expect(r.derived).toBe(true) + expect(r.detail).toContain("compute-bound") + expect(r.detail).toContain("ipc=2.80") + }) + + it("memory-bound: high cache miss rate", () => { + const summary: Record = { + ipc: PAP.present(0.5, "ratio", { nativeMetric: "ipc", semantic: "exact", derived: true, formula: "instructions/cycles" }), + cache_miss_rate: PAP.present(0.25, "ratio", { nativeMetric: "cache_miss_rate", semantic: "exact" }), + branch_misprediction_pct: PAP.present(3.0, "pct", { nativeMetric: "branch_misprediction_pct", semantic: "exact" }), + } + const profile = fakeCpuProfile("cpu_sampling", summary) + const r = ProfileService.roofline(profile) + expect(r.bound).toBe("memory") + expect(r.derived).toBe(true) + expect(r.detail).toContain("memory-bound") + expect(r.detail).toContain("cache_miss_rate=25.0%") + }) + + it("latency-bound: high branch misprediction rate", () => { + const summary: Record = { + ipc: PAP.present(1.0, "ratio", { nativeMetric: "ipc", semantic: "exact", derived: true, formula: "instructions/cycles" }), + cache_miss_rate: PAP.present(0.03, "ratio", { nativeMetric: "cache_miss_rate", semantic: "exact" }), + branch_misprediction_pct: PAP.present(18.0, "pct", { nativeMetric: "branch_misprediction_pct", semantic: "exact" }), + } + const profile = fakeCpuProfile("cpu_sampling", summary) + const r = ProfileService.roofline(profile) + expect(r.bound).toBe("latency") + expect(r.derived).toBe(true) + expect(r.detail).toContain("latency-bound") + expect(r.detail).toContain("branch_misprediction_pct=18.0%") + }) + + it("balanced: all metrics moderate", () => { + const summary: Record = { + ipc: PAP.present(1.5, "ratio", { nativeMetric: "ipc", semantic: "exact", derived: true, formula: "instructions/cycles" }), + cache_miss_rate: PAP.present(0.04, "ratio", { nativeMetric: "cache_miss_rate", semantic: "exact" }), + branch_misprediction_pct: PAP.present(4.0, "pct", { nativeMetric: "branch_misprediction_pct", semantic: "exact" }), + } + const profile = fakeCpuProfile("cpu_sampling", summary) + const r = ProfileService.roofline(profile) + expect(r.bound).toBe("balanced") + expect(r.derived).toBe(true) + expect(r.detail).toContain("balanced") + }) + + it("classifies cpu_hotspot domain the same way as cpu_sampling", () => { + const summary: Record = { + ipc: PAP.present(0.3, "ratio", { nativeMetric: "ipc", semantic: "exact", derived: true, formula: "instructions/cycles" }), + cache_miss_rate: PAP.present(0.30, "ratio", { nativeMetric: "cache_miss_rate", semantic: "exact" }), + memory_bound_pct: PAP.present(55, "pct", { nativeMetric: "memory_bound_pct", semantic: "exact" }), + } + const profile = fakeCpuProfile("cpu_hotspot", summary) + const r = ProfileService.roofline(profile) + expect(r.bound).toBe("memory") + expect(r.detail).toContain("memory-bound") + }) +}) diff --git a/packages/deepagent-code/test/deepagent/profile-tool-auto-adapter-selection.test.ts b/packages/deepagent-code/test/deepagent/profile-tool-auto-adapter-selection.test.ts new file mode 100644 index 00000000..ed448c58 --- /dev/null +++ b/packages/deepagent-code/test/deepagent/profile-tool-auto-adapter-selection.test.ts @@ -0,0 +1,98 @@ +import { describe, it, expect, beforeEach, afterEach } from "bun:test" +import { autoSelectAdapterId } from "../../src/tool/profile" + +// P3A auto-adapter selection: env-var heuristics + explicit override. +// Tests the pure `autoSelectAdapterId` function — no Effect layers needed. + +const ENV_KEYS = ["CUDA_VISIBLE_DEVICES", "ROCM_HOME", "HIP_VISIBLE_DEVICES", "VTUNE_PROFILING_DIR"] + +// Save and restore process.env around each test so tests don't bleed. +let savedEnv: Record = {} + +beforeEach(() => { + savedEnv = {} + for (const k of ENV_KEYS) { + savedEnv[k] = process.env[k] + delete process.env[k] + } +}) + +afterEach(() => { + for (const k of ENV_KEYS) { + if (savedEnv[k] === undefined) { + delete process.env[k] + } else { + process.env[k] = savedEnv[k] + } + } +}) + +describe("P3A profile tool — adapter auto-selection", () => { + describe("explicit override", () => { + it("explicit adapter:'perf' overrides all env vars", () => { + process.env["CUDA_VISIBLE_DEVICES"] = "0" + process.env["ROCM_HOME"] = "/opt/rocm" + process.env["VTUNE_PROFILING_DIR"] = "/opt/vtune" + expect(autoSelectAdapterId("perf")).toBe("perf") + }) + + it("explicit adapter:'ncu' returns ncu regardless of env", () => { + delete process.env["CUDA_VISIBLE_DEVICES"] + expect(autoSelectAdapterId("ncu")).toBe("ncu") + }) + + it("explicit adapter:'vtune' returns vtune regardless of env", () => { + delete process.env["VTUNE_PROFILING_DIR"] + expect(autoSelectAdapterId("vtune")).toBe("vtune") + }) + }) + + describe("CUDA env heuristic", () => { + it("CUDA_VISIBLE_DEVICES=0 → ncu", () => { + process.env["CUDA_VISIBLE_DEVICES"] = "0" + expect(autoSelectAdapterId()).toBe("ncu") + }) + + it("CUDA_VISIBLE_DEVICES='' (empty string, device present) → ncu", () => { + process.env["CUDA_VISIBLE_DEVICES"] = "" + expect(autoSelectAdapterId()).toBe("ncu") + }) + }) + + describe("ROCm env heuristic", () => { + it("ROCM_HOME=/opt/rocm → rocprof", () => { + process.env["ROCM_HOME"] = "/opt/rocm" + expect(autoSelectAdapterId()).toBe("rocprof") + }) + + it("HIP_VISIBLE_DEVICES=0 → rocprof", () => { + process.env["HIP_VISIBLE_DEVICES"] = "0" + expect(autoSelectAdapterId()).toBe("rocprof") + }) + }) + + describe("VTune env heuristic", () => { + it("VTUNE_PROFILING_DIR set → vtune", () => { + process.env["VTUNE_PROFILING_DIR"] = "/opt/intel/vtune" + expect(autoSelectAdapterId()).toBe("vtune") + }) + }) + + describe("no GPU env → perf fallback", () => { + it("no env vars set → perf (unless vtune binary on PATH, which CI won't have)", () => { + // No GPU env set. On CI, vtune won't be on PATH, so falls through to perf. + // VTUNE_PROFILING_DIR cleared in beforeEach. + const result = autoSelectAdapterId() + // perf OR vtune (if vtune happens to be on the test machine's PATH). + expect(["perf", "vtune"]).toContain(result) + }) + }) + + describe("CUDA takes priority over ROCm in env", () => { + it("CUDA_VISIBLE_DEVICES + ROCM_HOME both set → ncu wins (CUDA checked first)", () => { + process.env["CUDA_VISIBLE_DEVICES"] = "0" + process.env["ROCM_HOME"] = "/opt/rocm" + expect(autoSelectAdapterId()).toBe("ncu") + }) + }) +}) diff --git a/packages/deepagent-code/test/deepagent/profile-tool-d3-execute.test.ts b/packages/deepagent-code/test/deepagent/profile-tool-d3-execute.test.ts new file mode 100644 index 00000000..3fda3b21 --- /dev/null +++ b/packages/deepagent-code/test/deepagent/profile-tool-d3-execute.test.ts @@ -0,0 +1,191 @@ +import { afterEach, beforeAll, afterAll, describe, expect } from "bun:test" +import { Effect, Layer } from "effect" +import path from "path" +import os from "os" +import * as fs from "fs/promises" +import { FSUtil } from "@deepagent-code/core/fs-util" +import { CrossSpawnSpawner } from "@deepagent-code/core/cross-spawn-spawner" +import { Git } from "@/git" +import { Worktree } from "@/worktree" +import { LSP } from "@/lsp/lsp" +import { Config } from "@/config/config" +import { RuntimeFlags } from "@/effect/runtime-flags" +import { EventV2Bridge } from "@/event-v2-bridge" +import { RuntimeBase } from "@/runtime/base" +import * as Truncate from "@/tool/truncate" +import { Agent } from "@/agent/agent" +import { Tool } from "@/tool/tool" +import { ProfileTool, type ProfileMetadata } from "@/tool/profile" +import { disposeAllInstances } from "../fixture/fixture" +import { testEffect } from "../lib/effect" +import { InstanceStore } from "@/project/instance-store" +import { MessageID, SessionID } from "@/session/schema" + +// P3A (S1-v3.5) — REAL ProfileTool.execute behaviour tests. +// +// These replace the old "false confidence" tests that called ProfileService.run +// directly (never through the tool). They drive the actual ProfileTool.execute and +// prove the tool now: +// (1) routes through ProfileService.run → writes a real PROFILE_RESULT.json artifact +// (C1: the P4A evidence loop is live from the tool path), +// (2) goes through the R0 privilege gate fail-closed (C2/#4: denyAllProbe blocks), +// (3) reports roofline + artifactPath in metadata. +// +// A fake `perf` binary is injected on PATH so the real adapter (real probe, real +// collect→parse→normalize) runs end-to-end without needing Linux perf installed. + +let fakeBinDir: string +let originalPath: string | undefined + +const PERF_REPORT = `# Overhead Command Shared Object Symbol + 62.50% bench bench [.] compute_kernel + 20.00% bench bench [.] data_loader + 5.30% bench bench [.] io_thread_main +` + +const PERF_STAT = ` Performance counter stats for './bench': + + 2,000,000 cycles # 1.500 GHz + 1,000,000 instructions # 0.50 insn per cycle + 50,000 cache-misses # 50.000 % of all cache refs + 100,000 cache-references + 10,000 branch-misses # 5.000 % of all branches + 200,000 branches +` + +beforeAll(async () => { + fakeBinDir = await fs.mkdtemp(path.join(os.tmpdir(), "deepagent-fakeperf-")) + // A fake `perf` that answers record/report/stat like the real one. Node shebang + // keeps it cross-platform (macOS test runner has no real perf). + const script = `#!/usr/bin/env node +const args = process.argv.slice(2) +const sub = args[0] +if (sub === "record") { process.exit(0) } +if (sub === "report") { process.stdout.write(${JSON.stringify(PERF_REPORT)}); process.exit(0) } +if (sub === "stat") { process.stdout.write(${JSON.stringify(PERF_STAT)}); process.exit(0) } +process.exit(0) +` + const perfPath = path.join(fakeBinDir, "perf") + await fs.writeFile(perfPath, script, { mode: 0o755 }) + await fs.chmod(perfPath, 0o755) + originalPath = process.env.PATH + process.env.PATH = `${fakeBinDir}${path.delimiter}${originalPath ?? ""}` +}) + +afterAll(async () => { + process.env.PATH = originalPath + await fs.rm(fakeBinDir, { recursive: true, force: true }).catch(() => {}) +}) + +// Build the tool with the R0 gate probe injectable so we can test both allow + deny. +const toolLayer = (probe: RuntimeBase.PrivilegeProbe = RuntimeBase.allowAllProbe) => + Layer.mergeAll( + LSP.defaultLayer, + RuntimeBase.testLayer(probe).pipe(Layer.provide(Worktree.defaultLayer)), + Worktree.defaultLayer, + Truncate.defaultLayer, + Agent.defaultLayer, + FSUtil.defaultLayer, + CrossSpawnSpawner.defaultLayer, + Git.defaultLayer, + Config.defaultLayer, + RuntimeFlags.layer({}), + EventV2Bridge.defaultLayer, + ) + +type AskCall = { permission: string; patterns: readonly string[] } + +const makeCtx = (asks: AskCall[]): Tool.Context => ({ + sessionID: SessionID.make("ses_test"), + messageID: MessageID.make("msg_test"), + agent: "build", + abort: new AbortController().signal, + messages: [], + metadata: () => Effect.void, + ask: (req) => + Effect.sync(() => { + asks.push({ permission: req.permission, patterns: req.patterns }) + }), +}) + +describe("P3A ProfileTool.execute — real tool path", () => { + afterEach(() => disposeAllInstances()) + + const it = testEffect(toolLayer()) + + it.instance( + "runs collect→parse→normalize via ProfileService.run and writes PROFILE_RESULT.json", + () => + Effect.gen(function* () { + const def = yield* Tool.init(yield* ProfileTool) + const asks: AskCall[] = [] + const result = yield* def.execute({ target: "./bench", adapter: "perf" }, makeCtx(asks)) + const meta = result.metadata as ProfileMetadata + + // Reached the pipeline (not the "not available" early return): perf binary + // was found on PATH and ProfileService.run produced a normalized profile. + expect(meta.available).toBe(true) + expect(meta.adapterId).toBe("perf") + expect(meta.domain).toBe("cpu_sampling") + + // C1: a real artifact was written by ProfileService.run. + expect(meta.artifactPath).toBeTruthy() + const artifactRaw = yield* Effect.promise(() => fs.readFile(meta.artifactPath!, "utf8")) + const artifact = JSON.parse(artifactRaw) + expect(artifact.evidence_kind).toBe("profile") + expect(artifact.profile.adapterId).toBe("perf") + expect(artifact.roofline).toBeDefined() + + // Roofline classification is surfaced in metadata + top hotspot is compute_kernel. + expect(meta.roofline).toBeDefined() + expect(meta.hotspots?.[0]?.symbol).toBe("compute_kernel") + + // Output points at the real artifact, not a fabricated "read this file" note. + expect(result.output).toContain("PROFILE_RESULT.json") + + // The execution approval was requested once through ctx.ask. + expect(asks.filter((a) => a.permission === "execute").length).toBe(1) + }), + { git: true }, + ) + + it.instance( + "unknown adapter returns available:false before touching the gate", + () => + Effect.gen(function* () { + const def = yield* Tool.init(yield* ProfileTool) + const asks: AskCall[] = [] + const result = yield* def.execute({ target: "./bench", adapter: "definitely-not-a-profiler" }, makeCtx(asks)) + const meta = result.metadata as ProfileMetadata + expect(meta.available).toBe(false) + // No approval prompt for an adapter we can't even resolve. + expect(asks.length).toBe(0) + }), + { git: true }, + ) +}) + +describe("P3A ProfileTool.execute — fail-closed privilege gate (#4)", () => { + afterEach(() => disposeAllInstances()) + + const denyIt = testEffect(toolLayer(RuntimeBase.denyAllProbe)) + + denyIt.instance( + "denyAllProbe blocks perf (perf_event_paranoid unavailable) → privilege_blocked, no run", + () => + Effect.gen(function* () { + const def = yield* Tool.init(yield* ProfileTool) + const asks: AskCall[] = [] + const result = yield* def.execute({ target: "./bench", adapter: "perf" }, makeCtx(asks)) + const meta = result.metadata as ProfileMetadata + + // Binary IS present (fake perf on PATH), so we reach the gate — and it refuses. + expect(meta.available).toBe(false) + expect(meta.privilege_blocked).toBe(true) + expect(result.output.toLowerCase()).toContain("privilege") + // Fail-closed happens BEFORE approval (never prompt for an op that can't run). + expect(asks.length).toBe(0) + }), + { git: true }, + ) +}) diff --git a/packages/deepagent-code/test/deepagent/profile-tool-hotspots-with-symbols.test.ts b/packages/deepagent-code/test/deepagent/profile-tool-hotspots-with-symbols.test.ts new file mode 100644 index 00000000..4d5b4f72 --- /dev/null +++ b/packages/deepagent-code/test/deepagent/profile-tool-hotspots-with-symbols.test.ts @@ -0,0 +1,195 @@ +import { describe, it, expect } from "bun:test" +import { PAP } from "@/profile/pap" +import { RuntimeBase } from "@/runtime/base" +import { buildProfileOutput } from "../../src/tool/profile" + +// P3A profile tool — hotspot table with symbols, output budget. +// Tests that: +// (a) a fake adapter producing 5 hotspots → all 5 appear in output (top-10 includes all), +// (b) the output is correctly formatted (header, hotspot lines, summary, artifact note), +// (c) raw report bytes are NOT inlined — only the artifact ref note appears, +// (d) RuntimeBase.applyOutputBudget truncates correctly when output is large. + +function makeMetrics(selfPct: number): Record { + return { + self_pct: PAP.present(selfPct, "pct", { nativeMetric: "overhead", semantic: "exact" }), + cpi: PAP.present(1.8, "ratio", { nativeMetric: ["cycles", "instructions"], semantic: "exact" }), + ipc: PAP.present(0.56, "ratio", { + nativeMetric: ["instructions", "cycles"], + semantic: "exact", + derived: true, + formula: "instructions / cycles", + }), + clockticks: PAP.missing("not_collected"), + instructions_retired: PAP.missing("not_collected"), + cache_miss_rate: PAP.missing("not_collected"), + branch_misprediction_pct: PAP.missing("not_collected"), + } +} + +function makeHotspot(symbol: string, selfPct: number): PAP.Hotspot { + return { symbol, self_pct: selfPct, metrics: makeMetrics(selfPct) } +} + +const FIVE_HOTSPOTS: PAP.Hotspot[] = [ + makeHotspot("compute_kernel", 40.0), + makeHotspot("data_loader", 25.0), + makeHotspot("optimizer_step", 15.0), + makeHotspot("loss_fn", 12.0), + makeHotspot("io_thread", 8.0), +] + +const FAKE_NATIVE_REF: PAP.NativeReportRef = { + path: "/tmp/profile_result.perf.data", + format: "perf-data", + bytes: 1_024_000, + exportCommand: "perf script -i /tmp/profile_result.perf.data", +} + +function makeFiveHotspotProfile(): PAP.NormalizedProfile { + return { + domain: "cpu_sampling", + vendor: "cpu_generic", + adapterId: "perf", + target: { command: "./bench" }, + duration_ns: 2_000_000_000, + hotspots: FIVE_HOTSPOTS, + summary: { + ipc: PAP.present(0.48, "ratio", { + nativeMetric: ["instructions", "cycles"], + semantic: "exact", + derived: true, + formula: "instructions / cycles", + }), + cache_miss_rate: PAP.present(0.12, "ratio", { + nativeMetric: ["cache-misses", "cache-references"], + semantic: "exact", + }), + }, + raw_report_ref: FAKE_NATIVE_REF, + } +} + +describe("P3A profile tool — hotspots table with 5 symbols", () => { + it("(a) all 5 hotspots appear in output when total < top-10 limit", () => { + const normalized = makeFiveHotspotProfile() + const output = buildProfileOutput({ + adapterId: "perf", + target: "./bench", + normalized, + }) + + for (const { symbol } of FIVE_HOTSPOTS) { + expect(output).toContain(symbol!) + } + }) + + it("(b) output has correct structure: header / top hotspots / summary / evidence line", () => { + const normalized = makeFiveHotspotProfile() + const output = buildProfileOutput({ + adapterId: "perf", + target: "./bench", + normalized, + artifactPath: "/tmp/run/PROFILE_RESULT.json", + }) + + expect(output).toContain("profile: perf cpu_sampling on `./bench`") + expect(output).toContain("top hotspots:") + expect(output).toContain("summary:") + // Evidence line now points at the ACTUAL written artifact (P4A closed loop), + // rather than the old note that claimed a file that was never written. + expect(output).toContain("PROFILE_RESULT.json") + expect(output).toContain('evidence_kind:"profile"') + }) + + it("(b) hotspots are sorted by self_pct descending", () => { + const normalized = makeFiveHotspotProfile() + const output = buildProfileOutput({ + adapterId: "perf", + target: "./bench", + normalized, + }) + + const lines = output.split("\n") + const hotspotLines = lines.filter((l) => l.startsWith(" ") && l.includes("self:")) + expect(hotspotLines.length).toBe(5) + + // First hotspot must be compute_kernel (40%) — highest self_pct + expect(hotspotLines[0]).toContain("compute_kernel") + // Last hotspot must be io_thread (8%) — lowest self_pct + expect(hotspotLines[4]).toContain("io_thread") + }) + + it("(b) each hotspot line includes self_pct value", () => { + const normalized = makeFiveHotspotProfile() + const output = buildProfileOutput({ + adapterId: "perf", + target: "./bench", + normalized, + }) + + expect(output).toContain("40.0%") + expect(output).toContain("25.0%") + expect(output).toContain("15.0%") + }) + + it("(c) raw report bytes are NOT inlined in output", () => { + const normalized = makeFiveHotspotProfile() + const output = buildProfileOutput({ + adapterId: "perf", + target: "./bench", + normalized, + artifactPath: "/tmp/run/PROFILE_RESULT.json", + }) + + // The raw report path should not appear inline. + expect(output).not.toContain("/tmp/profile_result.perf.data") + // The perf data bytes (1 MB worth) should not appear inline. + expect(output).not.toContain("1024000") + // Only the evidence artifact reference is present. + expect(output).toContain("PROFILE_RESULT.json") + }) + + it("(d) RuntimeBase.applyOutputBudget truncates large output correctly", () => { + // Simulate a very large output string exceeding the default budget. + const largeOutput = "x".repeat(30_000) + "\nnote: full report in artifact (ref: PROFILE_RESULT.json)" + const budget: RuntimeBase.ResourceBudget = { timeoutMs: 60_000, maxInlineBytes: 24_000 } + const budgeted = RuntimeBase.applyOutputBudget(largeOutput, budget) + + expect(budgeted.truncated).toBe(true) + expect(budgeted.fullBytes).toBeGreaterThan(24_000) + expect(budgeted.inline).toContain("truncated") + expect(Buffer.byteLength(budgeted.inline, "utf8")).toBeLessThanOrEqual(24_000 + 200) // slight overhead for the truncation note + }) + + it("(d) small output passes through applyOutputBudget unchanged", () => { + const normalized = makeFiveHotspotProfile() + const output = buildProfileOutput({ + adapterId: "perf", + target: "./bench", + normalized, + }) + + // A typical 5-hotspot output is well under 24 KB. + const budgeted = RuntimeBase.applyOutputBudget(output) + expect(budgeted.truncated).toBe(false) + expect(budgeted.inline).toBe(output) + }) + + it("summary contains the neutral metric names (no native leak)", () => { + const normalized = makeFiveHotspotProfile() + const output = buildProfileOutput({ + adapterId: "perf", + target: "./bench", + normalized, + }) + + // ipc and cache_miss_rate are neutral names — they should appear in summary. + expect(output).toContain("ipc=") + expect(output).toContain("cache_miss_rate=") + // Native perf names must not appear in the tool output. + expect(output).not.toContain("instructions ") + expect(output).not.toContain("cache-misses") + expect(output).not.toContain("cache-references") + }) +}) diff --git a/packages/deepagent-code/test/deepagent/profile-tool-symbol-focus.test.ts b/packages/deepagent-code/test/deepagent/profile-tool-symbol-focus.test.ts new file mode 100644 index 00000000..cb24c68c --- /dev/null +++ b/packages/deepagent-code/test/deepagent/profile-tool-symbol-focus.test.ts @@ -0,0 +1,180 @@ +import { describe, it, expect } from "bun:test" +import { PAP } from "@/profile/pap" +import { buildProfileOutput, renderHotspot } from "../../src/tool/profile" + +// P3A profile tool — symbol/focus back-fill behaviour. +// Tests that: +// (a) the focus symbol is starred (*) in the hotspot table, +// (b) file_line from a resolved LSP candidate is shown in the focus line, +// (c) non-focus hotspots are NOT starred, +// (d) when the symbol is not resolved, the output says "symbol not found via LSP". + +function makeHotspot(name: string, selfPct: number, fileLine?: PAP.FileLine): PAP.Hotspot { + return { + symbol: name, + file_line: fileLine, + self_pct: selfPct, + metrics: { + self_pct: PAP.present(selfPct, "pct", { nativeMetric: "overhead", semantic: "exact" }), + cpi: PAP.present(2.1, "ratio", { nativeMetric: ["cycles", "instructions"], semantic: "exact" }), + ipc: PAP.present(0.48, "ratio", { + nativeMetric: ["instructions", "cycles"], + semantic: "exact", + derived: true, + formula: "instructions / cycles", + }), + clockticks: PAP.missing("not_collected"), + instructions_retired: PAP.missing("not_collected"), + cache_miss_rate: PAP.missing("not_collected"), + branch_misprediction_pct: PAP.missing("not_collected"), + }, + } +} + +const fakeNativeRef: PAP.NativeReportRef = { + path: "/tmp/profile.perf.data", + format: "perf-data", + bytes: 4096, +} + +function makeNormalizedProfile(hotspots: PAP.Hotspot[]): PAP.NormalizedProfile { + return { + domain: "cpu_sampling", + vendor: "cpu_generic", + adapterId: "perf", + target: { command: "python train.py" }, + duration_ns: 1_500_000_000, + hotspots, + summary: { + ipc: PAP.present(0.48, "ratio", { + nativeMetric: ["instructions", "cycles"], + semantic: "exact", + derived: true, + formula: "instructions / cycles", + }), + cache_miss_rate: PAP.present(0.12, "ratio", { + nativeMetric: ["cache-misses", "cache-references"], + semantic: "exact", + }), + }, + raw_report_ref: fakeNativeRef, + } +} + +describe("P3A profile tool — symbol focus back-fill", () => { + it("(a) focused hotspot is starred (*) in output", () => { + const hotspots = [ + makeHotspot("train_step", 38.0), + makeHotspot("matmul", 22.0), + makeHotspot("io_thread", 10.0), + ] + const normalized = makeNormalizedProfile(hotspots) + const output = buildProfileOutput({ + adapterId: "perf", + target: "python train.py", + normalized, + focus: "train_step", + focusFileLine: null, // not resolved yet + }) + + // The focus hotspot TABLE line must start with "* " + // (skip the "focus: train_step (...)" header line — look for hotspot table rows only) + const lines = output.split("\n") + const hotspotTableLine = lines.find((l) => (l.startsWith("* ") || l.startsWith(" ")) && l.includes("train_step")) + expect(hotspotTableLine).toBeDefined() + expect(hotspotTableLine!.startsWith("* ")).toBe(true) + + // Non-focus hotspots must start with " " (two spaces, not "*") + const matmulLine = lines.find((l) => l.includes("matmul")) + expect(matmulLine).toBeDefined() + expect(matmulLine!.startsWith(" ")).toBe(true) + expect(matmulLine!.startsWith("* ")).toBe(false) + }) + + it("(b) file_line is shown in the focus header line when LSP resolved it", () => { + const resolvedFileLine: PAP.FileLine = { file: "src/model.py", line: 42 } + + // Simulate what P3A does: back-fill file_line on the matching hotspot, then build output. + const hotspots = [ + makeHotspot("train_step", 38.0, resolvedFileLine), // file_line already back-filled + makeHotspot("matmul", 22.0), + ] + const normalized = makeNormalizedProfile(hotspots) + const output = buildProfileOutput({ + adapterId: "perf", + target: "python train.py", + normalized, + focus: "train_step", + focusFileLine: resolvedFileLine, + }) + + // Header should say "focus: train_step (src/model.py:42)" + expect(output).toContain("focus: train_step (src/model.py:42)") + }) + + it("(c) non-focus hotspots are never starred", () => { + const hotspots = [ + makeHotspot("train_step", 38.0), + makeHotspot("matmul", 22.0), + makeHotspot("io_thread", 10.0), + ] + const normalized = makeNormalizedProfile(hotspots) + const output = buildProfileOutput({ + adapterId: "perf", + target: "python train.py", + normalized, + focus: "train_step", + focusFileLine: null, + }) + + const lines = output.split("\n").filter((l) => l.startsWith(" ") || l.startsWith("* ")) + for (const line of lines) { + if (line.includes("matmul") || line.includes("io_thread")) { + expect(line.startsWith("* ")).toBe(false) + } + } + }) + + it("(d) 'symbol not found via LSP' shown when resolveSymbol returns not_found", () => { + const hotspots = [makeHotspot("train_step", 38.0)] + const normalized = makeNormalizedProfile(hotspots) + const output = buildProfileOutput({ + adapterId: "perf", + target: "python train.py", + normalized, + focus: "train_step", + focusFileLine: null, // LSP returned not_found → null + }) + + expect(output).toContain("(symbol not found via LSP)") + }) + + it("(e) no focus → no star markers and no focus header line", () => { + const hotspots = [makeHotspot("train_step", 38.0), makeHotspot("matmul", 22.0)] + const normalized = makeNormalizedProfile(hotspots) + const output = buildProfileOutput({ + adapterId: "perf", + target: "python train.py", + normalized, + // no focus + }) + + expect(output).not.toContain("focus:") + const lines = output.split("\n") + for (const line of lines) { + expect(line.startsWith("* ")).toBe(false) + } + }) + + it("renderHotspot starred vs unstarred smoke test", () => { + const h = makeHotspot("compute_fn", 55.3, { file: "src/gpu.py", line: 10 }) + const starred = renderHotspot(h, true) + const normal = renderHotspot(h, false) + expect(starred.startsWith("* ")).toBe(true) + expect(normal.startsWith(" ")).toBe(true) + expect(starred).toContain("compute_fn") + expect(starred).toContain("55.3%") + // cpi present in the hotspot + expect(starred).toContain("cpi:") + }) +}) diff --git a/packages/deepagent-code/test/deepagent/runtime-base.test.ts b/packages/deepagent-code/test/deepagent/runtime-base.test.ts new file mode 100644 index 00000000..4aeb28b3 --- /dev/null +++ b/packages/deepagent-code/test/deepagent/runtime-base.test.ts @@ -0,0 +1,120 @@ +import { afterEach, describe, expect } from "bun:test" +import { FSUtil } from "@deepagent-code/core/fs-util" +import { CrossSpawnSpawner } from "@deepagent-code/core/cross-spawn-spawner" +import { Effect, Layer, Ref, Exit, Cause } from "effect" +import { Git } from "../../src/git" +import { Worktree } from "../../src/worktree" +import { RuntimeBase } from "../../src/runtime/base" +import { InstanceState } from "../../src/effect/instance-state" +import { disposeAllInstances } from "../fixture/fixture" +import { testEffect } from "../lib/effect" + +// R0 (S1-v3.5): the runtime common base shared by DAP + PAP. Covers the four +// acceptance criteria: approve-once-per-session, fail-closed privilege gate, +// worktree isolation, and the output budget → artifact summary. + +const baseLayer = (probe?: RuntimeBase.PrivilegeProbe) => + Layer.mergeAll( + RuntimeBase.testLayer(probe).pipe(Layer.provide(Worktree.defaultLayer)), + Worktree.defaultLayer, + FSUtil.defaultLayer, + CrossSpawnSpawner.defaultLayer, + Git.defaultLayer, + ) + +describe("R0 runtime base", () => { + afterEach(() => disposeAllInstances()) + + describe("execution approval (once per session)", () => { + const it = testEffect(baseLayer(RuntimeBase.allowAllProbe)) + it.instance( + "asks once on first op, reuses the grant for in-session sub-ops", + () => + Effect.gen(function* () { + const base = yield* RuntimeBase.Service + const calls = yield* Ref.make(0) + const ask = () => Ref.update(calls, (n) => n + 1) + const gate = () => base.gate({ sessionKey: "sess-1", privileges: [], requestApproval: ask }) + yield* gate() // start → asks + yield* gate() // step → reuses + yield* gate() // continue → reuses + expect(yield* Ref.get(calls)).toBe(1) + // A different session asks again. + yield* base.gate({ sessionKey: "sess-2", privileges: [], requestApproval: ask }) + expect(yield* Ref.get(calls)).toBe(2) + }), + { git: true }, + ) + }) + + describe("privilege gate (fail-closed)", () => { + const it = testEffect(baseLayer(RuntimeBase.denyAllProbe)) + it.instance( + "fails closed when a required privilege is unavailable; never approves", + () => + Effect.gen(function* () { + const base = yield* RuntimeBase.Service + const calls = yield* Ref.make(0) + const exit = yield* base + .gate({ + sessionKey: "sess-priv", + privileges: [{ kind: "gpu_performance_counter", reason: "ncu needs GPU counters" }], + requestApproval: () => Ref.update(calls, (n) => n + 1), + }) + .pipe(Effect.exit) + expect(Exit.isFailure(exit)).toBe(true) + if (Exit.isFailure(exit)) { + const err = Cause.squash(exit.cause) + expect(err).toBeInstanceOf(RuntimeBase.UnsatisfiedPrivilegeError) + if (err instanceof RuntimeBase.UnsatisfiedPrivilegeError) { + expect(err.checks.some((c) => !c.satisfied)).toBe(true) + } + } + // fail-closed means we did NOT prompt for approval on an unrunnable op. + expect(yield* Ref.get(calls)).toBe(0) + }), + { git: true }, + ) + }) + + describe("worktree isolation", () => { + const it = testEffect(baseLayer(RuntimeBase.allowAllProbe)) + it.instance( + "runs the body in a worktree dir distinct from the main dir, then cleans up", + () => + Effect.gen(function* () { + const base = yield* RuntimeBase.Service + const instance = yield* InstanceState.context + const workdir = yield* base.withIsolation({ name: "r0-iso" }, (dir) => Effect.succeed(dir)) + expect(workdir).not.toBe(instance.directory) + expect(workdir).toContain("r0-iso") + // After completion the clean worktree is removed. + const wt = yield* Worktree.Service + const list = yield* wt.list() + expect(list.some((w) => w.directory === workdir)).toBe(false) + }), + { git: true }, + ) + }) + + describe("output budget → artifact", () => { + const it = testEffect(baseLayer(RuntimeBase.allowAllProbe)) + it.instance( + "keeps a small output inline; truncates a large one and flags it", + () => + Effect.gen(function* () { + const small = RuntimeBase.applyOutputBudget("hello", { timeoutMs: 1000, maxInlineBytes: 100 }) + expect(small.truncated).toBe(false) + expect(small.inline).toBe("hello") + + const big = "x".repeat(500) + const out = RuntimeBase.applyOutputBudget(big, { timeoutMs: 1000, maxInlineBytes: 100 }) + expect(out.truncated).toBe(true) + expect(out.fullBytes).toBe(500) + expect(out.inline).toContain("truncated") + expect(out.inline.length).toBeLessThan(big.length) + }), + { git: true }, + ) + }) +}) diff --git a/packages/deepagent-code/test/deepagent/runtime-domain-pack-adapter-gating.test.ts b/packages/deepagent-code/test/deepagent/runtime-domain-pack-adapter-gating.test.ts new file mode 100644 index 00000000..5ec36537 --- /dev/null +++ b/packages/deepagent-code/test/deepagent/runtime-domain-pack-adapter-gating.test.ts @@ -0,0 +1,219 @@ +import { describe, it, expect } from "bun:test" +import { DebugAdapter } from "../../src/debug/adapter" +import { ProfileAdapterRegistry } from "../../src/profile/adapters" + +// RX (S1-v3.5): domain-pack adapter gating. +// +// Verifies that: +// - Debug adapters (GDB) are absent before a domain pack registers them and +// present after registration; removed again on unregister. +// - Profile adapters (ncu/nsys — "CUDA pack") follow the same lifecycle via +// ProfileAdapterRegistry. +// +// Uses injected probes so tests run without real GDB/ncu/nsys binaries. + +// ——— debug adapter gating ———————————————————————————————————————————————————— + +describe("RX debug adapter domain-pack gating (DebugAdapter.Registry)", () => { + it("base set contains debugpy/delve/lldb but NOT gdb", () => { + const registry = DebugAdapter.make(DebugAdapter.installedProbe(["python3", "dlv", "lldb-dap"])) + expect(registry.has("debugpy")).toBe(true) + expect(registry.has("delve")).toBe(true) + expect(registry.has("lldb")).toBe(true) + // GDB is NOT in the base set — it requires a domain pack + expect(registry.has("gdb")).toBe(false) + }) + + it("registerGdb makes GDB available", () => { + const registry = DebugAdapter.make(DebugAdapter.installedProbe(["gdb"])) + expect(registry.has("gdb")).toBe(false) // not yet + + // Domain pack activates → registers GDB + DebugAdapter.registerGdb(registry) + + expect(registry.has("gdb")).toBe(true) + expect(registry.get("gdb")).toBeDefined() + expect(registry.get("gdb")!.id).toBe("gdb") + }) + + it("GDB resolves to an AdapterSpec when the binary is present", () => { + const registry = DebugAdapter.make(DebugAdapter.installedProbe(["gdb"])) + DebugAdapter.registerGdb(registry) + + const resolution = registry.resolveById("gdb") + expect(resolution.available).toBe(true) + if (resolution.available) { + expect(resolution.spec.id).toBe("gdb") + expect(resolution.spec.command).toContain("gdb") + expect(resolution.spec.args).toContain("--interpreter=dap") + } + }) + + it("GDB resolves graceful-missing when the binary is absent", () => { + const registry = DebugAdapter.make(DebugAdapter.missingProbe) + DebugAdapter.registerGdb(registry) + + const resolution = registry.resolveById("gdb") + expect(resolution.available).toBe(false) + if (!resolution.available) { + expect(resolution.message).toContain("gdb") + // Must give an install hint, not just "not found" + expect(resolution.message.length).toBeGreaterThan(10) + } + }) + + it("unregister removes GDB from the registry", () => { + const registry = DebugAdapter.make(DebugAdapter.installedProbe(["gdb"])) + DebugAdapter.registerGdb(registry) + expect(registry.has("gdb")).toBe(true) + + // Domain pack deactivates → unregisters GDB + registry.unregister("gdb") + + expect(registry.has("gdb")).toBe(false) + const resolution = registry.resolveById("gdb") + expect(resolution.available).toBe(false) + if (!resolution.available) { + expect(resolution.message).toContain("No debug adapter registered with id") + } + }) + + it("GDB adapter declares ptrace privilege (for R0 fail-closed gate)", () => { + expect(DebugAdapter.GDB.privileges.some((p) => p.kind === "ptrace")).toBe(true) + }) + + it("registering multiple adapters then removing one leaves others intact", () => { + const registry = DebugAdapter.make(DebugAdapter.installedProbe(["gdb", "python3", "dlv"])) + DebugAdapter.registerGdb(registry) + + expect(registry.has("gdb")).toBe(true) + expect(registry.has("debugpy")).toBe(true) + expect(registry.has("delve")).toBe(true) + + registry.unregister("gdb") + + expect(registry.has("gdb")).toBe(false) + // Base set still intact + expect(registry.has("debugpy")).toBe(true) + expect(registry.has("delve")).toBe(true) + }) +}) + +// ——— profile adapter gating —————————————————————————————————————————————————— + +describe("RX profile adapter domain-pack gating (ProfileAdapterRegistry)", () => { + it("empty registry has no adapters", () => { + const registry = new ProfileAdapterRegistry.Registry(ProfileAdapterRegistry.missingProbe) + expect(registry.list().length).toBe(0) + expect(registry.has("ncu")).toBe(false) + expect(registry.has("perf")).toBe(false) + }) + + it("make() pre-loads all five built-in adapters", () => { + const registry = ProfileAdapterRegistry.make(ProfileAdapterRegistry.missingProbe) + // All five registered (though binaries are missing — that's checked at resolve time) + expect(registry.has("ncu")).toBe(true) + expect(registry.has("nsys")).toBe(true) + expect(registry.has("rocprof")).toBe(true) + expect(registry.has("vtune")).toBe(true) + expect(registry.has("perf")).toBe(true) + }) + + it("registerCudaAdapters registers ncu + nsys on a blank registry", () => { + const probe = ProfileAdapterRegistry.installedProbe(["ncu", "nsys"]) + const registry = new ProfileAdapterRegistry.Registry(probe) + expect(registry.has("ncu")).toBe(false) + expect(registry.has("nsys")).toBe(false) + + // CUDA domain pack activates + ProfileAdapterRegistry.registerCudaAdapters(registry, probe) + + expect(registry.has("ncu")).toBe(true) + expect(registry.has("nsys")).toBe(true) + }) + + it("ncu resolves as available when binary is installed", () => { + const probe = ProfileAdapterRegistry.installedProbe(["ncu"]) + const registry = new ProfileAdapterRegistry.Registry(probe) + ProfileAdapterRegistry.registerCudaAdapters(registry, probe) + + const resolution = registry.resolveById("ncu") + expect(resolution.available).toBe(true) + if (resolution.available) { + expect(resolution.adapter.id).toBe("ncu") + expect(resolution.adapter.vendor).toBe("nvidia") + expect(resolution.adapter.domain).toBe("gpu_kernel") + } + }) + + it("ncu resolves graceful-missing when binary absent", () => { + const registry = new ProfileAdapterRegistry.Registry(ProfileAdapterRegistry.missingProbe) + ProfileAdapterRegistry.registerCudaAdapters(registry, ProfileAdapterRegistry.missingProbe) + + const resolution = registry.resolveById("ncu") + expect(resolution.available).toBe(false) + if (!resolution.available) { + expect(resolution.message).toContain("ncu") + } + }) + + it("unregister removes ncu from the registry", () => { + const probe = ProfileAdapterRegistry.installedProbe(["ncu", "nsys"]) + const registry = new ProfileAdapterRegistry.Registry(probe) + ProfileAdapterRegistry.registerCudaAdapters(registry, probe) + expect(registry.has("ncu")).toBe(true) + + // Domain pack deactivates → unregister ncu + registry.unregister("ncu") + + expect(registry.has("ncu")).toBe(false) + expect(registry.has("nsys")).toBe(true) // nsys still present + }) + + it("registerRocmAdapters registers rocprof", () => { + const probe = ProfileAdapterRegistry.installedProbe(["rocprofv3"]) + const registry = new ProfileAdapterRegistry.Registry(probe) + expect(registry.has("rocprof")).toBe(false) + + ProfileAdapterRegistry.registerRocmAdapters(registry, probe) + + expect(registry.has("rocprof")).toBe(true) + const r = registry.resolveById("rocprof") + expect(r.available).toBe(true) + if (r.available) { + expect(r.adapter.vendor).toBe("amd") + } + }) + + it("unregistered adapter resolves to graceful-missing with a clear message", () => { + const registry = new ProfileAdapterRegistry.Registry(ProfileAdapterRegistry.missingProbe) + const resolution = registry.resolveById("vtune") + expect(resolution.available).toBe(false) + if (!resolution.available) { + expect(resolution.adapterId).toBe("vtune") + expect(resolution.message).toContain("vtune") + } + }) + + it("ncu adapter declares gpu_performance_counter privilege (for R0 gate)", () => { + const probe = ProfileAdapterRegistry.installedProbe(["ncu"]) + const registry = ProfileAdapterRegistry.make(probe) + const ncu = registry.get("ncu")! + expect(ncu.privileges.some((p) => p.kind === "gpu_performance_counter")).toBe(true) + }) + + it("cross-domain: CUDA and ROCm adapters coexist in the same registry", () => { + const probe = ProfileAdapterRegistry.installedProbe(["ncu", "nsys", "rocprofv3"]) + const registry = new ProfileAdapterRegistry.Registry(probe) + ProfileAdapterRegistry.registerCudaAdapters(registry, probe) + ProfileAdapterRegistry.registerRocmAdapters(registry, probe) + + expect(registry.has("ncu")).toBe(true) + expect(registry.has("nsys")).toBe(true) + expect(registry.has("rocprof")).toBe(true) + + // Can resolve each independently + expect(registry.resolveById("ncu").available).toBe(true) + expect(registry.resolveById("rocprof").available).toBe(true) + }) +}) diff --git a/packages/deepagent-code/test/deepagent/runtime-plan-signal-high-only.test.ts b/packages/deepagent-code/test/deepagent/runtime-plan-signal-high-only.test.ts new file mode 100644 index 00000000..e46d31e6 --- /dev/null +++ b/packages/deepagent-code/test/deepagent/runtime-plan-signal-high-only.test.ts @@ -0,0 +1,225 @@ +import { describe, it, expect } from "bun:test" + +// RX (S1-v3.5): documents and tests the CONTRACT that runtime evidence (debug +// session / profile) can surface as a high-confidence plan signal, but NEVER +// auto-modifies plans, and NEVER degrades general/direct modes. +// +// This is a contract/documentation test: it asserts the SHAPE of evidence +// artifacts and verifies that their mere presence cannot trigger plan changes. +// No live debug or profile runs are needed — the contract is about data structures +// and invariants, not execution. + +// ——— DEBUG_SESSION.json evidence shape contract —————————————————————————————— + +type EvidenceKind = "lsp_query" | "debug_session" | "profile" + +interface EvidenceArtifact { + evidence_kind: EvidenceKind + [key: string]: unknown +} + +function isDebugEvidence(a: EvidenceArtifact): boolean { + return a.evidence_kind === "debug_session" +} + +function isProfileEvidence(a: EvidenceArtifact): boolean { + return a.evidence_kind === "profile" +} + +// ——— plan signal contract —————————————————————————————————————————————————— + +type ConfidenceLevel = "low" | "medium" | "high" | "confirmed" + +interface PlanSignal { + /** The evidence artifact that drives this signal. */ + evidence_kind: EvidenceKind + /** Confidence level; only "high" and "confirmed" may surface to plan layer. */ + confidence: ConfidenceLevel + /** What the signal says; never auto-applied. */ + description: string +} + +/** + * Contract: evidence may only become a plan signal at "high" or "confirmed" + * confidence. Low/medium evidence is logged but never forwarded to the plan. + * Even high-confidence signals are SURFACED (shown to the user / logged to the + * document graph) — they are NEVER auto-applied to the plan. + */ +function signalMayDrivePlan(signal: PlanSignal): boolean { + return signal.confidence === "high" || signal.confidence === "confirmed" +} + +/** + * Contract: no evidence artifact — however high-confidence — auto-modifies a + * plan. This function represents the gate: even if all conditions are met, the + * return value is "surface as suggestion", not "apply". + */ +function planActionForSignal(signal: PlanSignal): "no_action" | "surface_as_suggestion" { + if (!signalMayDrivePlan(signal)) return "no_action" + // Even high-confidence: SURFACE, never auto-apply. + return "surface_as_suggestion" +} + +// ——— general/direct mode degradation contract —————————————————————————————— + +type AgentMode = "general" | "direct" | "plan" + +/** + * Contract (§RX verification): debug/profile evidence does NOT change the + * agent's operating mode. general and direct modes are untouched. + */ +function modeAfterEvidence(currentMode: AgentMode, _evidence: EvidenceArtifact): AgentMode { + // Evidence never changes the mode. This is the invariant. + return currentMode +} + +// ——— tests —————————————————————————————————————————————————————————————————— + +describe("RX plan-signal high-only contract", () => { + describe("evidence artifact shape", () => { + it("DEBUG_SESSION.json has evidence_kind:debug_session", () => { + const artifact: EvidenceArtifact = { + evidence_kind: "debug_session", + session_id: "dbg-001", + backtrace: [], + variable_snapshot: {}, + } + expect(isDebugEvidence(artifact)).toBe(true) + expect(isProfileEvidence(artifact)).toBe(false) + }) + + it("PROFILE_RESULT.json has evidence_kind:profile", () => { + const artifact: EvidenceArtifact = { + evidence_kind: "profile", + profile: {}, + roofline: { bound: "compute", detail: "...", derived: true }, + } + expect(isProfileEvidence(artifact)).toBe(true) + expect(isDebugEvidence(artifact)).toBe(false) + }) + + it("evidence_kind is one of the three accepted values", () => { + const kinds: EvidenceKind[] = ["lsp_query", "debug_session", "profile"] + for (const kind of kinds) { + const a: EvidenceArtifact = { evidence_kind: kind } + expect(kinds).toContain(a.evidence_kind) + } + }) + }) + + describe("plan signal confidence gate", () => { + it("low-confidence debug evidence does NOT drive a plan signal", () => { + const signal: PlanSignal = { + evidence_kind: "debug_session", + confidence: "low", + description: "variable x was None in one run", + } + expect(signalMayDrivePlan(signal)).toBe(false) + expect(planActionForSignal(signal)).toBe("no_action") + }) + + it("medium-confidence profile evidence does NOT drive a plan signal", () => { + const signal: PlanSignal = { + evidence_kind: "profile", + confidence: "medium", + description: "matmul_kernel uses 70% of GPU time", + } + expect(signalMayDrivePlan(signal)).toBe(false) + expect(planActionForSignal(signal)).toBe("no_action") + }) + + it("high-confidence debug evidence CAN surface as a plan suggestion", () => { + const signal: PlanSignal = { + evidence_kind: "debug_session", + confidence: "high", + description: "foo() returns None on input=[1,2,3] — root cause confirmed via breakpoint", + } + expect(signalMayDrivePlan(signal)).toBe(true) + // But it is SURFACED, never auto-applied + expect(planActionForSignal(signal)).toBe("surface_as_suggestion") + }) + + it("high-confidence profile evidence CAN surface as a plan suggestion", () => { + const signal: PlanSignal = { + evidence_kind: "profile", + confidence: "high", + description: "matmul_kernel is DRAM-bandwidth-bound (91%); optimization target confirmed", + } + expect(signalMayDrivePlan(signal)).toBe(true) + expect(planActionForSignal(signal)).toBe("surface_as_suggestion") + }) + + it("confirmed-confidence evidence surfaces as suggestion (never auto-applies)", () => { + const signal: PlanSignal = { + evidence_kind: "debug_session", + confidence: "confirmed", + description: "NullPointerException always at line 42 with this input", + } + expect(planActionForSignal(signal)).toBe("surface_as_suggestion") + // NEVER "auto_apply" — that value does not exist in the type + }) + }) + + describe("general/direct mode non-degradation", () => { + it("debug evidence does not change general mode", () => { + const evidence: EvidenceArtifact = { evidence_kind: "debug_session" } + expect(modeAfterEvidence("general", evidence)).toBe("general") + }) + + it("profile evidence does not change direct mode", () => { + const evidence: EvidenceArtifact = { evidence_kind: "profile" } + expect(modeAfterEvidence("direct", evidence)).toBe("direct") + }) + + it("lsp_query evidence does not change general mode", () => { + const evidence: EvidenceArtifact = { evidence_kind: "lsp_query" } + expect(modeAfterEvidence("general", evidence)).toBe("general") + }) + + it("evidence in plan mode does not auto-advance the plan", () => { + // Plan mode stays in plan mode; evidence is surfaced but not executed + const evidence: EvidenceArtifact = { evidence_kind: "profile" } + expect(modeAfterEvidence("plan", evidence)).toBe("plan") + }) + }) + + describe("end-to-end evidence pipeline contract (§10 global acceptance gate §6)", () => { + it("high-confidence evidence enters the document graph as an artifact but does not modify the plan automatically", () => { + // §10-6: "debug/profile 证据落 artifact（evidence_kind）进文档图，可被计划/审计引用，不自动改计划" + const profileArtifact: EvidenceArtifact = { + evidence_kind: "profile", + profile: { domain: "gpu_kernel", hotspots: [{ kernel: "matmul", self_pct: 72 }] }, + roofline: { bound: "memory", detail: "memory-bound (dram_bandwidth_pct=91%)", derived: true }, + } + const debugArtifact: EvidenceArtifact = { + evidence_kind: "debug_session", + session_id: "dbg-42", + backtrace: [{ frame: 0, symbol: "foo", file: "src/foo.py", line: 42 }], + root_cause: "NullPointerException — foo() receives None from bar()", + } + + // Both are valid evidence artifacts + expect(isProfileEvidence(profileArtifact)).toBe(true) + expect(isDebugEvidence(debugArtifact)).toBe(true) + + // Even if forwarded as high-confidence signals, the action is SURFACE not AUTO-APPLY + const profileSignal: PlanSignal = { + evidence_kind: "profile", + confidence: "high", + description: `${profileArtifact.roofline}`, + } + const debugSignal: PlanSignal = { + evidence_kind: "debug_session", + confidence: "high", + description: `${debugArtifact.root_cause}`, + } + + expect(planActionForSignal(profileSignal)).toBe("surface_as_suggestion") + expect(planActionForSignal(debugSignal)).toBe("surface_as_suggestion") + + // General mode stays general — no automatic mode switch + expect(modeAfterEvidence("general", profileArtifact)).toBe("general") + expect(modeAfterEvidence("general", debugArtifact)).toBe("general") + }) + }) +}) diff --git a/packages/deepagent-code/test/deepagent/runtime-worktree-coplay.test.ts b/packages/deepagent-code/test/deepagent/runtime-worktree-coplay.test.ts new file mode 100644 index 00000000..3d556f79 --- /dev/null +++ b/packages/deepagent-code/test/deepagent/runtime-worktree-coplay.test.ts @@ -0,0 +1,149 @@ +import { afterEach, describe, expect } from "bun:test" +import { FSUtil } from "@deepagent-code/core/fs-util" +import { CrossSpawnSpawner } from "@deepagent-code/core/cross-spawn-spawner" +import { Effect, Layer } from "effect" +import { Git } from "../../src/git" +import { Worktree } from "../../src/worktree" +import { RuntimeBase } from "../../src/runtime/base" +import { InstanceState } from "../../src/effect/instance-state" +import { disposeAllInstances } from "../fixture/fixture" +import { testEffect } from "../lib/effect" + +// RX (S1-v3.5): verifies that R0's withIsolation creates an isolated worktree +// for BOTH debug and profile scenarios, then cleans up after the body completes. +// This test mirrors the isolation scenario in runtime-base.test.ts but confirms +// that the same mechanism works correctly when called from debug/profile paths. + +const baseLayer = (probe?: RuntimeBase.PrivilegeProbe) => + Layer.mergeAll( + RuntimeBase.testLayer(probe).pipe(Layer.provide(Worktree.defaultLayer)), + Worktree.defaultLayer, + FSUtil.defaultLayer, + CrossSpawnSpawner.defaultLayer, + Git.defaultLayer, + ) + +describe("RX runtime worktree coplay", () => { + afterEach(() => disposeAllInstances()) + + const it = testEffect(baseLayer(RuntimeBase.allowAllProbe)) + + describe("debug scenario: isolation for a debug session", () => { + it.instance( + "withIsolation returns a directory different from the main instance directory", + () => + Effect.gen(function* () { + const base = yield* RuntimeBase.Service + const ctx = yield* InstanceState.context + + const workdir = yield* base.withIsolation({ name: "rx-debug-session" }, (dir) => + Effect.succeed(dir), + ) + + // The isolated dir is distinct from the main project dir + expect(workdir).not.toBe(ctx.directory) + // The worktree name appears in the path (R0 appends it via Worktree.create) + expect(workdir).toContain("rx-debug-session") + }), + { git: true }, + ) + + it.instance( + "worktree is removed after the body completes (no orphaned worktrees)", + () => + Effect.gen(function* () { + const base = yield* RuntimeBase.Service + const wt = yield* Worktree.Service + + const workdir = yield* base.withIsolation({ name: "rx-debug-cleanup" }, (dir) => + Effect.succeed(dir), + ) + + // After completion the clean worktree should be gone + const list = yield* wt.list() + const still_present = list.some((w) => w.directory === workdir) + expect(still_present).toBe(false) + }), + { git: true }, + ) + + it.instance( + "body result is forwarded — isolation is transparent", + () => + Effect.gen(function* () { + const base = yield* RuntimeBase.Service + + const result = yield* base.withIsolation({ name: "rx-debug-body-result" }, (_dir) => + Effect.succeed({ session_id: "s-42", frames: 7 }), + ) + + expect(result.session_id).toBe("s-42") + expect(result.frames).toBe(7) + }), + { git: true }, + ) + }) + + describe("profile scenario: isolation for a profiling run", () => { + it.instance( + "withIsolation returns a directory distinct from main dir for profile scenario", + () => + Effect.gen(function* () { + const base = yield* RuntimeBase.Service + const ctx = yield* InstanceState.context + + const workdir = yield* base.withIsolation({ name: "rx-profile-run" }, (dir) => + Effect.succeed(dir), + ) + + expect(workdir).not.toBe(ctx.directory) + expect(workdir).toContain("rx-profile-run") + }), + { git: true }, + ) + + it.instance( + "two parallel isolation calls produce two distinct worktrees", + () => + Effect.gen(function* () { + const base = yield* RuntimeBase.Service + + // Simulate two concurrent profile/debug operations each getting their own tree + const [dirA, dirB] = yield* Effect.all( + [ + base.withIsolation({ name: "rx-parallel-a" }, (dir) => Effect.succeed(dir)), + base.withIsolation({ name: "rx-parallel-b" }, (dir) => Effect.succeed(dir)), + ], + { concurrency: 2 }, + ) + + expect(dirA).not.toBe(dirB) + expect(dirA).toContain("rx-parallel-a") + expect(dirB).toContain("rx-parallel-b") + }), + { git: true }, + ) + + it.instance( + "isolation cleans up even when the body produces a value (not just void)", + () => + Effect.gen(function* () { + const base = yield* RuntimeBase.Service + const wt = yield* Worktree.Service + + const artifactPath = yield* base.withIsolation({ name: "rx-profile-artifact" }, (dir) => + // Simulates what a real profile run would do: return an artifact path + Effect.succeed(`${dir}/PROFILE_RESULT.json`), + ) + + expect(artifactPath).toContain("PROFILE_RESULT.json") + + // The worktree has been cleaned up + const list = yield* wt.list() + const wtDir = artifactPath.replace("/PROFILE_RESULT.json", "") + expect(list.some((w) => w.directory === wtDir)).toBe(false) + }), + { git: true }, + ) + }) +}) diff --git a/packages/deepagent-code/test/fake/provider.ts b/packages/deepagent-code/test/fake/provider.ts index 17069ad2..70cac03c 100644 --- a/packages/deepagent-code/test/fake/provider.ts +++ b/packages/deepagent-code/test/fake/provider.ts @@ -54,6 +54,7 @@ export namespace ProviderTest { Provider.Service, Provider.Service.of({ list: Effect.fn("TestProvider.list")(() => Effect.succeed({ [row.id]: row })), + errors: Effect.fn("TestProvider.errors")(() => Effect.succeed([])), getProvider: Effect.fn("TestProvider.getProvider")((providerID) => { if (providerID === row.id) return Effect.succeed(row) return Effect.die(new Error(`Unknown test provider: ${providerID}`)) diff --git a/packages/deepagent-code/test/fixture/debug/fake-dap-adapter.js b/packages/deepagent-code/test/fixture/debug/fake-dap-adapter.js new file mode 100644 index 00000000..818c2889 --- /dev/null +++ b/packages/deepagent-code/test/fixture/debug/fake-dap-adapter.js @@ -0,0 +1,171 @@ +// Minimal fake Debug Adapter Protocol (DAP) adapter over stdio. +// +// Speaks the DAP base protocol wire format — Content-Length headers + JSON body, +// identical framing to LSP — but with DAP message shapes: +// request: { seq, type:"request", command, arguments } +// response: { seq, type:"response", request_seq, success, command, body } +// event: { seq, type:"event", event, body } +// +// It implements just enough of a real adapter (debugpy/delve/lldb) for D1's +// client + DebugService tests: initialize / launch / attach / setBreakpoints / +// configurationDone / threads / stackTrace / scopes / variables / evaluate / +// continue / next|stepIn|stepOut / terminate / disconnect, and emits the +// `initialized`, `stopped`, `output`, `terminated`, `exited` events. + +let outSeq = 1 +let readBuffer = Buffer.alloc(0) +let stepCount = 0 + +function encode(message) { + const json = JSON.stringify(message) + const header = `Content-Length: ${Buffer.byteLength(json, "utf8")}\r\n\r\n` + return Buffer.concat([Buffer.from(header, "utf8"), Buffer.from(json, "utf8")]) +} + +function decodeFrames(buffer) { + const results = [] + let idx + while ((idx = buffer.indexOf("\r\n\r\n")) !== -1) { + const header = buffer.slice(0, idx).toString("utf8") + const match = /Content-Length:\s*(\d+)/i.exec(header) + const length = match ? parseInt(match[1], 10) : 0 + const bodyStart = idx + 4 + const bodyEnd = bodyStart + length + if (buffer.length < bodyEnd) break + results.push(buffer.slice(bodyStart, bodyEnd).toString("utf8")) + buffer = buffer.slice(bodyEnd) + } + return { messages: results, rest: buffer } +} + +function write(message) { + process.stdout.write(encode(message)) +} + +function respond(request, body, success = true) { + write({ + seq: outSeq++, + type: "response", + request_seq: request.seq, + success, + command: request.command, + body, + }) +} + +function event(name, body) { + write({ seq: outSeq++, type: "event", event: name, body }) +} + +function handle(raw) { + let req + try { + req = JSON.parse(raw) + } catch { + return + } + if (req.type !== "request") return + + switch (req.command) { + case "initialize": + respond(req, { + supportsConfigurationDoneRequest: true, + supportsConditionalBreakpoints: true, + supportsEvaluateForHovers: true, + }) + // A real adapter signals readiness for configuration via `initialized`. + // We send it on launch/attach (below) so the client's waiter is already + // registered; sending here would race the client's subscription. + break + + case "launch": + case "attach": + // Signal the client to send breakpoints + configurationDone. + event("initialized", {}) + respond(req, {}) + event("output", { category: "stdout", output: "fake adapter started\n" }) + break + + case "setBreakpoints": { + const bps = (req.arguments && req.arguments.breakpoints) || [] + respond(req, { breakpoints: bps.map((b, i) => ({ id: i + 1, verified: true, line: b.line })) }) + break + } + + case "configurationDone": + respond(req, {}) + // Program runs and immediately hits a breakpoint. + event("stopped", { reason: "breakpoint", threadId: 1, allThreadsStopped: true }) + break + + case "threads": + respond(req, { threads: [{ id: 1, name: "main" }] }) + break + + case "stackTrace": + respond(req, { + stackFrames: [ + { id: 1, name: "main", line: 10, column: 1, source: { path: "/repro/main.py" } }, + { id: 2, name: "caller", line: 4, column: 1, source: { path: "/repro/main.py" } }, + ], + totalFrames: 2, + }) + break + + case "scopes": + respond(req, { scopes: [{ name: "Locals", variablesReference: 100, expensive: false }] }) + break + + case "variables": + respond(req, { + variables: [ + { name: "x", value: "42", type: "int", variablesReference: 0 }, + { name: "items", value: "[1, 2, 3]", type: "list", variablesReference: 101 }, + ], + }) + break + + case "evaluate": + respond(req, { result: `evaluated(${req.arguments && req.arguments.expression})`, variablesReference: 0 }) + break + + case "next": + case "stepIn": + case "stepOut": + respond(req, {}) + stepCount += 1 + // Stepping pauses again on the next line. + event("stopped", { reason: "step", threadId: 1, allThreadsStopped: true }) + break + + case "continue": + respond(req, { allThreadsContinued: true }) + // Resume to completion: program ends. + event("output", { category: "stdout", output: "done\n" }) + event("terminated", {}) + event("exited", { exitCode: 0 }) + break + + case "terminate": + respond(req, {}) + event("terminated", {}) + break + + case "disconnect": + respond(req, {}) + setTimeout(() => process.exit(0), 10) + break + + default: + // Unknown command: respond unsuccessfully, like a real adapter would. + respond(req, undefined, false) + break + } +} + +process.stdin.on("data", (chunk) => { + readBuffer = Buffer.concat([readBuffer, chunk]) + const { messages, rest } = decodeFrames(readBuffer) + readBuffer = rest + for (const message of messages) handle(message) +}) diff --git a/packages/deepagent-code/test/mcp/catalog.test.ts b/packages/deepagent-code/test/mcp/catalog.test.ts index 28045a88..33160dc5 100644 --- a/packages/deepagent-code/test/mcp/catalog.test.ts +++ b/packages/deepagent-code/test/mcp/catalog.test.ts @@ -69,19 +69,21 @@ describe("mcp.catalog", () => { expect(config.enabled).toBe(true) }) - it("M1/M7: instantiate(postgres) routes the connection string through env, never the command line", () => { + it("M1/M7/M-CRED: instantiate(postgres) routes the connection string through env as a ${KEY} ref, never plaintext", () => { const pg = McpCatalog.find("postgres-readonly")! const { config } = McpCatalog.instantiate(pg, { params: {}, credentialRefs: { DATABASE_URI: "postgres://u:p@h/db" }, }) if (config.type !== "local") throw new Error("expected local config") - // The secret must be in env, not argv (process-table leakage). - expect(config.environment?.DATABASE_URI).toBe("postgres://u:p@h/db") + // M-CRED: the secret is an env REFERENCE, not the plaintext value. + expect(config.environment?.DATABASE_URI).toBe("${DATABASE_URI}") + expect(JSON.stringify(config)).not.toContain("postgres://") + // And never on the command line (process-table leakage). expect(config.command.join(" ")).not.toContain("postgres://") }) - it("M1: instantiate(github) builds a remote config with the PAT in an Authorization header", () => { + it("M1/M-CRED: instantiate(github) builds a remote config with a ${KEY} ref in the Authorization header, never the PAT", () => { const github = McpCatalog.find("github")! const { config } = McpCatalog.instantiate(github, { params: {}, @@ -89,7 +91,9 @@ describe("mcp.catalog", () => { }) if (config.type !== "remote") throw new Error("expected remote config") expect(config.url).toContain("/readonly") - expect(config.headers?.Authorization).toBe("Bearer ghp_x") + // M-CRED: the PAT is an env REFERENCE, not the plaintext token. + expect(config.headers?.Authorization).toBe("Bearer ${GITHUB_PERSONAL_ACCESS_TOKEN}") + expect(JSON.stringify(config)).not.toContain("ghp_x") }) it("M1: instantiate fails-closed on a missing required param", () => { diff --git a/packages/deepagent-code/test/mcp/oauth-auto-connect.test.ts b/packages/deepagent-code/test/mcp/oauth-auto-connect.test.ts index 69b27e9d..82fa1ba9 100644 --- a/packages/deepagent-code/test/mcp/oauth-auto-connect.test.ts +++ b/packages/deepagent-code/test/mcp/oauth-auto-connect.test.ts @@ -128,6 +128,7 @@ const { MCP } = await import("../../src/mcp/index") const { EventV2Bridge } = await import("../../src/event-v2-bridge") const { Config } = await import("../../src/config/config") const { McpAuth } = await import("../../src/mcp/auth") +const { SecretStore } = await import("../../src/mcp/secret-store") const { McpOAuthProvider } = await import("../../src/mcp/oauth-provider") const { FSUtil } = await import("@deepagent-code/core/fs-util") const { CrossSpawnSpawner } = await import("@deepagent-code/core/cross-spawn-spawner") @@ -136,6 +137,7 @@ const mcpTest = testEffect( Layer.mergeAll( MCP.layer.pipe( Layer.provide(McpAuth.defaultLayer), + Layer.provide(SecretStore.testLayer()), Layer.provideMerge(EventV2Bridge.defaultLayer), Layer.provide(Config.defaultLayer), Layer.provide(CrossSpawnSpawner.defaultLayer), diff --git a/packages/deepagent-code/test/mcp/oauth-browser.test.ts b/packages/deepagent-code/test/mcp/oauth-browser.test.ts index 86007a7e..ffad3b7f 100644 --- a/packages/deepagent-code/test/mcp/oauth-browser.test.ts +++ b/packages/deepagent-code/test/mcp/oauth-browser.test.ts @@ -113,12 +113,14 @@ const { MCP } = await import("../../src/mcp/index") const { EventV2Bridge } = await import("../../src/event-v2-bridge") const { Config } = await import("../../src/config/config") const { McpAuth } = await import("../../src/mcp/auth") +const { SecretStore } = await import("../../src/mcp/secret-store") const { McpOAuthCallback } = await import("../../src/mcp/oauth-callback") const { FSUtil } = await import("@deepagent-code/core/fs-util") const { CrossSpawnSpawner } = await import("@deepagent-code/core/cross-spawn-spawner") const mcpTest = testEffect( MCP.layer.pipe( Layer.provide(McpAuth.defaultLayer), + Layer.provide(SecretStore.testLayer()), Layer.provideMerge(EventV2Bridge.defaultLayer), Layer.provide(Config.defaultLayer), Layer.provide(CrossSpawnSpawner.defaultLayer), diff --git a/packages/deepagent-code/test/provider/header-timeout.test.ts b/packages/deepagent-code/test/provider/header-timeout.test.ts index a7d659e0..bf0fb82c 100644 --- a/packages/deepagent-code/test/provider/header-timeout.test.ts +++ b/packages/deepagent-code/test/provider/header-timeout.test.ts @@ -135,8 +135,10 @@ it.live("headerTimeout is opt-in for non-OpenAI providers", () => }), ) -it.live("OpenAI Codex headerTimeout default can be disabled by config", () => +it.live("OpenAI Codex headerTimeout default cannot be overridden via config for official providers", () => Effect.gen(function* () { + // Official providers (openai, anthropic, …) ignore ALL config including transport options. + // headerTimeout can only be tuned through the provider settings UI, not config files. yield* withAuthContent( Effect.gen(function* () { yield* provideTmpdirInstance( @@ -144,7 +146,8 @@ it.live("OpenAI Codex headerTimeout default can be disabled by config", () => Effect.gen(function* () { const provider = yield* Provider.Service const openai = yield* provider.getProvider(ProviderV2.ID.openai) - expect(openai.options.headerTimeout).toBe(false) + // config sets false but official isolation means the catalog default (10_000) wins + expect(openai.options.headerTimeout).toBe(10_000) }), { config: { provider: { openai: { options: { headerTimeout: false } } } } }, ) diff --git a/packages/deepagent-code/test/provider/provider.test.ts b/packages/deepagent-code/test/provider/provider.test.ts index cee55546..9a7356bf 100644 --- a/packages/deepagent-code/test/provider/provider.test.ts +++ b/packages/deepagent-code/test/provider/provider.test.ts @@ -87,12 +87,21 @@ const deepagentAuthProviderFixture = pathToFileURL( path.join(import.meta.dir, "../fixture/deepagent-auth-provider.js"), ).href -const it = testEffect(Layer.mergeAll(Provider.defaultLayer, Env.defaultLayer, Plugin.defaultLayer)) +const it = testEffect(Layer.mergeAll(Provider.defaultLayer, Env.defaultLayer, Plugin.defaultLayer, Auth.defaultLayer)) const itWithAuth = testEffect( Layer.mergeAll(Provider.defaultLayer, Env.defaultLayer, Plugin.defaultLayer, Auth.defaultLayer), ) const experimentalModels = testEffect(providerLayer({ enableExperimentalModels: true })) +const connect = (providerID: ProviderV2.ID, key: string) => + Effect.gen(function* () { + const auth = yield* Auth.Service + yield* auth.set(providerID, { + type: "api", + key, + }) + }) + const alphaProviderConfig = { provider: { "custom-provider": { @@ -115,31 +124,140 @@ const alphaProviderConfig = { }, } -it.instance("provider loaded from env variable", () => +it.instance("official provider loaded from auth key store", () => Effect.gen(function* () { - yield* setProcessEnv("ANTHROPIC_API_KEY", "test-api-key") + yield* connect(ProviderV2.ID.anthropic, "test-api-key") const providers = yield* list expect(providers[ProviderV2.ID.anthropic]).toBeDefined() - // Provider should retain its connection source even if custom loaders - // merge additional options. - expect(providers[ProviderV2.ID.anthropic].source).toBe("env") + expect(providers[ProviderV2.ID.anthropic].source).toBe("api") expect(providers[ProviderV2.ID.anthropic].options.headers["anthropic-beta"]).toBeDefined() }), ) it.instance( - "provider loaded from config with apiKey option", + "third-party provider loaded from config with apiKey option", Effect.gen(function* () { const providers = yield* list - expect(providers[ProviderV2.ID.anthropic]).toBeDefined() + const provider = providers[ProviderV2.ID.make("custom-anthropic")] + expect(provider).toBeDefined() + expect(provider.source).toBe("custom") + expect(provider.options.apiKey).toBe("config-api-key") + }), + { + config: { + provider: { + "custom-anthropic": { + name: "Custom Anthropic", + npm: "@ai-sdk/anthropic", + options: { apiKey: "config-api-key" }, + models: { "custom-model": { name: "Custom Model" } }, + }, + }, + }, + }, +) + +it.instance( + "config provider with official id reports duplicate provider error", + Effect.gen(function* () { + const providers = yield* list + expect(providers[ProviderV2.ID.make("zhipuai")]).toBeUndefined() + const errors = yield* Provider.use.errors() + expect(errors).toEqual([ + { + source: "provider.zhipuai", + kind: "schema", + message: "Provider id conflicts with an official provider. Rename this third-party provider in your config.", + }, + ]) + }), + { + config: { + provider: { + zhipuai: { + name: "Custom Zhipu Endpoint", + api: "https://open.bigmodel.cn/api/coding/paas/v4", + options: { apiKey: "config-api-key", baseURL: "https://open.bigmodel.cn/api/coding/paas/v4" }, + models: { "custom-only": { name: "Custom Only", limit: { context: 128_000, output: 8192 } } }, + }, + }, + }, + }, +) + +it.instance( + "official provider ignores duplicate third-party config and loads from auth key store", + Effect.gen(function* () { + yield* connect(ProviderV2.ID.make("zhipuai"), "test-api-key") + const providers = yield* list + const provider = providers[ProviderV2.ID.make("zhipuai")] + expect(provider).toBeDefined() + expect(provider.source).toBe("api") + expect(provider.options.baseURL).toBeUndefined() + expect(provider.models["custom-only"]).toBeUndefined() + expect(provider.models["glm-5"].api.url).toBe("https://open.bigmodel.cn/api/paas/v4") + }), + { + config: { + provider: { + zhipuai: { + name: "Custom Zhipu Endpoint", + api: "https://open.bigmodel.cn/api/coding/paas/v4", + options: { baseURL: "https://open.bigmodel.cn/api/coding/paas/v4" }, + models: { "custom-only": { name: "Custom Only", limit: { context: 128_000, output: 8192 } } }, + }, + }, + }, + }, +) + +it.instance( + "non-official catalog id is a third-party provider from config", + Effect.gen(function* () { + const providers = yield* list + // mistral is in the models.dev catalog but is NOT official, so a config block owns it as a + // third-party provider: the config baseURL/apiKey/models apply and no conflict error is raised. + const provider = providers[ProviderV2.ID.make("mistral")] + expect(provider).toBeDefined() + expect(provider.source).toBe("custom") + expect(provider.options.apiKey).toBe("mistral-config-key") + expect(provider.models["my-mistral"]).toBeDefined() + const errors = yield* Provider.use.errors() + expect(errors.find((e) => e.source === "provider.mistral")).toBeUndefined() + }), + { + config: { + provider: { + mistral: { + name: "My Mistral", + npm: "@ai-sdk/openai-compatible", + options: { apiKey: "mistral-config-key", baseURL: "https://api.mistral.ai/v1" }, + models: { "my-mistral": { name: "My Mistral Model" } }, + }, + }, + }, + }, +) + +it.instance( + "legacy key-store entry for a non-official provider reports a warning", + Effect.gen(function* () { + // Old flow wrote third-party keys to the auth store; those are no longer read for non-official + // ids. The provider must not appear, and the user gets a migration warning. + yield* connect(ProviderV2.ID.make("groq"), "legacy-key") + const providers = yield* list + expect(providers[ProviderV2.ID.make("groq")]).toBeUndefined() + const errors = yield* Provider.use.errors() + const warning = errors.find((e) => e.source === "auth.groq") + expect(warning).toBeDefined() + expect(warning!.message).toContain("no longer used") }), - { config: { provider: { anthropic: { options: { apiKey: "config-api-key" } } } } }, ) it.instance( "disabled_providers excludes provider", Effect.gen(function* () { - yield* setProcessEnv("ANTHROPIC_API_KEY", "test-api-key") + yield* connect(ProviderV2.ID.anthropic, "test-api-key") const providers = yield* list expect(providers[ProviderV2.ID.anthropic]).toBeUndefined() }), @@ -149,8 +267,8 @@ it.instance( it.instance( "enabled_providers restricts to only listed providers", Effect.gen(function* () { - yield* setProcessEnv("ANTHROPIC_API_KEY", "test-api-key") - yield* setProcessEnv("OPENAI_API_KEY", "test-openai-key") + yield* connect(ProviderV2.ID.anthropic, "test-api-key") + yield* connect(ProviderV2.ID.openai, "test-openai-key") const providers = yield* list expect(providers[ProviderV2.ID.anthropic]).toBeDefined() expect(providers[ProviderV2.ID.openai]).toBeUndefined() @@ -159,38 +277,37 @@ it.instance( ) it.instance( - "model whitelist filters models for provider", + "official provider config whitelist is ignored", Effect.gen(function* () { - yield* setProcessEnv("ANTHROPIC_API_KEY", "test-api-key") + yield* connect(ProviderV2.ID.anthropic, "test-api-key") const providers = yield* list expect(providers[ProviderV2.ID.anthropic]).toBeDefined() const models = Object.keys(providers[ProviderV2.ID.anthropic].models) expect(models).toContain("claude-sonnet-4-20250514") - expect(models.length).toBe(1) + expect(models.length).toBeGreaterThan(1) }), { config: { provider: { anthropic: { whitelist: ["claude-sonnet-4-20250514"] } } } }, ) it.instance( - "model blacklist excludes specific models", + "official provider config blacklist is ignored", Effect.gen(function* () { - yield* setProcessEnv("ANTHROPIC_API_KEY", "test-api-key") + yield* connect(ProviderV2.ID.anthropic, "test-api-key") const providers = yield* list expect(providers[ProviderV2.ID.anthropic]).toBeDefined() const models = Object.keys(providers[ProviderV2.ID.anthropic].models) - expect(models).not.toContain("claude-sonnet-4-20250514") + expect(models).toContain("claude-sonnet-4-20250514") }), { config: { provider: { anthropic: { blacklist: ["claude-sonnet-4-20250514"] } } } }, ) it.instance( - "custom model alias via config", + "official provider config model alias is ignored", Effect.gen(function* () { - yield* setProcessEnv("ANTHROPIC_API_KEY", "test-api-key") + yield* connect(ProviderV2.ID.anthropic, "test-api-key") const providers = yield* list expect(providers[ProviderV2.ID.anthropic]).toBeDefined() - expect(providers[ProviderV2.ID.anthropic].models["my-alias"]).toBeDefined() - expect(providers[ProviderV2.ID.anthropic].models["my-alias"].name).toBe("My Custom Alias") + expect(providers[ProviderV2.ID.anthropic].models["my-alias"]).toBeUndefined() }), { config: { @@ -290,22 +407,21 @@ it.instance( ) it.instance( - "env variable takes precedence, config merges options", + "official provider auth ignores duplicate config options", Effect.gen(function* () { - yield* setProcessEnv("ANTHROPIC_API_KEY", "env-api-key") + yield* connect(ProviderV2.ID.anthropic, "env-api-key") const providers = yield* list expect(providers[ProviderV2.ID.anthropic]).toBeDefined() - // Config options should be merged - expect(providers[ProviderV2.ID.anthropic].options.timeout).toBe(60000) - expect(providers[ProviderV2.ID.anthropic].options.headerTimeout).toBe(10000) - expect(providers[ProviderV2.ID.anthropic].options.chunkTimeout).toBe(15000) + expect(providers[ProviderV2.ID.anthropic].options.timeout).toBeUndefined() + expect(providers[ProviderV2.ID.anthropic].options.headerTimeout).toBeUndefined() + expect(providers[ProviderV2.ID.anthropic].options.chunkTimeout).toBeUndefined() }), { config: { provider: { anthropic: { options: { timeout: 60000, headerTimeout: 10000, chunkTimeout: 15000 } } } } }, ) it.instance("getModel returns model for valid provider/model", () => Effect.gen(function* () { - yield* setProcessEnv("ANTHROPIC_API_KEY", "test-api-key") + yield* connect(ProviderV2.ID.anthropic, "test-api-key") const provider = yield* Provider.Service const model = yield* provider.getModel(ProviderV2.ID.anthropic, ModelV2.ID.make("claude-sonnet-4-20250514")) expect(model).toBeDefined() @@ -371,7 +487,7 @@ itWithAuth.instance( it.instance("getModel throws ModelNotFoundError for invalid model", () => Effect.gen(function* () { - yield* set("ANTHROPIC_API_KEY", "test-api-key") + yield* connect(ProviderV2.ID.anthropic, "test-api-key") const exit = yield* Provider.use .getModel(ProviderV2.ID.anthropic, ModelV2.ID.make("nonexistent-model")) .pipe(Effect.exit) @@ -404,7 +520,7 @@ test("parseModel handles model IDs with slashes", () => { it.instance("defaultModel returns first available model when no config set", () => Effect.gen(function* () { - yield* setProcessEnv("ANTHROPIC_API_KEY", "test-api-key") + yield* connect(ProviderV2.ID.anthropic, "test-api-key") const model = yield* Provider.use.defaultModel() expect(model.providerID).toBeDefined() expect(model.modelID).toBeDefined() @@ -414,7 +530,7 @@ it.instance("defaultModel returns first available model when no config set", () it.instance( "defaultModel respects config model setting", Effect.gen(function* () { - yield* setProcessEnv("ANTHROPIC_API_KEY", "test-api-key") + yield* connect(ProviderV2.ID.anthropic, "test-api-key") const model = yield* Provider.use.defaultModel() expect(String(model.providerID)).toBe("anthropic") expect(String(model.modelID)).toBe("claude-sonnet-4-20250514") @@ -480,11 +596,12 @@ it.instance( ) it.instance( - "model options are merged from existing model", + "official provider model options from config are ignored", Effect.gen(function* () { + yield* connect(ProviderV2.ID.anthropic, "test-api-key") const providers = yield* list const model = providers[ProviderV2.ID.anthropic].models["claude-sonnet-4-20250514"] - expect(model.options.customOption).toBe("custom-value") + expect(model.options.customOption).toBeUndefined() }), { config: { @@ -499,17 +616,18 @@ it.instance( ) it.instance( - "provider removed when all models filtered out", + "official provider whitelist cannot remove provider", Effect.gen(function* () { + yield* connect(ProviderV2.ID.anthropic, "test-api-key") const providers = yield* list - expect(providers[ProviderV2.ID.anthropic]).toBeUndefined() + expect(providers[ProviderV2.ID.anthropic]).toBeDefined() }), { config: { provider: { anthropic: { options: { apiKey: "test-api-key" }, whitelist: ["nonexistent-model"] } } } }, ) it.instance("closest finds model by partial match", () => Effect.gen(function* () { - yield* set("ANTHROPIC_API_KEY", "test-api-key") + yield* connect(ProviderV2.ID.anthropic, "test-api-key") const result = yield* Provider.use.closest(ProviderV2.ID.anthropic, ["sonnet-4"]) expect(result).toBeDefined() expect(String(result?.providerID)).toBe("anthropic") @@ -525,16 +643,13 @@ it.instance("closest returns undefined for nonexistent provider", () => ) it.instance( - "getModel uses realIdByKey for aliased models", + "official provider alias config is not added to getModel", Effect.gen(function* () { - yield* set("ANTHROPIC_API_KEY", "test-api-key") + yield* connect(ProviderV2.ID.anthropic, "test-api-key") const providers = yield* list - expect(providers[ProviderV2.ID.anthropic].models["my-sonnet"]).toBeDefined() - - const model = yield* Provider.use.getModel(ProviderV2.ID.anthropic, ModelV2.ID.make("my-sonnet")) - expect(model).toBeDefined() - expect(String(model.id)).toBe("my-sonnet") - expect(model.name).toBe("My Sonnet Alias") + expect(providers[ProviderV2.ID.anthropic].models["my-sonnet"]).toBeUndefined() + const exit = yield* Provider.use.getModel(ProviderV2.ID.anthropic, ModelV2.ID.make("my-sonnet")).pipe(Effect.exit) + expect(exit._tag).toBe("Failure") }), { config: { @@ -593,12 +708,12 @@ it.instance( ) it.instance( - "model inherits properties from existing database model", + "official provider model name from config is ignored", Effect.gen(function* () { - yield* set("ANTHROPIC_API_KEY", "test-api-key") + yield* connect(ProviderV2.ID.anthropic, "test-api-key") const providers = yield* list const model = providers[ProviderV2.ID.anthropic].models["claude-sonnet-4-20250514"] - expect(model.name).toBe("Custom Name for Sonnet") + expect(model.name).not.toBe("Custom Name for Sonnet") expect(model.capabilities.toolcall).toBe(true) expect(model.capabilities.attachment).toBe(true) expect(model.limit.context).toBeGreaterThan(0) @@ -613,7 +728,7 @@ it.instance( it.instance( "disabled_providers prevents loading even with env var", Effect.gen(function* () { - yield* set("OPENAI_API_KEY", "test-openai-key") + yield* connect(ProviderV2.ID.openai, "test-openai-key") const providers = yield* list expect(providers[ProviderV2.ID.openai]).toBeUndefined() }), @@ -623,8 +738,8 @@ it.instance( it.instance( "enabled_providers with empty array allows no providers", Effect.gen(function* () { - yield* set("ANTHROPIC_API_KEY", "test-api-key") - yield* set("OPENAI_API_KEY", "test-openai-key") + yield* connect(ProviderV2.ID.anthropic, "test-api-key") + yield* connect(ProviderV2.ID.openai, "test-openai-key") const providers = yield* list expect(Object.keys(providers).length).toBe(0) }), @@ -632,15 +747,15 @@ it.instance( ) it.instance( - "whitelist and blacklist can be combined", + "official provider whitelist and blacklist config is ignored", Effect.gen(function* () { - yield* set("ANTHROPIC_API_KEY", "test-api-key") + yield* connect(ProviderV2.ID.anthropic, "test-api-key") const providers = yield* list expect(providers[ProviderV2.ID.anthropic]).toBeDefined() const models = Object.keys(providers[ProviderV2.ID.anthropic].models) expect(models).toContain("claude-sonnet-4-20250514") - expect(models).not.toContain("claude-opus-4-20250514") - expect(models.length).toBe(1) + expect(models).toContain("claude-opus-4-20250514") + expect(models.length).toBeGreaterThan(1) }), { config: { @@ -711,7 +826,7 @@ it.instance( it.instance("getSmallModel returns appropriate small model", () => Effect.gen(function* () { - yield* set("ANTHROPIC_API_KEY", "test-api-key") + yield* connect(ProviderV2.ID.anthropic, "test-api-key") const model = yield* Provider.use.getSmallModel(ProviderV2.ID.anthropic) expect(model).toBeDefined() expect(model?.id).toContain("haiku") @@ -721,7 +836,7 @@ it.instance("getSmallModel returns appropriate small model", () => it.instance( "getSmallModel respects config small_model override", Effect.gen(function* () { - yield* set("ANTHROPIC_API_KEY", "test-api-key") + yield* connect(ProviderV2.ID.anthropic, "test-api-key") const model = yield* Provider.use.getSmallModel(ProviderV2.ID.anthropic) expect(model).toBeDefined() expect(String(model?.providerID)).toBe("anthropic") @@ -733,7 +848,7 @@ it.instance( it.instance( "getSmallModel ignores invalid config small_model", Effect.gen(function* () { - yield* set("ANTHROPIC_API_KEY", "test-api-key") + yield* connect(ProviderV2.ID.anthropic, "test-api-key") const model = yield* Provider.use.getSmallModel(ProviderV2.ID.anthropic) expect(model).toBeUndefined() }), @@ -756,15 +871,15 @@ test("provider.sort prioritizes preferred models", () => { }) it.instance( - "multiple providers can be configured simultaneously", + "official providers can be connected simultaneously without config overrides", Effect.gen(function* () { - yield* set("ANTHROPIC_API_KEY", "test-anthropic-key") - yield* set("OPENAI_API_KEY", "test-openai-key") + yield* connect(ProviderV2.ID.anthropic, "test-anthropic-key") + yield* connect(ProviderV2.ID.openai, "test-openai-key") const providers = yield* list expect(providers[ProviderV2.ID.anthropic]).toBeDefined() expect(providers[ProviderV2.ID.openai]).toBeDefined() - expect(providers[ProviderV2.ID.anthropic].options.timeout).toBe(30000) - expect(providers[ProviderV2.ID.openai].options.timeout).toBe(60000) + expect(providers[ProviderV2.ID.anthropic].options.timeout).toBeUndefined() + expect(providers[ProviderV2.ID.openai].options.timeout).toBeUndefined() }), { config: { @@ -802,11 +917,11 @@ it.instance( // Edge cases for model configuration it.instance( - "model alias name defaults to alias key when id differs", + "official provider alias key is ignored", Effect.gen(function* () { - yield* set("ANTHROPIC_API_KEY", "test-api-key") + yield* connect(ProviderV2.ID.anthropic, "test-api-key") const providers = yield* list - expect(providers[ProviderV2.ID.anthropic].models["sonnet"].name).toBe("sonnet") + expect(providers[ProviderV2.ID.anthropic].models["sonnet"]).toBeUndefined() }), { config: { @@ -868,13 +983,13 @@ it.instance( ) it.instance( - "model cost overrides existing cost values", + "official provider cost override from config is ignored", Effect.gen(function* () { - yield* set("ANTHROPIC_API_KEY", "test-api-key") + yield* connect(ProviderV2.ID.anthropic, "test-api-key") const providers = yield* list const model = providers[ProviderV2.ID.anthropic].models["claude-sonnet-4-20250514"] - expect(model.cost.input).toBe(999) - expect(model.cost.output).toBe(888) + expect(model.cost.input).not.toBe(999) + expect(model.cost.output).not.toBe(888) }), { config: { @@ -927,9 +1042,9 @@ it.instance( it.instance( "disabled_providers and enabled_providers interaction", Effect.gen(function* () { - yield* set("ANTHROPIC_API_KEY", "test-anthropic") - yield* set("OPENAI_API_KEY", "test-openai") - yield* set("GOOGLE_GENERATIVE_AI_API_KEY", "test-google") + yield* connect(ProviderV2.ID.anthropic, "test-anthropic") + yield* connect(ProviderV2.ID.openai, "test-openai") + yield* connect(ProviderV2.ID.google, "test-google") const providers = yield* list // anthropic: in enabled, not in disabled = allowed expect(providers[ProviderV2.ID.anthropic]).toBeDefined() @@ -1045,7 +1160,7 @@ it.instance( it.instance("getModel returns consistent results", () => Effect.gen(function* () { - yield* set("ANTHROPIC_API_KEY", "test-api-key") + yield* connect(ProviderV2.ID.anthropic, "test-api-key") const model1 = yield* Provider.use.getModel(ProviderV2.ID.anthropic, ModelV2.ID.make("claude-sonnet-4-20250514")) const model2 = yield* Provider.use.getModel(ProviderV2.ID.anthropic, ModelV2.ID.make("claude-sonnet-4-20250514")) expect(model1.providerID).toEqual(model2.providerID) @@ -1076,7 +1191,7 @@ it.instance( it.instance("ModelNotFoundError includes suggestions for typos", () => Effect.gen(function* () { - yield* set("ANTHROPIC_API_KEY", "test-api-key") + yield* connect(ProviderV2.ID.anthropic, "test-api-key") const error = yield* Provider.use .getModel(ProviderV2.ID.anthropic, ModelV2.ID.make("claude-sonet-4")) .pipe(Effect.flip) @@ -1087,7 +1202,7 @@ it.instance("ModelNotFoundError includes suggestions for typos", () => it.instance("ModelNotFoundError for provider includes suggestions", () => Effect.gen(function* () { - yield* set("ANTHROPIC_API_KEY", "test-api-key") + yield* connect(ProviderV2.ID.anthropic, "test-api-key") const error = yield* Provider.use .getModel(ProviderV2.ID.make("antropic"), ModelV2.ID.make("claude-sonnet-4")) .pipe(Effect.flip) @@ -1116,7 +1231,7 @@ it.instance("getProvider returns undefined for nonexistent provider", () => it.instance("getProvider returns provider info", () => Effect.gen(function* () { - yield* set("ANTHROPIC_API_KEY", "test-api-key") + yield* connect(ProviderV2.ID.anthropic, "test-api-key") const provider = yield* Provider.use.getProvider(ProviderV2.ID.anthropic) expect(provider).toBeDefined() expect(String(provider?.id)).toBe("anthropic") @@ -1125,7 +1240,7 @@ it.instance("getProvider returns provider info", () => it.instance("closest returns undefined when no partial match found", () => Effect.gen(function* () { - yield* set("ANTHROPIC_API_KEY", "test-api-key") + yield* connect(ProviderV2.ID.anthropic, "test-api-key") const result = yield* Provider.use.closest(ProviderV2.ID.anthropic, ["nonexistent-xyz-model"]) expect(result).toBeUndefined() }), @@ -1133,7 +1248,7 @@ it.instance("closest returns undefined when no partial match found", () => it.instance("closest checks multiple query terms in order", () => Effect.gen(function* () { - yield* set("ANTHROPIC_API_KEY", "test-api-key") + yield* connect(ProviderV2.ID.anthropic, "test-api-key") // First term won't match, second will const result = yield* Provider.use.closest(ProviderV2.ID.anthropic, ["nonexistent", "haiku"]) expect(result).toBeDefined() @@ -1165,14 +1280,12 @@ it.instance( ) it.instance( - "provider options are deeply merged", + "official provider options from config are ignored", Effect.gen(function* () { - yield* set("ANTHROPIC_API_KEY", "test-api-key") + yield* connect(ProviderV2.ID.anthropic, "test-api-key") const providers = yield* list - // Custom options should be merged - expect(providers[ProviderV2.ID.anthropic].options.timeout).toBe(30000) - expect(providers[ProviderV2.ID.anthropic].options.headers["X-Custom"]).toBe("custom-value") - // anthropic custom loader adds its own headers, they should coexist + expect(providers[ProviderV2.ID.anthropic].options.timeout).toBeUndefined() + expect(providers[ProviderV2.ID.anthropic].options.headers["X-Custom"]).toBeUndefined() expect(providers[ProviderV2.ID.anthropic].options.headers["anthropic-beta"]).toBeDefined() }), { @@ -1183,36 +1296,38 @@ it.instance( ) it.instance( - "hosted nvidia provider adds billing origin header", + "nvidia third-party config applies apiKey", Effect.gen(function* () { + // nvidia is a catalog provider but NOT one of the 6 official ids, so config owns it as a + // third-party provider: the catalog models survive and the config apiKey applies. const providers = yield* list - expect(providers[ProviderV2.ID.make("nvidia")].options.headers).toEqual({ - "HTTP-Referer": "https://deepagent-code.ai/", - "X-Title": "deepagent-code", - "X-BILLING-INVOKE-ORIGIN": "DeepAgent Code", - }) + const provider = providers[ProviderV2.ID.make("nvidia")] + expect(provider).toBeDefined() + expect(provider.source).toBe("custom") + expect(provider.options.apiKey).toBe("test-api-key") }), { config: { provider: { nvidia: { options: { apiKey: "test-api-key" } } } } }, ) it.instance( - "custom nvidia baseURL adds billing origin header", + "nvidia third-party config applies custom baseURL", Effect.gen(function* () { const providers = yield* list - expect(providers[ProviderV2.ID.make("nvidia")].options.headers).toEqual({ - "HTTP-Referer": "https://deepagent-code.ai/", - "X-Title": "deepagent-code", - "X-BILLING-INVOKE-ORIGIN": "DeepAgent Code", - }) + const provider = providers[ProviderV2.ID.make("nvidia")] + expect(provider).toBeDefined() + expect(provider.options.baseURL).toBe("http://localhost:8000/v1") + expect(provider.options.apiKey).toBe("test-api-key") }), { config: { provider: { nvidia: { options: { apiKey: "test-api-key", baseURL: "http://localhost:8000/v1" } } } } }, ) it.instance( - "explicit nvidia billing origin header is preserved", + "nvidia third-party config applies custom headers", Effect.gen(function* () { const providers = yield* list - expect(providers[ProviderV2.ID.make("nvidia")].options.headers["X-BILLING-INVOKE-ORIGIN"]).toBe("CustomOrigin") + const provider = providers[ProviderV2.ID.make("nvidia")] + expect(provider).toBeDefined() + expect(provider.options.baseURL).toBe("http://localhost:8000/v1") }), { config: { @@ -1230,13 +1345,12 @@ it.instance( ) it.instance( - "custom model inherits npm package from models.dev provider config", + "official provider custom model config is ignored", Effect.gen(function* () { - yield* set("OPENAI_API_KEY", "test-api-key") + yield* connect(ProviderV2.ID.openai, "test-api-key") const providers = yield* list const model = providers[ProviderV2.ID.openai].models["my-custom-model"] - expect(model).toBeDefined() - expect(model.api.npm).toBe("@ai-sdk/openai") + expect(model).toBeUndefined() }), { config: { @@ -1256,30 +1370,20 @@ it.instance( ) it.instance( - "custom model inherits api.url from models.dev provider", + "official provider custom api.url model config is ignored", Effect.gen(function* () { - yield* set("OPENROUTER_API_KEY", "test-api-key") + yield* connect(ProviderV2.ID.openai, "test-api-key") const providers = yield* list - expect(providers[ProviderV2.ID.openrouter]).toBeDefined() - - // New model not in database should inherit api.url from provider - const intellect = providers[ProviderV2.ID.openrouter].models["prime-intellect/intellect-3"] - expect(intellect).toBeDefined() - expect(intellect.api.url).toBe("https://openrouter.ai/api/v1") + expect(providers[ProviderV2.ID.openai]).toBeDefined() - // Another new model should also inherit api.url - const deepseek = providers[ProviderV2.ID.openrouter].models["deepseek/deepseek-r1-0528"] - expect(deepseek).toBeDefined() - expect(deepseek.api.url).toBe("https://openrouter.ai/api/v1") - expect(deepseek.name).toBe("DeepSeek R1") + expect(providers[ProviderV2.ID.openai].models["custom-only/model"]).toBeUndefined() }), { config: { provider: { - openrouter: { + openai: { models: { - "prime-intellect/intellect-3": {}, - "deepseek/deepseek-r1-0528": { name: "DeepSeek R1" }, + "custom-only/model": { name: "Custom Only" }, }, }, }, @@ -1376,7 +1480,7 @@ test("models.dev normalization fills required response fields", () => { expect(model.release_date).toBe("") }) -test("models.dev normalization infers reasoning for zhipuai glm-5.2", () => { +test("models.dev normalization infers reasoning for generic zhipuai glm-5.2", () => { const provider = { id: "zhipuai", name: "Zhipu AI", @@ -1395,6 +1499,35 @@ test("models.dev normalization infers reasoning for zhipuai glm-5.2", () => { }, } as unknown as ModelsDev.Provider + // Aligned with upstream: GLM-5.2 is a reasoning model across the whole Zhipu/Z.AI brand family, + // so the plain (non-coding-plan) face also infers reasoning and exposes high/max thinking tiers. + const model = Provider.fromModelsDevProvider(provider).models["glm-5.2"] + expect(model.capabilities.reasoning).toBe(true) + expect(model.variants).toEqual({ + high: { reasoningEffort: "high" }, + max: { reasoningEffort: "max" }, + }) +}) + +test("models.dev normalization infers reasoning for zhipuai coding-plan glm-5.2", () => { + const provider = { + id: "zhipuai-coding-plan", + name: "Zhipu AI Coding Plan", + env: [], + api: "https://open.bigmodel.cn/api/coding/paas/v4", + npm: "@ai-sdk/openai-compatible", + models: { + "glm-5.2": { + id: "glm-5.2", + name: "GLM-5.2", + family: "glm", + reasoning: false, + cost: { input: 0, output: 0 }, + limit: { context: 128_000, output: 8192 }, + }, + }, + } as unknown as ModelsDev.Provider + const model = Provider.fromModelsDevProvider(provider).models["glm-5.2"] expect(model.capabilities.reasoning).toBe(true) expect(model.variants).toEqual({ @@ -1405,7 +1538,7 @@ test("models.dev normalization infers reasoning for zhipuai glm-5.2", () => { it.instance("model variants are generated for reasoning models", () => Effect.gen(function* () { - yield* set("ANTHROPIC_API_KEY", "test-api-key") + yield* connect(ProviderV2.ID.anthropic, "test-api-key") const providers = yield* list // Claude sonnet 4 has reasoning capability const model = providers[ProviderV2.ID.anthropic].models["claude-sonnet-4-20250514"] @@ -1416,14 +1549,13 @@ it.instance("model variants are generated for reasoning models", () => ) it.instance( - "model variants can be disabled via config", + "official provider variant disable config is ignored", Effect.gen(function* () { - yield* set("ANTHROPIC_API_KEY", "test-api-key") + yield* connect(ProviderV2.ID.anthropic, "test-api-key") const providers = yield* list const model = providers[ProviderV2.ID.anthropic].models["claude-sonnet-4-20250514"] expect(model.variants).toBeDefined() - expect(model.variants!["high"]).toBeUndefined() - // max variant should still exist + expect(model.variants!["high"]).toBeDefined() expect(model.variants!["max"]).toBeDefined() }), { @@ -1438,13 +1570,13 @@ it.instance( ) it.instance( - "model variants can be customized via config", + "official provider variant customization config is ignored", Effect.gen(function* () { - yield* set("ANTHROPIC_API_KEY", "test-api-key") + yield* connect(ProviderV2.ID.anthropic, "test-api-key") const providers = yield* list const model = providers[ProviderV2.ID.anthropic].models["claude-sonnet-4-20250514"] expect(model.variants!["high"]).toBeDefined() - expect(model.variants!["high"].thinking.budgetTokens).toBe(20000) + expect(model.variants!["high"].thinking.budgetTokens).not.toBe(20000) }), { config: { @@ -1462,14 +1594,14 @@ it.instance( ) it.instance( - "disabled key is stripped from variant config", + "official provider variant custom field config is ignored", Effect.gen(function* () { - yield* set("ANTHROPIC_API_KEY", "test-api-key") + yield* connect(ProviderV2.ID.anthropic, "test-api-key") const providers = yield* list const model = providers[ProviderV2.ID.anthropic].models["claude-sonnet-4-20250514"] expect(model.variants!["max"]).toBeDefined() expect(model.variants!["max"].disabled).toBeUndefined() - expect(model.variants!["max"].customField).toBe("test") + expect(model.variants!["max"].customField).toBeUndefined() }), { config: { @@ -1487,13 +1619,13 @@ it.instance( ) it.instance( - "all variants can be disabled via config", + "official provider all-variant disable config is ignored", Effect.gen(function* () { - yield* set("ANTHROPIC_API_KEY", "test-api-key") + yield* connect(ProviderV2.ID.anthropic, "test-api-key") const providers = yield* list const model = providers[ProviderV2.ID.anthropic].models["claude-sonnet-4-20250514"] expect(model.variants).toBeDefined() - expect(Object.keys(model.variants!).length).toBe(0) + expect(Object.keys(model.variants!).length).toBeGreaterThan(0) }), { config: { @@ -1511,15 +1643,14 @@ it.instance( ) it.instance( - "variant config merges with generated variants", + "official provider variant merge config is ignored", Effect.gen(function* () { - yield* set("ANTHROPIC_API_KEY", "test-api-key") + yield* connect(ProviderV2.ID.anthropic, "test-api-key") const providers = yield* list const model = providers[ProviderV2.ID.anthropic].models["claude-sonnet-4-20250514"] expect(model.variants!["high"]).toBeDefined() - // Should have both the generated thinking config and the custom option expect(model.variants!["high"].thinking).toBeDefined() - expect(model.variants!["high"].extraOption).toBe("custom-value") + expect(model.variants!["high"].extraOption).toBeUndefined() }), { config: { @@ -1535,14 +1666,13 @@ it.instance( ) it.instance( - "variants filtered in second pass for database models", + "official provider variant filter config is ignored", Effect.gen(function* () { - yield* set("OPENAI_API_KEY", "test-api-key") + yield* connect(ProviderV2.ID.openai, "test-api-key") const providers = yield* list const model = providers[ProviderV2.ID.openai].models["gpt-5"] expect(model.variants).toBeDefined() - expect(model.variants!["high"]).toBeUndefined() - // Other variants should still exist + expect(model.variants!["high"]).toBeDefined() expect(model.variants!["medium"]).toBeDefined() }), { @@ -1671,7 +1801,7 @@ it.instance( ) const language = yield* provider.getLanguage(model) expect(languageBaseURL(language)).toBe( - "https://eu-aiplatform.googleapis.com/v1/projects/test-project/locations/eu/publishers/anthropic/models", + "https://aiplatform.eu.rep.googleapis.com/v1/projects/test-project/locations/eu/publishers/anthropic/models", ) }), { config: { enabled_providers: ["google-vertex"] } }, @@ -1726,17 +1856,17 @@ it.instance("cloudflare-ai-gateway loads with env variables", () => ) it.instance( - "cloudflare-ai-gateway forwards config metadata options", + "cloudflare-ai-gateway third-party config applies metadata options", Effect.gen(function* () { yield* set("CLOUDFLARE_ACCOUNT_ID", "test-account") yield* set("CLOUDFLARE_GATEWAY_ID", "test-gateway") yield* set("CLOUDFLARE_API_TOKEN", "test-token") const providers = yield* list - expect(providers[ProviderV2.ID.make("cloudflare-ai-gateway")]).toBeDefined() - expect(providers[ProviderV2.ID.make("cloudflare-ai-gateway")].options.metadata).toEqual({ - invoked_by: "test", - project: "deepagent-code", - }) + // cloudflare-ai-gateway is a catalog provider but not one of the 6 official ids, so it is a + // third-party provider: catalog models + loader survive and config options merge in. + const provider = providers[ProviderV2.ID.make("cloudflare-ai-gateway")] + expect(provider).toBeDefined() + expect(provider.options.metadata).toEqual({ invoked_by: "test", project: "deepagent-code" }) }), { config: { @@ -1835,8 +1965,8 @@ it.instance( ), ) - yield* set("ANTHROPIC_API_KEY", "test-anthropic-key") - yield* set("OPENAI_API_KEY", "test-openai-key") + yield* connect(ProviderV2.ID.anthropic, "test-anthropic-key") + yield* connect(ProviderV2.ID.openai, "test-openai-key") const providers = yield* list expect(providers[ProviderV2.ID.anthropic]).toBeDefined() expect(providers[ProviderV2.ID.openai]).toBeUndefined() diff --git a/packages/deepagent-code/test/provider/transform.test.ts b/packages/deepagent-code/test/provider/transform.test.ts index ed90698f..5eb30896 100644 --- a/packages/deepagent-code/test/provider/transform.test.ts +++ b/packages/deepagent-code/test/provider/transform.test.ts @@ -159,7 +159,7 @@ describe("ProviderTransform.options - zai/zhipuai thinking", () => { headers: {}, }) as any - for (const providerID of ["zai-coding-plan", "zai", "zhipuai-coding-plan", "zhipuai"]) { + for (const providerID of ["zai-coding-plan", "zhipuai-coding-plan", "zai", "zhipuai"]) { test(`${providerID} should set thinking cfg`, () => { const result = ProviderTransform.options({ model: createModel(providerID), @@ -173,6 +173,26 @@ describe("ProviderTransform.options - zai/zhipuai thinking", () => { }) }) } + + test("zhipuai with explicit coding endpoint should set thinking cfg", () => { + const model = createModel("zhipuai") + const result = ProviderTransform.options({ + model: { + ...model, + api: { + ...model.api, + url: "https://open.bigmodel.cn/api/coding/paas/v4", + }, + }, + sessionID, + providerOptions: {}, + }) + + expect(result.thinking).toEqual({ + type: "enabled", + clear_thinking: false, + }) + }) }) describe("ProviderTransform.options - google thinkingConfig gating", () => { @@ -2471,7 +2491,7 @@ describe("ProviderTransform.variants", () => { expect(result).toEqual({}) }) - test("glm-5.2 openai-compatible returns reasoning effort variants", () => { + test("glm-5.2 openai-compatible on generic zhipuai returns reasoning effort variants", () => { const model = createMockModel({ id: "zhipuai/glm-5.2", providerID: "zhipuai", @@ -2483,6 +2503,25 @@ describe("ProviderTransform.variants", () => { capabilities: { reasoning: true }, }) const result = ProviderTransform.variants(model) + // Aligned with upstream: plain (non-coding-plan) GLM-5.2 also exposes high/max thinking tiers. + expect(result).toEqual({ + high: { reasoningEffort: "high" }, + max: { reasoningEffort: "max" }, + }) + }) + + test("glm-5.2 coding-plan openai-compatible returns reasoning effort variants", () => { + const model = createMockModel({ + id: "zhipuai-coding-plan/glm-5.2", + providerID: "zhipuai-coding-plan", + api: { + id: "glm-5.2", + url: "https://open.bigmodel.cn/api/coding/paas/v4", + npm: "@ai-sdk/openai-compatible", + }, + capabilities: { reasoning: true }, + }) + const result = ProviderTransform.variants(model) expect(result).toEqual({ high: { reasoningEffort: "high" }, max: { reasoningEffort: "max" }, diff --git a/packages/deepagent-code/test/session/prompt.test.ts b/packages/deepagent-code/test/session/prompt.test.ts index c5f69cd1..a80c585a 100644 --- a/packages/deepagent-code/test/session/prompt.test.ts +++ b/packages/deepagent-code/test/session/prompt.test.ts @@ -47,6 +47,8 @@ import { SystemPrompt } from "../../src/session/system" import { Shell } from "../../src/shell/shell" import { Snapshot } from "../../src/snapshot" import { ToolRegistry } from "@/tool/registry" +import { DebugService } from "@/debug/service" +import { RuntimeBase } from "@/runtime/base" import { Truncate } from "@/tool/truncate" import * as Log from "@deepagent-code/core/util/log" import { CrossSpawnSpawner } from "@deepagent-code/core/cross-spawn-spawner" @@ -190,6 +192,40 @@ const blockingProcessor = Layer.succeed( }), ) +// V3.5: a no-op RuntimeBase (R0) stub so the tool registry layer can be built without +// dragging in the real Worktree→Project→Database chain. These prompt tests never invoke +// the debug/profile tools, so gate/withIsolation/checkPrivileges are never exercised. +const stubRuntimeBaseLayer = Layer.succeed( + RuntimeBase.Service, + RuntimeBase.Service.of({ + gate: () => Effect.void, + withIsolation: (_input, body) => body(""), + checkPrivileges: () => Effect.succeed([]), + }), +) + +// Fully-inert DebugService (D1) stub. The real DebugService.layer runs InstanceState.make +// + registers a scope finalizer at registry-build time, perturbing the instance-context +// lifecycle these prompt tests rely on. The debug tool is never invoked here. +const debugStubDie = (): Effect.Effect => + Effect.die("DebugService stub (not used in prompt tests)") +const stubDebugServiceLayer = Layer.succeed( + DebugService.Service, + DebugService.Service.of({ + start: debugStubDie, + setBreakpoints: debugStubDie, + continue: debugStubDie, + step: debugStubDie, + stackTrace: debugStubDie, + scopes: debugStubDie, + variables: debugStubDie, + evaluate: debugStubDie, + terminate: debugStubDie, + get: () => Effect.succeed(undefined), + list: () => Effect.succeed([]), + }), +) + function makePrompt(input?: { processor?: "blocking" }) { const deps = Layer.mergeAll( Session.defaultLayer, @@ -223,6 +259,13 @@ function makePrompt(input?: { processor?: "blocking" }) { Layer.provide(Search.defaultLayer), Layer.provide(Format.defaultLayer), Layer.provide(RuntimeFlags.layer({ experimentalEventSystem: true })), + // V3.5: the registry layer now requires DebugService + RuntimeBase (debug/profile + // tools route through D1/R0). These tests never invoke those tools, so provide the + // real (lightweight) DebugService over a no-op RuntimeBase stub — this satisfies the + // layer without pulling in the heavy Worktree→Project→Database chain (a second + // Database instance was stalling the shared LLM/provider path). + Layer.provide(stubDebugServiceLayer), + Layer.provide(stubRuntimeBaseLayer), Layer.provideMerge(todo), Layer.provideMerge(question), Layer.provideMerge(deps), diff --git a/packages/deepagent-code/test/session/snapshot-tool-race.test.ts b/packages/deepagent-code/test/session/snapshot-tool-race.test.ts index bb6a6a0c..7c540ec5 100644 --- a/packages/deepagent-code/test/session/snapshot-tool-race.test.ts +++ b/packages/deepagent-code/test/session/snapshot-tool-race.test.ts @@ -32,6 +32,8 @@ import { TestLLMServer } from "../lib/llm-server" import { NodeFileSystem } from "@effect/platform-node" import { Database } from "@deepagent-code/core/database/database" import { EventV2Bridge } from "@/event-v2-bridge" +import { DebugService } from "@/debug/service" +import { RuntimeBase } from "@/runtime/base" import { Agent as AgentSvc } from "../../src/agent/agent" import { Auth } from "../../src/auth" import { BackgroundJob } from "@/background/job" @@ -133,6 +135,38 @@ const status = SessionStatus.layer.pipe(Layer.provideMerge(EventV2Bridge.default const run = SessionRunState.layer.pipe(Layer.provide(status)) const infra = Layer.mergeAll(NodeFileSystem.layer, CrossSpawnSpawner.defaultLayer) +// V3.5: no-op RuntimeBase (R0) stub — lets the tool registry layer build without the +// heavy Worktree→Project→Database chain. This test never invokes debug/profile. +const stubRuntimeBaseLayer = Layer.succeed( + RuntimeBase.Service, + RuntimeBase.Service.of({ + gate: () => Effect.void, + withIsolation: (_input, body) => body(""), + checkPrivileges: () => Effect.succeed([]), + }), +) + +// Fully-inert DebugService (D1) stub — avoids InstanceState.make + finalizer side effects +// at registry-build time. This test never invokes the debug tool. +const debugStubDie = (): Effect.Effect => + Effect.die("DebugService stub (not used in this test)") +const stubDebugServiceLayer = Layer.succeed( + DebugService.Service, + DebugService.Service.of({ + start: debugStubDie, + setBreakpoints: debugStubDie, + continue: debugStubDie, + step: debugStubDie, + stackTrace: debugStubDie, + scopes: debugStubDie, + variables: debugStubDie, + evaluate: debugStubDie, + terminate: debugStubDie, + get: () => Effect.succeed(undefined), + list: () => Effect.succeed([]), + }), +) + function makeHttp() { const deps = Layer.mergeAll( Session.defaultLayer, @@ -166,6 +200,11 @@ function makeHttp() { Layer.provide(Search.defaultLayer), Layer.provide(Format.defaultLayer), Layer.provide(RuntimeFlags.layer({ experimentalEventSystem: true })), + // V3.5: debug/profile tools require DebugService + RuntimeBase. Provide the real + // (lightweight) DebugService over a no-op RuntimeBase stub — this test never invokes + // those tools, and it avoids the heavy Worktree→Database chain. + Layer.provide(stubDebugServiceLayer), + Layer.provide(stubRuntimeBaseLayer), Layer.provideMerge(todo), Layer.provideMerge(question), Layer.provideMerge(deps), diff --git a/packages/deepagent-code/test/settings/store.test.ts b/packages/deepagent-code/test/settings/store.test.ts new file mode 100644 index 00000000..e7392255 --- /dev/null +++ b/packages/deepagent-code/test/settings/store.test.ts @@ -0,0 +1,106 @@ +import { test, expect, describe, afterEach, beforeEach } from "bun:test" +import fs from "fs/promises" +import os from "os" +import path from "path" +import { SettingsStore } from "@/settings/store" + +// SettingsStore resolves its file under Global.Path.data, which honors DEEPAGENT_CODE_HOME. Point it +// at a throwaway dir so we never touch the real ~/.deepagent/code. +let home: string +const prevHome = process.env.DEEPAGENT_CODE_HOME + +beforeEach(async () => { + home = await fs.mkdtemp(path.join(os.tmpdir(), "deepagent-settings-test-")) + process.env.DEEPAGENT_CODE_HOME = home + SettingsStore.invalidate() +}) + +afterEach(async () => { + if (prevHome === undefined) delete process.env.DEEPAGENT_CODE_HOME + else process.env.DEEPAGENT_CODE_HOME = prevHome + SettingsStore.invalidate() + await fs.rm(home, { recursive: true, force: true }).catch(() => {}) +}) + +const settingsFile = () => path.join(home, "settings.json") + +describe("SettingsStore", () => { + test("missing file reads as empty settings", async () => { + expect(await SettingsStore.read()).toEqual({}) + }) + + test("update persists deepagent settings and reports changed", async () => { + const first = await SettingsStore.update({ deepagent: { agentMode: "xhigh", wishModel: "zhipuai/glm-4.7" } }) + expect(first.changed).toBe(true) + expect(first.settings.deepagent).toEqual({ agentMode: "xhigh", wishModel: "zhipuai/glm-4.7" }) + + SettingsStore.invalidate() + const reread = await SettingsStore.read() + expect(reread.deepagent).toEqual({ agentMode: "xhigh", wishModel: "zhipuai/glm-4.7" }) + + // file exists and is valid JSON + const raw = JSON.parse(await fs.readFile(settingsFile(), "utf8")) + expect(raw.deepagent.agentMode).toBe("xhigh") + }) + + test("no-op update reports unchanged", async () => { + await SettingsStore.update({ deepagent: { agentMode: "high" } }) + const again = await SettingsStore.update({ deepagent: { agentMode: "high" } }) + expect(again.changed).toBe(false) + }) + + test("merges partial deepagent patches", async () => { + await SettingsStore.update({ deepagent: { agentMode: "high" } }) + const merged = await SettingsStore.update({ deepagent: { selfLearning: "auto" } }) + expect(merged.settings.deepagent).toEqual({ agentMode: "high", selfLearning: "auto" }) + }) + + test("keeps transport only for official providers", async () => { + const result = await SettingsStore.update({ + providers: { + zhipuai: { headerTimeout: 15000, maxRetries: 3 }, + // not an official provider — must be dropped + "some-third-party": { headerTimeout: 999 } as never, + }, + }) + expect(result.settings.providers).toEqual({ zhipuai: { headerTimeout: 15000, maxRetries: 3 } }) + }) + + test("newly-official zhipu family is accepted", async () => { + const result = await SettingsStore.update({ + providers: { + "zhipuai-coding-plan": { headerTimeout: 20000 }, + zai: { timeout: 60000 }, + "zai-coding-plan": { chunkTimeout: 30000 }, + }, + }) + expect(result.settings.providers).toEqual({ + "zhipuai-coding-plan": { headerTimeout: 20000 }, + zai: { timeout: 60000 }, + "zai-coding-plan": { chunkTimeout: 30000 }, + }) + }) + + test("headerTimeout=false (disabled) is preserved; invalid values dropped", async () => { + const result = await SettingsStore.update({ + providers: { openai: { headerTimeout: false, chunkTimeout: -1 as never, maxRetries: 0 as never } }, + }) + // false kept; negative chunkTimeout and non-positive maxRetries dropped + expect(result.settings.providers).toEqual({ openai: { headerTimeout: false } }) + }) + + test("removing all transport keys for a provider drops the entry", async () => { + await SettingsStore.update({ providers: { openai: { headerTimeout: 10000 } } }) + const cleared = await SettingsStore.update({ providers: { openai: { headerTimeout: undefined as never } } }) + expect(cleared.settings.providers).toBeUndefined() + }) + + test("ignores unknown/garbage on read", async () => { + await fs.writeFile( + settingsFile(), + JSON.stringify({ deepagent: { agentMode: "bogus", wishModel: 42 }, providers: { notreal: { x: 1 } } }), + ) + SettingsStore.invalidate() + expect(await SettingsStore.read()).toEqual({}) + }) +}) diff --git a/packages/deepagent-code/test/tool/registry.test.ts b/packages/deepagent-code/test/tool/registry.test.ts index 8b72880d..f18e3363 100644 --- a/packages/deepagent-code/test/tool/registry.test.ts +++ b/packages/deepagent-code/test/tool/registry.test.ts @@ -37,6 +37,9 @@ import { MessageID, SessionID } from "@/session/schema" import { RuntimeFlags } from "@/effect/runtime-flags" import { ProviderV2 } from "@deepagent-code/core/provider" import { ModelV2 } from "@deepagent-code/core/model" +import { DebugService } from "@/debug/service" +import { RuntimeBase } from "@/runtime/base" +import { Worktree } from "@/worktree" const node = CrossSpawnSpawner.defaultLayer const configLayer = TestConfig.layer({ @@ -51,26 +54,39 @@ type RegistryLayerOptions = { const registryLayer = (opts: RegistryLayerOptions = {}) => ToolRegistry.layer .pipe( - Layer.provide(configLayer), - Layer.provide(opts.plugin ?? Plugin.defaultLayer), - Layer.provide(Question.defaultLayer), - Layer.provide(Todo.defaultLayer), - Layer.provide(Skill.defaultLayer), - Layer.provide(Agent.defaultLayer), - Layer.provide(Session.defaultLayer), - Layer.provide(Layer.mergeAll(SessionStatus.defaultLayer, BackgroundJob.defaultLayer)), - Layer.provide(Provider.defaultLayer), - Layer.provide(Layer.mergeAll(Git.defaultLayer, RepositoryCache.defaultLayer)), - Layer.provide(Reference.defaultLayer), - Layer.provide(LSP.defaultLayer), - Layer.provide(Instruction.defaultLayer), - Layer.provide(FSUtil.defaultLayer), - Layer.provide(EventV2Bridge.defaultLayer), - Layer.provide(FetchHttpClient.layer), - Layer.provide(Format.defaultLayer), - Layer.provide(Layer.mergeAll(node, Database.defaultLayer)), - Layer.provide(Search.defaultLayer), - Layer.provide(Truncate.defaultLayer), + // V3.5: debug/profile tools route through DebugService (D1) + RuntimeBase (R0). + // Provided closest to the base so the merged EventV2Bridge below (applied last) + // satisfies DebugService's requirement, mirroring ToolRegistry.defaultLayer. + Layer.provide(DebugService.layer), + Layer.provide(RuntimeBase.layer), + Layer.provide(Worktree.defaultLayer), + Layer.provide( + Layer.mergeAll( + configLayer, + opts.plugin ?? Plugin.defaultLayer, + Question.defaultLayer, + Todo.defaultLayer, + Skill.defaultLayer, + Agent.defaultLayer, + Session.defaultLayer, + SessionStatus.defaultLayer, + BackgroundJob.defaultLayer, + Provider.defaultLayer, + Git.defaultLayer, + RepositoryCache.defaultLayer, + Reference.defaultLayer, + LSP.defaultLayer, + Instruction.defaultLayer, + FSUtil.defaultLayer, + EventV2Bridge.defaultLayer, + FetchHttpClient.layer, + Format.defaultLayer, + node, + Database.defaultLayer, + Search.defaultLayer, + Truncate.defaultLayer, + ), + ), ) .pipe(Layer.provide(RuntimeFlags.layer(opts.flags ?? {}))) diff --git a/packages/desktop/package.json b/packages/desktop/package.json index 1e52038a..4e002675 100644 --- a/packages/desktop/package.json +++ b/packages/desktop/package.json @@ -1,7 +1,7 @@ { "name": "@deepagent-code/desktop", "private": true, - "version": "1.0.1", + "version": "1.1.0", "type": "module", "license": "AGPL-3.0-or-later", "homepage": "https://deepagent-code.ai", diff --git a/packages/desktop/src/main/desktop-menu-actions.ts b/packages/desktop/src/main/desktop-menu-actions.ts index 4fb0421f..fcb8665a 100644 --- a/packages/desktop/src/main/desktop-menu-actions.ts +++ b/packages/desktop/src/main/desktop-menu-actions.ts @@ -1,6 +1,7 @@ import { BrowserWindow } from "electron" import type { DesktopMenuAction } from "@deepagent-code/app/desktop-menu" -import { createMainWindow, updateTitlebar } from "./windows" +import { clampZoom, nextZoomLevel } from "@deepagent-code/app/zoom-levels" +import { createMainWindow, updateZoom } from "./windows" export type DesktopMenuActionHandlers = Partial<{ checkForUpdates: () => void @@ -45,10 +46,10 @@ export function runDesktopMenuAction( setZoom(win, 1) return case "view.zoomIn": - setZoom(win, (win?.webContents.getZoomFactor() ?? 1) + 0.2) + setZoom(win, nextZoomLevel(win?.webContents.getZoomFactor() ?? 1, "in")) return case "view.zoomOut": - setZoom(win, (win?.webContents.getZoomFactor() ?? 1) - 0.2) + setZoom(win, nextZoomLevel(win?.webContents.getZoomFactor() ?? 1, "out")) return case "view.toggleFullscreen": win?.setFullScreen(!win.isFullScreen()) @@ -79,6 +80,6 @@ export function runDesktopMenuAction( function setZoom(win: BrowserWindow | null, value: number) { if (!win) return - win.webContents.setZoomFactor(Math.min(Math.max(value, 0.2), 10)) - updateTitlebar(win) + win.webContents.setZoomFactor(clampZoom(value)) + updateZoom(win) } diff --git a/packages/desktop/src/main/menu.ts b/packages/desktop/src/main/menu.ts index f7be9d17..5335ec5f 100644 --- a/packages/desktop/src/main/menu.ts +++ b/packages/desktop/src/main/menu.ts @@ -34,7 +34,7 @@ export function createMenu(deps: Deps) { function nativeItem(entry: DesktopMenuEntry, deps: Deps): MenuItemConstructorOptions { if (entry.type === "separator") return { type: "separator" } - if (entry.role) return { role: nativeRole(entry.role) } + if (entry.role && !isZoomAction(entry.action)) return { role: nativeRole(entry.role) } const item: MenuItemConstructorOptions = { label: entry.label, @@ -65,3 +65,7 @@ function nativeItem(entry: DesktopMenuEntry, deps: Deps): MenuItemConstructorOpt function nativeRole(role: DesktopMenuRole) { return role as NonNullable } + +function isZoomAction(action: string | undefined): boolean { + return action === "view.zoomIn" || action === "view.zoomOut" || action === "view.resetZoom" +} diff --git a/packages/desktop/src/main/windows.ts b/packages/desktop/src/main/windows.ts index 5db2c160..eaac95e7 100644 --- a/packages/desktop/src/main/windows.ts +++ b/packages/desktop/src/main/windows.ts @@ -1,6 +1,7 @@ import windowState from "electron-window-state" import { resolveThemeVariant } from "@deepagent-code/ui/theme/resolve" import type { DesktopTheme } from "@deepagent-code/ui/theme/types" +import { nextZoomLevel } from "@deepagent-code/app/zoom-levels" import oc2ThemeJson from "../../../ui/src/theme/themes/oc-2.json" import { app, BrowserWindow, dialog, net, nativeImage, nativeTheme, protocol } from "electron" import { dirname, isAbsolute, join, relative, resolve } from "node:path" @@ -45,8 +46,6 @@ let relaunchHandler = () => { const titlebarThemes = new WeakMap>() const pinchZoomEnabled = new WeakMap() const titlebarHeight = 40 -const maxZoomLevel = 10 -const minZoomLevel = 0.2 export function setRelaunchHandler(handler: () => void) { relaunchHandler = handler @@ -394,7 +393,7 @@ function wireZoom(win: BrowserWindow) { win.webContents.on("zoom-changed", (event, zoomDirection) => { event.preventDefault() if (pinchZoomEnabled.get(win)) { - win.webContents.setZoomFactor(clampZoom(win.webContents.getZoomFactor() + (zoomDirection === "in" ? 0.2 : -0.2))) + win.webContents.setZoomFactor(nextZoomLevel(win.webContents.getZoomFactor(), zoomDirection === "in" ? "in" : "out")) updateZoom(win) return } @@ -403,11 +402,7 @@ function wireZoom(win: BrowserWindow) { }) } -function clampZoom(value: number) { - return Math.min(Math.max(value, minZoomLevel), maxZoomLevel) -} - -function updateZoom(win: BrowserWindow) { +export function updateZoom(win: BrowserWindow) { updateTitlebar(win) win.webContents.send("zoom-factor-changed", win.webContents.getZoomFactor()) } diff --git a/packages/desktop/src/renderer/index.tsx b/packages/desktop/src/renderer/index.tsx index a1e1bc81..18ffacaf 100644 --- a/packages/desktop/src/renderer/index.tsx +++ b/packages/desktop/src/renderer/index.tsx @@ -23,7 +23,7 @@ import { render } from "solid-js/web" import pkg from "../../package.json" import { initI18n, t } from "./i18n" import { initializationData, initializationReady } from "./initialization" -import { resetZoom, setPinchZoomEnabled, webviewZoom, zoomIn, zoomOut } from "./webview-zoom" +import { resetZoom, setPinchZoomEnabled, setZoom, webviewZoom, zoomIn, zoomOut } from "./webview-zoom" import { availableStartupServer, readyWslConnections } from "./wsl/connections" import "./styles.css" import { Splash } from "@deepagent-code/ui/logo" @@ -250,6 +250,8 @@ const createPlatform = (): Platform => { webviewZoom, + setWebviewZoom: setZoom, + getPinchZoomEnabled: () => window.api.getPinchZoomEnabled(), setPinchZoomEnabled, diff --git a/packages/desktop/src/renderer/webview-zoom.ts b/packages/desktop/src/renderer/webview-zoom.ts index 7993bf5e..4dae43b3 100644 --- a/packages/desktop/src/renderer/webview-zoom.ts +++ b/packages/desktop/src/renderer/webview-zoom.ts @@ -3,6 +3,7 @@ // SPDX-License-Identifier: MIT import { createSignal } from "solid-js" +import { clampZoom, nextZoomLevel } from "@deepagent-code/app/zoom-levels" const OS_NAME = (() => { if (navigator.userAgent.includes("Mac")) return "macos" @@ -23,14 +24,9 @@ let wheelPinch = undefined as } | undefined -const MAX_ZOOM_LEVEL = 10 -const MIN_ZOOM_LEVEL = 0.2 const WHEEL_PINCH_THRESHOLD = 20 -const WHEEL_PINCH_STEP = 0.2 const WHEEL_PINCH_END_DELAY = 160 -const clamp = (value: number) => Math.min(Math.max(value, MIN_ZOOM_LEVEL), MAX_ZOOM_LEVEL) - const applyZoom = (next: number) => { requestedZoom = next void window.api @@ -46,7 +42,7 @@ const applyZoom = (next: number) => { } window.api.onZoomFactorChanged((factor) => { - requestedZoom = clamp(factor) + requestedZoom = clampZoom(factor) setWebviewZoom(requestedZoom) }) @@ -66,8 +62,9 @@ const setPinchZoomEnabled = (enabled: boolean) => { } const resetZoom = () => applyZoom(1) -const zoomIn = () => applyZoom(clamp(requestedZoom + 0.2)) -const zoomOut = () => applyZoom(clamp(requestedZoom - 0.2)) +const zoomIn = () => applyZoom(nextZoomLevel(requestedZoom, "in")) +const zoomOut = () => applyZoom(nextZoomLevel(requestedZoom, "out")) +const setZoom = (level: number) => applyZoom(clampZoom(level)) const resetWheelPinch = () => { clearTimeout(wheelPinch?.timeout) @@ -101,7 +98,13 @@ const updateWheelPinch = (event: WheelEvent) => { } wheelPinch.active = true - applyZoom(clamp(wheelPinch.startZoom - (wheelPinch.totalDelta / WHEEL_PINCH_THRESHOLD) * WHEEL_PINCH_STEP)) + const direction = wheelPinch.totalDelta > 0 ? "out" : "in" + const target = nextZoomLevel(requestedZoom, direction) + if (target !== requestedZoom) { + applyZoom(target) + wheelPinch.totalDelta = 0 + wheelPinch.startZoom = target + } } window.addEventListener( @@ -135,4 +138,4 @@ window.addEventListener("keydown", (event) => { } }) -export { webviewZoom, resetZoom, setPinchZoomEnabled, zoomIn, zoomOut } +export { webviewZoom, resetZoom, setPinchZoomEnabled, setZoom, zoomIn, zoomOut } diff --git a/packages/ui/src/components/message-part.tsx b/packages/ui/src/components/message-part.tsx index 86730fa2..890d5e67 100644 --- a/packages/ui/src/components/message-part.tsx +++ b/packages/ui/src/components/message-part.tsx @@ -1361,6 +1361,7 @@ PART_MAPPING["tool"] = function ToolPartDisplay(props) { const i18n = useI18n() const part = () => props.part as ToolPart if (part().tool === "todowrite") return null + if (part().tool === "plan") return null const hideQuestion = createMemo( () => part().tool === "question" && (part().state.status === "pending" || part().state.status === "running"), diff --git a/packages/ui/src/components/session-turn.tsx b/packages/ui/src/components/session-turn.tsx index f16ae013..bfdaaeb7 100644 --- a/packages/ui/src/components/session-turn.tsx +++ b/packages/ui/src/components/session-turn.tsx @@ -96,7 +96,7 @@ function summaryDiff(value: SnapshotFileDiff): value is SummaryDiff { return typeof value.file === "string" } -const hidden = new Set(["todowrite"]) +const hidden = new Set(["todowrite", "plan"]) function partState(part: PartType, showReasoningSummaries: boolean) { if (part.type === "tool") {