@femtomc/mu-agent 26.2.41 → 26.2.42

package/dist/command_context.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"command_context.d.ts","sourceRoot":"","sources":["../src/command_context.ts"],"names":[],"mappings":"AAEA,MAAM,MAAM,uBAAuB,GAAG,UAAU,GAAG,cAAc,GAAG,MAAM,CAAC;AAE3E,MAAM,MAAM,8BAA8B,GACvC,iBAAiB,GACjB,mBAAmB,GACnB,sBAAsB,GACtB,uBAAuB,CAAC;AAE3B,MAAM,MAAM,yBAAyB,GAClC;IACA,IAAI,EAAE,UAAU,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,cAAc,EAAE,MAAM,CAAC;IACvB,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,uBAAuB,CAAC;CAC/B,GACD;IACA,IAAI,EAAE,QAAQ,CAAC;IACf,MAAM,EAAE,8BAA8B,CAAC;IACvC,OAAO,CAAC,EAAE,MAAM,CAAC;CAChB,CAAC;AAEL,MAAM,MAAM,0BAA0B,GAAG;IACxC,gBAAgB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CACrC,CAAC;AAsJF,qBAAa,sBAAsB;;gBAGf,IAAI,GAAE,0BAA+B;IAQjD,OAAO,CAAC,IAAI,EAAE;QACpB,QAAQ,EAAE,MAAM,CAAC;QACjB,UAAU,EAAE,MAAM,CAAC;QACnB,IAAI,EAAE,SAAS,MAAM,EAAE,CAAC;QACxB,iBAAiB,EAAE,MAAM,CAAC;QAC1B,eAAe,EAAE,MAAM,CAAC;QACxB,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;KAClC,GAAG,yBAAyB;CAqG7B"}
+{"version":3,"file":"command_context.d.ts","sourceRoot":"","sources":["../src/command_context.ts"],"names":[],"mappings":"AAEA,MAAM,MAAM,uBAAuB,GAAG,UAAU,GAAG,cAAc,GAAG,MAAM,CAAC;AAE3E,MAAM,MAAM,8BAA8B,GACvC,iBAAiB,GACjB,mBAAmB,GACnB,sBAAsB,GACtB,uBAAuB,CAAC;AAE3B,MAAM,MAAM,yBAAyB,GAClC;IACA,IAAI,EAAE,UAAU,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,cAAc,EAAE,MAAM,CAAC;IACvB,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,uBAAuB,CAAC;CAC/B,GACD;IACA,IAAI,EAAE,QAAQ,CAAC;IACf,MAAM,EAAE,8BAA8B,CAAC;IACvC,OAAO,CAAC,EAAE,MAAM,CAAC;CAChB,CAAC;AAEL,MAAM,MAAM,0BAA0B,GAAG;IACxC,gBAAgB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CACrC,CAAC;AAwJF,qBAAa,sBAAsB;;gBAGf,IAAI,GAAE,0BAA+B;IAQjD,OAAO,CAAC,IAAI,EAAE;QACpB,QAAQ,EAAE,MAAM,CAAC;QACjB,UAAU,EAAE,MAAM,CAAC;QACnB,IAAI,EAAE,SAAS,MAAM,EAAE,CAAC;QACxB,iBAAiB,EAAE,MAAM,CAAC;QAC1B,eAAe,EAAE,MAAM,CAAC;QACxB,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;KAClC,GAAG,yBAAyB;CAqG7B"}

package/dist/command_context.js

@@ -8,6 +8,8 @@ const ISSUE_TARGET_COMMANDS = new Set([
     "issue claim",
     "issue close",
     "run resume",
+    "run status",
+    "run interrupt",
 ]);
 const TOPIC_TARGET_COMMANDS = new Set(["forum read", "forum post"]);
 const GENERIC_TARGET_COMMANDS = new Set(["audit get", "dlq inspect", "dlq replay"]);

package/dist/extensions/activities.d.ts

@@ -0,0 +1,4 @@
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+export declare function activitiesExtension(pi: ExtensionAPI): void;
+export default activitiesExtension;
+//# sourceMappingURL=activities.d.ts.map

package/dist/extensions/activities.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"activities.d.ts","sourceRoot":"","sources":["../../src/extensions/activities.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,+BAA+B,CAAC;AAUlE,wBAAgB,mBAAmB,CAAC,EAAE,EAAE,YAAY,QAmHnD;AAED,eAAe,mBAAmB,CAAC"}

package/dist/extensions/activities.js

