@oqtopus-team/pi-qdash 0.1.3 → 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 {
@@ -393,6 +407,58 @@ type TaskResultFigureFile = DownloadedFile & {
   jsonFigurePaths: string[];
 };
 
+type CalibrationEvidence = {
+  id?: string;
+  source: string;
+  target?: Record<string, unknown>;
+  task?: Record<string, unknown>;
+  metrics?: Record<string, number | string | boolean | null>;
+  parameters?: Record<string, number | string | boolean | null>;
+  resultJson?: unknown;
+  figures?: Array<Record<string, unknown>>;
+  logs?: string[];
+  notes?: string;
+  history?: Array<Record<string, unknown>>;
+};
+
+function parameterValueRecord(value: unknown): Record<string, number | string | boolean | null> {
+  const output: Record<string, number | string | boolean | null> = {};
+  const input = value && typeof value === "object" ? value as Record<string, unknown> : {};
+  for (const [key, raw] of Object.entries(input)) {
+    const object = raw && typeof raw === "object" ? raw as Record<string, unknown> : undefined;
+    const candidate = object && "value" in object ? object.value : raw;
+    if (typeof candidate === "number" || typeof candidate === "string" || typeof candidate === "boolean" || candidate === null) output[key] = candidate;
+  }
+  return output;
+}
+
+function firstStringField(object: Record<string, unknown>, keys: string[]): string | undefined {
+  for (const key of keys) {
+    const value = object[key];
+    if (typeof value === "string" && value) return value;
+  }
+  return undefined;
+}
+
+function qcalEvidenceText(evidence: CalibrationEvidence): string {
+  const metrics = Object.entries(evidence.metrics ?? {}).slice(0, 8).map(([key, value]) => `  - ${key}: ${String(value)}`);
+  const figures = evidence.figures ?? [];
+  return boxed("QDash QCal Evidence", [
+    `id ${evidence.id ?? "n/a"}`,
+    `source ${evidence.source}`,
+    `target ${evidence.target?.id ?? evidence.target?.couplingId ?? evidence.target?.qids ?? "n/a"}`,
+    `task ${evidence.task?.name ?? "n/a"} (${evidence.task?.status ?? "unknown"})`,
+    "",
+    "Metrics",
+    ...(metrics.length ? metrics : ["  - none"]),
+    "",
+    `Figures ${figures.length}`,
+    ...figures.map((figure, index) => `  - #${index + 1} ${String(figure.role ?? "plot")} ${String(figure.path ?? figure.url ?? "")}`),
+    "",
+    "Use qcal_evaluate_bundle with details.evidence to evaluate this evidence with pi-qcal.",
+  ]).join("\n");
+}
+
 function cleanQuery(values: Record<string, unknown> = {}): Record<string, unknown> {
   return Object.fromEntries(Object.entries(values).filter(([, value]) => value !== undefined && value !== null));
 }
@@ -1288,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>>,
@@ -1676,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",
@@ -2187,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",
@@ -2462,6 +2643,105 @@ export default function qdashExtension(pi: ExtensionAPI) {
     },
   });
 
