@grafana/create-plugin 7.12.3 → 7.14.0

package/src/codemods/additions/scripts/experimental-app-sdk.ts

@@ -2,15 +2,20 @@ import { fileURLToPath } from 'node:url';
 import { styleText } from 'node:util';
 import { parseDocument, stringify, YAMLMap, Scalar } from 'yaml';
 import type { Context, ContextMessage } from '../../context.js';
+import type { TemplateData } from '../../../types.js';
 import { getBackendCmd } from '../../../commands/generate/print-success-message.js';
 import { output } from '../../../utils/utils.console.js';
-import { additionsDebug, renderTemplate } from '../../utils.js';
+import { additionsDebug, getTemplateDataFromContext, renderTemplate } from '../../utils.js';
+import { AGENT_INSTRUCTIONS_PATH, appendToAgentInstructions } from '../../utils.agents.js';
 import { addRequireToGoMod } from '../../utils.goMod.js';
-import { getTemplateData } from '../../../utils/utils.templates.js';
 
 // Grafana reads an app-sdk manifest from the plugin bundle, and registers its API server, only when
-// these toggles are enabled.
-const APP_SDK_FEATURE_TOGGLES = ['appplugins.loadAppManifest', 'appplugins.registerAPIServer'];
+// these toggles are enabled. The router middleware lets the app's requests through the router.
+const APP_SDK_FEATURE_TOGGLES = [
+  'appplugins.loadAppManifest',
+  'appplugins.registerAPIServer',
+  'grafana.useRouterMiddleware',
+];
 
 // Files copied verbatim from templates/app-sdk, and whether they get the "scaffolded by create-plugin,
 // don't edit" header. Paths are relative to both the template folder and the plugin root.
