mstro-app 0.5.0 → 0.5.5

package/server/services/plan/dependency-resolver.ts

@@ -1,5 +1,4 @@
 // Copyright (c) 2025-present Mstro, Inc. All rights reserved.
-// Licensed under the MIT License. See LICENSE file for details.
 
 /**
  * Dependency Resolver — Validates and computes the dependency DAG.

package/server/services/plan/executor.ts

@@ -1,5 +1,4 @@
 // Copyright (c) 2025-present Mstro, Inc. All rights reserved.
-// Licensed under the MIT License. See LICENSE file for details.
 
 /**
  * Plan Executor — Wave-based execution with parallel headless Claude Code instances.
@@ -55,6 +54,40 @@ export type ExecutionStatus = 'idle' | 'starting' | 'executing' | 'paused' | 'st
 /** Stop after this many consecutive waves with zero completions. */
 const MAX_CONSECUTIVE_EMPTY_WAVES = 3;
 
+/**
+ * Render a tool-call event as a short single-line label for the verbose
+ * Output stream — `Read · package.json`, `Bash · npm test`, etc. The web UI
+ * splits the label on the first ` · ` to render the tool name as a badge.
+ */
+function formatToolCallLine(toolName: string, input: Record<string, unknown> | undefined): string {
+  const arg = pickPrimaryArg(toolName, input);
+  return arg ? `${toolName} · ${arg}` : toolName;
+}
+
+function pickPrimaryArg(toolName: string, input: Record<string, unknown> | undefined): string {
+  if (!input) return '';
+  // Map common Claude Code tools to their most informative single argument.
+  const candidates: Record<string, string[]> = {
+    Read: ['file_path'],
+    Write: ['file_path'],
+    Edit: ['file_path'],
+    Glob: ['pattern'],
+    Grep: ['pattern'],
+    Bash: ['command'],
+    WebFetch: ['url'],
+    WebSearch: ['query'],
+    Task: ['description'],
+  };
+  const keys = candidates[toolName] ?? ['command', 'file_path', 'path', 'pattern', 'url', 'query'];
+  for (const key of keys) {
+    const value = input[key];
+    if (typeof value === 'string' && value.length > 0) {
+      return value.length > 120 ? `${value.slice(0, 117)}...` : value;
+    }
+  }
+  return '';
+}
+
 /** Per-issue stall timeouts (ms) — shorter than Agent Teams wave timeouts */
 const ISSUE_STALL_WARNING_MS = 900_000;    // 15 min
 const ISSUE_STALL_KILL_MS = 1_800_000;     // 30 min