+  pi.registerTool({
+    name: "qdash_build_qcal_evidence",
+    label: "QDash Build QCal Evidence",
+    description: "Build a provider-neutral CalibrationEvidence bundle from a QDash task result for evaluation by pi-qcal.",
+    promptSnippet: "Convert QDash calibration task results into pi-qcal CalibrationEvidence",
+    promptGuidelines: [
+      "Use qdash_build_qcal_evidence before qcal_evaluate_bundle when the user asks to evaluate QDash calibration data with pi-qcal.",
+      "qdash_build_qcal_evidence is read-only and only converts QDash data into a generic evidence bundle; it does not evaluate, execute, commit, or apply calibration parameters.",
+      "After qdash_build_qcal_evidence, pass details.evidence to qcal_evaluate_bundle and treat the result as advisory evidence.",
+    ],
+    parameters: Type.Object({
+      ...connectionParams,
+      taskId: Type.String(),
+      includeFigures: Type.Optional(Type.Boolean({ description: "Embed task image figures as data URLs. Defaults to true." })),
+      includeFigureAnalysis: Type.Optional(Type.Boolean({ description: "Analyze Plotly JSON figures and include summaries/warnings in notes. Defaults to true." })),
+      maxFigures: Type.Optional(Type.Number({ description: "Maximum image figures to embed. Defaults to 1." })),
+      includeRawTaskResult: Type.Optional(Type.Boolean({ description: "Include the full raw task result in resultJson. Defaults to false." })),
+    }),
+    async execute(_toolCallId, params: { profile?: string; configPath?: string; useEnv?: boolean; taskId: string; includeFigures?: boolean; includeFigureAnalysis?: boolean; maxFigures?: number; includeRawTaskResult?: boolean }) {
+      const client = await makeClient(params);
+      const task = await client.getTaskResult(params.taskId) as unknown as Record<string, unknown>;
+      const figures: Array<Record<string, unknown>> = [];
+      const notes: string[] = [];
+      const figurePaths = Array.isArray(task.figure_path) ? task.figure_path.filter((item): item is string => typeof item === "string") : [];
+      const jsonFigurePaths = Array.isArray(task.json_figure_path) ? task.json_figure_path.filter((item): item is string => typeof item === "string") : [];
+
+      if (params.includeFigureAnalysis !== false) {
+        const limit = Math.min(jsonFigurePaths.length, params.maxFigures ?? 1);
+        for (let index = 0; index < limit; index += 1) {
+          try {
+            const file: TaskResultFigureFile = await client.getTaskResultFigure(params.taskId, { index, preferJson: true });
+            const figure = JSON.parse(Buffer.from(file.data).toString("utf8")) as unknown;
+            const analysis = analyzePlotlyFigure(file.path ?? jsonFigurePaths[index] ?? "", figure, params.taskId);
+            notes.push(`Figure JSON analysis #${index + 1}:`, ...analysis.summaries.map((line) => `- ${line}`));
+            if (analysis.warnings.length) notes.push("Warnings:", ...analysis.warnings.map((line) => `- ${line}`));
+            figures.push({ path: file.path ?? jsonFigurePaths[index], role: "plotly", data: figure });
+          } catch (error) {
+            notes.push(`Figure JSON analysis #${index + 1} failed: ${error instanceof Error ? error.message : String(error)}`);
+          }
+        }
+      }
+
+      if (params.includeFigures !== false) {
+        const limit = Math.min(figurePaths.length, params.maxFigures ?? 1);
+        for (let index = 0; index < limit; index += 1) {
+          try {
+            const file: TaskResultFigureFile = await client.getTaskResultFigure(params.taskId, { index, preferJson: false });
+            const bytes = Buffer.from(file.data);
+            const mediaType = file.mediaType || mediaTypeForPath(file.path ?? figurePaths[index] ?? "");
+            if (mediaType.startsWith("image/")) {
+              figures.push({ path: file.path ?? figurePaths[index], url: `data:${mediaType};base64,${bytes.toString("base64")}`, mimeType: mediaType, role: "plot" });
+            }
+          } catch (error) {
+            notes.push(`Figure image #${index + 1} embedding failed: ${error instanceof Error ? error.message : String(error)}`);
+          }
+        }
+      }
+
+      const couplingId = firstStringField(task, ["coupling_id", "couplingId", "qid"]);
+      const qid = firstStringField(task, ["qid"]);
+      const evidence: CalibrationEvidence = {
+        id: params.taskId,
+        source: "external",
+        target: {
+          kind: couplingId && couplingId.includes("-") ? "coupling" : qid ? "qubit" : "system",
+          id: couplingId ?? qid,
+          couplingId: couplingId && couplingId.includes("-") ? couplingId : undefined,
+          qids: qid && !qid.includes("-") ? [qid] : undefined,
+          chipId: firstStringField(task, ["chip_id", "chipId"]),
+        },
+        task: {
+          name: firstStringField(task, ["task_name", "taskName", "name"]),
+          objective: `Evaluate QDash calibration task ${firstStringField(task, ["task_name", "taskName", "name"]) ?? params.taskId}`,
+          backend: firstStringField(task, ["backend", "chip_id", "chipId"]),
+          startedAt: firstStringField(task, ["start_at", "startAt"]),
+          completedAt: firstStringField(task, ["end_at", "endAt"]),
+          status: firstStringField(task, ["status"]),
+        },
+        metrics: parameterValueRecord(task.output_parameters),
+        parameters: { ...parameterValueRecord(task.input_parameters), ...parameterValueRecord(task.run_parameters) },
+        figures: figures.length ? figures : undefined,
+        notes: [
+          typeof task.message === "string" ? `Task message: ${task.message}` : undefined,
+          notes.length ? notes.join("\n") : undefined,
+        ].filter(Boolean).join("\n\n") || undefined,
+        resultJson: params.includeRawTaskResult ? task : {
+          task_id: task.task_id,
+          execution_id: task.execution_id,
+          flow_name: task.flow_name,
+          figure_path: figurePaths,
+          json_figure_path: jsonFigurePaths,
+          links: task._links,
+        },
+      };
+
+      return toTextToolResult(qcalEvidenceText(evidence), { evidence }, { tool: "qdash_build_qcal_evidence", taskId: params.taskId, evidence });
+    },
+  });
+
   registerQueryTool({
     name: "qdash_get_provenance_stats",
     label: "QDash Provenance Stats",
@@ -2916,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();
@@ -3029,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.3",
+  "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",