@oqtopus-team/pi-qdash 0.1.11-beta.21 → 0.1.11-beta.22

package/extensions/lib/abort.ts

@@ -0,0 +1,26 @@
+/**
+ * Stop waiting when the host cancels the call.
+ *
+ * The client's polling helpers (`waitForExecution` and friends) run until the
+ * execution finishes or their own timeout passes; they take no signal. A tool
+ * that awaits one directly keeps a cancelled turn alive until then: the host
+ * cannot end the turn, and the chat refuses the next message because the
+ * conversation is still busy. This races the wait against the signal, so the
+ * call returns as cancelled at once; the poll it leaves behind only reads.
+ */
+export class WaitCancelled extends Error {
+  override readonly name = "AbortError";
+  constructor(what: string) {
+    super(`${what} was cancelled before it finished; the execution itself keeps running in QDash.`);
+  }
+}
+
+export function withAbort<T>(promise: Promise<T>, signal: AbortSignal | undefined, what: string): Promise<T> {
+  if (!signal) return promise;
+  if (signal.aborted) return Promise.reject(new WaitCancelled(what));
+  return new Promise<T>((resolve, reject) => {
+    const onAbort = () => reject(new WaitCancelled(what));
+    signal.addEventListener("abort", onAbort, { once: true });
+    promise.then(resolve, reject).finally(() => signal.removeEventListener("abort", onAbort));
+  });
+}

package/extensions/lib/write-gate.ts

@@ -12,6 +12,8 @@ const WRITE_TOOL_NAMES = new Set([
   "qdash_create_forum_evidence_reply",
   "qdash_create_forum_image_reply",
   "qdash_run_pipeline",
+  "qdash_save_flow",
+  "qdash_execute_flow",
 ]);
 
 export function installQDashWriteGate(pi: ExtensionAPI): void {

package/extensions/qdash.ts

@@ -25,8 +25,10 @@ import { toFigureToolResult, toTextToolResult, toToolResult } from "./lib/result
 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 { withAbort } from "./lib/abort.js";
 import { qcalContextText, recordedParameters, sweepsOf, type RecordedParameter, type Sweep } from "./lib/qcal-evidence.js";
 import { registerCalibrationPipelineTools } from "./tools/calibration-pipeline.js";
+import { registerFlowAuthoringTools } from "./tools/flow-authoring.js";
 import { registerTaskKnowledgeTool } from "./tools/task-knowledge.js";
 import { registerTimeseriesComparisonTool } from "./tools/timeseries.js";
 import { analyzeWiringMarkdown, wiringInsightLines, type WiringInsights } from "./lib/wiring-analysis.js";
@@ -1484,6 +1486,11 @@ export default function qdashExtension(pi: ExtensionAPI) {
     makeClient,
     resolveChipId: (client, chipId) => defaultChipId(client as QDashClient, chipId),
   });
+  registerFlowAuthoringTools(pi, {
+    makeClient,
+    resolveChipId: (client, chipId) => defaultChipId(client as QDashClient, chipId),
+    flowPageUrl: (client, name) => qdashWebUrl(client as QDashClient, `/workflow/${encodeURIComponent(name)}`),
+  });
 
   pi.registerTool({
     name: "qdash_config_info",
@@ -1827,9 +1834,13 @@ export default function qdashExtension(pi: ExtensionAPI) {
       timeoutSeconds: Type.Optional(Type.Number()),
       pollIntervalSeconds: Type.Optional(Type.Number()),
     }),
-    async execute(_toolCallId, params: { profile?: string; configPath?: string; useEnv?: boolean; executionId: string; timeoutSeconds?: number; pollIntervalSeconds?: number }) {
+    async execute(_toolCallId, params: { profile?: string; configPath?: string; useEnv?: boolean; executionId: string; timeoutSeconds?: number; pollIntervalSeconds?: number }, signal) {
       const client = await makeClient(params);
-      const data = await client.waitForExecution(params.executionId, { timeoutSeconds: params.timeoutSeconds, pollIntervalSeconds: params.pollIntervalSeconds });
+      const data = await withAbort(
+        client.waitForExecution(params.executionId, { timeoutSeconds: params.timeoutSeconds, pollIntervalSeconds: params.pollIntervalSeconds }),
+        signal,
+        `Waiting for execution ${params.executionId}`,
+      );
       return toToolResult(withQDashLinks(client, data), { tool: "qdash_wait_execution", executionId: params.executionId, webBaseUrl: qdashWebBaseUrl(client) });
     },
   });
