@oqtopus-team/pi-qdash 0.1.4 → 0.1.5

package/extensions/qdash.ts

@@ -10,13 +10,16 @@ import { Type } from "typebox";
 
 import { analyzePlotlyFigure, figureAnalysisText } from "./lib/figure-analysis.js";
 import { fetchFigureDetails, figureComponent, figureResultText, mediaTypeForPath, type FigureDetails } from "./lib/figures.js";
+import { forumImageReplyContent, forumImageReplyPreview, loadLocalForumImages, type LocalForumImage } from "./lib/forum-images.js";
 import { forumDetailComponent, forumDetailLines, forumListLines, forumPostTitle, forumPostsFromPayload } from "./lib/forum-render.js";
+import { investigationContextSummary, validateInvestigationContext, type TimeseriesInvestigationContext } from "./lib/investigation-context.js";
 import { qdashObjectLinks, qdashWebBaseUrl, qdashWebUrl, safeConfig, withQDashLinks } from "./lib/links.js";
 import { arrayFromPayload, compactItems, firstNumber, firstString, formatItem, payloadTotal, statusIcon } from "./lib/payload.js";
 import { toTextToolResult, toToolResult } from "./lib/results.js";
 import { ansi, boxLinesToWidth, boxed, formatNumber, textComponent } from "./lib/render.js";
 import { plotSeriesLines, timeseriesPlotComponent, timeseriesPoints } from "./lib/timeseries-plot.js";
 import { installQDashWriteGate } from "./lib/write-gate.js";
