devsh-memory-mcp 0.2.1 → 0.3.1

package/README.md

@@ -88,14 +88,37 @@ With custom options:
 | `spawn_agent` | Spawn a sub-agent to work on a task |
 | `get_agent_status` | Get status of a spawned agent |
 | `list_spawned_agents` | List all agents in current orchestration |
-| `wait_for_agent` | Wait for agent to complete (blocking) |
+| `wait_for_agent` | Wait for agent to complete (polling) |
+| `wait_for_events` | Wait for events via SSE (event-driven, recommended) |
 | `cancel_agent` | Cancel a running/pending agent |
 | `get_orchestration_summary` | Get dashboard-style orchestration summary |
-| `pull_orchestration_updates` | Sync local PLAN.json with server |
+| `pull_orchestration_updates` | Sync local PLAN.json with server (read) |
+| `push_orchestration_updates` | Push task status/completion to server (write) |
 | `read_orchestration` | Read PLAN.json, AGENTS.json, or EVENTS.jsonl |
 | `append_event` | Append an orchestration event to EVENTS.jsonl |
 | `update_plan_task` | Update task status in PLAN.json |
 
+### Provider Session Tools
+
+| Tool | Description |
+|------|-------------|
+| `bind_provider_session` | Bind a Claude session ID or Codex thread ID to task |
+| `get_provider_session` | Get provider session binding for task resume |
+
+### Orchestration Learning Tools
+
+| Tool | Description |
+|------|-------------|
+| `log_learning` | Log an orchestration learning, error, or feature request to the server |
+| `get_active_orchestration_rules` | Fetch active orchestration rules for the team |
+
+**log_learning types:**
+- `learning` - Discovered a better orchestration pattern
+- `error` - Found an error pattern to avoid
+- `feature_request` - Missing capability that would help
+
+Logged items are reviewed by team leads and may be promoted to active orchestration rules.
+
 ### Environment Variables (Orchestration)
 
 | Variable | Description |
@@ -109,15 +132,22 @@ With custom options:
 ```
 /root/lifecycle/memory/
 ├── knowledge/
-│   └── MEMORY.md         # Long-term insights (P0/P1/P2 sections)
+│   └── MEMORY.md              # Long-term insights (P0/P1/P2 sections)
 ├── daily/
-│   └── {date}.md         # Daily session logs
+│   └── {date}.md              # Daily session logs
 ├── orchestration/
-│   ├── PLAN.json         # Orchestration task plan
-│   ├── AGENTS.json       # Agent registry
-│   └── EVENTS.jsonl      # Orchestration event log
-├── TASKS.json            # Task registry
-└── MAILBOX.json          # Inter-agent messages
+│   ├── PLAN.json              # Orchestration task plan
+│   ├── AGENTS.json            # Agent registry
+│   └── EVENTS.jsonl           # Orchestration event log
+├── behavior/
+│   ├── HOT.md                 # Active workflow preferences
+│   ├── corrections.jsonl      # User corrections log
+│   ├── LEARNINGS.jsonl        # Orchestration learnings
+│   ├── ERRORS.jsonl           # Error patterns
+│   ├── FEATURE_REQUESTS.jsonl # Feature requests
+│   └── skill-candidates.json  # Repeated patterns
+├── TASKS.json                 # Task registry
+└── MAILBOX.json               # Inter-agent messages
 ```
 
 ## Priority Tiers (MEMORY.md)

package/dist/{chunk-YTXBZTQ2.js → chunk-U2TWXSPB.js}