@@ -0,0 +1,125 @@
+import { StringEnum } from "@mariozechner/pi-ai";
+import { Type } from "@sinclair/typebox";
+import { clampInt, fetchMuJson, textResult, toJsonText } from "./shared.js";
+function trimOrNull(value) {
+    if (value == null)
+        return null;
+    const trimmed = value.trim();
+    return trimmed.length > 0 ? trimmed : null;
+}
+export function activitiesExtension(pi) {
+    const ActivitiesParams = Type.Object({
+        action: StringEnum(["list", "get", "start", "progress", "heartbeat", "complete", "fail", "cancel", "events"]),
+        activity_id: Type.Optional(Type.String({ description: "Activity ID" })),
+        title: Type.Optional(Type.String({ description: "Title for start" })),
+        kind: Type.Optional(Type.String({ description: "Activity kind for start/list filtering" })),
+        heartbeat_every_ms: Type.Optional(Type.Number({ description: "Heartbeat interval in ms for start" })),
+        status: Type.Optional(Type.String({ description: "Status filter for list" })),
+        message: Type.Optional(Type.String({ description: "Progress/final message" })),
+        reason: Type.Optional(Type.String({ description: "Heartbeat reason" })),
+        limit: Type.Optional(Type.Number({ description: "Optional limit for list/events" })),
+    });
+    pi.registerTool({
+        name: "mu_activities",
+        label: "Activities",
+        description: "Manage generic long-running activities. Actions: list, get, start, progress, heartbeat, complete, fail, cancel, events.",
+        parameters: ActivitiesParams,
+        async execute(_toolCallId, params) {
+            switch (params.action) {
+                case "list": {
+                    const query = new URLSearchParams();
+                    const status = trimOrNull(params.status);
+                    const kind = trimOrNull(params.kind);
+                    const limit = clampInt(params.limit, 50, 1, 500);
+                    if (status)
+                        query.set("status", status);
+                    if (kind)
+                        query.set("kind", kind);
+                    query.set("limit", String(limit));
+                    const payload = await fetchMuJson(`/api/activities?${query.toString()}`);
+                    return textResult(toJsonText(payload), { action: "list", status, kind, limit });
+                }
+                case "get": {
+                    const activityId = trimOrNull(params.activity_id);
+                    if (!activityId)
+                        return textResult("get requires activity_id");
+                    const payload = await fetchMuJson(`/api/activities/${encodeURIComponent(activityId)}`);
+                    return textResult(toJsonText(payload), { action: "get", activityId });
+                }
+                case "events": {
+                    const activityId = trimOrNull(params.activity_id);
+                    if (!activityId)
+                        return textResult("events requires activity_id");
+                    const limit = clampInt(params.limit, 200, 1, 2_000);
+                    const payload = await fetchMuJson(`/api/activities/${encodeURIComponent(activityId)}/events?limit=${limit}`);
+                    return textResult(toJsonText(payload), { action: "events", activityId, limit });
+                }
+                case "start": {
+                    const title = trimOrNull(params.title);
+                    if (!title)
+                        return textResult("start requires title");
+                    const kind = trimOrNull(params.kind);
+                    const heartbeatEveryMs = params.heartbeat_every_ms != null && Number.isFinite(params.heartbeat_every_ms)
+                        ? Math.max(0, Math.trunc(params.heartbeat_every_ms))
+                        : undefined;
+                    const payload = await fetchMuJson("/api/activities/start", {
+                        method: "POST",
+                        body: {
+                            title,
+                            kind,
+                            heartbeat_every_ms: heartbeatEveryMs,
+                        },
+                    });
+                    return textResult(toJsonText(payload), { action: "start", title, kind, heartbeatEveryMs });
+                }
+                case "progress": {
+                    const activityId = trimOrNull(params.activity_id);
+                    if (!activityId)
+                        return textResult("progress requires activity_id");
+                    const message = trimOrNull(params.message) ?? "progress updated";
+                    const payload = await fetchMuJson("/api/activities/progress", {
+                        method: "POST",
+                        body: {
+                            activity_id: activityId,
+                            message,
+                        },
+                    });
+                    return textResult(toJsonText(payload), { action: "progress", activityId, message });
+                }
+                case "heartbeat": {
+                    const activityId = trimOrNull(params.activity_id);
+                    if (!activityId)
+                        return textResult("heartbeat requires activity_id");
+                    const reason = trimOrNull(params.reason) ?? "manual";
+                    const payload = await fetchMuJson("/api/activities/heartbeat", {
+                        method: "POST",
+                        body: {
+                            activity_id: activityId,
+                            reason,
+                        },
+                    });
+                    return textResult(toJsonText(payload), { action: "heartbeat", activityId, reason });
+                }
+                case "complete":
+                case "fail":
+                case "cancel": {
+                    const activityId = trimOrNull(params.activity_id);
+                    if (!activityId)
+                        return textResult(`${params.action} requires activity_id`);
+                    const message = trimOrNull(params.message);
+                    const payload = await fetchMuJson(`/api/activities/${params.action}`, {
+                        method: "POST",
+                        body: {
+                            activity_id: activityId,
+                            message,
+                        },
+                    });
+                    return textResult(toJsonText(payload), { action: params.action, activityId, message });
+                }
+                default:
+                    return textResult(`unknown action: ${params.action}`);
+            }
+        },
+    });
+}
+export default activitiesExtension;

package/dist/extensions/heartbeats.d.ts

@@ -0,0 +1,4 @@
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+export declare function heartbeatsExtension(pi: ExtensionAPI): void;
+export default heartbeatsExtension;
+//# sourceMappingURL=heartbeats.d.ts.map

package/dist/extensions/heartbeats.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"heartbeats.d.ts","sourceRoot":"","sources":["../../src/extensions/heartbeats.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,+BAA+B,CAAC;AAUlE,wBAAgB,mBAAmB,CAAC,EAAE,EAAE,YAAY,QAyInD;AAED,eAAe,mBAAmB,CAAC"}

package/dist/extensions/heartbeats.js

