@seqyuan/pi-kernel-plot 0.2.1

package/dist/extensions/kernel-plot.d.ts

@@ -0,0 +1,2 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+export default function (pi: ExtensionAPI): void;

package/dist/extensions/kernel-plot.js

@@ -0,0 +1 @@
+import{createKernelPlotTools as n}from"../src/tools.js";function a(o){const e=n();o.registerTool(e.run),o.registerTool(e.stop),o.registerTool(e.artifacts),o.registerTool(e.configure),o.on("session_shutdown",async(r,s)=>{await e.disposeSession(s).catch(t=>{s.ui.notify(`kernel plot cleanup failed: ${t instanceof Error?t.message:String(t)}`,"warning")})})}export{a as default};

package/dist/src/core-adapter.d.ts

@@ -0,0 +1,2 @@
+import type { KernelLiteCore } from "./types.js";
+export declare function getKernelLiteCore(): Promise<KernelLiteCore>;

package/dist/src/core-adapter.js

@@ -0,0 +1 @@
+let r;async function o(){try{return await import("@seqyuan/kernel-lite-core")}catch(e){const t=e instanceof Error?e.message:String(e);throw new Error(`Cannot load @seqyuan/kernel-lite-core. Install or build packages/kernel-lite-core before using kernel_plot tools. Original error: ${t}`)}}async function n(){const e=await o();if(typeof e.createKernelLiteCore=="function")return await e.createKernelLiteCore();if(typeof e.run=="function"&&typeof e.listArtifacts=="function")return{run:e.run,stopSession:async t=>{if(typeof e.stopSession=="function"){await e.stopSession(t);return}if(typeof e.stop=="function"){await e.stop(t);return}throw new Error("@seqyuan/kernel-lite-core does not export stopSession or stop")},listArtifacts:e.listArtifacts,dispose:async()=>{typeof e.dispose=="function"&&await e.dispose()}};throw new Error("@seqyuan/kernel-lite-core must export createKernelLiteCore(), or top-level run(), listArtifacts(), and stop()/stopSession() functions")}async function s(){return r??=n(),await r}export{s as getKernelLiteCore};

package/dist/src/index.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/src/prompt.d.ts

@@ -0,0 +1,2 @@
+export declare const kernelPlotRunPromptSnippet = "Run short R/Python plotting code in a warm kernel and save artifacts to disk.";
+export declare const kernelPlotPromptGuidelines: string[];

package/dist/src/prompt.js

@@ -0,0 +1 @@
+const e="Run short R/Python plotting code in a warm kernel and save artifacts to disk.",t=["Use kernel_plot_run for iterative R/Python plotting when data should stay in memory across turns.",'Use kernel_plot_run with runtime: "worker" for one-shot reproducible scripts.',"In kernel_plot_run code, save every output under WARMPLOT_OUTPUT_DIR.","Do not rely on notebook display; explicitly save PNG, SVG, PDF, HTML, CSV, TSV, or JSON files.","After a failed kernel_plot_run, inspect stderr and rerun only the minimal corrected code.","Use kernel_plot_stop when the user is done with a large object or asks to free memory."];export{t as kernelPlotPromptGuidelines,e as kernelPlotRunPromptSnippet};

package/dist/src/render.d.ts

@@ -0,0 +1,8 @@
+import { Text } from "@earendil-works/pi-tui";
+export declare function renderKernelPlotResult(result: {
+    content: Array<{
+        type: string;
+        text?: string;
+    }>;
+    details?: unknown;
+}): Text;

package/dist/src/render.js