@@ -28,7 +28,6 @@ function createMemoryMcpServer(config) {
   const eventsPath = path.join(orchestrationDir, "EVENTS.jsonl");
   function readFile(filePath) {
     try {
-      if (!fs.existsSync(filePath)) return null;
       return fs.readFileSync(filePath, "utf-8");
     } catch {
       return null;
@@ -422,6 +421,33 @@ function createMemoryMcpServer(config) {
           }
         }
       },
+      {
+        name: "push_orchestration_updates",
+        description: "Push local orchestration state to the server. Reports task completion/failure and head agent status. Used for heartbeats and signaling orchestration completion. Requires CMUX_TASK_RUN_JWT environment variable.",
+        inputSchema: {
+          type: "object",
+          properties: {
+            orchestrationId: {
+              type: "string",
+              description: "The orchestration ID to push updates for. Uses CMUX_ORCHESTRATION_ID env var if not provided."
+            },
+            headAgentStatus: {
+              type: "string",
+              enum: ["running", "completed", "failed"],
+              description: "Head agent's overall status (optional, for heartbeat/completion signal)"
+            },
+            message: {
+              type: "string",
+              description: "Optional status message from head agent"
+            },
+            taskIds: {
+              type: "array",
+              items: { type: "string" },
+              description: "Optional list of local task IDs to push (default: all completed/failed tasks)"
+            }
+          }
+        }
+      },
       {
         name: "spawn_agent",
         description: "Spawn a sub-agent to work on a task. Requires CMUX_TASK_RUN_JWT for authentication. The sub-agent runs in a new sandbox and works on the specified prompt.",
@@ -528,6 +554,154 @@ function createMemoryMcpServer(config) {
           type: "object",
           properties: {}
         }
+      },
+      {
+        name: "bind_provider_session",
+        description: "Bind a provider-specific session ID to the current task. Use to enable session resume on task retry. Claude agents should call this with their session ID, Codex agents with their thread ID.",
+        inputSchema: {
+          type: "object",
+          properties: {
+            providerSessionId: {
+              type: "string",
+              description: "Claude session ID or equivalent for the provider"
+            },
+            providerThreadId: {
+              type: "string",
+              description: "Codex thread ID or equivalent for thread-based providers"
+            },
+            replyChannel: {
+              type: "string",
+              enum: ["mailbox", "sse", "pty", "ui"],
+              description: "Preferred communication channel for receiving messages"
+            }
+          }
+        }
+      },
+      {
+        name: "get_provider_session",
+        description: "Get the provider session binding for a task. Use to check if a session can be resumed.",
+        inputSchema: {
+          type: "object",
+          properties: {
+            taskId: {
+              type: "string",
+              description: "The orchestration task ID to get session for (optional, uses current task)"
+            }
+          }
+        }
+      },
+      {
+        name: "wait_for_events",
+        description: "Wait for orchestration events using SSE streaming. Returns when a matching event arrives or timeout. More efficient than polling wait_for_agent. Use for event-driven head agent loops.",
+        inputSchema: {
+          type: "object",
+          properties: {
+            orchestrationId: {
+              type: "string",
+              description: "The orchestration ID to subscribe to events for"
+            },
+            eventTypes: {
+              type: "array",
+              items: { type: "string" },
+              description: "Event types to wait for (e.g., ['task_completed', 'approval_required']). If empty, returns on any event."
+            },
+            timeout: {
+              type: "number",
+              description: "Maximum wait time in milliseconds (default: 30000 = 30 seconds)"
+            }
+          },
+          required: ["orchestrationId"]
+        }
+      },
+      {
+        name: "get_pending_approvals",
+        description: "Get pending approval requests for the current orchestration. Returns approvals that require human decision before agents can proceed.",
+        inputSchema: {
+          type: "object",
+          properties: {
+            orchestrationId: {
+              type: "string",
+              description: "The orchestration ID to get pending approvals for (optional, uses current if not provided)"
+            }
+          }
+        }
+      },
+      {
+        name: "resolve_approval",
+        description: "Resolve a pending approval request. Use to approve or deny actions that require human authorization.",
+        inputSchema: {
+          type: "object",
+          properties: {
+            requestId: {
+              type: "string",
+              description: "The approval request ID (apr_xxx format)"
+            },
+            resolution: {
+              type: "string",
+              enum: ["allow", "allow_once", "allow_session", "deny", "deny_always"],
+              description: "Resolution decision: allow (permit action), allow_once (permit this time only), allow_session (permit for session), deny (reject), deny_always (block permanently)"
+            },
+            note: {
+              type: "string",
+              description: "Optional note explaining the decision"
+            }
+          },
+          required: ["requestId", "resolution"]
+        }
+      },
+      {
+        name: "refresh_policy_rules",
+        description: "Fetch the latest centralized policy rules from the server and update local instruction files. Use this to get updated policies without restarting the sandbox. Requires CMUX_TASK_RUN_JWT.",
+        inputSchema: {
+          type: "object",
+          properties: {}
+        }
+      },
+      {
+        name: "log_learning",
+        description: "Log an orchestration learning, error, or feature request to the server. Learnings captured here are reviewed by team leads and may be promoted to active orchestration rules. Requires CMUX_TASK_RUN_JWT.",
+        inputSchema: {
+          type: "object",
+          properties: {
+            type: {
+              type: "string",
+              enum: ["learning", "error", "feature_request"],
+              description: "Type of event to log"
+            },
+            text: {
+              type: "string",
+              description: "The learning, error description, or feature request text"
+            },
+            lane: {
+              type: "string",
+              enum: ["hot", "orchestration", "project"],
+              description: "Suggested lane for the rule (default: orchestration)"
+            },
+            confidence: {
+              type: "number",
+              description: "Confidence score 0.0-1.0 (default: 0.5 for learnings, 0.8 for errors)"
+            },
+            metadata: {
+              type: "object",
+              description: "Optional metadata (e.g., error stack, related task IDs)"
+            }
+          },
+          required: ["type", "text"]
+        }
+      },
+      {
+        name: "get_active_orchestration_rules",
+        description: "Fetch the currently active orchestration rules for this team. Returns rules that are injected into agent instruction files. Requires CMUX_TASK_RUN_JWT.",
+        inputSchema: {
+          type: "object",
+          properties: {
+            lane: {
+              type: "string",
+              enum: ["hot", "orchestration", "project"],
+              description: "Filter by lane (optional)"
+            }
+          }
+        }
       }
     ]
   }));