@@ -0,0 +1,149 @@
+import { StringEnum } from "@mariozechner/pi-ai";
+import { Type } from "@sinclair/typebox";
+import { clampInt, fetchMuJson, textResult, toJsonText } from "./shared.js";
+function trimOrNull(value) {
+    if (value == null)
+        return null;
+    const trimmed = value.trim();
+    return trimmed.length > 0 ? trimmed : null;
+}
+export function heartbeatsExtension(pi) {
+    const Params = Type.Object({
+        action: StringEnum(["list", "get", "create", "update", "delete", "trigger", "enable", "disable"]),
+        program_id: Type.Optional(Type.String({ description: "Heartbeat program ID" })),
+        title: Type.Optional(Type.String({ description: "Program title" })),
+        target_kind: Type.Optional(Type.String({ description: "Target kind (run|activity)" })),
+        run_job_id: Type.Optional(Type.String({ description: "Run job ID target" })),
+        run_root_issue_id: Type.Optional(Type.String({ description: "Run root issue ID target" })),
+        activity_id: Type.Optional(Type.String({ description: "Activity ID target" })),
+        every_ms: Type.Optional(Type.Number({ description: "Heartbeat interval in ms" })),
+        reason: Type.Optional(Type.String({ description: "Heartbeat reason" })),
+        enabled: Type.Optional(Type.Boolean({ description: "Enabled state" })),
+        limit: Type.Optional(Type.Number({ description: "Max returned items for list" })),
+    });
+    pi.registerTool({
+        name: "mu_heartbeats",
+        label: "Heartbeats",
+        description: "Program and manage persistent heartbeat schedules. Actions: list, get, create, update, delete, trigger, enable, disable.",
+        parameters: Params,
+        async execute(_toolCallId, params) {
+            switch (params.action) {
+                case "list": {
+                    const query = new URLSearchParams();
+                    const targetKind = trimOrNull(params.target_kind);
+                    if (targetKind) {
+                        query.set("target_kind", targetKind);
+                    }
+                    if (typeof params.enabled === "boolean") {
+                        query.set("enabled", params.enabled ? "true" : "false");
+                    }
+                    query.set("limit", String(clampInt(params.limit, 50, 1, 500)));
+                    const payload = await fetchMuJson(`/api/heartbeats?${query.toString()}`);
+                    return textResult(toJsonText(payload), {
+                        action: "list",
+                        targetKind,
+                        enabled: params.enabled,
+                    });
+                }
+                case "get": {
+                    const programId = trimOrNull(params.program_id);
+                    if (!programId)
+                        return textResult("get requires program_id");
+                    const payload = await fetchMuJson(`/api/heartbeats/${encodeURIComponent(programId)}`);
+                    return textResult(toJsonText(payload), { action: "get", programId });
+                }
+                case "create": {
+                    const title = trimOrNull(params.title);
+                    const targetKind = trimOrNull(params.target_kind);
+                    if (!title)
+                        return textResult("create requires title");
+                    if (!targetKind)
+                        return textResult("create requires target_kind (run|activity)");
+                    const payload = await fetchMuJson("/api/heartbeats/create", {
+                        method: "POST",
+                        body: {
+                            title,
+                            target_kind: targetKind,
+                            run_job_id: trimOrNull(params.run_job_id),
+                            run_root_issue_id: trimOrNull(params.run_root_issue_id),
+                            activity_id: trimOrNull(params.activity_id),
+                            every_ms: params.every_ms != null && Number.isFinite(params.every_ms)
+                                ? Math.max(0, Math.trunc(params.every_ms))
+                                : undefined,
+                            reason: trimOrNull(params.reason),
+                            enabled: typeof params.enabled === "boolean" ? params.enabled : undefined,
+                        },
+                    });
+                    return textResult(toJsonText(payload), { action: "create", title, targetKind });
+                }
+                case "update": {
+                    const programId = trimOrNull(params.program_id);
+                    if (!programId)
+                        return textResult("update requires program_id");
+                    const payload = await fetchMuJson("/api/heartbeats/update", {
+                        method: "POST",
+                        body: {
+                            program_id: programId,
+                            title: trimOrNull(params.title),
+                            target_kind: trimOrNull(params.target_kind),
+                            run_job_id: trimOrNull(params.run_job_id),
+                            run_root_issue_id: trimOrNull(params.run_root_issue_id),
+                            activity_id: trimOrNull(params.activity_id),
+                            every_ms: params.every_ms != null && Number.isFinite(params.every_ms)
+                                ? Math.max(0, Math.trunc(params.every_ms))
+                                : undefined,
+                            reason: trimOrNull(params.reason),
+                            enabled: typeof params.enabled === "boolean" ? params.enabled : undefined,
+                        },
+                    });
+                    return textResult(toJsonText(payload), { action: "update", programId });
+                }
+                case "delete": {
+                    const programId = trimOrNull(params.program_id);
+                    if (!programId)
+                        return textResult("delete requires program_id");
+                    const payload = await fetchMuJson("/api/heartbeats/delete", {
+                        method: "POST",
+                        body: {
+                            program_id: programId,
+                        },
+                    });
+                    return textResult(toJsonText(payload), { action: "delete", programId });
+                }
+                case "trigger": {
+                    const programId = trimOrNull(params.program_id);
+                    if (!programId)
+                        return textResult("trigger requires program_id");
+                    const payload = await fetchMuJson("/api/heartbeats/trigger", {
+                        method: "POST",
+                        body: {
+                            program_id: programId,
+                            reason: trimOrNull(params.reason),
+                        },
+                    });
+                    return textResult(toJsonText(payload), { action: "trigger", programId });
+                }
+                case "enable":
+                case "disable": {
+                    const programId = trimOrNull(params.program_id);
+                    if (!programId)
+                        return textResult(`${params.action} requires program_id`);
+                    const payload = await fetchMuJson("/api/heartbeats/update", {
+                        method: "POST",
+                        body: {
+                            program_id: programId,
+                            enabled: params.action === "enable",
+                        },
+                    });
+                    return textResult(toJsonText(payload), {
+                        action: params.action,
+                        programId,
+                    });
+                }
+                default:
+                    return textResult(`unknown action: ${params.action}`);
+            }
+        },
+    });
+}
+export default heartbeatsExtension;