@@ -2036,12 +2047,16 @@ export default function qdashExtension(pi: ExtensionAPI) {
       timeoutSeconds: Type.Optional(Type.Number()),
       pollIntervalSeconds: Type.Optional(Type.Number()),
     }),
-    async execute(_toolCallId, params: { profile?: string; configPath?: string; useEnv?: boolean; sessionId: string; actionId: string; waitForExecution?: boolean; timeoutSeconds?: number; pollIntervalSeconds?: number }) {
+    async execute(_toolCallId, params: { profile?: string; configPath?: string; useEnv?: boolean; sessionId: string; actionId: string; waitForExecution?: boolean; timeoutSeconds?: number; pollIntervalSeconds?: number }, signal) {
       const client = await makeClient(params);
       const options = { timeoutSeconds: params.timeoutSeconds, pollIntervalSeconds: params.pollIntervalSeconds };
-      const data = params.waitForExecution
-        ? await client.waitForAgentActionExecution(params.sessionId, params.actionId, options)
-        : await client.waitForAgentAction(params.sessionId, params.actionId, options);
+      const data = await withAbort(
+        params.waitForExecution
+          ? client.waitForAgentActionExecution(params.sessionId, params.actionId, options)
+          : client.waitForAgentAction(params.sessionId, params.actionId, options),
+        signal,
+        `Waiting for agent action ${params.actionId}`,
+      );
       return toToolResult(data, { tool: "qdash_wait_agent_action" });
     },
   });
@@ -2440,9 +2455,16 @@ export default function qdashExtension(pi: ExtensionAPI) {
     promptSnippet: "Poll QDash until a candidate apply operation finishes",
     promptGuidelines: ["Use qdash_wait_agent_candidate_apply after applying a candidate commit when the user wants polling."],
     parameters: Type.Object({ ...connectionParams, sessionId: Type.String(), commitId: Type.String(), timeoutSeconds: Type.Optional(Type.Number()), pollIntervalSeconds: Type.Optional(Type.Number()) }),
-    async execute(_toolCallId, params: { profile?: string; configPath?: string; useEnv?: boolean; sessionId: string; commitId: string; timeoutSeconds?: number; pollIntervalSeconds?: number }) {
+    async execute(_toolCallId, params: { profile?: string; configPath?: string; useEnv?: boolean; sessionId: string; commitId: string; timeoutSeconds?: number; pollIntervalSeconds?: number }, signal) {
       const client = await makeClient(params);
-      return toToolResult(await client.waitForAgentCandidateApply(params.sessionId, params.commitId, { timeoutSeconds: params.timeoutSeconds, pollIntervalSeconds: params.pollIntervalSeconds }), { tool: "qdash_wait_agent_candidate_apply" });
+      return toToolResult(
+        await withAbort(
+          client.waitForAgentCandidateApply(params.sessionId, params.commitId, { timeoutSeconds: params.timeoutSeconds, pollIntervalSeconds: params.pollIntervalSeconds }),
+          signal,
+          `Waiting for candidate commit ${params.commitId}`,
+        ),
+        { tool: "qdash_wait_agent_candidate_apply" },
+      );
     },
   });
 

package/extensions/tools/flow-authoring.ts

