@agimon-ai/doompi-workflow 0.0.1-alpha.76 → 0.0.1-alpha.78

package/dist/src/services/backgroundWork/index.mjs

@@ -0,0 +1,61 @@
+import { DOOM_BACKGROUND_WORK_SERVICE, readDoomBackgroundWorkService } from "@agimon-ai/doompi-core/background-work";
+//#region src/services/backgroundWork/index.ts
+/**
+* Background-work registration for workflow runs.
+*
+* DESIGN PATTERNS:
+* - Hard dependency binding through Cordis injection
+* - Snapshot pattern: the extension pushes the current run set, the provider
+*   only reads it
+*
+* CODING STANDARDS:
+* - Named exports only
+* - Explicit return types on exported functions
+*
+* AVOID:
+* - Process-global symbols or dynamic imports for extension communication
+* - Reporting runs owned by another Pi session
+*/
+const PROVIDER_NAME = "workflow-mcp";
+/**
+* Register a background-work provider for this session's workflow runs.
+*
+* The runtime pins all announcements to the active Pi session and validates
+* each snapshot before it reaches another extension.
+*/
+function registerRunProvider(ctx) {
+	let items = [];
+	let provider;
+	let disposed = false;
+	ctx.inject([DOOM_BACKGROUND_WORK_SERVICE], (serviceContext) => {
+		if (disposed) return void 0;
+		const service = readDoomBackgroundWorkService(serviceContext);
+		if (!service) return void 0;
+		const registration = service.register({
+			provider: PROVIDER_NAME,
+			listActiveWork: () => items
+		});
+		provider = registration;
+		return () => {
+			registration.dispose();
+			if (provider === registration) provider = void 0;
+		};
+	});
+	return {
+		update(next) {
+			items = next;
+			provider?.update();
+		},
+		dispose() {
+			if (disposed) return;
+			disposed = true;
+			items = [];
+			provider?.dispose();
+			provider = void 0;
+		}
+	};
+}
+//#endregion
+export { registerRunProvider };
+
+//# sourceMappingURL=index.mjs.map