@@ -45,15 +50,20 @@ export default function appSdk(context: Context): Context {
 
   const changesBefore = Object.keys(context.listChanges()).length;
 
-  addTemplateFiles(context);
-  referenceAgentInstructions(context);
+  const data = getTemplateDataFromContext(context);
+  if (!data.orgName) {
+    throw new Error('src/plugin.json has no info.author.name, which the app-sdk uses to name the Go and CUE modules.');
+  }
+
+  addTemplateFiles(context, data);
+  referenceAgentInstructions(context, data);
   addGenerateScript(context);
   addFeatureToggle(context);
-  wireGoBackend(context);
+  wireGoBackend(context, data);
 
   // Only guide the user when we actually scaffolded something; a re-run should stay quiet.
   if (Object.keys(context.listChanges()).length > changesBefore) {
-    context.setMessage(buildNextStepsMessage(hasGoBackend(context)));
+    context.setMessage(buildNextStepsMessage(hasGoBackend(context), data.packageManagerName));
   }
 
   return context;
@@ -98,14 +108,14 @@ function skip(title: string, body: string[] = []) {
   output.warning({ title: `Skipping app-sdk: ${title}`, body });
 }
 
-function addTemplateFiles(context: Context) {
+function addTemplateFiles(context: Context, data: TemplateData) {
   for (const [file, includeWarning] of TEMPLATE_FILES) {
     if (context.doesFileExist(file)) {
       additionsDebug(`${file} already exists. Skipping.`);
       continue;
     }
 
-    context.addFile(file, renderTemplate(templatePath(file), includeWarning));
+    context.addFile(file, renderAppSdkTemplate(file, data, includeWarning));
   }
 }
 
@@ -113,6 +123,10 @@ function templatePath(file: string): string {
   return fileURLToPath(new URL(`../../../../templates/app-sdk/${file}`, import.meta.url));
 }
 
+function renderAppSdkTemplate(file: string, data: TemplateData, includeWarning = false): string {
+  return renderTemplate(templatePath(file), includeWarning, data);
+}
+
 /**
  * Points the plugin's agent instructions at the app-sdk ones.
  *
@@ -120,26 +134,21 @@ function templatePath(file: string): string {
  * have an instructions.md that predates the flag, so add it here — without it, an agent reading the
  * plugin's instructions has no idea kinds or generated code exist.
  */
-function referenceAgentInstructions(context: Context) {
-  const path = '.config/AGENTS/instructions.md';
-  const instructions = context.getFile(path);
-
-  if (!instructions) {
-    additionsDebug(`Could not find ${path}. Skipping the app-sdk reference.`);
+function referenceAgentInstructions(context: Context, data: TemplateData) {
+  if (!context.doesFileExist(AGENT_INSTRUCTIONS_PATH)) {
+    additionsDebug(`Could not find ${AGENT_INSTRUCTIONS_PATH}. Skipping the app-sdk reference.`);
     return;
   }
 
   if (!context.doesFileExist(APP_SDK_MD)) {
-    context.addFile(APP_SDK_MD, renderTemplate(templatePath(APP_SDK_MD), false));
-  }
-
-  if (instructions.includes(APP_SDK_MD)) {
-    return;
+    context.addFile(APP_SDK_MD, renderAppSdkTemplate(APP_SDK_MD, data));
   }
 
-  context.updateFile(
-    path,
-    `${instructions.trimEnd()}\n- This plugin defines its API resources as **CUE kinds** under \`kinds/\`, with TypeScript and Go types generated from them. Read @./${APP_SDK_MD} before changing anything under \`kinds/\` or any generated directory. **Never hand-edit generated code.**\n`
+  appendToAgentInstructions(
+    context,
+    APP_SDK_MD,
+    `- This plugin defines its API resources as **CUE kinds** under \`kinds/\`, with TypeScript and Go types generated from them. Read @./${APP_SDK_MD} before changing anything under \`kinds/\` or any generated directory. **Never hand-edit generated code.**\n`,
+    '\n'
   );
 }
 
@@ -235,20 +244,20 @@ function addFeatureToggle(context: Context) {
  * Wires the generated kinds into the Go backend, for app plugins that have one. Go code generation
  * itself is enabled when kinds/config.cue is first scaffolded, in addTemplateFiles.
  */
-function wireGoBackend(context: Context) {
+function wireGoBackend(context: Context, data: TemplateData) {
   if (!hasGoBackend(context)) {
     additionsDebug('No Go backend found. Skipping main.go wiring.');
     return;
   }
 
-  addAppProvider(context);
-  addGeneratedStubs(context);
+  addAppProvider(context, data);
+  addGeneratedStubs(context, data);
   wireMainGo(context);
   addGoModDependency(context);
 }
 
 // The go.mod version for grafana-app-sdk and its plugin/ submodule.
-const GRAFANA_APP_SDK_VERSION = 'v0.60.3';
+const GRAFANA_APP_SDK_VERSION = 'v0.60.16';
 
 /**
  * Adds github.com/grafana/grafana-app-sdk and its plugin/ submodule to go.mod. The generated Go kind
@@ -272,7 +281,7 @@ function addGoModDependency(context: Context) {
  * Not overwritten on a re-run — like kinds/*.cue, it's meant to be edited as the plugin adds
  * validators, mutators, or more kinds.
  */
-function addAppProvider(context: Context) {
+function addAppProvider(context: Context, data: TemplateData) {
   const path = 'pkg/provider/provider.go';
 
   if (context.doesFileExist(path)) {
@@ -280,7 +289,7 @@ function addAppProvider(context: Context) {
     return;
   }
 
-  context.addFile(path, renderTemplate(templatePath(path), false));
+  context.addFile(path, renderAppSdkTemplate(path, data));
 }
 
 // Stub doc.go files under pkg/generated/. Both are real packages `generate:kinds` fills in; they
@@ -295,14 +304,14 @@ const GENERATED_STUB_PATHS = ['pkg/generated/example/v1alpha1/doc.go', 'pkg/gene
  * Scaffolds stub packages under pkg/generated/, so provider.go's imports resolve for `go mod tidy`
  * before `generate:kinds` has run for the first time.
  */
-function addGeneratedStubs(context: Context) {
+function addGeneratedStubs(context: Context, data: TemplateData) {
   for (const path of GENERATED_STUB_PATHS) {
     if (context.doesFileExist(path)) {
       additionsDebug(`${path} already exists. Skipping.`);
       continue;
     }
 
-    context.addFile(path, renderTemplate(templatePath(path), false));
+    context.addFile(path, renderAppSdkTemplate(path, data));
   }
 }
 
@@ -398,8 +407,7 @@ ${errorBody}\t}`
 }
 
 /** Builds the message telling the user what to run next. */
-function buildNextStepsMessage(hasGoBackend: boolean): ContextMessage {
-  const { packageManagerName } = getTemplateData();
+function buildNextStepsMessage(hasGoBackend: boolean, packageManagerName: string): ContextMessage {
   const versionBadge = styleText(['reset', 'inverse', 'bold', 'cyan'], ` grafana-app-sdk@${GRAFANA_APP_SDK_VERSION} `);
 
   const commands = output.bulletList([

package/src/codemods/agentic/definitions.test.ts

@@ -0,0 +1,67 @@
+import { AGENT_DEFINITIONS } from './definitions.js';
+import { AgentInvocationContext } from './types.js';
+
+const invocationContext: AgentInvocationContext = {
+  systemPrompt: 'system prompt contents',
+  userPrompt: 'user prompt contents',
+  workspaceRoot: '/virtual/workspace',
+  handoffDir: '/virtual/workspace/node_modules/.cache/grafana-create-plugin/agent-runs/run-1',
+};
+
+function getDefinition(id: string) {
+  const definition = AGENT_DEFINITIONS.find((agentDefinition) => agentDefinition.id === id);
+  if (!definition) {
+    throw new Error(`No agent definition found for ${id}`);
+  }
+  return definition;
+}
+
+describe('AGENT_DEFINITIONS', () => {
+  it('should define claude-code and codex in preference order', () => {
+    expect(AGENT_DEFINITIONS.map((agentDefinition) => agentDefinition.id)).toEqual(['claude-code', 'codex']);
+  });
+
+  AGENT_DEFINITIONS.forEach((definition) => {
+    describe(definition.id, () => {
+      it('should have at least one binary name to probe', () => {
+        expect(definition.binaryNames.length).toBeGreaterThan(0);
+      });
+
+      it('should embed both prompts in the interactive invocation', () => {
+        const invocation = definition.buildInteractive(invocationContext);
+        const serialisedArgs = invocation.args.join(' ');
+        expect(serialisedArgs).toContain(invocationContext.systemPrompt);
+        expect(serialisedArgs).toContain(invocationContext.userPrompt);
+      });
+    });
+  });
+
+  it('should append the system prompt to the claude-code default rather than replace it', () => {
+    const invocation = getDefinition('claude-code').buildInteractive(invocationContext);
+    const appendIndex = invocation.args.indexOf('--append-system-prompt');
+
+    expect(appendIndex).toBeGreaterThan(-1);
+    expect(invocation.args[appendIndex + 1]).toBe(invocationContext.systemPrompt);
+    expect(invocation.args).not.toContain('--system-prompt');
+  });
+
+  it('should pre-authorize the handoff write for claude-code', () => {
+    const invocation = getDefinition('claude-code').buildInteractive(invocationContext);
+    const allowedToolsIndex = invocation.args.indexOf('--allowedTools');
+    expect(allowedToolsIndex).toBeGreaterThan(-1);
+    // claude-code only honours Edit(...) rules for file permission checks, and they cover Write too
+    expect(invocation.args[allowedToolsIndex + 1]).toBe(`Edit(${invocationContext.handoffDir}/**)`);
+  });
+
+  it('should end claude-code options before the user prompt', () => {
+    const invocation = getDefinition('claude-code').buildInteractive(invocationContext);
+
+    // --allowedTools takes a list, so without `--` the prompt is read as more rules and never sent
+    expect(invocation.args.slice(-2)).toEqual(['--', invocationContext.userPrompt]);
+  });
+
+  it('should pass the system prompt as developer instructions for codex', () => {
+    const invocation = getDefinition('codex').buildInteractive(invocationContext);
+    expect(invocation.args).toContain(`developer_instructions=${invocationContext.systemPrompt}`);
+  });
+});

package/src/codemods/agentic/definitions.ts

@@ -0,0 +1,33 @@
+import { AgentDefinition } from './types.js';
+
+// Pure data. Invocation args mirror the Nx agentic migrate implementation (nrwl/nx#35718, #35889)
+// and must be verified against the currently shipping agent CLIs when changed.
+export const AGENT_DEFINITIONS: AgentDefinition[] = [
+  {
+    id: 'claude-code',
+    displayName: 'Claude Code',
+    binaryNames: ['claude'],
+    buildInteractive: (invocationContext) => ({
+      args: [
+        // appended rather than replaced, so claude-code keeps its own tool and safety guidance
+        '--append-system-prompt',
+        invocationContext.systemPrompt,
+        // pre-authorize the handoff write so the session cannot stall on a permission prompt.
+        // claude-code matches file permissions against Edit(...) rules only; they cover Write too
+        '--allowedTools',
+        `Edit(${invocationContext.handoffDir}/**)`,
+        // --allowedTools takes a list, so end the options or the prompt is read as more rules
+        '--',
+        invocationContext.userPrompt,
+      ],
+    }),
+  },
+  {
+    id: 'codex',
+    displayName: 'OpenAI Codex',
+    binaryNames: ['codex'],
+    buildInteractive: (invocationContext) => ({
+      args: ['-c', `developer_instructions=${invocationContext.systemPrompt}`, invocationContext.userPrompt],
+    }),
+  },
+];

package/src/codemods/agentic/detect.test.ts

@@ -0,0 +1,136 @@
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { constants } from 'node:fs';
+import { access } from 'node:fs/promises';
+import which from 'which';
+import { detectInstalledAgents, isInsideAgent, resolveAgentFromPath } from './detect.js';
+import { AgentDefinition } from './types.js';
+
+vi.mock('which');
+vi.mock('node:fs/promises');
+
+const whichMock = vi.mocked(which);
+const accessMock = vi.mocked(access);
+
+function createDefinition(overrides: Partial<AgentDefinition>): AgentDefinition {
+  return {
+    id: 'claude-code',
+    displayName: 'Claude Code',
+    binaryNames: ['claude'],
+    buildInteractive: () => ({ args: [] }),
+    ...overrides,
+  };
+}
+
+describe('detectInstalledAgents', () => {
+  beforeEach(() => {
+    vi.resetAllMocks();
+  });
+
+  it('should detect an agent found on the PATH', async () => {
+    whichMock.mockResolvedValue('/usr/local/bin/claude');
+
+    const installed = await detectInstalledAgents([createDefinition({})]);
+
+    expect(installed).toHaveLength(1);
+    expect(installed[0].binaryPath).toBe('/usr/local/bin/claude');
+    expect(whichMock).toHaveBeenCalledWith('claude', { nothrow: true });
+  });
+
+  it('should return an empty list when nothing is installed', async () => {
+    // @ts-expect-error - the nothrow overload returns string | null which the mocked union cannot infer
+    whichMock.mockResolvedValue(null);
+
+    const installed = await detectInstalledAgents([createDefinition({})]);
+
+    expect(installed).toEqual([]);
+  });
+
+  it('should preserve definition order even when probes resolve out of order', async () => {
+    whichMock.mockImplementation((binaryName) => {
+      if (binaryName === 'claude') {
+        return new Promise((resolve) => {
+          setTimeout(() => resolve('/usr/local/bin/claude'), 20);
+        });
+      }
+      return Promise.resolve('/usr/local/bin/codex');
+    });
+
+    const installed = await detectInstalledAgents([
+      createDefinition({}),
+      createDefinition({ id: 'codex', displayName: 'OpenAI Codex', binaryNames: ['codex'] }),
+    ]);
+
+    expect(installed.map((agent) => agent.definition.id)).toEqual(['claude-code', 'codex']);
+  });
+});
+
+describe('isInsideAgent', () => {
+  it.each(['CLAUDECODE', 'CURSOR_TRACE_ID', 'OPENCODE', 'CODEX_THREAD_ID', 'GEMINI_CLI', 'VSCODE_AGENT', 'REPL_ID'])(
+    'should return true when %s is set',
+    (envVar) => {
+      expect(isInsideAgent({ [envVar]: '1' })).toBe(true);
+    }
+  );
+
+  it('should return false when no agent environment variables are set', () => {
+    expect(isInsideAgent({ PATH: '/usr/bin', TERM: 'xterm-256color' })).toBe(false);
+  });
+
+  it('should return false when an agent environment variable is set but empty', () => {
+    expect(isInsideAgent({ CLAUDECODE: '' })).toBe(false);
+  });
+});
+
+describe('resolveAgentFromPath', () => {
+  beforeEach(() => {
+    vi.resetAllMocks();
+    accessMock.mockResolvedValue(undefined);
+  });
+
+  it('should resolve the definition from the binary name', async () => {
+    const definition = createDefinition({});
+
+    const agent = await resolveAgentFromPath('/opt/homebrew/bin/claude', [definition]);
+
+    expect(agent.definition).toBe(definition);
+    expect(agent.binaryPath).toBe('/opt/homebrew/bin/claude');
+  });
+
+  it('should expand a leading ~ to the home directory, since shells leave it alone after --agent=', async () => {
+    const agent = await resolveAgentFromPath('~/.claude/local/claude', [createDefinition({})]);
+
+    expect(agent.binaryPath).toBe(join(homedir(), '.claude/local/claude'));
+    expect(accessMock).toHaveBeenCalledWith(join(homedir(), '.claude/local/claude'), constants.X_OK);
+  });
+
+  it('should check the path is executable', async () => {
+    await resolveAgentFromPath('/opt/homebrew/bin/claude', [createDefinition({})]);
+
+    expect(accessMock).toHaveBeenCalledWith('/opt/homebrew/bin/claude', constants.X_OK);
+  });
+
+  it('should throw when the binary name matches no known agent', async () => {
+    await expect(resolveAgentFromPath('/usr/local/bin/mystery', [createDefinition({})])).rejects.toThrow(
+      /Could not tell which agent/
+    );
+  });
+
+  it('should name the expected binaries when the name matches nothing', async () => {
+    await expect(resolveAgentFromPath('/usr/local/bin/mystery', [createDefinition({})])).rejects.toThrow(/claude/);
+  });
+
+  it('should throw when the path is not executable', async () => {
+    accessMock.mockRejectedValue(new Error('EACCES'));
+
+    await expect(resolveAgentFromPath('/opt/homebrew/bin/claude', [createDefinition({})])).rejects.toThrow(
+      /not an executable file/
+    );
+  });
+
+  it('should not check executability when the name matches nothing', async () => {
+    await expect(resolveAgentFromPath('/usr/local/bin/mystery', [createDefinition({})])).rejects.toThrow();
+
+    expect(accessMock).not.toHaveBeenCalled();
+  });
+});

package/src/codemods/agentic/detect.ts

@@ -0,0 +1,75 @@
+import { constants } from 'node:fs';
+import { access } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { basename, join } from 'node:path';
+import which from 'which';
+import { AGENT_DEFINITIONS } from './definitions.js';
+import { AgentDefinition, InstalledAgent } from './types.js';
+
+// Environment variables set by AI agent CLIs/IDEs when they run a shell command.
+// Used to avoid spawning an agent from inside another agent.
+const AGENT_ENV_VARS = [
+  'CLAUDECODE',
+  'CURSOR_TRACE_ID',
+  'OPENCODE',
+  'CODEX_THREAD_ID',
+  'GEMINI_CLI',
+  'VSCODE_AGENT',
+  'REPL_ID',
+];
+
+export async function detectInstalledAgents(
+  definitions: AgentDefinition[] = AGENT_DEFINITIONS
+): Promise<InstalledAgent[]> {
+  const probes = await Promise.all(definitions.map(detectAgent));
+  return probes.filter((agent): agent is InstalledAgent => agent !== null);
+}
+
+// escape hatch for agents installed outside PATH, e.g. claude at ~/.claude/local/claude. the binary
+// name has to identify the agent because each one takes different invocation arguments
+export async function resolveAgentFromPath(
+  agentPath: string,
+  definitions: AgentDefinition[] = AGENT_DEFINITIONS
+): Promise<InstalledAgent> {
+  const binaryPath = expandHomeDirectory(agentPath);
+  const binaryName = basename(binaryPath);
+  const definition = definitions.find((agentDefinition) => agentDefinition.binaryNames.includes(binaryName));
+
+  if (!definition) {
+    const expectedNames = definitions.flatMap((agentDefinition) => agentDefinition.binaryNames).join(', ');
+    throw new Error(
+      `Could not tell which agent "${binaryPath}" is. Expected the file to be named one of: ${expectedNames}.`
+    );
+  }
+
+  try {
+    await access(binaryPath, constants.X_OK);
+  } catch {
+    throw new Error(`The agent path "${binaryPath}" is not an executable file.`);
+  }
+
+  return { definition, binaryPath };
+}
+
+// shells only expand ~ at the start of a word, so `--agent=~/...` reaches us unexpanded
+function expandHomeDirectory(agentPath: string): string {
+  if (!agentPath.startsWith('~/')) {
+    return agentPath;
+  }
+  return join(homedir(), agentPath.slice(2));
+}
+
+export function isInsideAgent(env: NodeJS.ProcessEnv = process.env): boolean {
+  return AGENT_ENV_VARS.some((envVar) => Boolean(env[envVar]));
+}
+
+async function detectAgent(definition: AgentDefinition): Promise<InstalledAgent | null> {
+  for (const binaryName of definition.binaryNames) {
+    const binaryPath = await which(binaryName, { nothrow: true });
+    if (binaryPath) {
+      return { definition, binaryPath };
+    }
+  }
+
+  return null;
+}

package/src/codemods/agentic/handoff.test.ts

@@ -0,0 +1,102 @@
+import { existsSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import {
+  createRunId,
+  ensureRunDir,
+  getHandoffPath,
+  getRunDir,
+  AGENT_RUNS_DIR,
+  parseHandoff,
+  wipeAgentRuns,
+} from './handoff.js';
+
+describe('run dir lifecycle', () => {
+  let basePath: string;
+
+  beforeEach(() => {
+    basePath = mkdtempSync(join(tmpdir(), 'cp-handoff-test-'));
+  });
+
+  afterEach(() => {
+    rmSync(basePath, { recursive: true, force: true });
+  });
+
+  it('should build run dirs under the agent-runs cache dir', () => {
+    expect(getRunDir(basePath, 'run-1')).toBe(join(basePath, AGENT_RUNS_DIR, 'run-1'));
+  });
+
+  it('should build handoff paths from the migration name', () => {
+    const runDir = getRunDir(basePath, 'run-1');
+    expect(getHandoffPath(runDir, '013-example')).toBe(join(runDir, '013-example.json'));
+  });
+
+  it('should create run dirs and tolerate them already existing', () => {
+    const runDir = getRunDir(basePath, 'run-1');
+    ensureRunDir(runDir);
+    expect(existsSync(runDir)).toBe(true);
+    expect(() => ensureRunDir(runDir)).not.toThrow();
+  });
+
+  it('should wipe all previous runs', () => {
+    const runDir = getRunDir(basePath, 'run-1');
+    ensureRunDir(runDir);
+    writeFileSync(getHandoffPath(runDir, '013-example'), '{}');
+
+    wipeAgentRuns(basePath);
+
+    expect(existsSync(join(basePath, AGENT_RUNS_DIR))).toBe(false);
+  });
+
+  it('should not throw when wiping a base path with no runs', () => {
+    expect(() => wipeAgentRuns(basePath)).not.toThrow();
+  });
+});
+
+describe('createRunId', () => {
+  it('should create ids that are safe to use as directory names', () => {
+    expect(createRunId()).toMatch(/^[a-z0-9-]+$/);
+  });
+
+  it('should create unique ids', () => {
+    expect(createRunId()).not.toBe(createRunId());
+  });
+});
+
+describe('parseHandoff', () => {
+  it('should parse a success handoff', () => {
+    expect(parseHandoff('{"status":"success","summary":"done"}')).toEqual({ status: 'success', summary: 'done' });
+  });
+
+  it('should parse a failed handoff', () => {
+    expect(parseHandoff('{"status":"failed","summary":"could not migrate"}')).toEqual({
+      status: 'failed',
+      summary: 'could not migrate',
+    });
+  });
+
+  it('should drop unknown keys', () => {
+    expect(parseHandoff('{"status":"success","summary":"done","extras":{"foo":1}}')).toEqual({
+      status: 'success',
+      summary: 'done',
+    });
+  });
+
+  it('should return undefined for malformed JSON', () => {
+    expect(parseHandoff('{"status": "succ')).toBeUndefined();
+  });
+
+  it('should return undefined for unexpected status values', () => {
+    expect(parseHandoff('{"status":"maybe","summary":"done"}')).toBeUndefined();
+  });
+
+  it('should return undefined when summary is missing', () => {
+    expect(parseHandoff('{"status":"success"}')).toBeUndefined();
+  });
+
+  it('should not be vulnerable to prototype pollution', () => {
+    const handoff = parseHandoff('{"status":"success","summary":"done","__proto__":{"polluted":true}}');
+    expect(handoff).toEqual({ status: 'success', summary: 'done' });
+    expect('polluted' in {}).toBe(false);
+  });
+});

package/src/codemods/agentic/handoff.ts

@@ -0,0 +1,45 @@
+import { randomBytes } from 'node:crypto';
+import { mkdirSync, rmSync } from 'node:fs';
+import { join } from 'node:path';
+import * as v from 'valibot';
+import { Handoff } from './types.js';
+
+// The handoff file is ephemeral single-run IPC between the spawned agent and create-plugin:
+// the agent writes it as its final action, the runner polls and consumes it immediately.
+// It lives under node_modules so it is gitignored in every scaffold and never needs to persist.
+export const AGENT_RUNS_DIR = join('node_modules', '.cache', 'grafana-create-plugin', 'agent-runs');
+
+const handoffSchema = v.object({
+  status: v.picklist(['success', 'failed']),
+  summary: v.string(),
+});
+
+export function createRunId(): string {
+  return `${Date.now().toString(36)}-${randomBytes(4).toString('hex')}`;
+}
+
+export function getRunDir(basePath: string, runId: string): string {
+  return join(basePath, AGENT_RUNS_DIR, runId);
+}
+
+export function getHandoffPath(runDir: string, stepName: string): string {
+  return join(runDir, `${stepName}.json`);
+}
+
+// re-run before every agent session; a package manager install may have pruned the cache dir
+export function ensureRunDir(runDir: string): void {
+  mkdirSync(runDir, { recursive: true });
+}
+
+export function wipeAgentRuns(basePath: string): void {
+  rmSync(join(basePath, AGENT_RUNS_DIR), { recursive: true, force: true });
+}
+
+export function parseHandoff(raw: string): Handoff | undefined {
+  try {
+    const parsed = v.parse(handoffSchema, JSON.parse(raw));
+    return { status: parsed.status, summary: parsed.summary };
+  } catch {
+    return undefined;
+  }
+}