@@ -874,6 +1048,111 @@ function createMemoryMcpServer(config) {
           };
         }
       }
+      case "push_orchestration_updates": {
+        const { orchestrationId: argOrchId, headAgentStatus, message, taskIds } = args;
+        const orchestrationId = argOrchId ?? process.env.CMUX_ORCHESTRATION_ID;
+        const jwt = process.env.CMUX_TASK_RUN_JWT;
+        const apiBaseUrl = process.env.CMUX_API_BASE_URL ?? "https://cmux.sh";
+        if (!orchestrationId) {
+          return {
+            content: [{
+              type: "text",
+              text: "No orchestration ID provided. Pass orchestrationId parameter or set CMUX_ORCHESTRATION_ID env var."
+            }]
+          };
+        }
+        if (!jwt) {
+          return {
+            content: [{
+              type: "text",
+              text: "CMUX_TASK_RUN_JWT environment variable not set. This tool requires JWT authentication."
+            }]
+          };
+        }
+        try {
+          const plan = readPlan();
+          if (!plan && !headAgentStatus) {
+            return {
+              content: [{
+                type: "text",
+                text: "No PLAN.json found and no headAgentStatus provided. Nothing to push."
+              }]
+            };
+          }
+          const tasksToPush = [];
+          if (plan) {
+            for (const task of plan.tasks) {
+              if (taskIds && taskIds.length > 0 && !taskIds.includes(task.id)) {
+                continue;
+              }
+              if (task.status === "completed" || task.status === "failed") {
+                tasksToPush.push({
+                  id: task.id,
+                  status: task.status,
+                  result: task.result,
+                  errorMessage: task.errorMessage
+                });
+              }
+            }
+          }
+          const url = `${apiBaseUrl}/api/v1/cmux/orchestration/${orchestrationId}/sync`;
+          const response = await fetch(url, {
+            method: "POST",
+            headers: {
+              "Authorization": `Bearer ${jwt}`,
+              "Content-Type": "application/json"
+            },
+            body: JSON.stringify({
+              orchestrationId,
+              headAgentStatus,
+              message,
+              tasks: tasksToPush.length > 0 ? tasksToPush : void 0
+            })
+          });
+          if (!response.ok) {
+            const errorText = await response.text();
+            return {
+              content: [{
+                type: "text",
+                text: `Failed to push orchestration updates: ${response.status} ${errorText}`
+              }]
+            };
+          }
+          const result = await response.json();
+          appendEvent({
+            timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+            event: "orchestration_pushed",
+            message: result.message ?? `Pushed ${tasksToPush.length} tasks`,
+            metadata: {
+              orchestrationId,
+              headAgentStatus,
+              tasksPushed: tasksToPush.length,
+              tasksUpdated: result.tasksUpdated
+            }
+          });
+          return {
+            content: [{
+              type: "text",
+              text: JSON.stringify({
+                success: true,
+                orchestrationId,
+                headAgentStatus,
+                tasksPushed: tasksToPush.length,
+                tasksUpdated: result.tasksUpdated,
+                message: result.message
+              }, null, 2)
+            }]
+          };
+        } catch (error) {
+          const errorMsg = error instanceof Error ? error.message : String(error);
+          return {
+            content: [{
+              type: "text",
+              text: `Error pushing orchestration updates: ${errorMsg}`
+            }]
+          };
+        }
+      }
       case "spawn_agent": {
         const { prompt, agentName: spawnAgentName, repo, branch, dependsOn, priority } = args;
         const jwt = process.env.CMUX_TASK_RUN_JWT;
@@ -1289,6 +1568,685 @@ function createMemoryMcpServer(config) {
           };
         }
       }