+import { registerTimeseriesComparisonTool } from "./tools/timeseries.js";
 import { analyzeWiringMarkdown, wiringInsightLines, type WiringInsights } from "./lib/wiring-analysis.js";
 
 type QDashQueryParams = {
@@ -131,6 +134,7 @@ type QDashContextState = {
   taskName?: string;
   lastExecutionId?: string;
   lastTaskId?: string;
+  investigation?: TimeseriesInvestigationContext;
 };
 
 const CONTEXT_ENTRY_TYPE = "qdash-context";
@@ -151,7 +155,8 @@ function contextSummary(): string {
   const chip = currentContext.chipId ?? "auto-chip";
   const session = currentContext.agentSessionId ? ` session:${shortId(currentContext.agentSessionId)}` : "";
   const target = currentContext.qid ? ` q${currentContext.qid}` : currentContext.couplingId ? ` c${currentContext.couplingId}` : "";
-  return `qdash ${profile} ${chip}${target}${session}`;
+  const investigation = currentContext.investigation?.name ? ` investigation:${currentContext.investigation.name}` : "";
+  return `qdash ${profile} ${chip}${target}${session}${investigation}`;
 }
 
 function contextStatusLine(theme?: Theme): string {
@@ -179,8 +184,16 @@ function contextStatusLine(theme?: Theme): string {
 function isQDashContextState(value: unknown): value is QDashContextState {
   if (!value || typeof value !== "object") return false;
   const context = value as QDashContextState;
-  return [context.profile, context.chipId, context.agentSessionId, context.qid, context.couplingId, context.taskName, context.lastExecutionId, context.lastTaskId]
+  const stringsValid = [context.profile, context.chipId, context.agentSessionId, context.qid, context.couplingId, context.taskName, context.lastExecutionId, context.lastTaskId]
     .every((item) => item === undefined || typeof item === "string");
+  if (!stringsValid) return false;
+  if (context.investigation === undefined) return true;
+  try {
+    validateInvestigationContext(context.investigation);
+    return true;
+  } catch {
+    return false;
+  }
 }
 
 function loadGlobalContext(): QDashContextState {
@@ -194,8 +207,9 @@ function loadGlobalContext(): QDashContextState {
 }
 
 function saveGlobalContext(context: QDashContextState): void {
+  const { investigation: _investigation, ...globalContext } = context;
   mkdirSync(dirname(GLOBAL_CONTEXT_PATH), { recursive: true });
-  writeFileSync(GLOBAL_CONTEXT_PATH, `${JSON.stringify(context, null, 2)}\n`, "utf8");
+  writeFileSync(GLOBAL_CONTEXT_PATH, `${JSON.stringify(globalContext, null, 2)}\n`, "utf8");
 }
 
 function adoptContextFromToolInput(input: unknown): boolean {
@@ -1340,6 +1354,56 @@ function taskFigurePaths(task: Record<string, unknown>, maxFigures: number): str
   return Array.isArray(paths) ? paths.filter((item): item is string => typeof item === "string").slice(0, maxFigures) : [];
 }
 
+type ForumImageReplyParams = {
+  parentPostId: string;
+  imagePaths: string[];
+  interpretation: string;
+  title?: string;
+};
+
+type PreparedForumImageReply = {
+  parent: Record<string, unknown>;
+  images: LocalForumImage[];
+  title: string;
+  preview: string;
+};
+
+async function prepareForumImageReply(client: QDashClient, params: ForumImageReplyParams): Promise<PreparedForumImageReply> {
+  const parent = await client.getForumPost(params.parentPostId) as unknown as Record<string, unknown>;
+  const images = loadLocalForumImages(params.imagePaths);
+  const title = params.title ?? `${new Date().toISOString().slice(0, 10)} 追加分析画像`;
+  const preview = forumImageReplyPreview(title, images, params.interpretation);
+  return { parent, images, title, preview };
+}
+
+async function createForumImageReply(client: QDashClient, params: ForumImageReplyParams, prepared: PreparedForumImageReply) {
+  const uploaded = [];
+  for (const image of prepared.images) {
+    const result = await client.uploadForumImage(image.blob, image.filename);
+    uploaded.push({ ...image, url: result.url });
+  }
+  const content = forumImageReplyContent(prepared.title, uploaded, params.interpretation);
+  const parent = prepared.parent;
+  const request = {
+    category: firstString(parent, ["category"]) ?? "other",
+    title: null,
+    content,
+    content_blocks: [],
+    parent_id: params.parentPostId,
+    chip_id: firstString(parent, ["chip_id", "chipId"]),
+    target_type: firstString(parent, ["target_type", "targetType"]),
+    target_id: firstString(parent, ["target_id", "targetId"]),
+    cooldown_id: firstString(parent, ["cooldown_id", "cooldownId"]),
+    status: firstString(parent, ["status"]) ?? "open",
+  };
+  const reply = await client.createForumPost(request as never);
+  return {
+    reply,
+    content,
+    images: uploaded.map(({ blob: _blob, ...image }) => image),
+  };
+}
+
 async function buildForumEvidenceReply(client: QDashClient, params: ForumEvidenceReplyParams) {
   const [parent, task] = await Promise.all([
     client.getForumPost(params.parentPostId) as unknown as Promise<Record<string, unknown>>,
@@ -1728,6 +1792,12 @@ export default function qdashExtension(pi: ExtensionAPI) {
     },
   });
 
+  registerTimeseriesComparisonTool(pi, {
+    makeClient,
+    defaultChipId,
+    investigationContext: () => currentContext.investigation,
+  });
+
   registerQueryTool({
     name: "qdash_list_task_results",
     label: "QDash List Task Results",
@@ -2239,6 +2309,65 @@ export default function qdashExtension(pi: ExtensionAPI) {
     },
   });
 
+  pi.registerTool({
+    name: "qdash_preview_forum_image_reply",
+    label: "QDash Preview Forum Image Reply",
+    description: "Preview a QDash forum reply that will upload and embed locally generated analysis images. Read-only; no image or post is created.",
+    promptSnippet: "Preview local analysis images and forum reply content before uploading",
+    promptGuidelines: [
+      "Use qdash_preview_forum_image_reply before uploading locally generated analysis images to a forum thread.",
+      "Show the image paths and reply content, then require explicit confirmation before publishing.",
+    ],
+    parameters: Type.Object({
+      ...connectionParams,
+      parentPostId: Type.String(),
+      imagePaths: Type.Array(Type.String(), { minItems: 1, maxItems: 8 }),
+      interpretation: Type.String({ description: "Human-readable interpretation or context shown after the images." }),
+      title: Type.Optional(Type.String()),
+    }),
+    async execute(_toolCallId, params: { profile?: string; configPath?: string; useEnv?: boolean; parentPostId: string; imagePaths: string[]; interpretation: string; title?: string }) {
+      const client = await makeClient(params);
+      const prepared = await prepareForumImageReply(client, params);
+      return toTextToolResult(prepared.preview, {
+        preview: prepared.preview,
+        parent: prepared.parent,
+        images: prepared.images.map(({ blob: _blob, ...image }) => image),
+      }, { tool: "qdash_preview_forum_image_reply" });
+    },
+  });
+
+  pi.registerTool({
+    name: "qdash_create_forum_image_reply",
+    label: "QDash Create Forum Image Reply",
+    description: "Upload locally generated analysis images and create a QDash forum reply embedding them. This is a write operation and requires confirmation.",
+    promptSnippet: "Upload local analysis images and create a forum reply after explicit confirmation",
+    promptGuidelines: [
+      "Use qdash_create_forum_image_reply only after previewing the exact image paths and reply content with qdash_preview_forum_image_reply.",
+      "Require explicit confirmation before uploading images or creating the reply.",
+    ],
+    parameters: Type.Object({
+      ...connectionParams,
+      parentPostId: Type.String(),
+      imagePaths: Type.Array(Type.String(), { minItems: 1, maxItems: 8 }),
+      interpretation: Type.String({ description: "Human-readable interpretation or context shown after the images." }),
+      title: Type.Optional(Type.String()),
+      confirmWrite: Type.Optional(Type.Boolean()),
+    }),
+    async execute(_toolCallId, params: ConfirmableParams & { profile?: string; configPath?: string; useEnv?: boolean; parentPostId: string; imagePaths: string[]; interpretation: string; title?: string }, _signal, _onUpdate, ctx) {
+      const client = await makeClient(params);
+      const prepared = await prepareForumImageReply(client, params);
+      if (!params.confirmWrite) {
+        const confirmed = ctx.hasUI && await ctx.ui.confirm("Upload images and create QDash forum reply?", prepared.preview.slice(0, 1800));
+        if (!confirmed) throw new Error("qdash_create_forum_image_reply requires explicit confirmation");
+      }
+      const created = await createForumImageReply(client, params, prepared);
+      const postId = firstString(created.reply as unknown as Record<string, unknown>, ["id"]);
+      const parentUrl = qdashWebUrl(client, `/forum/posts/${encodeURIComponent(params.parentPostId)}`);
+      const text = [`created forum image reply${postId ? ` ${postId}` : ""}`, `parent ${parentUrl}`, "", created.content].join("\n");
+      return toTextToolResult(text, created, { tool: "qdash_create_forum_image_reply", url: parentUrl });
+    },
+  });
+
   pi.registerTool({
     name: "qdash_create_forum_evidence_reply",
     label: "QDash Create Forum Evidence Reply",
@@ -3067,8 +3196,49 @@ export default function qdashExtension(pi: ExtensionAPI) {
     },
   });
 
+  pi.registerCommand("qdash-investigation-setup", {
+    description: "Create or edit a reusable generic timeseries investigation context; accepts optional JSON",
+    handler: async (args, ctx) => {
+      const template: TimeseriesInvestigationContext = currentContext.investigation ?? {
+        name: "timeseries-investigation",
+        timezoneOffsetMinutes: 540,
+        qdashSeries: currentContext.qid ? [
+          { parameter: "metric_a", qid: currentContext.qid },
+          { parameter: "metric_b", qid: currentContext.qid },
+        ] : [
+          { parameter: "metric_a" },
+          { parameter: "metric_b" },
+        ],
+        analysis: { resampleMinutes: 1, detrend: "none", normalize: "none" },
+      };
+      const source = args.trim() || await ctx.ui.editor("QDash investigation context (JSON)", JSON.stringify(template, null, 2));
+      if (!source) return;
+      try {
+        const investigation = validateInvestigationContext(JSON.parse(source));
+        currentContext = { ...currentContext, investigation };
+        persistContext();
+        refreshContextUi(ctx);
+        ctx.ui.setWidget("qdash", ["QDash Investigation", investigationContextSummary(investigation)]);
+        ctx.ui.notify(`Investigation context saved: ${investigationContextSummary(investigation)}`, "info");
+      } catch (error) {
+        ctx.ui.notify(`Invalid investigation context: ${error instanceof Error ? error.message : String(error)}`, "error");
+      }
+    },
+  });
+
+  pi.registerCommand("qdash-clear-investigation", {
+    description: "Clear the reusable timeseries investigation context without changing profile/chip context",
+    handler: async (_args, ctx) => {
+      const { investigation: _investigation, ...rest } = currentContext;
+      currentContext = rest;
+      persistContext();
+      refreshContextUi(ctx);
+      ctx.ui.notify("QDash investigation context cleared", "info");
+    },
+  });
+
   pi.registerCommand("qdash-clear-context", {
-    description: "Clear the current QDash profile/chip/agent-session context",
+    description: "Clear the current QDash profile/chip/agent-session/investigation context",
     handler: async (_args, ctx) => {
       currentContext = {};
       persistContext();
@@ -3180,6 +3350,7 @@ export default function qdashExtension(pi: ExtensionAPI) {
         `last execution ${currentContext.lastExecutionId ?? "none"}`,
         `last task ${currentContext.lastTaskId ?? "none"}`,
         `agent session ${currentContext.agentSessionId ?? "none"}`,
+        `investigation ${currentContext.investigation ? investigationContextSummary(currentContext.investigation) : "none"}`,
       ]);
       ctx.ui.notify(contextSummary(), "info");
     },

package/extensions/tools/timeseries.ts

@@ -0,0 +1,211 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import type { QDashClient } from "@oqtopus-team/qdash-client";
+import { Type } from "typebox";
+
+import {
+  compareTimeseries,
+  csvInspectionText,
+  inspectExternalCsv,
+  loadExternalCsvSeries,
+  timeseriesComparisonText,
+  type CsvTimeFormat,
+  type ExternalCsvSpec,
+  type NumericTimeseries,
+} from "../lib/timeseries-analysis.js";
+import type { TimeseriesInvestigationContext } from "../lib/investigation-context.js";
+import { toTextToolResult } from "../lib/results.js";
+import { timeseriesPoints } from "../lib/timeseries-plot.js";
+
+type ComparisonToolParams = {
+  profile?: string;
+  configPath?: string;
+  useEnv?: boolean;
+  chipId?: string;
+  startAt?: string;
+  endAt?: string;
+  withinHours?: number;
+  qdashSeries?: Array<{ parameter: string; qid?: string; tag?: string; label?: string; unit?: string; scale?: number; offset?: number }>;
+  csvSeries?: Array<ExternalCsvSpec & { timeFormat?: CsvTimeFormat }>;
+  resampleMinutes?: number;
+  smoothingWindowMinutes?: number;
+  detrend?: string;
+  normalize?: string;
+  maxInterpolationGapMinutes?: number;
+  periodSearch?: { minMinutes: number; maxMinutes: number; stepMinutes?: number };
+  includeAlignedData?: boolean;
+  useInvestigationContext?: boolean;
+};
+
+export type TimeseriesToolDependencies = {
+  makeClient: (params: { profile?: string; configPath?: string; useEnv?: boolean }) => Promise<QDashClient>;
+  defaultChipId: (client: QDashClient, chipId?: string) => Promise<string>;
+  investigationContext?: () => TimeseriesInvestigationContext | undefined;
+};
+
+export function registerTimeseriesComparisonTool(pi: ExtensionAPI, dependencies: TimeseriesToolDependencies): void {
+  pi.registerTool({
+    name: "qdash_inspect_timeseries_csv",
+    label: "QDash Inspect Timeseries CSV",
+    description: "Inspect a local CSV schema and numeric/time characteristics before mapping it into a QDash timeseries comparison. Read-only; never uploads the file.",
+    promptSnippet: "Inspect local CSV columns, numeric ranges, timestamps, and cadence before comparison",
+    promptGuidelines: [
+      "Use qdash_inspect_timeseries_csv before qdash_compare_timeseries when a local CSV schema, timestamp format, timezone, or numeric columns are not already known.",
+      "Do not infer the timezone of naive timestamps from qdash_inspect_timeseries_csv samples; ask for or supply an explicit timezone offset.",
+    ],
+    parameters: Type.Object({
+      path: Type.String({ description: "Local CSV path, absolute or relative to the current working directory." }),
+      delimiter: Type.Optional(Type.String({ description: "Single-character delimiter. Defaults to comma." })),
+      skipRows: Type.Optional(Type.Number({ description: "Rows before the header. Defaults to 0." })),
+      timeColumn: Type.Optional(Type.String({ description: "Optional timestamp column to validate." })),
+      timeFormat: Type.Optional(Type.String({ description: "iso, yyyy/M/d H:mm, yyyy-MM-dd HH:mm:ss, unix-seconds, or unix-milliseconds." })),
+      timezoneOffsetMinutes: Type.Optional(Type.Number({ description: "Required to validate timestamps without an explicit zone; JST is 540." })),
+      scanRows: Type.Optional(Type.Number({ description: "Rows to profile, from 1 to 100000. Defaults to 10000." })),
+    }),
+    async execute(_toolCallId, params: {
+      path: string;
+      delimiter?: string;
+      skipRows?: number;
+      timeColumn?: string;
+      timeFormat?: CsvTimeFormat;
+      timezoneOffsetMinutes?: number;
+      scanRows?: number;
+    }, _signal, _onUpdate, ctx) {
+      const inspection = inspectExternalCsv(params, ctx.cwd);
+      return toTextToolResult(csvInspectionText(inspection), inspection, {
+        tool: "qdash_inspect_timeseries_csv",
+        path: inspection.path,
+      });
+    },
+  });
+
+  pi.registerTool({
+    name: "qdash_compare_timeseries",
+    label: "QDash Compare Timeseries",
+    description: "Compare two or more QDash and/or local CSV numeric timeseries on a common time grid. Read-only; reports alignment, correlations, optional shared-period fits, phases, and statistical caveats without inferring causality.",
+    promptSnippet: "Compare generic QDash metrics and external CSV sensor timeseries",
+    promptGuidelines: [
+      "Use qdash_compare_timeseries when comparing multiple QDash metrics, targets, or local CSV sensor logs over time.",
+      "For qdash_compare_timeseries local CSV inputs, explicitly specify timestamp format and timezone offset when timestamps have no zone.",
+      "Treat qdash_compare_timeseries correlations and shared periods as evidence of association, not proof of causality.",
+    ],
+    parameters: Type.Object({
+      profile: Type.Optional(Type.String({ description: "QDash profile name. Defaults to env when QDASH_BASE_URL is set, otherwise 'default'." })),
+      configPath: Type.Optional(Type.String({ description: "Optional path to qdash config.ini." })),
+      useEnv: Type.Optional(Type.Boolean({ description: "Force QDASH_* environment variables instead of a profile." })),
+      chipId: Type.Optional(Type.String({ description: "Chip ID. Defaults to the active/default chip when omitted." })),
+      startAt: Type.Optional(Type.String({ description: "Optional common start timestamp as an ISO timestamp with timezone." })),
+      endAt: Type.Optional(Type.String({ description: "Optional common end timestamp as an ISO timestamp with timezone." })),
+      withinHours: Type.Optional(Type.Number({ description: "QDash lookback when startAt is omitted. Defaults to 168 hours." })),
+      useInvestigationContext: Type.Optional(Type.Boolean({ description: "Use missing series/window/transform defaults from the active investigation context. Defaults to true." })),
+      qdashSeries: Type.Optional(Type.Array(Type.Object({
+        parameter: Type.String({ description: "QDash task-result parameter name." }),
+        qid: Type.Optional(Type.String()),
+        tag: Type.Optional(Type.String()),
+        label: Type.Optional(Type.String({ description: "Unique display label. Defaults to parameter plus qid/returned series." })),
+        unit: Type.Optional(Type.String({ description: "Optional output unit override." })),
+        scale: Type.Optional(Type.Number({ description: "Multiply QDash values by this factor. Defaults to 1." })),
+        offset: Type.Optional(Type.Number({ description: "Add this value after scaling. Defaults to 0." })),
+      }), { maxItems: 12 })),
+      csvSeries: Type.Optional(Type.Array(Type.Object({
+        path: Type.String({ description: "Local CSV path, absolute or relative to the current working directory." }),
+        timeColumn: Type.String(),
+        valueColumns: Type.Array(Type.Object({
+          column: Type.String(),
+          label: Type.Optional(Type.String()),
+          unit: Type.Optional(Type.String()),
+          scale: Type.Optional(Type.Number()),
+          offset: Type.Optional(Type.Number()),
+        }), { minItems: 1, maxItems: 12 }),
+        timeFormat: Type.Optional(Type.String({ description: "iso, yyyy/M/d H:mm, yyyy-MM-dd HH:mm:ss, unix-seconds, or unix-milliseconds. Defaults to iso." })),
+        timezoneOffsetMinutes: Type.Optional(Type.Number({ description: "Required for timestamps without an explicit zone; for JST use 540." })),
+        delimiter: Type.Optional(Type.String({ description: "Single-character delimiter. Defaults to comma." })),
+        skipRows: Type.Optional(Type.Number({ description: "Rows to skip before the header. Defaults to 0." })),
+        filters: Type.Optional(Type.Record(Type.String(), Type.Array(Type.String()), { description: "Optional exact-match row filters keyed by column name." })),
+      }), { maxItems: 8 })),
+      resampleMinutes: Type.Optional(Type.Number({ description: "Common grid interval. Defaults to 1 minute." })),
+      smoothingWindowMinutes: Type.Optional(Type.Number({ description: "Centered moving-average window. Zero disables smoothing." })),
+      detrend: Type.Optional(Type.String({ description: "none or linear. Defaults to none." })),
+      normalize: Type.Optional(Type.String({ description: "none or zscore. Defaults to none." })),
+      maxInterpolationGapMinutes: Type.Optional(Type.Number({ description: "Do not interpolate across larger source gaps." })),
+      periodSearch: Type.Optional(Type.Object({
+        minMinutes: Type.Number(),
+        maxMinutes: Type.Number(),
+        stepMinutes: Type.Optional(Type.Number()),
+      })),
+      includeAlignedData: Type.Optional(Type.Boolean({ description: "Include transformed aligned rows in structured details. Defaults to false." })),
+    }),
+    async execute(_toolCallId, params: ComparisonToolParams, _signal, _onUpdate, ctx) {
+      const investigation = params.useInvestigationContext === false ? undefined : dependencies.investigationContext?.();
+      const analysis = investigation?.analysis;
+      const detrend = params.detrend ?? analysis?.detrend ?? "none";
+      const normalize = params.normalize ?? analysis?.normalize ?? "none";
+      if (detrend !== "none" && detrend !== "linear") throw new Error("detrend must be 'none' or 'linear'");
+      if (normalize !== "none" && normalize !== "zscore") throw new Error("normalize must be 'none' or 'zscore'");
+      const csvSpecs = (params.csvSeries ?? investigation?.csvSeries ?? []).map((spec) => ({
+        ...spec,
+        timezoneOffsetMinutes: spec.timezoneOffsetMinutes ?? investigation?.timezoneOffsetMinutes,
+      }));
+      const qdashSpecs = (params.qdashSeries ?? investigation?.qdashSeries ?? []).map((spec) => ({
+        ...spec,
+        tag: spec.tag ?? investigation?.tag,
+      }));
+      const csv = csvSpecs.flatMap((spec) => loadExternalCsvSeries(spec, ctx.cwd));
+      const qdash: NumericTimeseries[] = [];
+      let resolvedStartAt = params.startAt ?? investigation?.startAt;
+      let resolvedEndAt = params.endAt ?? investigation?.endAt;
+      if (qdashSpecs.length > 0) {
+        resolvedEndAt = resolvedEndAt ?? new Date().toISOString();
+        resolvedStartAt = resolvedStartAt ?? new Date(Date.parse(resolvedEndAt) - (params.withinHours ?? 168) * 3_600_000).toISOString();
+        const client = await dependencies.makeClient(params);
+        const chipId = await dependencies.defaultChipId(client, params.chipId);
+        const fetched = await Promise.all(qdashSpecs.map(async (spec) => {
+          const data = await client.getTaskResultsTimeseries({
+            chipId,
+            parameter: spec.parameter,
+            qid: spec.qid,
+            tag: spec.tag,
+            startAt: resolvedStartAt!,
+            endAt: resolvedEndAt!,
+          });
+          return { spec, points: timeseriesPoints(data) };
+        }));
+        for (const { spec, points } of fetched) {
+          const groups = new Map<string, typeof points>();
+          for (const point of points) {
+            if (!point.at) continue;
+            const group = spec.qid ?? point.series;
+            groups.set(group, [...(groups.get(group) ?? []), point]);
+          }
+          for (const [group, values] of groups) {
+            const suffix = spec.qid ? ` q${spec.qid}` : groups.size > 1 ? ` ${group}` : "";
+            qdash.push({
+              label: spec.label ? groups.size > 1 ? `${spec.label} ${group}` : spec.label : `${spec.parameter}${suffix}`,
+              unit: spec.unit ?? values.find((point) => point.unit)?.unit,
+              source: "qdash",
+              points: values.map((point) => ({
+                at: point.at!,
+                value: point.value * (spec.scale ?? 1) + (spec.offset ?? 0),
+              })),
+            });
+          }
+        }
+      }
+      const comparison = compareTimeseries([...qdash, ...csv], {
+        startAt: resolvedStartAt,
+        endAt: resolvedEndAt,
+        resampleMinutes: params.resampleMinutes ?? analysis?.resampleMinutes,
+        smoothingWindowMinutes: params.smoothingWindowMinutes ?? analysis?.smoothingWindowMinutes,
+        detrend,
+        normalize,
+        maxInterpolationGapMinutes: params.maxInterpolationGapMinutes ?? analysis?.maxInterpolationGapMinutes,
+        periodSearch: params.periodSearch ?? analysis?.periodSearch,
+        includeAlignedData: params.includeAlignedData,
+      });
+      return toTextToolResult(timeseriesComparisonText(comparison), comparison, {
+        tool: "qdash_compare_timeseries",
+        seriesCount: comparison.series.length,
+        investigation: investigation?.name,
+      });
+    },
+  });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oqtopus-team/pi-qdash",
-  "version": "0.1.4",
+  "version": "0.1.5",
   "description": "Pi extension for querying QDash via @oqtopus-team/qdash-client",
   "type": "module",
   "license": "Apache-2.0",
@@ -24,7 +24,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@oqtopus-team/qdash-client": "^0.1.3"
+    "@oqtopus-team/qdash-client": "^0.1.4"
   },
   "peerDependencies": {
     "@earendil-works/pi-coding-agent": "*",
@@ -39,7 +39,8 @@
     ]
   },
   "scripts": {
-    "check": "tsc --noEmit"
+    "check": "tsc --noEmit",
+    "test": "rm -rf .test-dist && tsc --noEmit false --outDir .test-dist && node --test tests/*.test.mjs; status=$?; rm -rf .test-dist; exit $status"
   },
   "devDependencies": {
     "@earendil-works/pi-coding-agent": "^0.74.0",

package/skills/qdash/SKILL.md

@@ -15,7 +15,7 @@ Use the pi-qdash tools instead of scraping the UI or hand-writing auth headers.
    - `qdash_get_chip_metrics`, `qdash_list_chip_qubits`, `qdash_list_chip_couplings`
    - `qdash_list_cryostats`, `qdash_list_cooldowns`
    - `qdash_get_cooldown_wiring`, `qdash_wiring_insights`, `qdash_list_cooldown_wiring_events`
-   - `qdash_get_timeseries`, `qdash_plot_timeseries`
+   - `qdash_get_timeseries`, `qdash_plot_timeseries`, `qdash_inspect_timeseries_csv`, `qdash_compare_timeseries`
    - `qdash_list_task_results`, `qdash_get_task_result`
    - `qdash_list_issues`
    - `qdash_list_flows`, `qdash_get_flow`
@@ -24,6 +24,7 @@ Use the pi-qdash tools instead of scraping the UI or hand-writing auth headers.
    - `qdash_list_forum_posts`, `qdash_get_forum_post`, `qdash_list_forum_replies`
    - `qdash_get_figure`, `qdash_get_task_figures`, `qdash_recent_calibration_figure`, `qdash_analyze_figure_json`, `qdash_build_qcal_evidence`
    - `qdash_create_forum_evidence_reply` for confirmed evidence curation replies with visible task figures
+   - `qdash_preview_forum_image_reply`, then `qdash_create_forum_image_reply` for confirmed uploads of locally generated analysis images
 3. Use harness overview tools for status and triage:
    - `qdash_investigate` for natural-language requests to investigate or compare recent calibration, target history, figures, failures, issues, and Forum context
    - `qdash_compare_calibration` for read-only before/after comparison of repeated target calibration results
@@ -64,6 +65,8 @@ Use these commands to make pi behave like a QDash-specific harness with persiste
 /qdash-use-chip [chip_id]
 /qdash-use-target qid <qid> | coupling <coupling_id>
 /qdash-use-agent-session <session_id>
+/qdash-investigation-setup [json]
+/qdash-clear-investigation
 /qdash-context
 /qdash-dashboard [limit]
 /qdash-wiring-insights
@@ -73,6 +76,29 @@ Use these commands to make pi behave like a QDash-specific harness with persiste
 
 Prefer the current context when the user has already selected a profile/chip/session. Tools use that context when parameters are omitted.
 
+## Generic timeseries comparison
+
+Use `qdash_compare_timeseries` when the investigation needs to align multiple
+QDash metrics/targets, local CSV sensor logs, or both. For repeated calls, use
+`/qdash-investigation-setup` to store the arbitrary series mappings, window,
+timezone, and transform defaults; explicit tool arguments override the preset.
+Do not assume a specific
+CSV layout, metric name, target, unit, timestamp format, or timezone:
+
+1. Inspect unknown CSV headers, numeric coverage, and optional time cadence with
+   `qdash_inspect_timeseries_csv` first.
+2. Supply `timeColumn`, one or more `valueColumns`, and optional exact-match
+   `filters`; use `scale`/`offset` only for explicit unit conversion.
+3. For timestamps without a zone, require an explicit
+   `timezoneOffsetMinutes` (JST is `540`) rather than relying on the host clock.
+4. Start with raw/no-transform comparison, then state any smoothing,
+   interpolation, detrending, normalization, and period-search settings.
+5. Report overlap duration, source point counts, aligned point count, number of
+   observed cycles, correlations, phases, and explained fractions together.
+6. Treat correlation and shared periodicity as evidence of association. Do not
+   claim direct causality without intervention, longer observation, or evidence
+   that excludes a common driver.
+
 For cryostat wiring requests, start with `qdash_get_cooldown_wiring`. Pass `cooldownId` when the user names one; otherwise pass `cryoId`, or omit both to resolve the active/newest cooldown from the current/default chip. Prefer the compact `wiring.markdown`; request raw blocks only when structural or embedded BlockNote data is necessary, and request history when investigating wiring changes. Set `includeInsights` or call `qdash_wiring_insights` when the user asks what is characteristic, unusual, or worth checking in attenuation; summarize control/readout totals and affected qubits/MUXes instead of dumping the raw table.
 
 ## Configuration
@@ -94,10 +120,11 @@ When the user wants to preserve an investigated observation in QDash forum/notes
 2. Summarize the observation as evidence, not as an automatic calibration decision.
 3. Prefer replying to an existing target/coupling forum thread when one exists.
 4. Use `qdash_create_forum_evidence_reply` for task-result evidence so figures are embedded as QDash UI image blocks (`/api/executions/figure?path=...`) and visible in the forum.
-5. Include task and execution QDash Web URLs in the reply.
-6. When mentioning history or trends, include links to representative historical task results.
-7. Mark agent-authored evidence with a footer such as `— 🤖 by pi-qdash`.
-8. Ask for confirmation before creating/updating the forum post.
+5. For locally generated analysis images, call `qdash_preview_forum_image_reply` first, show the exact paths and reply text, then use `qdash_create_forum_image_reply` only after explicit confirmation. Supported images are PNG, JPEG, GIF, and WebP up to 5 MB each.
+6. Include task and execution QDash Web URLs in the reply when applicable.
+7. When mentioning history or trends, include links to representative historical task results.
+8. Mark agent-authored evidence with a footer such as `— 🤖 by pi-qdash`.
+9. Ask for confirmation before uploading images or creating/updating the forum post.
 
 ## Safety