@@ -0,0 +1,3 @@
+import{Text as e}from"@earendil-works/pi-tui";function a(t){return!Number.isFinite(t)||t<0?"unknown":t<1024?`${t} B`:t<1024*1024?`${(t/1024).toFixed(1)} KB`:`${(t/1024/1024).toFixed(1)} MB`}function i(t){return`- ${t.path} (${t.kind}, ${a(t.size)})`}function s(t){const n=t.details;if(!n||n.schema!=="kernel-plot.result.v1"){const r=t.content.find(o=>o.type==="text")?.text??"";return new e(r,0,0)}if(n.kind==="run"){const r=[`kernel_plot_run ${n.run.status}`,`run_id: ${n.run.runId}`,`runtime: ${n.run.runtime}`,`artifacts: ${n.artifacts.length}`,...n.artifacts.slice(0,8).map(i)];return new e(r.join(`
+`),0,0)}if(n.kind==="stop")return new e(`kernel_plot_stop stopped ${n.stopped.language??"all languages"}`,0,0);const u=[`kernel_plot_artifacts ${n.artifacts.length}`,...n.artifacts.slice(0,12).map(i)];return new e(u.join(`
+`),0,0)}export{s as renderKernelPlotResult};

package/dist/src/tools.d.ts

@@ -0,0 +1,210 @@
+import { type ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { renderKernelPlotResult } from "./render.js";
+import type { KernelLanguage, KernelPlotArtifactsDetails, KernelPlotRunDetails, KernelPlotStopDetails, KernelPlotToolDetails, ToolContent } from "./types.js";
+interface RunParams {
+    language: KernelLanguage;
+    code: string;
+    runtime?: "kernel-lite" | "worker";
+    title?: string;
+    timeoutMs?: number;
+}
+interface StopParams {
+    language?: KernelLanguage;
+}
+interface ArtifactsParams {
+    limit?: number;
+}
+export declare function createKernelPlotTools(): {
+    run: {
+        name: string;
+        label: string;
+        description: string;
+        promptSnippet: string;
+        promptGuidelines: string[];
+        executionMode: "sequential";
+        parameters: unknown;
+        execute(_toolCallId: string, params: RunParams, signal: AbortSignal, _onUpdate: unknown, ctx: ExtensionContext): Promise<{
+            content: ToolContent;
+            details: KernelPlotRunDetails;
+        }>;
+        renderResult: typeof renderKernelPlotResult;
+    };
+    stop: {
+        name: string;
+        label: string;
+        description: string;
+        promptSnippet: string;
+        promptGuidelines: string[];
+        executionMode: "sequential";
+        parameters: unknown;
+        execute(_toolCallId: string, params: StopParams, _signal: AbortSignal, _onUpdate: unknown, ctx: ExtensionContext): Promise<{
+            content: {
+                type: string;
+                text: string;
+            }[];
+            details: KernelPlotStopDetails;
+        }>;
+        renderResult: typeof renderKernelPlotResult;
+    };
+    artifacts: {
+        name: string;
+        label: string;
+        description: string;
+        promptSnippet: string;
+        promptGuidelines: string[];
+        parameters: unknown;
+        execute(_toolCallId: string, params: ArtifactsParams, _signal: AbortSignal, _onUpdate: unknown, ctx: ExtensionContext): Promise<{
+            content: {
+                type: string;
+                text: string;
+            }[];
+            details: KernelPlotArtifactsDetails;
+        }>;
+        renderResult: typeof renderKernelPlotResult;
+    };
+    configure: {
+        name: string;
+        label: string;
+        description: string;
+        promptSnippet: string;
+        promptGuidelines: string[];
+        parameters: unknown;
+        execute(_toolCallId: string, params: {
+            action: "list" | "select" | "add" | "edit" | "delete" | "scan";
+            language?: KernelLanguage;
+            kernelId?: string;
+            config?: {
+                command: string;
+                args?: string;
+                displayName?: string;
+                env?: string;
+            };
+        }, _signal: AbortSignal, _onUpdate: unknown, ctx: ExtensionContext): Promise<{
+            content: {
+                type: string;
+                text: string;
+            }[];
+            details: {
+                schema: string;
+                kind: string;
+                action: string;
+                kernels: {
+                    id: string;
+                    language: import("@seqyuan/kernel-lite-core").KernelLanguage;
+                    displayName: string;
+                    command: string;
+                    isDefault: boolean;
+                    isSelected: boolean;
+                }[];
+                projectConfig: string;
+                globalConfig: string;
+                selectedKernel?: undefined;
+                kernel?: undefined;
+                deletedKernelId?: undefined;
+                newKernels?: undefined;
+                errors?: undefined;
+                scanTime?: undefined;
+            };
+        } | {
+            content: {
+                type: string;
+                text: string;
+            }[];
+            details: {
+                schema: string;
+                kind: string;
+                action: string;
+                selectedKernel: {
+                    language: import("@seqyuan/kernel-lite-core").KernelLanguage;
+                    command: string;
+                    args: string[];
+                    displayName: string;
+                    env: Record<string, string>;
+                    id: string;
+                };
+                kernels?: undefined;
+                projectConfig?: undefined;
+                globalConfig?: undefined;
+                kernel?: undefined;
+                deletedKernelId?: undefined;
+                newKernels?: undefined;
+                errors?: undefined;
+                scanTime?: undefined;
+            };
+        } | {
+            content: {
+                type: string;
+                text: string;
+            }[];
+            details: {
+                schema: string;
+                kind: string;
+                action: string;
+                kernel: {
+                    language: KernelLanguage;
+                    command: string;
+                    args: any;
+                    displayName: string;
+                    env: any;
+                    id: string;
+                };
+                kernels?: undefined;
+                projectConfig?: undefined;
+                globalConfig?: undefined;
+                selectedKernel?: undefined;
+                deletedKernelId?: undefined;
+                newKernels?: undefined;
+                errors?: undefined;
+                scanTime?: undefined;
+            };
+        } | {
+            content: {
+                type: string;
+                text: string;
+            }[];
+            details: {
+                schema: string;
+                kind: string;
+                action: string;
+                deletedKernelId: string;
+                kernels?: undefined;
+                projectConfig?: undefined;
+                globalConfig?: undefined;
+                selectedKernel?: undefined;
+                kernel?: undefined;
+                newKernels?: undefined;
+                errors?: undefined;
+                scanTime?: undefined;
+            };
+        } | {
+            content: {
+                type: string;
+                text: string;
+            }[];
+            details: {
+                schema: string;
+                kind: string;
+                action: string;
+                newKernels: {
+                    language: import("@seqyuan/kernel-lite-core").KernelLanguage;
+                    command: string;
+                    args: string[];
+                    displayName: string;
+                    env: Record<string, string>;
+                    id: string;
+                }[];
+                errors: string[];
+                scanTime: string;
+                kernels?: undefined;
+                projectConfig?: undefined;
+                globalConfig?: undefined;
+                selectedKernel?: undefined;
+                kernel?: undefined;
+                deletedKernelId?: undefined;
+            };
+        }>;
+        renderResult: typeof renderKernelPlotResult;
+    };
+    disposeSession(ctx: ExtensionContext): Promise<void>;
+};
+export type { KernelLanguage, KernelPlotToolDetails };

package/dist/src/tools.js

@@ -0,0 +1,7 @@
+import{StringEnum as I,Type as n}from"@earendil-works/pi-ai";import{defineTool as _}from"@earendil-works/pi-coding-agent";import{readFile as T,stat as A}from"node:fs/promises";import{getKernelLiteCore as $}from"./core-adapter.js";import{kernelPlotPromptGuidelines as v,kernelPlotRunPromptSnippet as U}from"./prompt.js";import{renderKernelPlotResult as S}from"./render.js";const L=4e3,M=2*1024*1024,K=I(["python","r"],{description:"Runtime language for the plotting code."}),D=I(["kernel-lite","worker"],{description:"kernel-lite keeps language state warm; worker runs a one-shot script."});function P(t,l=L){const a=t??"";return a.length<=l?a:`${a.slice(0,l)}
+[truncated ${a.length-l} chars]`}function b(t){return t.sessionManager.getSessionId()}function N(t){return t.length===0?["artifacts: none"]:["artifacts:",...t.map(l=>`- ${l.path}`)]}function G(t){const l=[`kernel_plot_run ${t.status}`,`run_id: ${t.runId}`,`runtime: ${t.runtime}`,`script: ${t.scriptPath}`,`stdout: ${t.stdoutPath}`,`stderr: ${t.stderrPath}`],a=P(t.stdout,1200).trim(),k=P(t.stderr,1200).trim();return a&&l.push("stdout:",a),k&&l.push("stderr:",k),t.error&&l.push(`error: ${t.error}`),l.push(...N(t.artifacts)),l.join(`
+`)}async function q(t){const l=t.find(a=>a.kind==="image"&&(a.mimeType==="image/png"||a.mimeType==="image/jpeg"||a.mimeType==="image/webp"));if(l)try{const a=await A(l.path);return!a.isFile()||a.size>M?void 0:{type:"image",data:(await T(l.path)).toString("base64"),mimeType:l.mimeType}}catch{return}}function J(t){return{schema:"kernel-plot.result.v1",kind:"run",run:{runId:t.runId,status:t.status,language:t.language,runtime:t.runtime,title:t.title,stdoutPath:t.stdoutPath,stderrPath:t.stderrPath,scriptPath:t.scriptPath,outputDir:t.outputDir,stdoutPreview:P(t.stdout),stderrPreview:P(t.stderr),error:t.error},artifacts:t.artifacts,nextAction:t.status==="succeeded"?"Inspect the artifact paths or continue iterating with kernel_plot_run.":"Inspect stderr and rerun only the minimal corrected code."}}function F(t){return["kernel_plot_artifacts",...N(t)].join(`
+`)}function Y(){const t=_({name:"kernel_plot_run",label:"Kernel Plot Run",description:"Execute short R or Python plotting code in a warm kernel-lite runtime or one-shot worker and archive generated artifacts.",promptSnippet:U,promptGuidelines:v,executionMode:"sequential",parameters:n.Object({language:K,code:n.String({description:"R or Python code. Save files under WARMPLOT_OUTPUT_DIR or PI_KERNEL_PLOT_OUTPUT_DIR."}),runtime:n.Optional(D),title:n.Optional(n.String({description:"Short title for the run."})),timeoutMs:n.Optional(n.Number({description:"Execution timeout in milliseconds."}))}),async execute(h,e,w,O,c){const d=await(await $()).run({cwd:c.cwd,ownerId:b(c),language:e.language,runtime:e.runtime,code:e.code,title:e.title,timeoutMs:e.timeoutMs,signal:w}),g=[{type:"text",text:G(d)}],m=await q(d.artifacts);return m&&g.push(m),{content:g,details:J(d)}},renderResult:S}),l=_({name:"kernel_plot_stop",label:"Kernel Plot Stop",description:"Stop the current Pi session's warm plotting kernel for one language or all languages.",promptSnippet:"Stop warm R/Python plotting kernels and release their memory.",promptGuidelines:v,executionMode:"sequential",parameters:n.Object({language:n.Optional(K)}),async execute(h,e,w,O,c){const f=await $(),d=b(c);await f.stopSession({ownerId:d,language:e.language});const g={schema:"kernel-plot.result.v1",kind:"stop",stopped:{ownerId:d,language:e.language},artifacts:[],nextAction:"Use kernel_plot_run to start a fresh warm kernel when needed."};return{content:[{type:"text",text:`kernel_plot_stop stopped ${e.language??"all languages"}`}],details:g}},renderResult:S}),a=_({name:"kernel_plot_artifacts",label:"Kernel Plot Artifacts",description:"List recent archived plotting artifacts for the current Pi session.",promptSnippet:"List recent R/Python plotting artifact paths for this session.",promptGuidelines:v,parameters:n.Object({limit:n.Optional(n.Number({description:"Maximum number of recent artifacts to list."}))}),async execute(h,e,w,O,c){const f=await $(),d=b(c),g=await f.listArtifacts({cwd:c.cwd,ownerId:d,limit:e.limit}),m={schema:"kernel-plot.result.v1",kind:"artifacts",ownerId:d,artifacts:g,nextAction:"Open or inspect the listed artifact paths, or continue plotting with kernel_plot_run."};return{content:[{type:"text",text:F(g)}],details:m}},renderResult:S}),k=_({name:"kernel_plot_configure",label:"Kernel Plot Configure",description:"Configure Python/R kernel environments for plotting. Supports listing, selecting, adding, editing, deleting kernels, and scanning environments.",promptSnippet:"Configure which Python/R interpreter to use for plotting.",promptGuidelines:v,parameters:n.Object({action:I(["list","select","add","edit","delete","scan"],{description:"Action to perform: list kernels, select for project, add new, edit existing, delete, or scan environments."}),language:n.Optional(I(["python","r"],{description:"Filter by language (for list/scan) or specify language (for select)."})),kernelId:n.Optional(n.String({description:"Kernel ID for select/edit/delete actions."})),config:n.Optional(n.Object({command:n.String({description:"Path to interpreter executable."}),args:n.Optional(n.String({description:"Command-line arguments (JSON array string)."})),displayName:n.Optional(n.String({description:"Human-readable name."})),env:n.Optional(n.String({description:"Environment variables (JSON object string)."}))}))}),async execute(h,e,w,O,c){const{loadGlobalConfig:f,saveGlobalConfig:d,loadProjectConfig:g,saveProjectConfig:m,scanAllEnvironments:C,scanPythonEnvironments:E,scanREnvironments:R}=await import("@seqyuan/kernel-lite-core"),r=await f(),x=await g(c.cwd);switch(e.action){case"list":{const o=Object.entries(r.kernels).filter(([u,i])=>!e.language||i.language===e.language).map(([u,i])=>({id:u,language:i.language,displayName:i.displayName,command:i.command,isDefault:r.defaultKernel[i.language]===u,isSelected:x?.selectedKernels[i.language]===u}));return{content:[{type:"text",text:["Available kernels:",...o.map(u=>`- ${u.id}: ${u.displayName} (${u.command})${u.isDefault?" [default]":""}${u.isSelected?" [selected]":""}`)].join(`
+`)}],details:{schema:"kernel-plot.result.v1",kind:"configure",action:"list",kernels:o,projectConfig:`${c.cwd}/.pi/warmplot.json`,globalConfig:"~/.config/warmplot.json"}}}case"select":{if(!e.language||!e.kernelId)throw new Error("select action requires language and kernelId");const o=r.kernels[e.kernelId];if(!o)throw new Error(`Kernel '${e.kernelId}' not found. Available: ${Object.keys(r.kernels).join(", ")}`);const s=x||{version:"1.0",selectedKernels:{}};return s.selectedKernels[e.language]=e.kernelId,await m(c.cwd,s),{content:[{type:"text",text:`Selected '${e.kernelId}' (${o.displayName}) for ${e.language} in this project.
+Config saved to ${c.cwd}/.pi/warmplot.json`}],details:{schema:"kernel-plot.result.v1",kind:"configure",action:"select",selectedKernel:{id:e.kernelId,...o}}}}case"add":{if(!e.kernelId||!e.config?.command)throw new Error("add action requires kernelId and config.command");if(r.kernels[e.kernelId])throw new Error(`Kernel '${e.kernelId}' already exists. Use 'edit' action to modify it.`);const o=e.config.command.toLowerCase(),s=o.includes("python")?"python":o.includes("r")?"r":"python",u=e.config.args?JSON.parse(e.config.args):s==="python"?["-u"]:["--slave","--vanilla"],i=e.config.env?JSON.parse(e.config.env):{},p={language:s,command:e.config.command,args:u,displayName:e.config.displayName||`${s} (${e.kernelId})`,env:i};return r.kernels[e.kernelId]=p,await d(r),{content:[{type:"text",text:`Added kernel '${e.kernelId}': ${p.displayName} (${p.command})`}],details:{schema:"kernel-plot.result.v1",kind:"configure",action:"add",kernel:{id:e.kernelId,...p}}}}case"edit":{if(!e.kernelId||!e.config)throw new Error("edit action requires kernelId and config");const o=r.kernels[e.kernelId];if(!o)throw new Error(`Kernel '${e.kernelId}' not found. Available: ${Object.keys(r.kernels).join(", ")}`);const s={...o,...e.config.command&&{command:e.config.command},...e.config.args&&{args:JSON.parse(e.config.args)},...e.config.displayName&&{displayName:e.config.displayName},...e.config.env&&{env:{...o.env,...JSON.parse(e.config.env)}}};return r.kernels[e.kernelId]=s,await d(r),{content:[{type:"text",text:`Updated kernel '${e.kernelId}': ${s.displayName} (${s.command})`}],details:{schema:"kernel-plot.result.v1",kind:"configure",action:"edit",kernel:{id:e.kernelId,...s}}}}case"delete":{if(!e.kernelId)throw new Error("delete action requires kernelId");if(!r.kernels[e.kernelId])throw new Error(`Kernel '${e.kernelId}' not found`);if(e.kernelId==="default-python"||e.kernelId==="default-r")throw new Error("Cannot delete system default kernels");delete r.kernels[e.kernelId];for(const o of["python","r"])r.defaultKernel[o]===e.kernelId&&delete r.defaultKernel[o];return await d(r),{content:[{type:"text",text:`Deleted kernel '${e.kernelId}'`}],details:{schema:"kernel-plot.result.v1",kind:"configure",action:"delete",deletedKernelId:e.kernelId}}}case"scan":{const o=e.language?e.language==="python"?await E(c.cwd):await R(c.cwd):await C(c.cwd),s=[];for(const i of o.newKernels){const p=i.displayName.toLowerCase().replace(/[^a-z0-9-]/g,"-").replace(/-+/g,"-");let y=p,j=1;for(;r.kernels[y];)y=`${p}-${j}`,j++;r.kernels[y]=i,s.push({id:y,...i})}return r.scanCache={lastScan:new Date().toISOString(),scannedKernels:Object.keys(r.kernels)},await d(r),{content:[{type:"text",text:[`Scanned environments, found ${s.length} new kernels:`,...s.map(i=>`- ${i.id}: ${i.displayName} (${i.command})`),...o.errors.length>0?["","Warnings:",...o.errors.map(i=>`- ${i}`)]:[]].join(`
+`)}],details:{schema:"kernel-plot.result.v1",kind:"configure",action:"scan",newKernels:s,errors:o.errors,scanTime:r.scanCache.lastScan}}}default:throw new Error(`Unknown action: ${e.action}`)}},renderResult:S});return{run:t,stop:l,artifacts:a,configure:k,async disposeSession(h){await(await $()).stopSession({ownerId:b(h)})}}}export{Y as createKernelPlotTools};

package/dist/src/types.d.ts

@@ -0,0 +1,107 @@
+export type KernelLanguage = "python" | "r";
+export type KernelRuntime = "kernel-lite" | "worker" | "jupyter";
+export type KernelRunStatus = "queued" | "running" | "succeeded" | "failed" | "cancelled" | "timed_out";
+export type ArtifactKind = "image" | "html" | "document" | "text" | "data" | "other";
+export interface ExecuteKernelRunInput {
+    cwd: string;
+    ownerId: string;
+    language: KernelLanguage;
+    runtime?: Exclude<KernelRuntime, "jupyter">;
+    code: string;
+    title?: string;
+    archiveRoot?: string;
+    timeoutMs?: number;
+    env?: Record<string, string>;
+    signal?: AbortSignal;
+}
+export interface KernelArtifact {
+    path: string;
+    relativePath: string;
+    archivePath: string;
+    name: string;
+    mimeType: string;
+    kind: ArtifactKind;
+    size: number;
+}
+export interface ExecuteKernelRunResult {
+    runId: string;
+    ownerId: string;
+    language: KernelLanguage;
+    runtime: KernelRuntime;
+    status: KernelRunStatus;
+    title?: string;
+    stdout: string;
+    stderr: string;
+    exitCode: number | null;
+    error: string | null;
+    cancelled: boolean;
+    timedOut: boolean;
+    scriptPath: string;
+    stdoutPath: string;
+    stderrPath: string;
+    outputDir: string;
+    artifacts: KernelArtifact[];
+    createdAt: string;
+    completedAt: string;
+}
+export interface KernelLiteCore {
+    run(input: ExecuteKernelRunInput): Promise<ExecuteKernelRunResult>;
+    stopSession(input: {
+        cwd?: string;
+        ownerId: string;
+        language?: KernelLanguage;
+    }): Promise<void>;
+    cancelRun?(runId: string, reason?: string): Promise<boolean>;
+    listArtifacts(input: {
+        cwd: string;
+        ownerId: string;
+        limit?: number;
+    }): Promise<KernelArtifact[]>;
+    dispose(): Promise<void>;
+}
+export type ToolContent = Array<{
+    type: "text";
+    text: string;
+} | {
+    type: "image";
+    data: string;
+    mimeType: string;
+}>;
+export interface KernelPlotRunDetails {
+    schema: "kernel-plot.result.v1";
+    kind: "run";
+    run: {
+        runId: string;
+        status: KernelRunStatus;
+        language: KernelLanguage;
+        runtime: KernelRuntime;
+        title?: string;
+        stdoutPath: string;
+        stderrPath: string;
+        scriptPath: string;
+        outputDir: string;
+        stdoutPreview: string;
+        stderrPreview: string;
+        error: string | null;
+    };
+    artifacts: KernelArtifact[];
+    nextAction: string;
+}
+export interface KernelPlotStopDetails {
+    schema: "kernel-plot.result.v1";
+    kind: "stop";
+    stopped: {
+        ownerId: string;
+        language?: KernelLanguage;
+    };
+    artifacts: KernelArtifact[];
+    nextAction: string;
+}
+export interface KernelPlotArtifactsDetails {
+    schema: "kernel-plot.result.v1";
+    kind: "artifacts";
+    ownerId: string;
+    artifacts: KernelArtifact[];
+    nextAction: string;
+}
+export type KernelPlotToolDetails = KernelPlotRunDetails | KernelPlotStopDetails | KernelPlotArtifactsDetails;

package/package.json

@@ -0,0 +1,70 @@
+{
+  "name": "@seqyuan/pi-kernel-plot",
+  "version": "0.2.1",
+  "description": "Pi package adapter for warm R/Python kernel plotting artifacts.",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/seqyuan/warmplot.git",
+    "directory": "packages/pi-kernel-plot"
+  },
+  "bugs": {
+    "url": "https://github.com/seqyuan/warmplot/issues"
+  },
+  "homepage": "https://github.com/seqyuan/warmplot#readme",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "keywords": [
+    "pi-package",
+    "kernel",
+    "plot",
+    "python",
+    "r"
+  ],
+  "files": [
+    "dist",
+    "!dist/**/*.map",
+    "!dist/**/*.tsbuildinfo",
+    "skills",
+    "package.json",
+    "README.md"
+  ],
+  "pi": {
+    "extensions": [
+      "./dist/extensions/kernel-plot.js"
+    ],
+    "skills": [
+      "./skills"
+    ]
+  },
+  "scripts": {
+    "prepack": "node ../../scripts/check-pack-protection.mjs .",
+    "prepublishOnly": "node ../../scripts/check-pack-protection.mjs ."
+  },
+  "dependencies": {
+    "@seqyuan/kernel-lite-core": "^0.2.1"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-ai": "*",
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*",
+    "typebox": "*"
+  },
+  "peerDependenciesMeta": {
+    "@earendil-works/pi-ai": {
+      "optional": true
+    },
+    "@earendil-works/pi-coding-agent": {
+      "optional": true
+    },
+    "@earendil-works/pi-tui": {
+      "optional": true
+    },
+    "typebox": {
+      "optional": true
+    }
+  }
+}