+      case "bind_provider_session": {
+        const { providerSessionId, providerThreadId, replyChannel } = args;
+        const jwt = process.env.CMUX_TASK_RUN_JWT;
+        const apiBaseUrl = process.env.CMUX_API_BASE_URL ?? "https://cmux.sh";
+        const orchestrationId = process.env.CMUX_ORCHESTRATION_ID;
+        const taskRunId = process.env.CMUX_TASK_RUN_ID;
+        if (!jwt) {
+          return {
+            content: [{
+              type: "text",
+              text: "CMUX_TASK_RUN_JWT environment variable not set."
+            }]
+          };
+        }
+        try {
+          const url = `${apiBaseUrl}/api/v1/cmux/orchestration/sessions/bind`;
+          const response = await fetch(url, {
+            method: "POST",
+            headers: {
+              "Authorization": `Bearer ${jwt}`,
+              "Content-Type": "application/json"
+            },
+            body: JSON.stringify({
+              // Only include orchestrationId if set, otherwise API uses taskRunId from JWT
+              ...orchestrationId && { orchestrationId },
+              taskRunId,
+              providerSessionId,
+              providerThreadId,
+              replyChannel,
+              agentName
+            })
+          });
+          if (!response.ok) {
+            const errorText = await response.text();
+            return {
+              content: [{
+                type: "text",
+                text: `Failed to bind session: ${response.status} ${errorText}`
+              }]
+            };
+          }
+          const result = await response.json();
+          return {
+            content: [{
+              type: "text",
+              text: JSON.stringify({
+                success: true,
+                message: "Provider session bound successfully",
+                bindingId: result.bindingId,
+                updated: result.updated
+              }, null, 2)
+            }]
+          };
+        } catch (error) {
+          const errorMsg = error instanceof Error ? error.message : String(error);
+          return {
+            content: [{
+              type: "text",
+              text: `Error binding provider session: ${errorMsg}`
+            }]
+          };
+        }
+      }
+      case "get_provider_session": {
+        const { taskId: providedTaskId } = args;
+        const jwt = process.env.CMUX_TASK_RUN_JWT;
+        const apiBaseUrl = process.env.CMUX_API_BASE_URL ?? "https://cmux.sh";
+        const taskId = providedTaskId ?? process.env.CMUX_TASK_RUN_ID;
+        if (!jwt) {
+          return {
+            content: [{
+              type: "text",
+              text: "CMUX_TASK_RUN_JWT environment variable not set."
+            }]
+          };
+        }
+        if (!taskId) {
+          return {
+            content: [{
+              type: "text",
+              text: "No task ID provided and CMUX_TASK_RUN_ID not set."
+            }]
+          };
+        }
+        try {
+          const url = `${apiBaseUrl}/api/v1/cmux/orchestration/sessions/${taskId}`;
+          const response = await fetch(url, {
+            method: "GET",
+            headers: {
+              "Authorization": `Bearer ${jwt}`
+            }
+          });
+          if (!response.ok) {
+            if (response.status === 404) {
+              return {
+                content: [{
+                  type: "text",
+                  text: JSON.stringify({
+                    found: false,
+                    message: "No provider session binding found for this task"
+                  }, null, 2)
+                }]
+              };
+            }
+            const errorText = await response.text();
+            return {
+              content: [{
+                type: "text",
+                text: `Failed to get session: ${response.status} ${errorText}`
+              }]
+            };
+          }
+          const session = await response.json();
+          return {
+            content: [{
+              type: "text",
+              text: JSON.stringify({
+                found: true,
+                taskId: session.taskId,
+                orchestrationId: session.orchestrationId,
+                provider: session.provider,
+                agentName: session.agentName,
+                mode: session.mode,
+                providerSessionId: session.providerSessionId,
+                providerThreadId: session.providerThreadId,
+                replyChannel: session.replyChannel,
+                status: session.status,
+                lastActiveAt: session.lastActiveAt
+              }, null, 2)
+            }]
+          };
+        } catch (error) {
+          const errorMsg = error instanceof Error ? error.message : String(error);
+          return {
+            content: [{
+              type: "text",
+              text: `Error getting provider session: ${errorMsg}`
+            }]
+          };
+        }
+      }
+      case "wait_for_events": {
+        const { orchestrationId, eventTypes = [], timeout = 3e4 } = args;
+        const jwt = process.env.CMUX_TASK_RUN_JWT;
+        const apiBaseUrl = process.env.CMUX_API_BASE_URL ?? "https://cmux.sh";
+        if (!jwt) {
+          return {
+            content: [{
+              type: "text",
+              text: "CMUX_TASK_RUN_JWT environment variable not set. This tool requires JWT authentication."
+            }]
+          };
+        }
+        const startTime = Date.now();
+        let reader;
+        try {
+          const url = `${apiBaseUrl}/api/orchestrate/v2/events/${orchestrationId}`;
+          const controller = new AbortController();
+          const timeoutId = setTimeout(() => controller.abort(), timeout);
+          const response = await fetch(url, {
+            method: "GET",
+            headers: {
+              "Authorization": `Bearer ${jwt}`,
+              "Accept": "text/event-stream"
+            },
+            signal: controller.signal
+          });
+          if (!response.ok) {
+            clearTimeout(timeoutId);
+            const errorText = await response.text();
+            return {
+              content: [{
+                type: "text",
+                text: `Failed to connect to event stream: ${response.status} ${errorText}`
+              }]
+            };
+          }
+          reader = response.body?.getReader();
+          if (!reader) {
+            clearTimeout(timeoutId);
+            return {
+              content: [{
+                type: "text",
+                text: "No response body from event stream"
+              }]
+            };
+          }
+          const decoder = new TextDecoder();
+          let buffer = "";
+          while (Date.now() - startTime < timeout) {
+            const { value, done } = await reader.read();
+            if (done) break;
+            buffer += decoder.decode(value, { stream: true });
+            const lines = buffer.split("\n");
+            buffer = lines.pop() ?? "";
+            for (const line of lines) {
+              if (line.startsWith("data: ")) {
+                try {
+                  const event = JSON.parse(line.slice(6));
+                  if (eventTypes.length === 0 || eventTypes.includes(event.type)) {
+                    clearTimeout(timeoutId);
+                    return {
+                      content: [{
+                        type: "text",
+                        text: JSON.stringify({
+                          event,
+                          waitDuration: Date.now() - startTime
+                        }, null, 2)
+                      }]
+                    };
+                  }
+                } catch {
+                }
+              }
+            }
+          }
+          clearTimeout(timeoutId);
+          return {
+            content: [{
+              type: "text",
+              text: JSON.stringify({
+                status: "timeout",
+                message: `No matching events received within ${timeout}ms`,
+                eventTypesFilter: eventTypes,
+                waitDuration: Date.now() - startTime
+              }, null, 2)
+            }]
+          };
+        } catch (error) {
+          if (error instanceof Error && error.name === "AbortError") {
+            return {
+              content: [{
+                type: "text",
+                text: JSON.stringify({
+                  status: "timeout",
+                  message: `Connection timed out after ${timeout}ms`
+                }, null, 2)
+              }]
+            };
+          }
+          const errorMsg = error instanceof Error ? error.message : String(error);
+          return {
+            content: [{
+              type: "text",
+              text: `Error waiting for events: ${errorMsg}`
+            }]
+          };
+        } finally {
+          if (reader) {
+            try {
+              reader.cancel();
+            } catch {
+            }
+          }
+        }
+      }
+      case "get_pending_approvals": {
+        const { orchestrationId: providedOrchId } = args;
+        const jwt = process.env.CMUX_TASK_RUN_JWT;
+        const apiBaseUrl = process.env.CMUX_API_BASE_URL ?? "https://cmux.sh";
+        const orchestrationId = providedOrchId ?? process.env.CMUX_ORCHESTRATION_ID;
+        if (!jwt) {
+          return {
+            content: [{
+              type: "text",
+              text: "CMUX_TASK_RUN_JWT environment variable not set. This tool requires JWT authentication."
+            }]
+          };
+        }
+        if (!orchestrationId) {
+          return {
+            content: [{
+              type: "text",
+              text: "No orchestration ID provided and CMUX_ORCHESTRATION_ID not set."
+            }]
+          };
+        }
+        try {
+          const url = `${apiBaseUrl}/api/orchestrate/approvals/${orchestrationId}/pending`;
+          const response = await fetch(url, {
+            method: "GET",
+            headers: {
+              "Authorization": `Bearer ${jwt}`,
+              "Content-Type": "application/json"
+            }
+          });
+          if (!response.ok) {
+            const errorText = await response.text();
+            return {
+              content: [{
+                type: "text",
+                text: `Failed to get pending approvals: ${response.status} ${errorText}`
+              }]
+            };
+          }
+          const approvals = await response.json();
+          return {
+            content: [{
+              type: "text",
+              text: JSON.stringify({
+                orchestrationId,
+                pendingCount: Array.isArray(approvals) ? approvals.length : 0,
+                approvals
+              }, null, 2)
+            }]
+          };
+        } catch (error) {
+          const errorMsg = error instanceof Error ? error.message : String(error);
+          return {
+            content: [{
+              type: "text",
+              text: `Error getting pending approvals: ${errorMsg}`
+            }]
+          };
+        }
+      }
+      case "resolve_approval": {
+        const { requestId, resolution, note } = args;
+        const jwt = process.env.CMUX_TASK_RUN_JWT;
+        const apiBaseUrl = process.env.CMUX_API_BASE_URL ?? "https://cmux.sh";
+        if (!jwt) {
+          return {
+            content: [{
+              type: "text",
+              text: "CMUX_TASK_RUN_JWT environment variable not set. This tool requires JWT authentication."
+            }]
+          };
+        }
+        try {
+          const url = `${apiBaseUrl}/api/orchestrate/approvals/${requestId}/resolve`;
+          const response = await fetch(url, {
+            method: "POST",
+            headers: {
+              "Authorization": `Bearer ${jwt}`,
+              "Content-Type": "application/json"
+            },
+            body: JSON.stringify({ resolution, note })
+          });
+          if (!response.ok) {
+            const errorText = await response.text();
+            return {
+              content: [{
+                type: "text",
+                text: `Failed to resolve approval: ${response.status} ${errorText}`
+              }]
+            };
+          }
+          const result = await response.json();
+          return {
+            content: [{
+              type: "text",
+              text: JSON.stringify({
+                requestId,
+                resolution,
+                status: "resolved",
+                ...result
+              }, null, 2)
+            }]
+          };
+        } catch (error) {
+          const errorMsg = error instanceof Error ? error.message : String(error);
+          return {
+            content: [{
+              type: "text",
+              text: `Error resolving approval: ${errorMsg}`
+            }]
+          };
+        }
+      }
+      case "refresh_policy_rules": {
+        const jwt = process.env.CMUX_TASK_RUN_JWT;
+        const callbackUrl = process.env.CMUX_CALLBACK_URL;
+        const agentNameFull = process.env.CMUX_AGENT_NAME;
+        const isOrchestrationHead = process.env.CMUX_IS_ORCHESTRATION_HEAD === "1";
+        if (!jwt) {
+          return {
+            content: [{
+              type: "text",
+              text: "CMUX_TASK_RUN_JWT environment variable not set. This tool requires JWT authentication."
+            }]
+          };
+        }
+        if (!callbackUrl) {
+          return {
+            content: [{
+              type: "text",
+              text: "CMUX_CALLBACK_URL environment variable not set. Cannot reach policy server."
+            }]
+          };
+        }
+        if (!agentNameFull) {
+          return {
+            content: [{
+              type: "text",
+              text: "CMUX_AGENT_NAME environment variable not set. Cannot determine agent type."
+            }]
+          };
+        }
+        const agentType = agentNameFull.split("/")[0];
+        const validAgentTypes = ["claude", "codex", "gemini", "opencode"];
+        if (!validAgentTypes.includes(agentType)) {
+          return {
+            content: [{
+              type: "text",
+              text: `Unknown agent type '${agentType}'. Expected one of: ${validAgentTypes.join(", ")}`
+            }]
+          };
+        }
+        const context = isOrchestrationHead ? "cloud_workspace" : "task_sandbox";
+        try {
+          const url = new URL(`${callbackUrl}/api/agent/policy-rules`);
+          url.searchParams.set("agentType", agentType);
+          url.searchParams.set("context", context);
+          const response = await fetch(url.toString(), {
+            method: "GET",
+            headers: {
+              "x-cmux-token": jwt,
+              "Convex-Client": "node-1.0.0"
+            }
+          });
+          if (!response.ok) {
+            const errorText = await response.text();
+            return {
+              content: [{
+                type: "text",
+                text: `Failed to fetch policy rules: ${response.status} ${errorText}`
+              }]
+            };
+          }
+          const result = await response.json();
+          if (!result.rules || result.rules.length === 0) {
+            return {
+              content: [{
+                type: "text",
+                text: "No policy rules found for this context."
+              }]
+            };
+          }
+          const categoryOrder = {
+            git_policy: 1,
+            security: 2,
+            workflow: 3,
+            tool_restriction: 4,
+            custom: 5
+          };
+          const categoryLabels = {
+            git_policy: "Git Policy",
+            security: "Security",
+            workflow: "Workflow",
+            tool_restriction: "Tool Restrictions",
+            custom: "Custom"
+          };
+          const byCategory = /* @__PURE__ */ new Map();
+          for (const rule of result.rules) {
+            const existing = byCategory.get(rule.category) ?? [];
+            existing.push(rule);
+            byCategory.set(rule.category, existing);
+          }
+          for (const rules of byCategory.values()) {
+            rules.sort((a, b) => a.priority - b.priority);
+          }
+          let markdown = "# Agent Policy Rules\n\n";
+          markdown += "> These rules are centrally managed by cmux and override repo-level rules.\n";
+          markdown += `> Last refreshed: ${(/* @__PURE__ */ new Date()).toISOString()}
+
+`;
+          const sortedCategories = Array.from(byCategory.keys()).sort(
+            (a, b) => (categoryOrder[a] ?? 99) - (categoryOrder[b] ?? 99)
+          );
+          for (const category of sortedCategories) {
+            const rules = byCategory.get(category);
+            if (!rules || rules.length === 0) continue;
+            const label = categoryLabels[category] ?? category;
+            markdown += `## ${label}
+
+`;
+            for (const rule of rules) {
+              markdown += `${rule.ruleText}
+
+`;
+            }
+          }
+          const updates = [];
+          const claudeMdPath = path.join(process.env.HOME ?? "/root", ".claude", "CLAUDE.md");
+          const codexMdPath = path.join(process.env.HOME ?? "/root", ".codex", "instructions.md");
+          const updateInstructionFile = (filePath) => {
+            try {
+              let content;
+              try {
+                content = fs.readFileSync(filePath, "utf-8");
+              } catch {
+                return false;
+              }
+              const policyMarkerStart = "# Agent Policy Rules";
+              const startIdx = content.indexOf(policyMarkerStart);
+              if (startIdx === -1) {
+                const firstHeadingEnd = content.indexOf("\n\n");
+                if (firstHeadingEnd > 0) {
+                  content = content.slice(0, firstHeadingEnd + 2) + markdown + "\n" + content.slice(firstHeadingEnd + 2);
+                } else {
+                  content = markdown + "\n" + content;
+                }
+              } else {
+                const nextHeadingMatch = content.slice(startIdx + policyMarkerStart.length).match(/\n# [A-Z]/);
+                const memoryProtocolMatch = content.slice(startIdx + policyMarkerStart.length).match(/\n## cmux Agent Memory Protocol/);
+                let endIdx;
+                if (memoryProtocolMatch && memoryProtocolMatch.index !== void 0) {
+                  endIdx = startIdx + policyMarkerStart.length + memoryProtocolMatch.index;
+                } else if (nextHeadingMatch && nextHeadingMatch.index !== void 0) {
+                  endIdx = startIdx + policyMarkerStart.length + nextHeadingMatch.index;
+                } else {
+                  endIdx = content.length;
+                }
+                content = content.slice(0, startIdx) + markdown + content.slice(endIdx);
+              }
+              fs.writeFileSync(filePath, content, "utf-8");
+              return true;
+            } catch {
+              return false;
+            }
+          };
+          if (updateInstructionFile(claudeMdPath)) {
+            updates.push("~/.claude/CLAUDE.md");
+          }
+          if (updateInstructionFile(codexMdPath)) {
+            updates.push("~/.codex/instructions.md");
+          }
+          return {
+            content: [{
+              type: "text",
+              text: JSON.stringify({
+                refreshed: true,
+                rulesCount: result.rules.length,
+                categories: sortedCategories,
+                updatedFiles: updates,
+                message: updates.length > 0 ? `Successfully refreshed ${result.rules.length} policy rules. Updated: ${updates.join(", ")}` : `Fetched ${result.rules.length} policy rules but could not update local files.`
+              }, null, 2)
+            }]
+          };
+        } catch (error) {
+          const errorMsg = error instanceof Error ? error.message : String(error);
+          return {
+            content: [{
+              type: "text",
+              text: `Error refreshing policy rules: ${errorMsg}`
+            }]
+          };
+        }
+      }
+      case "log_learning": {
+        const jwt = process.env.CMUX_TASK_RUN_JWT;
+        const apiBase = process.env.CMUX_API_BASE_URL ?? "https://cmux.sh";
+        if (!jwt) {
+          return {
+            content: [{
+              type: "text",
+              text: "Error: CMUX_TASK_RUN_JWT not set. This tool requires authentication."
+            }]
+          };
+        }
+        const { type, text, lane, confidence, metadata } = args;
+        try {
+          const eventType = type === "learning" ? "learning_logged" : type === "error" ? "error_logged" : "feature_request_logged";
+          const response = await fetch(`${apiBase}/api/v1/cmux/orchestration/learning/log`, {
+            method: "POST",
+            headers: {
+              "Content-Type": "application/json",
+              "Authorization": `Bearer ${jwt}`
+            },
+            body: JSON.stringify({
+              eventType,
+              text,
+              lane: lane ?? "orchestration",
+              confidence: confidence ?? (type === "error" ? 0.8 : 0.5),
+              metadata
+            })
+          });
+          if (!response.ok) {
+            const errText = await response.text();
+            return {
+              content: [{
+                type: "text",
+                text: `Error logging ${type}: ${response.status} ${errText}`
+              }]
+            };
+          }
+          const result = await response.json();
+          return {
+            content: [{
+              type: "text",
+              text: JSON.stringify({
+                logged: true,
+                eventType,
+                eventId: result.eventId,
+                ruleId: result.ruleId,
+                message: `Successfully logged ${type}. It will be reviewed for promotion to active rules.`
+              }, null, 2)
+            }]
+          };
+        } catch (error) {
+          const errorMsg = error instanceof Error ? error.message : String(error);
+          return {
+            content: [{
+              type: "text",
+              text: `Error logging ${type}: ${errorMsg}`
+            }]
+          };
+        }
+      }
+      case "get_active_orchestration_rules": {
+        const jwt = process.env.CMUX_TASK_RUN_JWT;
+        const apiBase = process.env.CMUX_API_BASE_URL ?? "https://cmux.sh";
+        if (!jwt) {
+          return {
+            content: [{
+              type: "text",
+              text: "Error: CMUX_TASK_RUN_JWT not set. This tool requires authentication."
+            }]
+          };
+        }
+        const { lane } = args;
+        try {
+          const url = new URL(`${apiBase}/api/v1/cmux/orchestration/rules`);
+          if (lane) {
+            url.searchParams.set("lane", lane);
+          }
+          const response = await fetch(url.toString(), {
+            method: "GET",
+            headers: {
+              "Authorization": `Bearer ${jwt}`
+            }
+          });
+          if (!response.ok) {
+            const errText = await response.text();
+            return {
+              content: [{
+                type: "text",
+                text: `Error fetching orchestration rules: ${response.status} ${errText}`
+              }]
+            };
+          }
+          const result = await response.json();
+          const rules = result.rules ?? [];
+          const byLane = /* @__PURE__ */ new Map();
+          for (const rule of rules) {
+            const laneRules = byLane.get(rule.lane) ?? [];
+            laneRules.push({ text: rule.text, confidence: rule.confidence });
+            byLane.set(rule.lane, laneRules);
+          }
+          let output = `# Active Orchestration Rules (${rules.length} total)
+
+`;
+          for (const [ruleLane, laneRules] of byLane.entries()) {
+            const laneLabel = ruleLane === "hot" ? "Hot (High Priority)" : ruleLane === "orchestration" ? "Orchestration" : "Project-Specific";
+            output += `## ${laneLabel}
+
+`;
+            for (const rule of laneRules.sort((a, b) => b.confidence - a.confidence)) {
+              output += `- ${rule.text}
+`;
+            }
+            output += "\n";
+          }
+          return {
+            content: [{
+              type: "text",
+              text: output
+            }]
+          };
+        } catch (error) {
+          const errorMsg = error instanceof Error ? error.message : String(error);
+          return {
+            content: [{
+              type: "text",
+              text: `Error fetching orchestration rules: ${errorMsg}`
+            }]
+          };
+        }
+      }
       default:
         return { content: [{ type: "text", text: `Unknown tool: ${name}` }] };
     }

package/dist/cli.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import {
   runServer
-} from "./chunk-YTXBZTQ2.js";
+} from "./chunk-U2TWXSPB.js";
 
 // src/cli.ts
 function parseArgs() {

package/dist/index.js

@@ -1,7 +1,7 @@
 import {
   createMemoryMcpServer,
   runServer
-} from "./chunk-YTXBZTQ2.js";
+} from "./chunk-U2TWXSPB.js";
 export {
   createMemoryMcpServer,
   runServer

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "devsh-memory-mcp",
-  "version": "0.2.1",
+  "version": "0.3.1",
   "description": "MCP server for devsh/cmux agent memory - enables Claude Desktop and external clients to access sandbox memory and orchestrate multi-agent workflows",
   "type": "module",
   "main": "dist/index.js",