@@ -0,0 +1,226 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+
+import { toTextToolResult } from "../lib/results.js";
+
+/**
+ * Flow authoring: saving a Prefect flow the agent wrote.
+ *
+ * A flow is Python that runs on the QDash workflow worker with hardware and
+ * database access, so saving one is a confirmation-gated write, and running one
+ * (`qdash_execute_flow`) is another. QDash owns the
+ * real validation (`POST /flows`: the `@flow` function must exist, the file is
+ * formatted with ruff, and a Prefect deployment is registered); these checks
+ * only catch what would certainly be rejected, so the user is not asked to
+ * approve a save that cannot succeed. Templates and helpers are read through
+ * `qdash_query` (`flow_templates`, `flow_template`, `flow_helper_files`,
+ * `flow_helper_file`), existing flows through `qdash_get_flow`.
+ */
+
+type ConnectionParams = { profile?: string; configPath?: string; useEnv?: boolean };
+
+export type SaveFlowRequest = {
+  name: string;
+  description: string;
+  code: string;
+  flow_function_name: string;
+  chip_id: string;
+  default_parameters: Record<string, unknown>;
+  default_run_parameters: Record<string, unknown>;
+  tags: string[];
+};
+
+export type SaveFlowResult = { name: string; file_path: string; message: string };
+
+export type FlowExecution = {
+  execution_id: string;
+  flow_run_id: string;
+  flow_run_url: string;
+  qdash_ui_url: string;
+  message: string;
+};
+
+/** The slice of QDashClient these tools use; tests pass a stub. */
+export type FlowClient = {
+  saveFlow(request: SaveFlowRequest): Promise<unknown>;
+  executeFlow(name: string, parameters?: Record<string, unknown>): Promise<unknown>;
+};
+
+export type FlowAuthoringDependencies = {
+  makeClient(params: ConnectionParams): Promise<FlowClient>;
+  /** The chip the flow is for: the explicit id, else the session/default chip. */
+  resolveChipId(client: FlowClient, chipId?: string): Promise<string>;
+  /** The QDash web page of a flow, when the web URL is known. */
+  flowPageUrl?(client: FlowClient, name: string): string | undefined;
+};
+
+const FLOW_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/;
+
+/** Why a save would certainly be rejected, before anyone is asked to approve it. */
+export function flowCodeProblems(name: string, code: string, functionName: string): string[] {
+  const problems: string[] = [];
+  if (!FLOW_NAME.test(name)) problems.push(`name '${name}' must be letters, digits and underscores, not starting with a digit`);
+  if (!FLOW_NAME.test(functionName)) problems.push(`flowFunctionName '${functionName}' is not a Python identifier`);
+  if (!/^\s*@flow\b/m.test(code)) problems.push("the code has no `@flow` decorator (import it with `from prefect import flow`)");
+  if (!new RegExp(`^\\s*(?:async\\s+)?def\\s+${functionName}\\s*\\(`, "m").test(code)) {
+    problems.push(`the code defines no function named '${functionName}'`);
+  }
+  if (!/^\s*(?:from|import)\s+prefect\b/m.test(code)) problems.push("the code does not import prefect");
+  return problems;
+}
+
+function detailOf(error: unknown): string | undefined {
+  if (!error || typeof error !== "object") return undefined;
+  const payload = (error as { payload?: unknown }).payload;
+  const detail = payload && typeof payload === "object" ? (payload as { detail?: unknown }).detail : undefined;
+  if (typeof detail === "string") return detail;
+  const message = (error as { message?: unknown }).message;
+  return typeof message === "string" ? message : undefined;
+}
+
+export function formatSavedFlow(result: SaveFlowResult, chipId: string, url: string | undefined): string {
+  return [
+    `${result.message} (chip ${chipId}).`,
+    `File: ${result.file_path}`,
+    ...(url ? [`Page: ${url}`] : []),
+    "The flow is registered as a Prefect deployment. Saving did not run it; qdash_execute_flow runs it when the user asks.",
+  ].join("\n");
+}
+
+export function formatFlowExecution(result: FlowExecution, name: string): string {
+  return [
+    `${result.message || `Flow '${name}' started.`}`,
+    `Execution: ${result.execution_id}`,
+    `QDash: ${result.qdash_ui_url}`,
+    `Prefect: ${result.flow_run_url}`,
+    "Follow it with qdash_wait_execution; completed tasks write their calibrated parameters to QDash directly.",
+  ].join("\n");
+}
+
+const connectionParams = {
+  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." })),
+};
+
+export function registerFlowAuthoringTools(pi: Pick<ExtensionAPI, "registerTool">, deps: FlowAuthoringDependencies): void {
+  pi.registerTool({
+    name: "qdash_save_flow",
+    label: "QDash Save Flow",
+    description:
+      "Save a Prefect flow (Python) as a QDash workflow: writes the file, formats it, registers its Prefect deployment, and records it in the project. Saving an existing name replaces that flow. Confirmation-gated write operation: the flow runs later on the workflow worker with hardware access. Start from a template (qdash_query flow_templates / flow_template) or an existing flow (qdash_get_flow).",
+    promptSnippet: "Save a Prefect flow the user asked you to write as a QDash workflow",
+    promptGuidelines: [
+      "Before qdash_save_flow, read a template or the existing flow and keep its structure: the @flow function, the helper imports, and the terminal handling.",
+      "Show the user the whole code and say which chip it is for; the save is confirmation-gated and replaces a flow of the same name.",
+      "Saving does not run the flow. Do not run it unless the user asks.",
+    ],
+    parameters: Type.Object({
+      ...connectionParams,
+      name: Type.String({ description: "Flow name: letters, digits and underscores. Also the file name and, by default, the @flow function name." }),
+      code: Type.String({ description: "The complete Python source of the flow module." }),
+      description: Type.Optional(Type.String({ description: "One line shown on the Workflow page." })),
+      chipId: Type.Optional(Type.String({ description: "Chip the flow is for. Defaults to the session/default chip." })),
+      flowFunctionName: Type.Optional(Type.String({ description: "The @flow function to deploy when it is not named like the flow." })),
+      defaultParameters: Type.Optional(Type.Object({}, { additionalProperties: true, description: "Default values of the flow function's parameters." })),
+      defaultRunParameters: Type.Optional(Type.Object({}, { additionalProperties: true, description: "Run parameters applied to every task, such as shots or interval." })),
+      tags: Type.Optional(Type.Array(Type.String())),
+      confirmWrite: Type.Optional(Type.Boolean({ description: "Required for non-interactive execution. Set true only after explicit user confirmation." })),
+    }),
+    async execute(
+      _toolCallId,
+      params: ConnectionParams & {
+        name: string;
+        code: string;
+        description?: string;
+        chipId?: string;
+        flowFunctionName?: string;
+        defaultParameters?: Record<string, unknown>;
+        defaultRunParameters?: Record<string, unknown>;
+        tags?: string[];
+        confirmWrite?: boolean;
+      },
+      _signal,
+      _onUpdate,
+      ctx,
+    ) {
+      const functionName = params.flowFunctionName ?? params.name;
+      const problems = flowCodeProblems(params.name, params.code, functionName);
+      if (problems.length > 0) {
+        const text = [
+          `The flow cannot be saved as it is (${problems.length} problem${problems.length === 1 ? "" : "s"}). Nothing was written.`,
+          ...problems.map((problem) => `- ${problem}`),
+        ].join("\n");
+        return toTextToolResult(text, { problems }, { tool: "qdash_save_flow", saved: false, problemCount: problems.length });
+      }
+      if (!params.confirmWrite) {
+        if (!ctx.hasUI || !(await ctx.ui.confirm("Save QDash flow?", `This writes flow '${params.name}' to the project and registers its deployment.`))) {
+          throw new Error("qdash_save_flow requires explicit confirmation");
+        }
+      }
+      const client = await deps.makeClient(params);
+      const chipId = await deps.resolveChipId(client, params.chipId);
+      try {
+        const result = (await client.saveFlow({
+          name: params.name,
+          description: params.description ?? "",
+          code: params.code,
+          flow_function_name: functionName,
+          chip_id: chipId,
+          default_parameters: params.defaultParameters ?? {},
+          default_run_parameters: params.defaultRunParameters ?? {},
+          tags: params.tags ?? [],
+        })) as SaveFlowResult;
+        const url = deps.flowPageUrl?.(client, result.name);
+        return toTextToolResult(formatSavedFlow(result, chipId, url), { ...result, chip_id: chipId, url }, {
+          tool: "qdash_save_flow",
+          saved: true,
+          flowName: result.name,
+          chipId,
+        });
+      } catch (error) {
+        const detail = detailOf(error);
+        if (!detail) throw error;
+        return toTextToolResult(
+          `QDash rejected the flow: ${detail}\nNothing was saved. Fix the code and save again.`,
+          { detail },
+          { tool: "qdash_save_flow", saved: false },
+        );
+      }
+    },
+  });
+
+  pi.registerTool({
+    name: "qdash_execute_flow",
+    label: "QDash Execute Flow",
+    description:
+      "Run a saved QDash flow as one execution, with parameters that override its defaults. Confirmation-gated write operation: the flow runs on the workflow worker with hardware access, takes the project execution lock, and completed tasks write their calibrated parameters to QDash directly.",
+    promptSnippet: "Run a saved QDash flow after explicit user confirmation",
+    promptGuidelines: [
+      "Use qdash_execute_flow only when the user asks to run a flow; saving one with qdash_save_flow is not a request to run it.",
+      "Check qdash_list_executions for a running execution first; a flow takes the project execution lock.",
+      "After it starts, follow the execution with qdash_wait_execution and summarize failed targets.",
+    ],
+    parameters: Type.Object({
+      ...connectionParams,
+      name: Type.String({ description: "The saved flow's name." }),
+      parameters: Type.Optional(Type.Object({}, { additionalProperties: true, description: "Flow function parameters; override the flow's default_parameters." })),
+      confirmWrite: Type.Optional(Type.Boolean({ description: "Required for non-interactive execution. Set true only after explicit user confirmation." })),
+    }),
+    async execute(_toolCallId, params: ConnectionParams & { name: string; parameters?: Record<string, unknown>; confirmWrite?: boolean }, _signal, _onUpdate, ctx) {
+      if (!params.confirmWrite) {
+        if (!ctx.hasUI || !(await ctx.ui.confirm("Run QDash flow?", `This starts flow '${params.name}' on the workflow worker. Completed tasks update calibrated parameters in QDash directly.`))) {
+          throw new Error("qdash_execute_flow requires explicit confirmation");
+        }
+      }
+      const client = await deps.makeClient(params);
+      const result = (await client.executeFlow(params.name, params.parameters ?? {})) as FlowExecution;
+      return toTextToolResult(formatFlowExecution(result, params.name), result, {
+        tool: "qdash_execute_flow",
+        flowName: params.name,
+        executionId: result.execution_id,
+        started: true,
+      });
+    },
+  });
+}