package/dist/src/services/backgroundWork/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.mjs","names":[],"sources":["../../../../src/services/backgroundWork/index.ts"],"sourcesContent":["/**\n * Background-work registration for workflow runs.\n *\n * DESIGN PATTERNS:\n * - Hard dependency binding through Cordis injection\n * - Snapshot pattern: the extension pushes the current run set, the provider\n *   only reads it\n *\n * CODING STANDARDS:\n * - Named exports only\n * - Explicit return types on exported functions\n *\n * AVOID:\n * - Process-global symbols or dynamic imports for extension communication\n * - Reporting runs owned by another Pi session\n */\n\nimport {\n  DOOM_BACKGROUND_WORK_SERVICE,\n  type BackgroundWorkProviderHandle,\n  readDoomBackgroundWorkService,\n} from '@agimon-ai/doompi-core/background-work';\nimport type { Context } from '@deepseek-ai/cordis';\n\nexport interface RunProviderItem {\n  id: string;\n  sessionId: string;\n}\n\nexport interface RunProviderHandle {\n  /** Replace the reported run set. */\n  update(items: RunProviderItem[]): void;\n  /** Remove the registration. Safe to call when registration never happened. */\n  dispose(): void;\n}\n\nconst PROVIDER_NAME = 'workflow-mcp';\n\n/**\n * Register a background-work provider for this session's workflow runs.\n *\n * The runtime pins all announcements to the active Pi session and validates\n * each snapshot before it reaches another extension.\n */\nexport function registerRunProvider(ctx: Context): RunProviderHandle {\n  let items: RunProviderItem[] = [];\n  let provider: BackgroundWorkProviderHandle | undefined;\n  let disposed = false;\n  ctx.inject([DOOM_BACKGROUND_WORK_SERVICE], (serviceContext) => {\n    if (disposed) return undefined;\n    const service = readDoomBackgroundWorkService(serviceContext);\n    if (!service) return undefined;\n    const registration = service.register({ provider: PROVIDER_NAME, listActiveWork: () => items });\n    provider = registration;\n    return () => {\n      registration.dispose();\n      if (provider === registration) provider = undefined;\n    };\n  });\n  const handle: RunProviderHandle = {\n    update(next) {\n      items = next;\n      provider?.update();\n    },\n    dispose() {\n      if (disposed) return;\n      disposed = true;\n      items = [];\n      provider?.dispose();\n      provider = undefined;\n    },\n  };\n  return handle;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;AAoCA,MAAM,gBAAgB;;;;;;;AAQtB,SAAgB,oBAAoB,KAAiC;CACnE,IAAI,QAA2B,CAAC;CAChC,IAAI;CACJ,IAAI,WAAW;CACf,IAAI,OAAO,CAAC,4BAA4B,IAAI,mBAAmB;EAC7D,IAAI,UAAU,OAAO,KAAA;EACrB,MAAM,UAAU,8BAA8B,cAAc;EAC5D,IAAI,CAAC,SAAS,OAAO,KAAA;EACrB,MAAM,eAAe,QAAQ,SAAS;GAAE,UAAU;GAAe,sBAAsB;EAAM,CAAC;EAC9F,WAAW;EACX,aAAa;GACX,aAAa,QAAQ;GACrB,IAAI,aAAa,cAAc,WAAW,KAAA;EAC5C;CACF,CAAC;CAcD,OAAO;EAZL,OAAO,MAAM;GACX,QAAQ;GACR,UAAU,OAAO;EACnB;EACA,UAAU;GACR,IAAI,UAAU;GACd,WAAW;GACX,QAAQ,CAAC;GACT,UAAU,QAAQ;GAClB,WAAW,KAAA;EACb;CAEU;AACd"}

package/dist/src/services/piToolBridge/index.cjs

@@ -0,0 +1,205 @@
+//#region src/services/piToolBridge/index.ts
+/**
+* Environment variable stamped onto every run launched from a Pi session.
+*
+* `RunWorkflowService` forwards `env` to the inner CLI invocation across the
+* `launch-command` delegation boundary and persists it on the run record, so
+* this survives backgrounding and identifies the launching session afterwards.
+*/
+const PI_SESSION_ENV = "PI_SESSION_ID";
+/** Operator override for the per-session launch ceiling. */
+const MAX_CONCURRENT_ENV = "WORKFLOW_MCP_MAX_CONCURRENT";
+const DEFAULT_MAX_CONCURRENT = 5;
+/** Resolve the per-session launch ceiling from the environment. */
+function resolveMaxConcurrent(env = process.env) {
+	const parsed = Number(env[MAX_CONCURRENT_ENV]);
+	return Number.isInteger(parsed) && parsed > 0 ? parsed : DEFAULT_MAX_CONCURRENT;
+}
+/**
+* True when this session launched the run.
+*
+* Fails closed on a missing session id: an unstamped record (a CLI launch) and
+* a call arriving before the session id is known both match nothing, so no run
+* ever leaks across sessions through an undefined-equals-undefined comparison.
+*/
+function isSessionRun(record, sessionId) {
+	return sessionId !== void 0 && record.env?.["PI_SESSION_ID"] === sessionId;
+}
+/** Runs launched by one Pi session that are still running. */
+function runsForSession(records, sessionId) {
+	return records.filter((record) => isSessionRun(record, sessionId) && record.stage === "running");
+}
+/**
+* What the caller is told when the registry, not the launcher, acknowledged a
+* launch.
+*
+* Leads with the run key because it is the handle every other workflow action
+* takes, and it is no longer available any other way: the launcher's own output
+* is not waited for, so nothing else in this result carries it.
+*/
+function launchedRunSummary(record) {
+	return [
+		`Started ${record.displayName} in workspace ${record.workspace}.`,
+		`Run key: ${record.runKey}`,
+		"The run is registered and going. This call returned at that point rather than waiting for the launcher process to exit."
+	].join("\n");
+}
+/**
+* What the caller is told when the launch was handed off but no run has
+* registered inside the acknowledgement budget.
+*
+* Deliberately not an error: the launcher is slow rather than broken often
+* enough that failing here would strand runs that go on to start normally.
+* There is no run key to offer yet, so it points at the surfaces that do not
+* need one.
+*/
+function launchHandoffSummary(workflowPath) {
+	return [
+		`Launch handed off for ${workflowPath}, but no run has registered yet.`,
+		"Nothing was cancelled: the launcher is still starting, and a run that registers later still reports back here when it finishes.",
+		"Do not launch it again. Ask the user to check the active workflow list if they need to see it sooner."
+	].join("\n");
+}
+/**
+* Escape sequences a terminal consumes rather than prints.
+*
+* Built from a string with the rule silenced, the way `doom-runner`'s own
+* scrubber does it, because matching the escape byte is the entire job. Not
+* imported from there: that package's published build is a stale artifact
+* missing the export, and a launch notice should not need another package's
+* build to be current.
+*/
+const ESCAPE_SEQUENCE = new RegExp([
+	"\\u001B\\[[0-9;?]*[ -/]*[@-~]",
+	"\\u001B\\][^\\u0007\\u001B]*(?:\\u0007|\\u001B\\\\)",
+	"\\u001B[@-Z\\\\-_]"
+].join("|"), "g");
+/** Rows made only of box-drawing: separators that carry nothing once trimmed. */
+const RULE_ROW = /^[\s─-╿]*$/u;
+const NOTICE_LINE_LIMIT = 3;
+/**
+* Widest a notice row may be before it is clipped.
+*
+* A three-line cap does not bound a toast on its own: the engine announces its
+* delegation by echoing the whole shell command, temp script path included, and
+* one line of that wraps across three rows of a narrow terminal and shoves the
+* transcript around. Clipped at a width every terminal can hold instead.
+*/
+const NOTICE_WIDTH_LIMIT = 100;
+/**
+* Cut a tool result down to something a toast can hold.
+*
+* The launch result used to reach `ui.notify` whole, and for a workflow that
+* executes in this process that result is the engine's entire console log:
+* banner, run directory, job tree, rules, colour. Pi rendered every line of it
+* over the transcript, which reads as a broken screen rather than as output.
+* Escape sequences go first: the log carries colour the notification would
+* render as literal text, and a stray clear or cursor-move would do to the
+* screen exactly what this function exists to prevent.
+*/
+function launchNotice(text, limit = NOTICE_LINE_LIMIT) {
+	const lines = text.replace(ESCAPE_SEQUENCE, "").split("\n").map((line) => line.trimEnd()).filter((line) => line.trim().length > 0 && !RULE_ROW.test(line)).map((line) => line.length > NOTICE_WIDTH_LIMIT ? `${line.slice(0, 99)}…` : line);
+	if (lines.length === 0) return "Workflow started.";
+	if (lines.length <= limit) return lines.join("\n");
+	return [...lines.slice(0, limit), `… ${lines.length - limit} more lines, in the run's own output.`].join("\n");
+}
+/** Flatten MCP tool content to text for Pi. */
+function toolResultText(result) {
+	return result.content.map((part) => part.type === "text" ? part.text : "").filter(Boolean).join("\n").trim();
+}
+/**
+* Convert an MCP tool result into a Pi tool result.
+*
+* Pi signals tool failure by throwing: the agent loop catches it and builds the
+* error result. So an `isError` MCP result becomes a thrown error rather than a
+* successful result carrying a flag Pi would ignore.
+*/
+function toAgentToolResult(tool, result, errorOptions = []) {
+	const text = toolResultText(result) || "No output.";
+	if (result.isError) throw new Error(withOptions(text, errorOptions));
+	return {
+		content: [{
+			type: "text",
+			text
+		}],
+		details: { tool }
+	};
+}
+/**
+* Attach a short menu of next steps to a problem.
+*
+* An error with no route forward is where an agent invents one: retrying a
+* capacity limit, relaunching a run that should be recovered, or silently
+* giving up on work the user is waiting for. Naming two or three real options
+* turns an error into a decision, and the decision belongs to the user.
+*/
+function withOptions(problem, options) {
+	if (options.length === 0) return problem;
+	return [
+		problem,
+		"",
+		"Options, put these to the user rather than picking one yourself:",
+		...options.map(bullet)
+	].join("\n");
+}
+function bullet(option) {
+	return `- ${option}`;
+}
+/** The job and step a run died on, preferring the progress log to the record. */
+function failurePosition(record, jobs) {
+	const failedJob = jobs.find((job) => job.status === "failed");
+	const failedStep = failedJob?.steps.find((step) => step.status === "failed");
+	return {
+		job: failedJob?.name ?? record.failedJob,
+		step: failedStep?.name,
+		reason: failedStep?.reason ?? failedJob?.reason
+	};
+}
+/**
+* Describe a finished run for the agent that launched it.
+*
+* Carries the job identifiers back so a dispatching agent can match the run to
+* the work item it launched it for without another lookup. When the run failed,
+* carries the failing step and a set of options too: the agent is being told
+* about this out of band, with no user question in flight, so without them it
+* has to guess whether to recover, relaunch, or report.
+*/
+function finishedRunSummary(record, jobs = []) {
+	const outcome = record.stage === "completed" ? "completed" : `ended in ${record.stage}`;
+	const failure = failurePosition(record, jobs);
+	const lines = [
+		`Workflow run ${record.runKey} in workspace ${record.workspace} ${outcome}.`,
+		record.workflowId ? `Workflow: ${record.workflowId}` : void 0,
+		failure.job ? `Failed job: ${failure.job}${failure.step ? ` (step: ${failure.step})` : ""}` : void 0,
+		record.errorMessage ? `Error: ${record.errorMessage}` : void 0,
+		failure.reason && failure.reason !== record.errorMessage ? `Step reported: ${failure.reason}` : void 0
+	];
+	const jobId = record.env?.AGIFLOW_JOB_ID;
+	if (jobId) lines.push(`Agiflow job: ${record.env?.AGIFLOW_JOB_KIND ?? "unknown"} ${jobId}`);
+	const summary = lines.filter((line) => Boolean(line)).join("\n");
+	if (record.stage === "completed") return summary;
+	if (record.outcome === "interrupted") return withOptions(summary, [`workflow_run {"action":"recover","runKey":${JSON.stringify(record.runKey)}}: pick it up where it stopped.`, "Leave it stopped and move on."]);
+	const diagnosticText = [record.errorMessage, failure.reason].filter(Boolean).join("\n");
+	if (diagnosticText.includes("JOB_ALREADY_CLAIMED")) return withOptions(summary, ["Report contention: another worker owns this job. Do not unlock, release, or retry the claim automatically."]);
+	if (diagnosticText.includes("WORKFLOW_NOT_OWNED") || /release failed/i.test(diagnosticText)) return withOptions(summary, ["Inspect the current workflow ownership and ask the user before any release or unlock. Never force another worker’s lock."]);
+	if (/running workflow not found/i.test(diagnosticText)) return withOptions(summary, [`workflow_run {"action":"status","runKey":${JSON.stringify(record.runKey)}}: re-check current state before retrying.`, "Report the recorded terminal state when no running owner remains."]);
+	return withOptions(summary, [
+		`workflow_run {"action":"tail","runKey":${JSON.stringify(record.runKey)}}: read the run's own output first, when the error above does not explain the failure.`,
+		`workflow_run {"action":"recover","runKey":${JSON.stringify(record.runKey)}}: resume from the failed job, keeping the work already done. Fits a transient or external cause.`,
+		"Report the failure and stop, when it needs a code change or a decision you cannot make."
+	]);
+}
+//#endregion
+exports.PI_SESSION_ENV = PI_SESSION_ENV;
+exports.finishedRunSummary = finishedRunSummary;
+exports.isSessionRun = isSessionRun;
+exports.launchHandoffSummary = launchHandoffSummary;
+exports.launchNotice = launchNotice;
+exports.launchedRunSummary = launchedRunSummary;
+exports.resolveMaxConcurrent = resolveMaxConcurrent;
+exports.runsForSession = runsForSession;
+exports.toAgentToolResult = toAgentToolResult;
+exports.toolResultText = toolResultText;
+exports.withOptions = withOptions;
+
+//# sourceMappingURL=index.cjs.map

package/dist/src/services/piToolBridge/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.cjs","names":[],"sources":["../../../../src/services/piToolBridge/index.ts"],"sourcesContent":["/**\n * Pure bridging logic between MCP tool results and the Pi tool surface.\n *\n * DESIGN PATTERNS:\n * - Adapter pattern: MCP `CallToolResult` is converted to Pi's result shape\n * - Pure module: no service or tool-class imports, so this is unit-testable\n *   without constructing the workflow execution stack\n *\n * CODING STANDARDS:\n * - Named exports only\n * - Explicit return types on exported functions\n *\n * AVOID:\n * - Importing tool classes or services here (that belongs in `piTools.ts`)\n * - Returning an error flag Pi does not read; Pi tools signal failure by throwing\n */\n\nimport type { WorkflowProgressJob, WorkflowRunRecord } from '@agimon-ai/workflow-mcp';\nimport type { AgentToolResult } from '@earendil-works/pi-coding-agent';\nimport type { CallToolResult } from '@modelcontextprotocol/sdk/types.js';\n\n/**\n * Environment variable stamped onto every run launched from a Pi session.\n *\n * `RunWorkflowService` forwards `env` to the inner CLI invocation across the\n * `launch-command` delegation boundary and persists it on the run record, so\n * this survives backgrounding and identifies the launching session afterwards.\n */\nexport const PI_SESSION_ENV = 'PI_SESSION_ID';\n\n/** Operator override for the per-session launch ceiling. */\nconst MAX_CONCURRENT_ENV = 'WORKFLOW_MCP_MAX_CONCURRENT';\nconst DEFAULT_MAX_CONCURRENT = 5;\n\nexport interface WorkflowToolDetails {\n  tool: string;\n}\n\n/** Resolve the per-session launch ceiling from the environment. */\nexport function resolveMaxConcurrent(env: NodeJS.ProcessEnv = process.env): number {\n  const parsed = Number(env[MAX_CONCURRENT_ENV]);\n  return Number.isInteger(parsed) && parsed > 0 ? parsed : DEFAULT_MAX_CONCURRENT;\n}\n\n/**\n * True when this session launched the run.\n *\n * Fails closed on a missing session id: an unstamped record (a CLI launch) and\n * a call arriving before the session id is known both match nothing, so no run\n * ever leaks across sessions through an undefined-equals-undefined comparison.\n */\nexport function isSessionRun(record: WorkflowRunRecord, sessionId: string | undefined): boolean {\n  return sessionId !== undefined && record.env?.[PI_SESSION_ENV] === sessionId;\n}\n\n/** Runs launched by one Pi session that are still running. */\nexport function runsForSession(records: WorkflowRunRecord[], sessionId: string): WorkflowRunRecord[] {\n  return records.filter((record) => isSessionRun(record, sessionId) && record.stage === 'running');\n}\n\n/**\n * What the caller is told when the registry, not the launcher, acknowledged a\n * launch.\n *\n * Leads with the run key because it is the handle every other workflow action\n * takes, and it is no longer available any other way: the launcher's own output\n * is not waited for, so nothing else in this result carries it.\n */\nexport function launchedRunSummary(record: WorkflowRunRecord): string {\n  return [\n    `Started ${record.displayName} in workspace ${record.workspace}.`,\n    `Run key: ${record.runKey}`,\n    'The run is registered and going. This call returned at that point rather than waiting for the launcher process to exit.',\n  ].join('\\n');\n}\n\n/**\n * What the caller is told when the launch was handed off but no run has\n * registered inside the acknowledgement budget.\n *\n * Deliberately not an error: the launcher is slow rather than broken often\n * enough that failing here would strand runs that go on to start normally.\n * There is no run key to offer yet, so it points at the surfaces that do not\n * need one.\n */\nexport function launchHandoffSummary(workflowPath: string): string {\n  return [\n    `Launch handed off for ${workflowPath}, but no run has registered yet.`,\n    'Nothing was cancelled: the launcher is still starting, and a run that registers later still reports back here when it finishes.',\n    'Do not launch it again. Ask the user to check the active workflow list if they need to see it sooner.',\n  ].join('\\n');\n}\n\n/**\n * Escape sequences a terminal consumes rather than prints.\n *\n * Built from a string with the rule silenced, the way `doom-runner`'s own\n * scrubber does it, because matching the escape byte is the entire job. Not\n * imported from there: that package's published build is a stale artifact\n * missing the export, and a launch notice should not need another package's\n * build to be current.\n */\n// oxlint-disable-next-line no-control-regex -- matching terminal control bytes is the point\nconst ESCAPE_SEQUENCE = new RegExp(\n  ['\\\\u001B\\\\[[0-9;?]*[ -/]*[@-~]', '\\\\u001B\\\\][^\\\\u0007\\\\u001B]*(?:\\\\u0007|\\\\u001B\\\\\\\\)', '\\\\u001B[@-Z\\\\\\\\-_]'].join(\n    '|',\n  ),\n  'g',\n);\n\n/** Rows made only of box-drawing: separators that carry nothing once trimmed. */\nconst RULE_ROW = /^[\\s─-╿]*$/u;\nconst NOTICE_LINE_LIMIT = 3;\n/**\n * Widest a notice row may be before it is clipped.\n *\n * A three-line cap does not bound a toast on its own: the engine announces its\n * delegation by echoing the whole shell command, temp script path included, and\n * one line of that wraps across three rows of a narrow terminal and shoves the\n * transcript around. Clipped at a width every terminal can hold instead.\n */\nconst NOTICE_WIDTH_LIMIT = 100;\n\n/**\n * Cut a tool result down to something a toast can hold.\n *\n * The launch result used to reach `ui.notify` whole, and for a workflow that\n * executes in this process that result is the engine's entire console log:\n * banner, run directory, job tree, rules, colour. Pi rendered every line of it\n * over the transcript, which reads as a broken screen rather than as output.\n * Escape sequences go first: the log carries colour the notification would\n * render as literal text, and a stray clear or cursor-move would do to the\n * screen exactly what this function exists to prevent.\n */\nexport function launchNotice(text: string, limit: number = NOTICE_LINE_LIMIT): string {\n  const lines = text\n    .replace(ESCAPE_SEQUENCE, '')\n    .split('\\n')\n    .map((line) => line.trimEnd())\n    .filter((line) => line.trim().length > 0 && !RULE_ROW.test(line))\n    .map((line) => (line.length > NOTICE_WIDTH_LIMIT ? `${line.slice(0, NOTICE_WIDTH_LIMIT - 1)}…` : line));\n  if (lines.length === 0) return 'Workflow started.';\n  if (lines.length <= limit) return lines.join('\\n');\n  return [...lines.slice(0, limit), `… ${lines.length - limit} more lines, in the run's own output.`].join('\\n');\n}\n\n/** Flatten MCP tool content to text for Pi. */\nexport function toolResultText(result: CallToolResult): string {\n  return result.content\n    .map((part) => (part.type === 'text' ? part.text : ''))\n    .filter(Boolean)\n    .join('\\n')\n    .trim();\n}\n\n/**\n * Convert an MCP tool result into a Pi tool result.\n *\n * Pi signals tool failure by throwing: the agent loop catches it and builds the\n * error result. So an `isError` MCP result becomes a thrown error rather than a\n * successful result carrying a flag Pi would ignore.\n */\nexport function toAgentToolResult(\n  tool: string,\n  result: CallToolResult,\n  errorOptions: string[] = [],\n): AgentToolResult<WorkflowToolDetails> {\n  const text = toolResultText(result) || 'No output.';\n  if (result.isError) throw new Error(withOptions(text, errorOptions));\n  return { content: [{ type: 'text', text }], details: { tool } };\n}\n\n/**\n * Attach a short menu of next steps to a problem.\n *\n * An error with no route forward is where an agent invents one: retrying a\n * capacity limit, relaunching a run that should be recovered, or silently\n * giving up on work the user is waiting for. Naming two or three real options\n * turns an error into a decision, and the decision belongs to the user.\n */\nexport function withOptions(problem: string, options: string[]): string {\n  if (options.length === 0) return problem;\n  return [problem, '', 'Options, put these to the user rather than picking one yourself:', ...options.map(bullet)].join(\n    '\\n',\n  );\n}\n\nfunction bullet(option: string): string {\n  return `- ${option}`;\n}\n\n/** The job and step a run died on, preferring the progress log to the record. */\nfunction failurePosition(\n  record: WorkflowRunRecord,\n  jobs: WorkflowProgressJob[],\n): { job?: string; step?: string; reason?: string } {\n  // The progress log knows which step was in flight; the record only names the\n  // job. Falling back keeps this working for runs that predate the log.\n  const failedJob = jobs.find((job) => job.status === 'failed');\n  const failedStep = failedJob?.steps.find((step) => step.status === 'failed');\n  return {\n    job: failedJob?.name ?? record.failedJob,\n    step: failedStep?.name,\n    reason: failedStep?.reason ?? failedJob?.reason,\n  };\n}\n\n/**\n * Describe a finished run for the agent that launched it.\n *\n * Carries the job identifiers back so a dispatching agent can match the run to\n * the work item it launched it for without another lookup. When the run failed,\n * carries the failing step and a set of options too: the agent is being told\n * about this out of band, with no user question in flight, so without them it\n * has to guess whether to recover, relaunch, or report.\n */\nexport function finishedRunSummary(record: WorkflowRunRecord, jobs: WorkflowProgressJob[] = []): string {\n  const outcome = record.stage === 'completed' ? 'completed' : `ended in ${record.stage}`;\n  const failure = failurePosition(record, jobs);\n  const lines: Array<string | undefined> = [\n    `Workflow run ${record.runKey} in workspace ${record.workspace} ${outcome}.`,\n    record.workflowId ? `Workflow: ${record.workflowId}` : undefined,\n    failure.job ? `Failed job: ${failure.job}${failure.step ? ` (step: ${failure.step})` : ''}` : undefined,\n    record.errorMessage ? `Error: ${record.errorMessage}` : undefined,\n    failure.reason && failure.reason !== record.errorMessage ? `Step reported: ${failure.reason}` : undefined,\n  ];\n  const jobId = record.env?.AGIFLOW_JOB_ID;\n  if (jobId) lines.push(`Agiflow job: ${record.env?.AGIFLOW_JOB_KIND ?? 'unknown'} ${jobId}`);\n\n  const summary = lines.filter((line): line is string => Boolean(line)).join('\\n');\n  if (record.stage === 'completed') return summary;\n\n  // A run the user stopped is not a defect, so it gets no diagnosis step: the\n  // question is only whether to pick it back up.\n  const stopped = record.outcome === 'interrupted';\n  if (stopped) {\n    return withOptions(summary, [\n      `workflow_run {\"action\":\"recover\",\"runKey\":${JSON.stringify(record.runKey)}}: pick it up where it stopped.`,\n      'Leave it stopped and move on.',\n    ]);\n  }\n\n  const diagnosticText = [record.errorMessage, failure.reason].filter(Boolean).join('\\n');\n  if (diagnosticText.includes('JOB_ALREADY_CLAIMED')) {\n    return withOptions(summary, [\n      'Report contention: another worker owns this job. Do not unlock, release, or retry the claim automatically.',\n    ]);\n  }\n  if (diagnosticText.includes('WORKFLOW_NOT_OWNED') || /release failed/i.test(diagnosticText)) {\n    return withOptions(summary, [\n      'Inspect the current workflow ownership and ask the user before any release or unlock. Never force another worker’s lock.',\n    ]);\n  }\n  if (/running workflow not found/i.test(diagnosticText)) {\n    return withOptions(summary, [\n      `workflow_run {\"action\":\"status\",\"runKey\":${JSON.stringify(record.runKey)}}: re-check current state before retrying.`,\n      'Report the recorded terminal state when no running owner remains.',\n    ]);\n  }\n\n  return withOptions(summary, [\n    `workflow_run {\"action\":\"tail\",\"runKey\":${JSON.stringify(record.runKey)}}: read the run's own output first, when the error above does not explain the failure.`,\n    `workflow_run {\"action\":\"recover\",\"runKey\":${JSON.stringify(record.runKey)}}: resume from the failed job, keeping the work already done. Fits a transient or external cause.`,\n    'Report the failure and stop, when it needs a code change or a decision you cannot make.',\n  ]);\n}\n"],"mappings":"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"}

package/dist/src/services/piToolBridge/index.mjs

@@ -0,0 +1,195 @@
+//#region src/services/piToolBridge/index.ts
+/**
+* Environment variable stamped onto every run launched from a Pi session.
+*
+* `RunWorkflowService` forwards `env` to the inner CLI invocation across the
+* `launch-command` delegation boundary and persists it on the run record, so
+* this survives backgrounding and identifies the launching session afterwards.
+*/
+const PI_SESSION_ENV = "PI_SESSION_ID";
+/** Operator override for the per-session launch ceiling. */
+const MAX_CONCURRENT_ENV = "WORKFLOW_MCP_MAX_CONCURRENT";
+const DEFAULT_MAX_CONCURRENT = 5;
+/** Resolve the per-session launch ceiling from the environment. */
+function resolveMaxConcurrent(env = process.env) {
+	const parsed = Number(env[MAX_CONCURRENT_ENV]);
+	return Number.isInteger(parsed) && parsed > 0 ? parsed : DEFAULT_MAX_CONCURRENT;
+}
+/**
+* True when this session launched the run.
+*
+* Fails closed on a missing session id: an unstamped record (a CLI launch) and
+* a call arriving before the session id is known both match nothing, so no run
+* ever leaks across sessions through an undefined-equals-undefined comparison.
+*/
+function isSessionRun(record, sessionId) {
+	return sessionId !== void 0 && record.env?.["PI_SESSION_ID"] === sessionId;
+}
+/** Runs launched by one Pi session that are still running. */
+function runsForSession(records, sessionId) {
+	return records.filter((record) => isSessionRun(record, sessionId) && record.stage === "running");
+}
+/**
+* What the caller is told when the registry, not the launcher, acknowledged a
+* launch.
+*
+* Leads with the run key because it is the handle every other workflow action
+* takes, and it is no longer available any other way: the launcher's own output
+* is not waited for, so nothing else in this result carries it.
+*/
+function launchedRunSummary(record) {
+	return [
+		`Started ${record.displayName} in workspace ${record.workspace}.`,
+		`Run key: ${record.runKey}`,
+		"The run is registered and going. This call returned at that point rather than waiting for the launcher process to exit."
+	].join("\n");
+}
+/**
+* What the caller is told when the launch was handed off but no run has
+* registered inside the acknowledgement budget.
+*
+* Deliberately not an error: the launcher is slow rather than broken often
+* enough that failing here would strand runs that go on to start normally.
+* There is no run key to offer yet, so it points at the surfaces that do not
+* need one.
+*/
+function launchHandoffSummary(workflowPath) {
+	return [
+		`Launch handed off for ${workflowPath}, but no run has registered yet.`,
+		"Nothing was cancelled: the launcher is still starting, and a run that registers later still reports back here when it finishes.",
+		"Do not launch it again. Ask the user to check the active workflow list if they need to see it sooner."
+	].join("\n");
+}
+/**
+* Escape sequences a terminal consumes rather than prints.
+*
+* Built from a string with the rule silenced, the way `doom-runner`'s own
+* scrubber does it, because matching the escape byte is the entire job. Not
+* imported from there: that package's published build is a stale artifact
+* missing the export, and a launch notice should not need another package's
+* build to be current.
+*/
+const ESCAPE_SEQUENCE = new RegExp([
+	"\\u001B\\[[0-9;?]*[ -/]*[@-~]",
+	"\\u001B\\][^\\u0007\\u001B]*(?:\\u0007|\\u001B\\\\)",
+	"\\u001B[@-Z\\\\-_]"
+].join("|"), "g");
+/** Rows made only of box-drawing: separators that carry nothing once trimmed. */
+const RULE_ROW = /^[\s─-╿]*$/u;
+const NOTICE_LINE_LIMIT = 3;
+/**
+* Widest a notice row may be before it is clipped.
+*
+* A three-line cap does not bound a toast on its own: the engine announces its
+* delegation by echoing the whole shell command, temp script path included, and
+* one line of that wraps across three rows of a narrow terminal and shoves the
+* transcript around. Clipped at a width every terminal can hold instead.
+*/
+const NOTICE_WIDTH_LIMIT = 100;
+/**
+* Cut a tool result down to something a toast can hold.
+*
+* The launch result used to reach `ui.notify` whole, and for a workflow that
+* executes in this process that result is the engine's entire console log:
+* banner, run directory, job tree, rules, colour. Pi rendered every line of it
+* over the transcript, which reads as a broken screen rather than as output.
+* Escape sequences go first: the log carries colour the notification would
+* render as literal text, and a stray clear or cursor-move would do to the
+* screen exactly what this function exists to prevent.
+*/
+function launchNotice(text, limit = NOTICE_LINE_LIMIT) {
+	const lines = text.replace(ESCAPE_SEQUENCE, "").split("\n").map((line) => line.trimEnd()).filter((line) => line.trim().length > 0 && !RULE_ROW.test(line)).map((line) => line.length > NOTICE_WIDTH_LIMIT ? `${line.slice(0, 99)}…` : line);
+	if (lines.length === 0) return "Workflow started.";
+	if (lines.length <= limit) return lines.join("\n");
+	return [...lines.slice(0, limit), `… ${lines.length - limit} more lines, in the run's own output.`].join("\n");
+}
+/** Flatten MCP tool content to text for Pi. */
+function toolResultText(result) {
+	return result.content.map((part) => part.type === "text" ? part.text : "").filter(Boolean).join("\n").trim();
+}
+/**
+* Convert an MCP tool result into a Pi tool result.
+*
+* Pi signals tool failure by throwing: the agent loop catches it and builds the
+* error result. So an `isError` MCP result becomes a thrown error rather than a
+* successful result carrying a flag Pi would ignore.
+*/
+function toAgentToolResult(tool, result, errorOptions = []) {
+	const text = toolResultText(result) || "No output.";
+	if (result.isError) throw new Error(withOptions(text, errorOptions));
+	return {
+		content: [{
+			type: "text",
+			text
+		}],
+		details: { tool }
+	};
+}
+/**
+* Attach a short menu of next steps to a problem.
+*
+* An error with no route forward is where an agent invents one: retrying a
+* capacity limit, relaunching a run that should be recovered, or silently
+* giving up on work the user is waiting for. Naming two or three real options
+* turns an error into a decision, and the decision belongs to the user.
+*/
+function withOptions(problem, options) {
+	if (options.length === 0) return problem;
+	return [
+		problem,
+		"",
+		"Options, put these to the user rather than picking one yourself:",
+		...options.map(bullet)
+	].join("\n");
+}
+function bullet(option) {
+	return `- ${option}`;
+}
+/** The job and step a run died on, preferring the progress log to the record. */
+function failurePosition(record, jobs) {
+	const failedJob = jobs.find((job) => job.status === "failed");
+	const failedStep = failedJob?.steps.find((step) => step.status === "failed");
+	return {
+		job: failedJob?.name ?? record.failedJob,
+		step: failedStep?.name,
+		reason: failedStep?.reason ?? failedJob?.reason
+	};
+}
+/**
+* Describe a finished run for the agent that launched it.
+*
+* Carries the job identifiers back so a dispatching agent can match the run to
+* the work item it launched it for without another lookup. When the run failed,
+* carries the failing step and a set of options too: the agent is being told
+* about this out of band, with no user question in flight, so without them it
+* has to guess whether to recover, relaunch, or report.
+*/
+function finishedRunSummary(record, jobs = []) {
+	const outcome = record.stage === "completed" ? "completed" : `ended in ${record.stage}`;
+	const failure = failurePosition(record, jobs);
+	const lines = [
+		`Workflow run ${record.runKey} in workspace ${record.workspace} ${outcome}.`,
+		record.workflowId ? `Workflow: ${record.workflowId}` : void 0,
+		failure.job ? `Failed job: ${failure.job}${failure.step ? ` (step: ${failure.step})` : ""}` : void 0,
+		record.errorMessage ? `Error: ${record.errorMessage}` : void 0,
+		failure.reason && failure.reason !== record.errorMessage ? `Step reported: ${failure.reason}` : void 0
+	];
+	const jobId = record.env?.AGIFLOW_JOB_ID;
+	if (jobId) lines.push(`Agiflow job: ${record.env?.AGIFLOW_JOB_KIND ?? "unknown"} ${jobId}`);
+	const summary = lines.filter((line) => Boolean(line)).join("\n");
+	if (record.stage === "completed") return summary;
+	if (record.outcome === "interrupted") return withOptions(summary, [`workflow_run {"action":"recover","runKey":${JSON.stringify(record.runKey)}}: pick it up where it stopped.`, "Leave it stopped and move on."]);
+	const diagnosticText = [record.errorMessage, failure.reason].filter(Boolean).join("\n");
+	if (diagnosticText.includes("JOB_ALREADY_CLAIMED")) return withOptions(summary, ["Report contention: another worker owns this job. Do not unlock, release, or retry the claim automatically."]);
+	if (diagnosticText.includes("WORKFLOW_NOT_OWNED") || /release failed/i.test(diagnosticText)) return withOptions(summary, ["Inspect the current workflow ownership and ask the user before any release or unlock. Never force another worker’s lock."]);
+	if (/running workflow not found/i.test(diagnosticText)) return withOptions(summary, [`workflow_run {"action":"status","runKey":${JSON.stringify(record.runKey)}}: re-check current state before retrying.`, "Report the recorded terminal state when no running owner remains."]);
+	return withOptions(summary, [
+		`workflow_run {"action":"tail","runKey":${JSON.stringify(record.runKey)}}: read the run's own output first, when the error above does not explain the failure.`,
+		`workflow_run {"action":"recover","runKey":${JSON.stringify(record.runKey)}}: resume from the failed job, keeping the work already done. Fits a transient or external cause.`,
+		"Report the failure and stop, when it needs a code change or a decision you cannot make."
+	]);
+}
+//#endregion
+export { PI_SESSION_ENV, finishedRunSummary, isSessionRun, launchHandoffSummary, launchNotice, launchedRunSummary, resolveMaxConcurrent, runsForSession, toAgentToolResult, toolResultText, withOptions };
+
+//# sourceMappingURL=index.mjs.map

package/dist/src/services/piToolBridge/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.mjs","names":[],"sources":["../../../../src/services/piToolBridge/index.ts"],"sourcesContent":["/**\n * Pure bridging logic between MCP tool results and the Pi tool surface.\n *\n * DESIGN PATTERNS:\n * - Adapter pattern: MCP `CallToolResult` is converted to Pi's result shape\n * - Pure module: no service or tool-class imports, so this is unit-testable\n *   without constructing the workflow execution stack\n *\n * CODING STANDARDS:\n * - Named exports only\n * - Explicit return types on exported functions\n *\n * AVOID:\n * - Importing tool classes or services here (that belongs in `piTools.ts`)\n * - Returning an error flag Pi does not read; Pi tools signal failure by throwing\n */\n\nimport type { WorkflowProgressJob, WorkflowRunRecord } from '@agimon-ai/workflow-mcp';\nimport type { AgentToolResult } from '@earendil-works/pi-coding-agent';\nimport type { CallToolResult } from '@modelcontextprotocol/sdk/types.js';\n\n/**\n * Environment variable stamped onto every run launched from a Pi session.\n *\n * `RunWorkflowService` forwards `env` to the inner CLI invocation across the\n * `launch-command` delegation boundary and persists it on the run record, so\n * this survives backgrounding and identifies the launching session afterwards.\n */\nexport const PI_SESSION_ENV = 'PI_SESSION_ID';\n\n/** Operator override for the per-session launch ceiling. */\nconst MAX_CONCURRENT_ENV = 'WORKFLOW_MCP_MAX_CONCURRENT';\nconst DEFAULT_MAX_CONCURRENT = 5;\n\nexport interface WorkflowToolDetails {\n  tool: string;\n}\n\n/** Resolve the per-session launch ceiling from the environment. */\nexport function resolveMaxConcurrent(env: NodeJS.ProcessEnv = process.env): number {\n  const parsed = Number(env[MAX_CONCURRENT_ENV]);\n  return Number.isInteger(parsed) && parsed > 0 ? parsed : DEFAULT_MAX_CONCURRENT;\n}\n\n/**\n * True when this session launched the run.\n *\n * Fails closed on a missing session id: an unstamped record (a CLI launch) and\n * a call arriving before the session id is known both match nothing, so no run\n * ever leaks across sessions through an undefined-equals-undefined comparison.\n */\nexport function isSessionRun(record: WorkflowRunRecord, sessionId: string | undefined): boolean {\n  return sessionId !== undefined && record.env?.[PI_SESSION_ENV] === sessionId;\n}\n\n/** Runs launched by one Pi session that are still running. */\nexport function runsForSession(records: WorkflowRunRecord[], sessionId: string): WorkflowRunRecord[] {\n  return records.filter((record) => isSessionRun(record, sessionId) && record.stage === 'running');\n}\n\n/**\n * What the caller is told when the registry, not the launcher, acknowledged a\n * launch.\n *\n * Leads with the run key because it is the handle every other workflow action\n * takes, and it is no longer available any other way: the launcher's own output\n * is not waited for, so nothing else in this result carries it.\n */\nexport function launchedRunSummary(record: WorkflowRunRecord): string {\n  return [\n    `Started ${record.displayName} in workspace ${record.workspace}.`,\n    `Run key: ${record.runKey}`,\n    'The run is registered and going. This call returned at that point rather than waiting for the launcher process to exit.',\n  ].join('\\n');\n}\n\n/**\n * What the caller is told when the launch was handed off but no run has\n * registered inside the acknowledgement budget.\n *\n * Deliberately not an error: the launcher is slow rather than broken often\n * enough that failing here would strand runs that go on to start normally.\n * There is no run key to offer yet, so it points at the surfaces that do not\n * need one.\n */\nexport function launchHandoffSummary(workflowPath: string): string {\n  return [\n    `Launch handed off for ${workflowPath}, but no run has registered yet.`,\n    'Nothing was cancelled: the launcher is still starting, and a run that registers later still reports back here when it finishes.',\n    'Do not launch it again. Ask the user to check the active workflow list if they need to see it sooner.',\n  ].join('\\n');\n}\n\n/**\n * Escape sequences a terminal consumes rather than prints.\n *\n * Built from a string with the rule silenced, the way `doom-runner`'s own\n * scrubber does it, because matching the escape byte is the entire job. Not\n * imported from there: that package's published build is a stale artifact\n * missing the export, and a launch notice should not need another package's\n * build to be current.\n */\n// oxlint-disable-next-line no-control-regex -- matching terminal control bytes is the point\nconst ESCAPE_SEQUENCE = new RegExp(\n  ['\\\\u001B\\\\[[0-9;?]*[ -/]*[@-~]', '\\\\u001B\\\\][^\\\\u0007\\\\u001B]*(?:\\\\u0007|\\\\u001B\\\\\\\\)', '\\\\u001B[@-Z\\\\\\\\-_]'].join(\n    '|',\n  ),\n  'g',\n);\n\n/** Rows made only of box-drawing: separators that carry nothing once trimmed. */\nconst RULE_ROW = /^[\\s─-╿]*$/u;\nconst NOTICE_LINE_LIMIT = 3;\n/**\n * Widest a notice row may be before it is clipped.\n *\n * A three-line cap does not bound a toast on its own: the engine announces its\n * delegation by echoing the whole shell command, temp script path included, and\n * one line of that wraps across three rows of a narrow terminal and shoves the\n * transcript around. Clipped at a width every terminal can hold instead.\n */\nconst NOTICE_WIDTH_LIMIT = 100;\n\n/**\n * Cut a tool result down to something a toast can hold.\n *\n * The launch result used to reach `ui.notify` whole, and for a workflow that\n * executes in this process that result is the engine's entire console log:\n * banner, run directory, job tree, rules, colour. Pi rendered every line of it\n * over the transcript, which reads as a broken screen rather than as output.\n * Escape sequences go first: the log carries colour the notification would\n * render as literal text, and a stray clear or cursor-move would do to the\n * screen exactly what this function exists to prevent.\n */\nexport function launchNotice(text: string, limit: number = NOTICE_LINE_LIMIT): string {\n  const lines = text\n    .replace(ESCAPE_SEQUENCE, '')\n    .split('\\n')\n    .map((line) => line.trimEnd())\n    .filter((line) => line.trim().length > 0 && !RULE_ROW.test(line))\n    .map((line) => (line.length > NOTICE_WIDTH_LIMIT ? `${line.slice(0, NOTICE_WIDTH_LIMIT - 1)}…` : line));\n  if (lines.length === 0) return 'Workflow started.';\n  if (lines.length <= limit) return lines.join('\\n');\n  return [...lines.slice(0, limit), `… ${lines.length - limit} more lines, in the run's own output.`].join('\\n');\n}\n\n/** Flatten MCP tool content to text for Pi. */\nexport function toolResultText(result: CallToolResult): string {\n  return result.content\n    .map((part) => (part.type === 'text' ? part.text : ''))\n    .filter(Boolean)\n    .join('\\n')\n    .trim();\n}\n\n/**\n * Convert an MCP tool result into a Pi tool result.\n *\n * Pi signals tool failure by throwing: the agent loop catches it and builds the\n * error result. So an `isError` MCP result becomes a thrown error rather than a\n * successful result carrying a flag Pi would ignore.\n */\nexport function toAgentToolResult(\n  tool: string,\n  result: CallToolResult,\n  errorOptions: string[] = [],\n): AgentToolResult<WorkflowToolDetails> {\n  const text = toolResultText(result) || 'No output.';\n  if (result.isError) throw new Error(withOptions(text, errorOptions));\n  return { content: [{ type: 'text', text }], details: { tool } };\n}\n\n/**\n * Attach a short menu of next steps to a problem.\n *\n * An error with no route forward is where an agent invents one: retrying a\n * capacity limit, relaunching a run that should be recovered, or silently\n * giving up on work the user is waiting for. Naming two or three real options\n * turns an error into a decision, and the decision belongs to the user.\n */\nexport function withOptions(problem: string, options: string[]): string {\n  if (options.length === 0) return problem;\n  return [problem, '', 'Options, put these to the user rather than picking one yourself:', ...options.map(bullet)].join(\n    '\\n',\n  );\n}\n\nfunction bullet(option: string): string {\n  return `- ${option}`;\n}\n\n/** The job and step a run died on, preferring the progress log to the record. */\nfunction failurePosition(\n  record: WorkflowRunRecord,\n  jobs: WorkflowProgressJob[],\n): { job?: string; step?: string; reason?: string } {\n  // The progress log knows which step was in flight; the record only names the\n  // job. Falling back keeps this working for runs that predate the log.\n  const failedJob = jobs.find((job) => job.status === 'failed');\n  const failedStep = failedJob?.steps.find((step) => step.status === 'failed');\n  return {\n    job: failedJob?.name ?? record.failedJob,\n    step: failedStep?.name,\n    reason: failedStep?.reason ?? failedJob?.reason,\n  };\n}\n\n/**\n * Describe a finished run for the agent that launched it.\n *\n * Carries the job identifiers back so a dispatching agent can match the run to\n * the work item it launched it for without another lookup. When the run failed,\n * carries the failing step and a set of options too: the agent is being told\n * about this out of band, with no user question in flight, so without them it\n * has to guess whether to recover, relaunch, or report.\n */\nexport function finishedRunSummary(record: WorkflowRunRecord, jobs: WorkflowProgressJob[] = []): string {\n  const outcome = record.stage === 'completed' ? 'completed' : `ended in ${record.stage}`;\n  const failure = failurePosition(record, jobs);\n  const lines: Array<string | undefined> = [\n    `Workflow run ${record.runKey} in workspace ${record.workspace} ${outcome}.`,\n    record.workflowId ? `Workflow: ${record.workflowId}` : undefined,\n    failure.job ? `Failed job: ${failure.job}${failure.step ? ` (step: ${failure.step})` : ''}` : undefined,\n    record.errorMessage ? `Error: ${record.errorMessage}` : undefined,\n    failure.reason && failure.reason !== record.errorMessage ? `Step reported: ${failure.reason}` : undefined,\n  ];\n  const jobId = record.env?.AGIFLOW_JOB_ID;\n  if (jobId) lines.push(`Agiflow job: ${record.env?.AGIFLOW_JOB_KIND ?? 'unknown'} ${jobId}`);\n\n  const summary = lines.filter((line): line is string => Boolean(line)).join('\\n');\n  if (record.stage === 'completed') return summary;\n\n  // A run the user stopped is not a defect, so it gets no diagnosis step: the\n  // question is only whether to pick it back up.\n  const stopped = record.outcome === 'interrupted';\n  if (stopped) {\n    return withOptions(summary, [\n      `workflow_run {\"action\":\"recover\",\"runKey\":${JSON.stringify(record.runKey)}}: pick it up where it stopped.`,\n      'Leave it stopped and move on.',\n    ]);\n  }\n\n  const diagnosticText = [record.errorMessage, failure.reason].filter(Boolean).join('\\n');\n  if (diagnosticText.includes('JOB_ALREADY_CLAIMED')) {\n    return withOptions(summary, [\n      'Report contention: another worker owns this job. Do not unlock, release, or retry the claim automatically.',\n    ]);\n  }\n  if (diagnosticText.includes('WORKFLOW_NOT_OWNED') || /release failed/i.test(diagnosticText)) {\n    return withOptions(summary, [\n      'Inspect the current workflow ownership and ask the user before any release or unlock. Never force another worker’s lock.',\n    ]);\n  }\n  if (/running workflow not found/i.test(diagnosticText)) {\n    return withOptions(summary, [\n      `workflow_run {\"action\":\"status\",\"runKey\":${JSON.stringify(record.runKey)}}: re-check current state before retrying.`,\n      'Report the recorded terminal state when no running owner remains.',\n    ]);\n  }\n\n  return withOptions(summary, [\n    `workflow_run {\"action\":\"tail\",\"runKey\":${JSON.stringify(record.runKey)}}: read the run's own output first, when the error above does not explain the failure.`,\n    `workflow_run {\"action\":\"recover\",\"runKey\":${JSON.stringify(record.runKey)}}: resume from the failed job, keeping the work already done. Fits a transient or external cause.`,\n    'Report the failure and stop, when it needs a code change or a decision you cannot make.',\n  ]);\n}\n"],"mappings":";;;;;;;;AA4BA,MAAa,iBAAiB;;AAG9B,MAAM,qBAAqB;AAC3B,MAAM,yBAAyB;;AAO/B,SAAgB,qBAAqB,MAAyB,QAAQ,KAAa;CACjF,MAAM,SAAS,OAAO,IAAI,mBAAmB;CAC7C,OAAO,OAAO,UAAU,MAAM,KAAK,SAAS,IAAI,SAAS;AAC3D;;;;;;;;AASA,SAAgB,aAAa,QAA2B,WAAwC;CAC9F,OAAO,cAAc,KAAA,KAAa,OAAO,MAAA,qBAA0B;AACrE;;AAGA,SAAgB,eAAe,SAA8B,WAAwC;CACnG,OAAO,QAAQ,QAAQ,WAAW,aAAa,QAAQ,SAAS,KAAK,OAAO,UAAU,SAAS;AACjG;;;;;;;;;AAUA,SAAgB,mBAAmB,QAAmC;CACpE,OAAO;EACL,WAAW,OAAO,YAAY,gBAAgB,OAAO,UAAU;EAC/D,YAAY,OAAO;EACnB;CACF,CAAC,CAAC,KAAK,IAAI;AACb;;;;;;;;;;AAWA,SAAgB,qBAAqB,cAA8B;CACjE,OAAO;EACL,yBAAyB,aAAa;EACtC;EACA;CACF,CAAC,CAAC,KAAK,IAAI;AACb;;;;;;;;;;AAYA,MAAM,kBAAkB,IAAI,OAC1B;CAAC;CAAiC;CAAuD;AAAoB,CAAC,CAAC,KAC7G,GACF,GACA,GACF;;AAGA,MAAM,WAAW;AACjB,MAAM,oBAAoB;;;;;;;;;AAS1B,MAAM,qBAAqB;;;;;;;;;;;;AAa3B,SAAgB,aAAa,MAAc,QAAgB,mBAA2B;CACpF,MAAM,QAAQ,KACX,QAAQ,iBAAiB,EAAE,CAAC,CAC5B,MAAM,IAAI,CAAC,CACX,KAAK,SAAS,KAAK,QAAQ,CAAC,CAAC,CAC7B,QAAQ,SAAS,KAAK,KAAK,CAAC,CAAC,SAAS,KAAK,CAAC,SAAS,KAAK,IAAI,CAAC,CAAC,CAChE,KAAK,SAAU,KAAK,SAAS,qBAAqB,GAAG,KAAK,MAAM,GAAG,EAAsB,EAAE,KAAK,IAAK;CACxG,IAAI,MAAM,WAAW,GAAG,OAAO;CAC/B,IAAI,MAAM,UAAU,OAAO,OAAO,MAAM,KAAK,IAAI;CACjD,OAAO,CAAC,GAAG,MAAM,MAAM,GAAG,KAAK,GAAG,KAAK,MAAM,SAAS,MAAM,sCAAsC,CAAC,CAAC,KAAK,IAAI;AAC/G;;AAGA,SAAgB,eAAe,QAAgC;CAC7D,OAAO,OAAO,QACX,KAAK,SAAU,KAAK,SAAS,SAAS,KAAK,OAAO,EAAG,CAAC,CACtD,OAAO,OAAO,CAAC,CACf,KAAK,IAAI,CAAC,CACV,KAAK;AACV;;;;;;;;AASA,SAAgB,kBACd,MACA,QACA,eAAyB,CAAC,GACY;CACtC,MAAM,OAAO,eAAe,MAAM,KAAK;CACvC,IAAI,OAAO,SAAS,MAAM,IAAI,MAAM,YAAY,MAAM,YAAY,CAAC;CACnE,OAAO;EAAE,SAAS,CAAC;GAAE,MAAM;GAAQ;EAAK,CAAC;EAAG,SAAS,EAAE,KAAK;CAAE;AAChE;;;;;;;;;AAUA,SAAgB,YAAY,SAAiB,SAA2B;CACtE,IAAI,QAAQ,WAAW,GAAG,OAAO;CACjC,OAAO;EAAC;EAAS;EAAI;EAAoE,GAAG,QAAQ,IAAI,MAAM;CAAC,CAAC,CAAC,KAC/G,IACF;AACF;AAEA,SAAS,OAAO,QAAwB;CACtC,OAAO,KAAK;AACd;;AAGA,SAAS,gBACP,QACA,MACkD;CAGlD,MAAM,YAAY,KAAK,MAAM,QAAQ,IAAI,WAAW,QAAQ;CAC5D,MAAM,aAAa,WAAW,MAAM,MAAM,SAAS,KAAK,WAAW,QAAQ;CAC3E,OAAO;EACL,KAAK,WAAW,QAAQ,OAAO;EAC/B,MAAM,YAAY;EAClB,QAAQ,YAAY,UAAU,WAAW;CAC3C;AACF;;;;;;;;;;AAWA,SAAgB,mBAAmB,QAA2B,OAA8B,CAAC,GAAW;CACtG,MAAM,UAAU,OAAO,UAAU,cAAc,cAAc,YAAY,OAAO;CAChF,MAAM,UAAU,gBAAgB,QAAQ,IAAI;CAC5C,MAAM,QAAmC;EACvC,gBAAgB,OAAO,OAAO,gBAAgB,OAAO,UAAU,GAAG,QAAQ;EAC1E,OAAO,aAAa,aAAa,OAAO,eAAe,KAAA;EACvD,QAAQ,MAAM,eAAe,QAAQ,MAAM,QAAQ,OAAO,WAAW,QAAQ,KAAK,KAAK,OAAO,KAAA;EAC9F,OAAO,eAAe,UAAU,OAAO,iBAAiB,KAAA;EACxD,QAAQ,UAAU,QAAQ,WAAW,OAAO,eAAe,kBAAkB,QAAQ,WAAW,KAAA;CAClG;CACA,MAAM,QAAQ,OAAO,KAAK;CAC1B,IAAI,OAAO,MAAM,KAAK,gBAAgB,OAAO,KAAK,oBAAoB,UAAU,GAAG,OAAO;CAE1F,MAAM,UAAU,MAAM,QAAQ,SAAyB,QAAQ,IAAI,CAAC,CAAC,CAAC,KAAK,IAAI;CAC/E,IAAI,OAAO,UAAU,aAAa,OAAO;CAKzC,IADgB,OAAO,YAAY,eAEjC,OAAO,YAAY,SAAS,CAC1B,6CAA6C,KAAK,UAAU,OAAO,MAAM,EAAE,kCAC3E,+BACF,CAAC;CAGH,MAAM,iBAAiB,CAAC,OAAO,cAAc,QAAQ,MAAM,CAAC,CAAC,OAAO,OAAO,CAAC,CAAC,KAAK,IAAI;CACtF,IAAI,eAAe,SAAS,qBAAqB,GAC/C,OAAO,YAAY,SAAS,CAC1B,4GACF,CAAC;CAEH,IAAI,eAAe,SAAS,oBAAoB,KAAK,kBAAkB,KAAK,cAAc,GACxF,OAAO,YAAY,SAAS,CAC1B,0HACF,CAAC;CAEH,IAAI,8BAA8B,KAAK,cAAc,GACnD,OAAO,YAAY,SAAS,CAC1B,4CAA4C,KAAK,UAAU,OAAO,MAAM,EAAE,6CAC1E,mEACF,CAAC;CAGH,OAAO,YAAY,SAAS;EAC1B,0CAA0C,KAAK,UAAU,OAAO,MAAM,EAAE;EACxE,6CAA6C,KAAK,UAAU,OAAO,MAAM,EAAE;EAC3E;CACF,CAAC;AACH"}