@@ -232,7 +265,6 @@ export class PlanExecutor extends EventEmitter {
   /** Run waves until done, paused, stopped, or stalled. */
   private async runWaveLoop(): Promise<'done' | 'stalled' | 'dead'> {
     let consecutiveZeroCompletions = 0;
-    const maxParallel = await getBoardMaxParallelAgents(this.context.pmDir, this.effectiveBoardId(), this.emitWarn);
 
     while (!this.shouldStop && !this.shouldPause) {
       const readyIssues = await this.pickReadyIssues();
@@ -241,6 +273,9 @@ export class PlanExecutor extends EventEmitter {
         return await this.hasDeadIssues() ? 'dead' : 'done';
       }
 
+      // Re-read on each wave so users can scale agents up/down mid-execution
+      // without restarting — the new value takes effect at the next wave boundary.
+      const maxParallel = await getBoardMaxParallelAgents(this.context.pmDir, this.effectiveBoardId(), this.emitWarn);
       const completedCount = await this.executeWave(readyIssues.slice(0, maxParallel));
 
       if (completedCount > 0) {
@@ -344,6 +379,7 @@ export class PlanExecutor extends EventEmitter {
     });
 
     const boardLogDir = boardDir ? join(boardDir, 'logs') : undefined;
+    const emitOutput = (text: string) => this.emit('output', { issueId: issue.id, text });
     const result = await runWithFileLogger(`pm-issue-${issue.id}`, () => runIssueWithRetry({
       workingDir: effectiveDir,
       prompt,
@@ -351,8 +387,16 @@ export class PlanExecutor extends EventEmitter {
       stallKillMs: ISSUE_STALL_KILL_MS,
       stallHardCapMs: ISSUE_STALL_HARD_CAP_MS,
       stallMaxExtensions: ISSUE_STALL_MAX_EXTENSIONS,
-      outputCallback: (text: string) => {
-        this.emit('output', { issueId: issue.id, text });
+      outputCallback: emitOutput,
+      // Thinking deltas: marker-prefix so the web UI can classify them as a
+      // separate verbose-only block type without needing a new message field.
+      thinkingCallback: (text: string) => emitOutput(`[[MSTRO_THINKING]]${text}`),
+      // Tool calls: emit a single line per completed tool with a short arg
+      // summary. The 'tool_complete' event fires after input has fully
+      // streamed in, so we can render the tool with its real arguments.
+      toolUseCallback: (event) => {
+        if (event.type !== 'tool_complete' || !event.toolName) return;
+        emitOutput(`[[MSTRO_TOOL]]${formatToolCallLine(event.toolName, event.completeInput)}`);
       },
       extraEnv: this.extraEnv,
       abortSignal,

package/server/services/plan/front-matter.ts

@@ -1,5 +1,4 @@
 // Copyright (c) 2025-present Mstro, Inc. All rights reserved.
-// Licensed under the MIT License. See LICENSE file for details.
 
 /**
  * Front Matter Utilities — Read/write YAML front matter fields.

package/server/services/plan/issue-classification.ts

@@ -1,5 +1,4 @@
 // Copyright (c) 2025-present Mstro, Inc. All rights reserved.
-// Licensed under the MIT License. See LICENSE file for details.
 
 import type { Issue } from './types.js';
 

package/server/services/plan/issue-loader.ts

@@ -1,5 +1,4 @@
 // Copyright (c) 2025-present Mstro, Inc. All rights reserved.
-// Licensed under the MIT License. See LICENSE file for details.
 
 /**
  * Issue loader: wraps parser.ts to load either board-scoped or

package/server/services/plan/issue-prompt-builder.ts

@@ -1,5 +1,4 @@
 // Copyright (c) 2025-present Mstro, Inc. All rights reserved.
-// Licensed under the MIT License. See LICENSE file for details.
 
 /**
  * Issue Prompt Builder — Constructs a prompt for a single headless Claude Code instance.
@@ -9,6 +8,7 @@
  */
 
 import { join } from 'node:path';
+import { type ResolvedAgent, resolveAgentHints } from './agent-resolver.js';
 import { resolveIsCodeTask } from './issue-classification.js';
 import type { Issue } from './types.js';
 
@@ -22,6 +22,41 @@ export interface IssuePromptOptions {
   outputPath: string;
 }
 
+/**
+ * Render the Agents section of an issue prompt. Splits resolved hints from
+ * unresolved ones so Claude knows which names are real subagents to delegate to
+ * via the Task tool, vs. role hints for which the user has no installed match.
+ */
+function renderAgentsSection(resolved: ResolvedAgent[]): string {
+  if (resolved.length === 0) return '';
+
+  const matched = resolved.filter(r => r.resolvedName);
+  const unmatched = resolved.filter(r => !r.resolvedName);
+
+  const lines: string[] = ['', '## Suggested Agents'];
+
+  if (matched.length > 0) {
+    lines.push('Delegate the relevant portions of this work to these subagents using the Task tool (subagent_type = the agent name). Use them as primary executors when the work matches their expertise:');
+    for (const r of matched) {
+      const desc = r.info?.description ? ` — ${r.info.description}` : '';
+      const labelHint = r.hint.toLowerCase() !== (r.resolvedName ?? '').toLowerCase()
+        ? ` (matched from "${r.hint}")`
+        : '';
+      lines.push(`- \`${r.resolvedName}\`${labelHint}${desc}`);
+    }
+  }
+
+  if (unmatched.length > 0) {
+    lines.push('');
+    lines.push('Role hints with no installed subagent match — use the general-purpose agent (or your best judgment) for work in these areas:');
+    for (const r of unmatched) {
+      lines.push(`- ${r.hint}`);
+    }
+  }
+
+  return `\n${lines.join('\n')}`;
+}
+
 /**
  * Build a self-contained prompt for one issue.
  * The resulting Claude Code session will work independently —
@@ -46,6 +81,8 @@ export function buildIssuePrompt(options: IssuePromptOptions): string {
     ? `\n## Predecessor Outputs\nRead these before starting — they contain context from upstream issues:\n${predecessorDocs.map(d => `- ${d}`).join('\n')}`
     : '';
 
+  const agentSection = renderAgentsSection(resolveAgentHints(issue.agents, workingDir));
+
   const outDir = boardDir ? join(boardDir, 'out') : pmDir ? join(pmDir, 'out') : join(workingDir, '.mstro', 'pm', 'out');
 
   return `You are executing issue ${issue.id}: ${issue.title}.
@@ -68,7 +105,7 @@ ${criteria || 'No specific criteria defined.'}
 
 ### Technical Notes
 ${issue.technicalNotes || 'None'}
-${files}${predecessorSection}
+${files}${predecessorSection}${agentSection}
 
 ## Your Task
 

package/server/services/plan/issue-retry.ts

@@ -1,8 +1,7 @@
 // Copyright (c) 2025-present Mstro, Inc. All rights reserved.
-// Licensed under the MIT License. See LICENSE file for details.
 
 import { ResilientRunner } from '../../cli/headless/resilient-runner.js';
-import type { SessionResult } from '../../cli/headless/types.js';
+import type { SessionResult, ToolUseEvent } from '../../cli/headless/types.js';
 
 export interface IssueRunnerConfig {
   workingDir: string;
@@ -12,6 +11,8 @@ export interface IssueRunnerConfig {
   stallHardCapMs: number;
   stallMaxExtensions: number;
   outputCallback?: (text: string) => void;
+  thinkingCallback?: (text: string) => void;
+  toolUseCallback?: (event: ToolUseEvent) => void;
   extraEnv?: Record<string, string>;
   abortSignal?: AbortSignal;
 }
@@ -27,6 +28,8 @@ export async function runIssueWithRetry(config: IssueRunnerConfig): Promise<Sess
     stallHardCapMs: config.stallHardCapMs,
     stallMaxExtensions: config.stallMaxExtensions,
     outputCallback: config.outputCallback,
+    thinkingCallback: config.thinkingCallback,
+    toolUseCallback: config.toolUseCallback,
     verbose: true,
     extraEnv: config.extraEnv,
     abortSignal: config.abortSignal,

package/server/services/plan/issue-writer.ts

@@ -1,5 +1,4 @@
 // Copyright (c) 2025-present Mstro, Inc. All rights reserved.
-// Licensed under the MIT License. See LICENSE file for details.
 
 /**
  * Issue file mutations: front-matter status updates, activity note appends,

package/server/services/plan/output-manager.ts

@@ -1,5 +1,4 @@
 // Copyright (c) 2025-present Mstro, Inc. All rights reserved.
-// Licensed under the MIT License. See LICENSE file for details.
 
 /**
  * Output Manager — Resolves output paths, lists existing docs, and publishes outputs.

package/server/services/plan/parser-core.ts

@@ -1,5 +1,4 @@
 // Copyright (c) 2025-present Mstro, Inc. All rights reserved.
-// Licensed under the MIT License. See LICENSE file for details.
 
 /**
  * YAML front-matter parsing and entity parsers for PPS (.mstro/pm/) files.
@@ -288,6 +287,7 @@ export function parseIssue(content: string, filePath: string): Issue {
     reviewGate: (['none', 'auto', 'required'].includes(String(fm.review_gate)) ? String(fm.review_gate) : 'auto') as Issue['reviewGate'],
     outputType: (['code', 'document', 'auto'].includes(String(fm.output_type)) ? String(fm.output_type) : 'auto') as Issue['outputType'],
     outputFile: optionalString(fm.output_file),
+    agents: toStringArray(fm.agents),
     body,
     path: filePath,
   };

package/server/services/plan/parser-migration.ts

@@ -1,5 +1,4 @@
 // Copyright (c) 2025-present Mstro, Inc. All rights reserved.
-// Licensed under the MIT License. See LICENSE file for details.
 
 /**
  * Legacy → Board-centric migration for .mstro/pm/ directories.

package/server/services/plan/parser.ts

@@ -1,5 +1,4 @@
 // Copyright (c) 2025-present Mstro, Inc. All rights reserved.
-// Licensed under the MIT License. See LICENSE file for details.
 
 /**
  * PPS Parser — Public API for reading .mstro/pm/ directories.

package/server/services/plan/progress-log.ts

@@ -1,5 +1,4 @@
 // Copyright (c) 2025-present Mstro, Inc. All rights reserved.
-// Licensed under the MIT License. See LICENSE file for details.
 
 /**
  * Progress log writer: ensures output directories exist and appends

package/server/services/plan/prompt-builder.ts

@@ -1,5 +1,4 @@
 // Copyright (c) 2025-present Mstro, Inc. All rights reserved.
-// Licensed under the MIT License. See LICENSE file for details.
 
 /**
  * Prompt Builder — Constructs the Agent Teams coordinator prompt.

package/server/services/plan/readiness-planner.ts

@@ -1,5 +1,4 @@
 // Copyright (c) 2025-present Mstro, Inc. All rights reserved.
-// Licensed under the MIT License. See LICENSE file for details.
 
 /**
  * Pure helpers for wave readiness: human-readable completion reasons

package/server/services/plan/review-gate.ts

@@ -1,5 +1,4 @@
 // Copyright (c) 2025-present Mstro, Inc. All rights reserved.
-// Licensed under the MIT License. See LICENSE file for details.
 
 /**
  * Review Gate — AI-powered quality gate for completed issues.

package/server/services/plan/state-reconciler.ts

@@ -1,5 +1,4 @@
 // Copyright (c) 2025-present Mstro, Inc. All rights reserved.
-// Licensed under the MIT License. See LICENSE file for details.
 
 /**
  * State Reconciler — Recomputes STATE.md from individual issue files.

package/server/services/plan/types.ts

@@ -1,5 +1,4 @@
 // Copyright (c) 2025-present Mstro, Inc. All rights reserved.
-// Licensed under the MIT License. See LICENSE file for details.
 
 /**
  * Plan Types — Project Plan Spec (PPS) data structures
@@ -99,6 +98,10 @@ export interface Issue {
   outputType: 'code' | 'document' | 'auto';
   // Planned output file path (from front matter output_file, relative to working dir)
   outputFile: string | null;
+  // Agent hints for the executing Claude Code session — names or general roles
+  // (e.g. ["backend-architect", "database-architect"], ["product, design"]).
+  // Empty = no agent hints; the executor uses default behavior.
+  agents: string[];
   // Full markdown body
   body: string;
   // File path relative to .mstro/pm/

package/server/services/plan/watcher.ts

@@ -1,5 +1,4 @@
 // Copyright (c) 2025-present Mstro, Inc. All rights reserved.
-// Licensed under the MIT License. See LICENSE file for details.
 
 /**
  * Plan Watcher — Watches .mstro/pm/ directory for changes and broadcasts updates.

package/server/services/platform-credentials.ts

@@ -1,5 +1,4 @@
 // Copyright (c) 2025-present Mstro, Inc. All rights reserved.
-// Licensed under the MIT License. See LICENSE file for details.
 
 /**
  * Platform Credentials — Token management for device authentication.

package/server/services/platform-token-lifecycle.ts

@@ -0,0 +1,171 @@
+// Copyright (c) 2025-present Mstro, Inc. All rights reserved.
+
+/**
+ * Token Lifecycle — refresh, verify, and auth-expired signaling for the
+ * platform device token. Extracted from PlatformConnection so the relay
+ * lifecycle (sockets, reconnect, heartbeat) and the auth lifecycle (token
+ * refresh, verify, expired-signal) can be reasoned about apart. The token
+ * lifecycle has its own clock (24h periodic check), its own remote endpoints
+ * (/refresh, /verify), and its own failure modes (revocation vs. transient
+ * network error) — none of which need to be in PlatformConnection.
+ */
+
+import {
+  getCredentials,
+  shouldRefreshToken,
+  updateCredentials,
+} from './platform-credentials.js'
+
+const PERIODIC_CHECK_INTERVAL_MS = 24 * 60 * 60 * 1000
+
+export interface TokenLifecycleDeps {
+  /** Platform base URL — used to compose /api/auth/device/{refresh,verify} */
+  platformUrl: string
+  /** Send a message upstream over the live relay socket (no-op if closed). */
+  send: (message: unknown) => void
+  /** Read the current relay connection ID at the moment auth-expired fires. */
+  getConnectionId: () => string | null
+}
+
+export class TokenLifecycle {
+  private intervalHandle: ReturnType<typeof setInterval> | null = null
+
+  constructor(private readonly deps: TokenLifecycleDeps) {}
+
+  /**
+   * Refresh the device token if it's older than the refresh interval.
+   * Returns `true` if the token is (still) valid after this call, `false`
+   * if refresh was attempted and rejected with an auth error — in which
+   * case the caller should surface an auth-expired signal to the web
+   * rather than silently reusing a dead token.
+   */
+  async maybeRefresh(): Promise<boolean> {
+    const creds = getCredentials()
+    if (!creds) return false
+    if (!shouldRefreshToken(creds)) return true
+
+    try {
+      const response = await fetch(`${this.deps.platformUrl}/api/auth/device/refresh`, {
+        method: 'POST',
+        headers: {
+          'Authorization': `Bearer ${creds.token}`,
+          'Content-Type': 'application/json'
+        }
+      })
+
+      if (response.ok) {
+        const data = await response.json() as { accessToken: string }
+        updateCredentials({
+          token: data.accessToken,
+          lastRefreshedAt: new Date().toISOString()
+        })
+        return true
+      }
+      if (response.status === 401 || response.status === 403) {
+        console.warn(`[Platform] Token refresh failed — auth is expired (${response.status}). Run \`mstro login --force\`.`)
+        this.notifyAuthExpired()
+        return false
+      }
+      console.warn(`[Platform] Token refresh failed with status ${response.status}, will retry later`)
+      return true
+    } catch (err) {
+      console.warn('[Platform] Token refresh error:', err)
+      return true
+    }
+  }
+
+  /**
+   * Verify the current token against the platform. A rejection (401/403)
+   * means the token is permanently invalid (revoked, signing-key rotation,
+   * account deleted); the caller should stop looping reconnects and tell
+   * the user to run `mstro login --force`.
+   *
+   * Returns `true` when the token is valid or the verification endpoint
+   * is unreachable (we prefer false negatives to false positives — a
+   * network blip shouldn't force a re-login).
+   */
+  async verify(): Promise<boolean> {
+    const creds = getCredentials()
+    if (!creds?.token) return false
+    try {
+      const response = await fetch(`${this.deps.platformUrl}/api/auth/device/verify`, {
+        method: 'POST',
+        headers: { 'Authorization': `Bearer ${creds.token}` },
+      })
+      if (response.status === 401 || response.status === 403) {
+        console.warn(`[Platform] Token verify rejected (${response.status}) — auth is expired.`)
+        return false
+      }
+      return true
+    } catch {
+      // Network error: treat as "probably valid" so a flaky connection
+      // doesn't force users to re-login. The WebSocket open itself will
+      // catch a truly bad token via the 4001 path.
+      return true
+    }
+  }
+
+  /**
+   * Surface an auth-expired condition to any paired web clients.
+   *
+   * Two cooperating paths deliver this signal — either alone is enough,
+   * both together cover every timing edge:
+   *
+   *   1. **CLI-initiated (this method):** we detected a 401 from the
+   *      `/refresh` or `/verify` endpoint *while the relay socket is
+   *      still open*. The injected `send` pushes the message upstream so
+   *      the server relays it to paired webs before the CLI closes.
+   *      A no-op if the socket is already closed.
+   *
+   *   2. **Server-initiated:** when the platform closes a CLI socket
+   *      with 4001 or 4008, `handleAuthClose` in `clientHandlers.ts`
+   *      broadcasts the same `clientAuthExpired` to paired webs. This
+   *      covers cases where the CLI never had a chance to detect the
+   *      rejection itself (e.g. token revoked while the socket was idle,
+   *      server-side token rotation).
+   *
+   * IMPORTANT: never route this through PlatformConnection's
+   * `onRelayedMessage` callback — that callback feeds INCOMING web→CLI
+   * requests into the local handler, which would treat
+   * `clientAuthExpired` as an unknown inbound request.
+   */
+  notifyAuthExpired(): void {
+    this.deps.send({
+      type: 'clientAuthExpired',
+      data: {
+        connectionId: this.deps.getConnectionId(),
+        message: 'The CLI\'s device token is invalid — run `mstro login --force` on the machine.',
+      },
+    })
+  }
+
+  /**
+   * Best-effort token verification, fired in parallel with the socket
+   * open so a slow verify endpoint never delays reconnect.
+   *
+   * Only runs when the token is stale enough that we'd be about to
+   * refresh anyway — keeps the hot path free of an extra network call.
+   * A truly-revoked token that slips past this check still hits 4001
+   * on the WebSocket, which also triggers `notifyAuthExpired`.
+   */
+  maybeVerifyInParallel(): void {
+    const creds = getCredentials()
+    if (!creds || !shouldRefreshToken(creds)) return
+    this.verify().then((valid) => {
+      if (!valid) this.notifyAuthExpired()
+    }).catch(() => { /* network error — rely on 4001 close path */ })
+  }
+
+  startPeriodicCheck(): void {
+    this.intervalHandle = setInterval(() => {
+      this.maybeRefresh()
+    }, PERIODIC_CHECK_INTERVAL_MS)
+  }
+
+  stopPeriodicCheck(): void {
+    if (this.intervalHandle) {
+      clearInterval(this.intervalHandle)
+      this.intervalHandle = null
+    }
+  }
+}