package/extensions/tools/task-knowledge.ts

@@ -99,6 +99,19 @@ function notFound(error: unknown): boolean {
   return value.status === 404 || value.statusCode === 404 || value.response?.status === 404 || /\b404\b|not found/i.test(String(value.message ?? ""));
 }
 
+const INLINE_IMAGE = /\(data:image\/[a-z0-9.+-]+;base64,[A-Za-z0-9+/=]+\)/g;
+
+/**
+ * The knowledge markdown as the model should read it: QDash inlines the
+ * expected-plot figures as base64 data URIs for self-contained rendering, which
+ * costs tens of thousands of tokens and tells a text model nothing. The alt
+ * text stays; the figure itself is shown on QDash's Knowledge page and by
+ * qdash_get_figure for results.
+ */
+export function withoutInlineImages(markdown: string): string {
+  return markdown.replace(INLINE_IMAGE, "(figure omitted: shown on the task's Knowledge page)");
+}
+
 export function registerTaskKnowledgeTool(pi: Pick<ExtensionAPI, "registerTool">, deps: TaskKnowledgeDependencies): void {
   pi.registerTool({
     name: "qdash_get_task_knowledge",
@@ -125,9 +138,11 @@ export function registerTaskKnowledgeTool(pi: Pick<ExtensionAPI, "registerTool">
           : await client.getTaskKnowledgeMarkdown(params.taskName);
         const markdown = format === "summary"
           ? taskKnowledgeSummary(data as TaskKnowledge)
-          : typeof data === "string"
-            ? data
-            : text((data as { markdown?: unknown })?.markdown) ?? JSON.stringify(data, null, 2);
+          : withoutInlineImages(
+              typeof data === "string"
+                ? data
+                : text((data as { markdown?: unknown })?.markdown) ?? JSON.stringify(data, null, 2),
+            );
         return toTextToolResult(markdown, data, { taskName: params.taskName, format, found: true });
       } catch (error) {
         if (!notFound(error)) throw error;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oqtopus-team/pi-qdash",
-  "version": "0.1.11-beta.21",
+  "version": "0.1.11-beta.22",
   "description": "Pi extension for querying QDash via @oqtopus-team/qdash-client",
   "type": "module",
   "license": "Apache-2.0",

package/skills/qdash/SKILL.md

@@ -41,6 +41,7 @@ Prefer the dedicated tool that matches the question. Use `qdash_query` only as a
    - `qdash_create_forum_post`, `qdash_update_forum_post` — create or update Forum content
    - `qdash_create_forum_evidence_reply`, `qdash_create_forum_image_reply` — publish previously reviewed evidence replies
    - `qdash_run_pipeline` — run a validated pipeline spec as one execution
+   - `qdash_save_flow`, `qdash_execute_flow` — save a Prefect flow you wrote as a QDash workflow, and run a saved flow (see Authoring a flow)
 4. Agent workflow state tools:
    - `qdash_get_agent_session`, `qdash_get_agent_action`, `qdash_list_agent_actions`, `qdash_wait_agent_action` — inspect agent workflow state
    - `qdash_list_agent_action_candidates`, `qdash_get_agent_candidate_commit`, `qdash_wait_agent_candidate_apply` — inspect candidates and apply status
@@ -67,6 +68,17 @@ Rules:
 - A pipeline takes the project execution lock. Check `qdash_list_executions` for a running execution before starting one.
 - Prefer short pipelines (one or two steps) when the next step depends on the result: run, inspect results and figures, then compose the next spec. Calibrated parameters persist in QDash between executions, so a later spec continues from the earlier one. Retries and branches are your decision between executions, not something the spec expresses.
 
+## Authoring a flow
+
+A flow is a Python module with one `@flow` function that QDash runs on its workflow worker, with hardware and database access. Pipelines (above) cover ordered task lists without code; write a flow only when the user needs logic a pipeline cannot express: loops until convergence, branching on results, custom parameter sweeps.
+
+Workflow:
+
+1. Start from what exists. `qdash_query` with `flow_templates` lists the templates and `flow_template` returns one with its code; `qdash_get_flow` returns a saved flow; `flow_helper_files` / `flow_helper_file` show the helpers templates import. Keep the template's structure: its imports, the `@flow` signature, and the terminal handling at the end of the run.
+2. Write the module. Name the `@flow` function like the flow unless the user wants otherwise. Task and parameter names must come from `qdash_get_pipeline_catalog` and the template; do not invent them. When a shell workspace is available, draft the file there and run `python -m py_compile` on it before showing it.
+3. Show the user the complete code and the chip it is for, then `qdash_save_flow`. QDash checks the `@flow` function, formats the file, registers a Prefect deployment, and replaces a flow of the same name. A rejection comes back as text with QDash's reason; fix the code and save again.
+4. Saving does not run anything. Run it only when the user asks: `qdash_execute_flow` with the flow's parameters (confirmation-gated, takes the project execution lock), then `qdash_wait_execution`.
+
 ## Session context
 
 When running in pi CLI, use `qdash_config_info` if the profile or non-secret connection settings are unclear.