package/dist/extensions/index.d.ts

@@ -1,6 +1,9 @@
+export { activitiesExtension } from "./activities.js";
 export { brandingExtension } from "./branding.js";
 export { eventLogExtension } from "./event-log.js";
+export { heartbeatsExtension } from "./heartbeats.js";
 export { messagingSetupExtension } from "./messaging-setup.js";
+export { orchestrationRunsExtension } from "./orchestration-runs.js";
 export { serverToolsExtension } from "./server-tools.js";
 /**
  * Serve-mode extension module paths.

package/dist/extensions/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/extensions/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAClD,OAAO,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AACnD,OAAO,EAAE,uBAAuB,EAAE,MAAM,sBAAsB,CAAC;AAC/D,OAAO,EAAE,oBAAoB,EAAE,MAAM,mBAAmB,CAAC;AASzD;;;;;;GAMG;AACH,eAAO,MAAM,mBAAmB,UAE/B,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/extensions/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AACtD,OAAO,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAClD,OAAO,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AACnD,OAAO,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AACtD,OAAO,EAAE,uBAAuB,EAAE,MAAM,sBAAsB,CAAC;AAC/D,OAAO,EAAE,0BAA0B,EAAE,MAAM,yBAAyB,CAAC;AACrE,OAAO,EAAE,oBAAoB,EAAE,MAAM,mBAAmB,CAAC;AAiBzD;;;;;;GAMG;AACH,eAAO,MAAM,mBAAmB,UAE/B,CAAC"}

package/dist/extensions/index.js

@@ -1,8 +1,19 @@
+export { activitiesExtension } from "./activities.js";
 export { brandingExtension } from "./branding.js";
 export { eventLogExtension } from "./event-log.js";
+export { heartbeatsExtension } from "./heartbeats.js";
 export { messagingSetupExtension } from "./messaging-setup.js";
+export { orchestrationRunsExtension } from "./orchestration-runs.js";
 export { serverToolsExtension } from "./server-tools.js";
-const SERVE_EXTENSION_MODULE_BASENAMES = ["branding", "server-tools", "event-log", "messaging-setup"];
+const SERVE_EXTENSION_MODULE_BASENAMES = [
+    "branding",
+    "server-tools",
+    "event-log",
+    "messaging-setup",
+    "orchestration-runs",
+    "activities",
+    "heartbeats",
+];
 const RUNTIME_EXTENSION = import.meta.url.endsWith(".ts") ? "ts" : "js";
 function resolveBundledExtensionPath(moduleBasename) {
     return new URL(`./${moduleBasename}.${RUNTIME_EXTENSION}`, import.meta.url).pathname;

package/dist/extensions/orchestration-runs.d.ts

@@ -0,0 +1,4 @@
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+export declare function orchestrationRunsExtension(pi: ExtensionAPI): void;
+export default orchestrationRunsExtension;
+//# sourceMappingURL=orchestration-runs.d.ts.map

package/dist/extensions/orchestration-runs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"orchestration-runs.d.ts","sourceRoot":"","sources":["../../src/extensions/orchestration-runs.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,+BAA+B,CAAC;AAUlE,wBAAgB,0BAA0B,CAAC,EAAE,EAAE,YAAY,QAiH1D;AAED,eAAe,0BAA0B,CAAC"}

package/dist/extensions/orchestration-runs.js

@@ -0,0 +1,123 @@
+import { StringEnum } from "@mariozechner/pi-ai";
+import { Type } from "@sinclair/typebox";
+import { clampInt, fetchMuJson, textResult, toJsonText } from "./shared.js";
+function trimOrNull(value) {
+    if (value == null)
+        return null;
+    const trimmed = value.trim();
+    return trimmed.length > 0 ? trimmed : null;
+}
+export function orchestrationRunsExtension(pi) {
+    const RunsParams = Type.Object({
+        action: StringEnum(["list", "status", "start", "resume", "interrupt", "heartbeat", "trace"]),
+        job_id: Type.Optional(Type.String({ description: "Run job ID" })),
+        root_issue_id: Type.Optional(Type.String({ description: "Run root issue ID (mu-...)" })),
+        prompt: Type.Optional(Type.String({ description: "Prompt for run start" })),
+        max_steps: Type.Optional(Type.Number({ description: "Optional max steps for start/resume" })),
+        limit: Type.Optional(Type.Number({ description: "Optional limit (list/trace)" })),
+        status: Type.Optional(Type.String({ description: "Optional status filter for list" })),
+        reason: Type.Optional(Type.String({ description: "Optional heartbeat reason (default: manual)" })),
+    });
+    pi.registerTool({
+        name: "mu_runs",
+        label: "Runs",
+        description: "Manage orchestration runs. Actions: list, status, start, resume, interrupt, heartbeat, trace (stdout/stderr + .mu/log hints).",
+        parameters: RunsParams,
+        async execute(_toolCallId, params) {
+            switch (params.action) {
+                case "list": {
+                    const query = new URLSearchParams();
+                    const status = trimOrNull(params.status);
+                    if (status)
+                        query.set("status", status);
+                    const limit = clampInt(params.limit, 50, 1, 500);
+                    query.set("limit", String(limit));
+                    const payload = await fetchMuJson(`/api/runs?${query.toString()}`);
+                    return textResult(toJsonText(payload), { action: "list", status, limit });
+                }
+                case "status": {
+                    const id = trimOrNull(params.job_id) ?? trimOrNull(params.root_issue_id);
+                    if (!id)
+                        return textResult("status requires job_id or root_issue_id");
+                    const payload = await fetchMuJson(`/api/runs/${encodeURIComponent(id)}`);
+                    return textResult(toJsonText(payload), { action: "status", id });
+                }
+                case "start": {
+                    const prompt = trimOrNull(params.prompt);
+                    if (!prompt)
+                        return textResult("start requires prompt");
+                    const maxSteps = params.max_steps != null && Number.isFinite(params.max_steps)
+                        ? Math.max(1, Math.trunc(params.max_steps))
+                        : undefined;
+                    const payload = await fetchMuJson("/api/runs/start", {
+                        method: "POST",
+                        body: {
+                            prompt,
+                            max_steps: maxSteps,
+                        },
+                    });
+                    return textResult(toJsonText(payload), { action: "start", prompt, maxSteps });
+                }
+                case "resume": {
+                    const rootIssueId = trimOrNull(params.root_issue_id);
+                    if (!rootIssueId)
+                        return textResult("resume requires root_issue_id");
+                    const maxSteps = params.max_steps != null && Number.isFinite(params.max_steps)
+                        ? Math.max(1, Math.trunc(params.max_steps))
+                        : undefined;
+                    const payload = await fetchMuJson("/api/runs/resume", {
+                        method: "POST",
+                        body: {
+                            root_issue_id: rootIssueId,
+                            max_steps: maxSteps,
+                        },
+                    });
+                    return textResult(toJsonText(payload), { action: "resume", rootIssueId, maxSteps });
+                }
+                case "interrupt": {
+                    const jobId = trimOrNull(params.job_id);
+                    const rootIssueId = trimOrNull(params.root_issue_id);
+                    if (!jobId && !rootIssueId) {
+                        return textResult("interrupt requires job_id or root_issue_id");
+                    }
+                    const payload = await fetchMuJson("/api/runs/interrupt", {
+                        method: "POST",
+                        body: {
+                            job_id: jobId,
+                            root_issue_id: rootIssueId,
+                        },
+                    });
+                    return textResult(toJsonText(payload), { action: "interrupt", jobId, rootIssueId });
+                }
+                case "heartbeat": {
+                    const jobId = trimOrNull(params.job_id);
+                    const rootIssueId = trimOrNull(params.root_issue_id);
+                    if (!jobId && !rootIssueId) {
+                        return textResult("heartbeat requires job_id or root_issue_id");
+                    }
+                    const reason = trimOrNull(params.reason) ?? "manual";
+                    const payload = await fetchMuJson("/api/runs/heartbeat", {
+                        method: "POST",
+                        body: {
+                            job_id: jobId,
+                            root_issue_id: rootIssueId,
+                            reason,
+                        },
+                    });
+                    return textResult(toJsonText(payload), { action: "heartbeat", jobId, rootIssueId, reason });
+                }
+                case "trace": {
+                    const id = trimOrNull(params.job_id) ?? trimOrNull(params.root_issue_id);
+                    if (!id)
+                        return textResult("trace requires job_id or root_issue_id");
+                    const limit = clampInt(params.limit, 200, 1, 2_000);
+                    const payload = await fetchMuJson(`/api/runs/${encodeURIComponent(id)}/trace?limit=${limit}`);
+                    return textResult(toJsonText(payload), { action: "trace", id, limit });
+                }
+                default:
+                    return textResult(`unknown action: ${params.action}`);
+            }
+        },
+    });
+}
+export default orchestrationRunsExtension;

package/dist/extensions/server-tools.js

@@ -53,7 +53,7 @@ export function serverToolsExtension(pi) {
         const extra = [
             "",
             `[MU SERVER] Connected at ${url}.`,
-            "Tools: mu_status, mu_control_plane, mu_issues, mu_forum, mu_events.",
+            "Tools: mu_status, mu_control_plane, mu_issues, mu_forum, mu_events, mu_runs, mu_activities, mu_heartbeats.",
             "Use these tools to inspect repository state and control-plane runtime before advising users.",
         ].join("\n");
         return {

package/dist/operator.d.ts

@@ -1,5 +1,6 @@
 import { z } from "zod";
 import { CommandContextResolver } from "./command_context.js";
+import { type CreateMuSessionOpts, type MuSession } from "./session_factory.js";
 export type MessagingOperatorInboundEnvelope = {
     channel: string;
     channel_tenant_id: string;
@@ -30,10 +31,18 @@ export declare const OperatorApprovedCommandSchema: z.ZodDiscriminatedUnion<[z.Z
     kind: z.ZodLiteral<"forum_read">;
     topic: z.ZodOptional<z.ZodString>;
     limit: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"run_list">;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"run_status">;
+    root_issue_id: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>, z.ZodObject<{
     kind: z.ZodLiteral<"run_resume">;
     root_issue_id: z.ZodOptional<z.ZodString>;
     max_steps: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"run_interrupt">;
+    root_issue_id: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>, z.ZodObject<{
     kind: z.ZodLiteral<"run_start">;
     prompt: z.ZodString;
@@ -58,10 +67,18 @@ export declare const OperatorBackendTurnResultSchema: z.ZodDiscriminatedUnion<[z
         kind: z.ZodLiteral<"forum_read">;
         topic: z.ZodOptional<z.ZodString>;
         limit: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<"run_list">;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<"run_status">;
+        root_issue_id: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>, z.ZodObject<{
         kind: z.ZodLiteral<"run_resume">;
         root_issue_id: z.ZodOptional<z.ZodString>;
         max_steps: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<"run_interrupt">;
+        root_issue_id: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>, z.ZodObject<{
         kind: z.ZodLiteral<"run_start">;
         prompt: z.ZodString;
@@ -77,6 +94,7 @@ export type OperatorBackendTurnInput = {
 };
 export interface MessagingOperatorBackend {
     runTurn(input: OperatorBackendTurnInput): Promise<OperatorBackendTurnResult>;
+    dispose?(): void | Promise<void>;
 }
 export type OperatorDecision = {
     kind: "response";
@@ -129,6 +147,7 @@ export declare class MessagingOperatorRuntime {
         inbound: InboundEnvelope;
         binding: IdentityBinding;
     }): Promise<OperatorDecision>;
+    stop(): Promise<void>;
 }
 export type PiMessagingOperatorBackendOpts = {
     provider?: string;
@@ -137,12 +156,17 @@ export type PiMessagingOperatorBackendOpts = {
     systemPrompt?: string;
     timeoutMs?: number;
     extensionPaths?: string[];
+    sessionFactory?: (opts: CreateMuSessionOpts) => Promise<MuSession>;
+    nowMs?: () => number;
+    sessionIdleTtlMs?: number;
+    maxSessions?: number;
 };
 export declare const DEFAULT_CHAT_SYSTEM_PROMPT: string;
 export declare class PiMessagingOperatorBackend implements MessagingOperatorBackend {
     #private;
     constructor(opts?: PiMessagingOperatorBackendOpts);
     runTurn(input: OperatorBackendTurnInput): Promise<OperatorBackendTurnResult>;
+    dispose(): void;
 }
 export {};
 //# sourceMappingURL=operator.d.ts.map

package/dist/operator.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"operator.d.ts","sourceRoot":"","sources":["../src/operator.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"operator.d.ts","sourceRoot":"","sources":["../src/operator.ts"],"names":[],"mappings":"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"}

package/dist/operator.js

@@ -12,11 +12,20 @@ export const OperatorApprovedCommandSchema = z.discriminatedUnion("kind", [
         topic: z.string().trim().min(1).optional(),
         limit: z.number().int().min(1).max(500).optional(),
     }),
+    z.object({ kind: z.literal("run_list") }),
+    z.object({
+        kind: z.literal("run_status"),
+        root_issue_id: z.string().trim().min(1).optional(),
+    }),
     z.object({
         kind: z.literal("run_resume"),
         root_issue_id: z.string().trim().min(1).optional(),
         max_steps: z.number().int().min(1).max(500).optional(),
     }),
+    z.object({
+        kind: z.literal("run_interrupt"),
+        root_issue_id: z.string().trim().min(1).optional(),
+    }),
     z.object({
         kind: z.literal("run_start"),
         prompt: z.string().trim().min(1),
@@ -74,6 +83,17 @@ export class ApprovedCommandBroker {
                 }
                 break;
             }
+            case "run_list":
+                commandKey = "run list";
+                args = [];
+                break;
+            case "run_status":
+                commandKey = "run status";
+                args = [];
+                if (opts.proposal.root_issue_id) {
+                    args.push(normalizeArg(opts.proposal.root_issue_id));
+                }
+                break;
             case "run_resume": {
                 if (!this.#runTriggersEnabled) {
                     return { kind: "reject", reason: "operator_action_disallowed", details: "run triggers disabled" };
@@ -88,6 +108,17 @@ export class ApprovedCommandBroker {
                 }
                 break;
             }
+            case "run_interrupt": {
+                if (!this.#runTriggersEnabled) {
+                    return { kind: "reject", reason: "operator_action_disallowed", details: "run triggers disabled" };
+                }
+                commandKey = "run interrupt";
+                args = [];
+                if (opts.proposal.root_issue_id) {
+                    args.push(normalizeArg(opts.proposal.root_issue_id));
+                }
+                break;
+            }
             case "run_start": {
                 if (!this.#runTriggersEnabled) {
                     return { kind: "reject", reason: "operator_action_disallowed", details: "run triggers disabled" };
@@ -230,6 +261,10 @@ export class MessagingOperatorRuntime {
             operatorTurnId: turnId,
         };
     }
+    async stop() {
+        this.#sessionByConversation.clear();
+        await this.#backend.dispose?.();
+    }
 }
 export const DEFAULT_CHAT_SYSTEM_PROMPT = [
     "You are mu, an AI assistant for the mu orchestration platform.",
@@ -242,16 +277,53 @@ export const DEFAULT_CHAT_SYSTEM_PROMPT = [
     "",
     "Be concise, practical, and actionable.",
 ].join("\n");
+const OPERATOR_COMMAND_PREFIX = "MU_COMMAND:";
 const DEFAULT_OPERATOR_SYSTEM_PROMPT = [
     "You are mu, an AI assistant for the mu orchestration platform.",
     "You have tools to interact with the mu server: mu_status, mu_control_plane, mu_issues, mu_forum, mu_events.",
     "Use these tools to answer questions about repository state, issues, events, and control-plane runtime state.",
     "For adapter setup workflow, use mu_messaging_setup (check/preflight/plan/apply/verify/guide).",
     "You can help users set up messaging integrations (Slack, Discord, Telegram, Gmail planning).",
+    "You may either respond normally or emit an approved control-plane command.",
+    `To emit a command, output exactly one line with prefix ${OPERATOR_COMMAND_PREFIX} followed by compact JSON.`,
+    "Example:",
+    `MU_COMMAND: {\"kind\":\"run_start\",\"prompt\":\"ship release\"}`,
+    "Available command kinds: status, ready, issue_list, issue_get, forum_read, run_list, run_status, run_start, run_resume, run_interrupt.",
     "",
     "Be concise, practical, and actionable.",
-    "Respond in plain text — do not wrap in JSON.",
+    "For normal conversational answers, respond in plain text.",
 ].join("\n");
+function parseOperatorCommandDirective(text) {
+    const whole = text.trim();
+    if (whole.startsWith("{") && whole.endsWith("}")) {
+        try {
+            return OperatorApprovedCommandSchema.parse(JSON.parse(whole));
+        }
+        catch {
+            // fall through to explicit MU_COMMAND parsing
+        }
+    }
+    const lines = text.split(/\r?\n/);
+    for (const line of lines) {
+        const trimmed = line.trim();
+        if (!trimmed.startsWith(OPERATOR_COMMAND_PREFIX)) {
+            continue;
+        }
+        const payloadText = trimmed.slice(OPERATOR_COMMAND_PREFIX.length).trim();
+        if (payloadText.length === 0) {
+            throw new Error("operator_command_directive_missing_payload");
+        }
+        let parsed;
+        try {
+            parsed = JSON.parse(payloadText);
+        }
+        catch (err) {
+            throw new Error(`operator_command_directive_invalid_json: ${err instanceof Error ? err.message : String(err)}`);
+        }
+        return OperatorApprovedCommandSchema.parse(parsed);
+    }
+    return null;
+}
 function buildOperatorPrompt(input) {
     return [
         `[Messaging context]`,
@@ -269,6 +341,11 @@ export class PiMessagingOperatorBackend {
     #systemPrompt;
     #timeoutMs;
     #extensionPaths;
+    #sessionFactory;
+    #nowMs;
+    #sessionIdleTtlMs;
+    #maxSessions;
+    #sessions = new Map();
     constructor(opts = {}) {
         this.#provider = opts.provider;
         this.#model = opts.model;
@@ -276,71 +353,136 @@ export class PiMessagingOperatorBackend {
         this.#systemPrompt = opts.systemPrompt ?? DEFAULT_OPERATOR_SYSTEM_PROMPT;
         this.#timeoutMs = Math.max(1_000, Math.trunc(opts.timeoutMs ?? 90_000));
         this.#extensionPaths = opts.extensionPaths ?? [];
+        this.#sessionFactory = opts.sessionFactory ?? createMuSession;
+        this.#nowMs = opts.nowMs ?? Date.now;
+        this.#sessionIdleTtlMs = Math.max(60_000, Math.trunc(opts.sessionIdleTtlMs ?? 30 * 60 * 1_000));
+        this.#maxSessions = Math.max(1, Math.trunc(opts.maxSessions ?? 32));
     }
-    async runTurn(input) {
-        const session = await createMuSession({
-            cwd: input.inbound.repo_root,
+    #disposeSession(sessionId) {
+        const entry = this.#sessions.get(sessionId);
+        if (!entry) {
+            return;
+        }
+        this.#sessions.delete(sessionId);
+        try {
+            entry.session.dispose();
+        }
+        catch {
+            // Best effort cleanup.
+        }
+    }
+    #pruneSessions(nowMs) {
+        for (const [sessionId, entry] of this.#sessions.entries()) {
+            if (nowMs - entry.lastUsedAtMs > this.#sessionIdleTtlMs) {
+                this.#disposeSession(sessionId);
+            }
+        }
+        if (this.#sessions.size <= this.#maxSessions) {
+            return;
+        }
+        const byOldestUse = [...this.#sessions.entries()].sort((a, b) => a[1].lastUsedAtMs - b[1].lastUsedAtMs);
+        while (this.#sessions.size > this.#maxSessions && byOldestUse.length > 0) {
+            const [sessionId] = byOldestUse.shift();
+            this.#disposeSession(sessionId);
+        }
+    }
+    async #createSession(repoRoot, nowMs) {
+        const session = await this.#sessionFactory({
+            cwd: repoRoot,
             systemPrompt: this.#systemPrompt,
             provider: this.#provider,
             model: this.#model,
             thinking: this.#thinking,
             extensionPaths: this.#extensionPaths,
         });
-        try {
-            await session.bindExtensions({
-                commandContextActions: {
-                    waitForIdle: () => session.agent.waitForIdle(),
-                    newSession: async () => ({ cancelled: true }),
-                    fork: async () => ({ cancelled: true }),
-                    navigateTree: async () => ({ cancelled: true }),
-                    switchSession: async () => ({ cancelled: true }),
-                    reload: async () => { },
-                },
-                onError: () => { },
-            });
-            let assistantText = "";
-            const unsub = session.subscribe((event) => {
-                if (event?.type === "message_end" && event?.message?.role === "assistant") {
-                    const msg = event.message;
-                    if (typeof msg.text === "string") {
-                        assistantText = msg.text;
-                    }
-                    else if (typeof msg.content === "string") {
-                        assistantText = msg.content;
-                    }
-                    else if (Array.isArray(msg.content)) {
-                        const parts = [];
-                        for (const item of msg.content) {
-                            const t = typeof item === "string" ? item : item?.text;
-                            if (typeof t === "string" && t.trim().length > 0)
-                                parts.push(t);
-                        }
-                        if (parts.length > 0)
-                            assistantText = parts.join("\n");
+        await session.bindExtensions({
+            commandContextActions: {
+                waitForIdle: () => session.agent.waitForIdle(),
+                newSession: async () => ({ cancelled: true }),
+                fork: async () => ({ cancelled: true }),
+                navigateTree: async () => ({ cancelled: true }),
+                switchSession: async () => ({ cancelled: true }),
+                reload: async () => { },
+            },
+            onError: () => { },
+        });
+        return {
+            session,
+            repoRoot,
+            createdAtMs: nowMs,
+            lastUsedAtMs: nowMs,
+        };
+    }
+    async #resolveSession(sessionId, repoRoot) {
+        const nowMs = Math.trunc(this.#nowMs());
+        this.#pruneSessions(nowMs);
+        const existing = this.#sessions.get(sessionId);
+        if (existing && existing.repoRoot === repoRoot) {
+            existing.lastUsedAtMs = nowMs;
+            return existing;
+        }
+        if (existing && existing.repoRoot !== repoRoot) {
+            this.#disposeSession(sessionId);
+        }
+        const created = await this.#createSession(repoRoot, nowMs);
+        this.#sessions.set(sessionId, created);
+        this.#pruneSessions(nowMs);
+        return created;
+    }
+    async runTurn(input) {
+        const sessionRecord = await this.#resolveSession(input.sessionId, input.inbound.repo_root);
+        const session = sessionRecord.session;
+        let assistantText = "";
+        const unsub = session.subscribe((event) => {
+            if (event?.type === "message_end" && event?.message?.role === "assistant") {
+                const msg = event.message;
+                if (typeof msg.text === "string") {
+                    assistantText = msg.text;
+                }
+                else if (typeof msg.content === "string") {
+                    assistantText = msg.content;
+                }
+                else if (Array.isArray(msg.content)) {
+                    const parts = [];
+                    for (const item of msg.content) {
+                        const t = typeof item === "string" ? item : item?.text;
+                        if (typeof t === "string" && t.trim().length > 0)
+                            parts.push(t);
                     }
+                    if (parts.length > 0)
+                        assistantText = parts.join("\n");
                 }
-            });
-            const timeoutPromise = new Promise((_, reject) => {
-                setTimeout(() => reject(new Error("pi operator timeout")), this.#timeoutMs);
-            });
-            try {
-                await Promise.race([
-                    session.prompt(buildOperatorPrompt(input), { expandPromptTemplates: false }),
-                    timeoutPromise,
-                ]);
-            }
-            finally {
-                unsub();
-            }
-            // The agent now responds naturally with tools — always return as respond
-            const message = assistantText.trim();
-            if (!message) {
-                throw new Error("operator_empty_response");
             }
-            return { kind: "respond", message: message.slice(0, 2000) };
+        });
+        const timeoutPromise = new Promise((_, reject) => {
+            setTimeout(() => reject(new Error("pi operator timeout")), this.#timeoutMs);
+        });
+        try {
+            await Promise.race([
+                session.prompt(buildOperatorPrompt(input), { expandPromptTemplates: false }),
+                timeoutPromise,
+            ]);
         }
         finally {
-            session.dispose();
+            unsub();
+            sessionRecord.lastUsedAtMs = Math.trunc(this.#nowMs());
+        }
+        const message = assistantText.trim();
+        if (!message) {
+            throw new Error("operator_empty_response");
+        }
+        const command = parseOperatorCommandDirective(message);
+        if (command) {
+            return {
+                kind: "command",
+                command,
+            };
+        }
+        return { kind: "respond", message: message.slice(0, 2000) };
+    }
+    dispose() {
+        for (const sessionId of [...this.#sessions.keys()]) {
+            this.#disposeSession(sessionId);
         }
     }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@femtomc/mu-agent",
-  "version": "26.2.41",
+  "version": "26.2.42",
   "description": "Shared agent runtime for mu chat, orchestration roles, and serve extensions.",
   "keywords": [
     "mu",
@@ -22,7 +22,7 @@
     "dist/**"
   ],
   "dependencies": {
-    "@femtomc/mu-core": "26.2.41",
+    "@femtomc/mu-core": "26.2.42",
     "@mariozechner/pi-agent-core": "^0.52.12",
     "@mariozechner/pi-ai": "^0.52.12",
     "@mariozechner/pi-coding-agent": "^0.52.12",