package/skills/kernel-plot/SKILL.md

@@ -0,0 +1,93 @@
+---
+name: kernel-plot
+description: Use Pi kernel plotting tools for iterative R/Python data visualization, saving artifacts from warm kernel sessions under WARMPLOT_OUTPUT_DIR.
+---
+
+# Kernel Plot
+
+Use this skill when the user wants iterative R or Python plotting, especially when data should stay loaded across turns.
+
+## Tool Choice
+
+- Use `kernel_plot_configure` to manage Python/R environments (list, select, scan, add, edit, delete kernels).
+- Use `kernel_plot_run` with the default `kernel-lite` runtime for short iterative plotting code that benefits from warm memory.
+- Use `kernel_plot_run` with `runtime: "worker"` for one-shot scripts that should run from a clean process.
+- Use `kernel_plot_artifacts` to list recent outputs from the current Pi session.
+- Use `kernel_plot_stop` when the user is done with large objects or asks to free memory.
+
+## Kernel Configuration
+
+Before running code, you can configure which Python/R environment to use:
+
+```
+# List available kernels
+kernel_plot_configure({ action: "list" })
+
+# Scan for new environments (conda, virtualenv, pyenv, etc.)
+kernel_plot_configure({ action: "scan" })
+
+# Select a kernel for this project
+kernel_plot_configure({ action: "select", language: "python", kernelId: "conda-bio" })
+
+# Add a custom kernel
+kernel_plot_configure({
+  action: "add",
+  kernelId: "my-venv",
+  config: {
+    command: "/path/to/venv/bin/python",
+    displayName: "My Project Venv"
+  }
+})
+```
+
+The selected kernel persists for the current project in `.pi/warmplot.json`. Global kernel configurations are stored in `~/.config/warmplot.json`.
+
+**Kernel Selection Priority:**
+1. Project configuration (`.pi/warmplot.json`)
+2. Global default (`~/.config/warmplot.json`)
+3. System PATH (`python3` or `R`)
+
+## Runtime Rules
+
+- Always save outputs under `WARMPLOT_OUTPUT_DIR`.
+- Treat `PI_KERNEL_PLOT_OUTPUT_DIR` and `OPENANNO_PLOT_OUTPUT_DIR` as compatibility aliases if present.
+- Do not rely on notebook display hooks. Save figures or tables explicitly.
+- Prefer deterministic names such as `umap_by_cluster.png`, `markers_heatmap.pdf`, or `cluster_counts.csv`.
+- Print concise summaries only. Write large tables to CSV, TSV, JSON, or parquet-like outputs supported by the environment.
+
+## Python Patterns
+
+```python
+import os
+from pathlib import Path
+
+out = Path(os.environ["WARMPLOT_OUTPUT_DIR"])
+out.mkdir(parents=True, exist_ok=True)
+
+# matplotlib
+fig = ax.get_figure()
+fig.savefig(out / "plot.png", dpi=300, bbox_inches="tight")
+
+# plotly
+fig.write_html(out / "plot.html", include_plotlyjs="cdn")
+```
+
+For Scanpy workflows, keep the main object name stable, usually `adata`, so later calls can reuse it.
+
+## R Patterns
+
+```r
+out <- Sys.getenv("WARMPLOT_OUTPUT_DIR")
+dir.create(out, recursive = TRUE, showWarnings = FALSE)
+
+ggsave(file.path(out, "plot.png"), p, width = 7, height = 5, dpi = 300)
+write.csv(markers, file.path(out, "markers.csv"), row.names = FALSE)
+```
+
+For Seurat workflows, keep the main object name stable, usually `obj`, so later calls can reuse it.
+
+## Failure Handling
+
+- If a run fails, inspect stderr first.
+- Rerun only the minimal corrected code unless the user asks for a full rerun.
+- If warm state is likely corrupted, call `kernel_plot_stop` for the affected language and rerun setup code.