maestro-flow 0.5.38 → 0.5.40

package/.codex/skills/team-lifecycle-v4/instructions/agent-instruction.md

@@ -25,15 +25,12 @@
 
 2. **Explore domain** (use CLI analysis tools):
    ```
-   exec_command({
-     cmd: `maestro delegate "PURPOSE: Research domain for {requirement}
+   shell_exec(`maestro delegate "PURPOSE: Research domain for {requirement}
    TASK: • Identify problem statement • Define target users • Extract constraints • Map integration points
    CONTEXT: @**/* | Memory: {requirement}
    EXPECTED: Structured research context with problem/users/domain/constraints
-   CONSTRAINTS: Read-only analysis" --role analyze --mode analysis --rule analysis-trace-code-execution`,
-     yield_time_ms: 30000, max_output_tokens: 6000
-   })
-   // ⚠️ If session_id returned → poll write_stdin until completion (see @~/.maestro/workflows/delegate-protocol.codex.md)
+   CONSTRAINTS: Read-only analysis" --role analyze --mode analysis --rule analysis-trace-code-execution`, { timeout: 30000 })
+   // Execution mapping: @~/.maestro/workflows/shell-exec-protocol.md
    ```
 
 3. **Extract structured context**:
@@ -296,15 +293,12 @@
 
 2. **Explore codebase** (use CLI analysis tools):
    ```
-   exec_command({
-     cmd: `maestro delegate "PURPOSE: Explore codebase for {requirement}
+   shell_exec(`maestro delegate "PURPOSE: Explore codebase for {requirement}
    TASK: • Identify relevant files • Find existing patterns • Locate integration points
    CONTEXT: @**/* | Memory: {requirement}
    EXPECTED: Exploration findings with file paths and patterns
-   CONSTRAINTS: Read-only analysis" --role explore --mode analysis --rule analysis-trace-code-execution`,
-     yield_time_ms: 30000, max_output_tokens: 6000
-   })
-   // ⚠️ If session_id returned → poll write_stdin until completion (see @~/.maestro/workflows/delegate-protocol.codex.md)
+   CONSTRAINTS: Read-only analysis" --role explore --mode analysis --rule analysis-trace-code-execution`, { timeout: 30000 })
+   // Execution mapping: @~/.maestro/workflows/shell-exec-protocol.md
    ```
 
 3. **Generate implementation plan**:

package/.codex/skills/team-lifecycle-v4/roles/analyst/role.md

@@ -36,17 +36,13 @@ Research and codebase exploration for context gathering.
 4. If topic references file (@path or .md/.txt) -> read it
 5. CLI seed analysis:
    ```
-   exec_command({
-     cmd: `maestro delegate "PURPOSE: Analyze topic, extract structured seed info.
+   shell_exec(`maestro delegate "PURPOSE: Analyze topic, extract structured seed info.
    TASK: * Extract problem statement * Identify target users * Determine domain
    * List constraints * Identify 3-5 exploration dimensions
    TOPIC: <topic-content>
    MODE: analysis
-   EXPECTED: JSON with: problem_statement, target_users[], domain, constraints[], exploration_dimensions[]" --role analyze --mode analysis`,
-     yield_time_ms: 30000,
-     max_output_tokens: 6000
-   })
-   // ⚠️ If session_id returned → poll write_stdin until completion (see @~/.maestro/workflows/delegate-protocol.codex.md)
+   EXPECTED: JSON with: problem_statement, target_users[], domain, constraints[], exploration_dimensions[]" --role analyze --mode analysis`, { timeout: 30000 })
+   // Execution mapping: @~/.maestro/workflows/shell-exec-protocol.md
    // NEVER skip — seed analysis result is required for context packaging
    ```
 6. Parse result JSON
@@ -60,16 +56,12 @@ Research and codebase exploration for context gathering.
 
 When project detected:
 ```
-exec_command({
-  cmd: `maestro delegate "PURPOSE: Explore codebase for context
+shell_exec(`maestro delegate "PURPOSE: Explore codebase for context
 TASK: * Identify tech stack * Map architecture patterns * Document conventions * List integration points
 MODE: analysis
 CONTEXT: @**/*
-EXPECTED: JSON with: tech_stack[], architecture_patterns[], conventions[], integration_points[]" --role explore --mode analysis`,
-  yield_time_ms: 30000,
-  max_output_tokens: 6000
-})
-// ⚠️ If session_id returned → poll write_stdin until completion (see @~/.maestro/workflows/delegate-protocol.codex.md)
+EXPECTED: JSON with: tech_stack[], architecture_patterns[], conventions[], integration_points[]" --role explore --mode analysis`, { timeout: 30000 })
+// Execution mapping: @~/.maestro/workflows/shell-exec-protocol.md
 // NEVER skip — codebase context is required for downstream roles
 ```
 

package/.codex/skills/team-lifecycle-v4/roles/executor/commands/implement.md

@@ -51,12 +51,8 @@ CONSTRAINTS: Only modify listed files | Follow existing patterns
 
 CLI call:
 ```
-exec_command({
-  cmd: `maestro delegate "<prompt>" --role implement --mode write --rule development-implement-feature`,
-  yield_time_ms: 30000,
-  max_output_tokens: 6000
-})
-// ⚠️ If session_id returned → poll write_stdin until completion (see @~/.maestro/workflows/delegate-protocol.codex.md)
+shell_exec(`maestro delegate "<prompt>" --role implement --mode write --rule development-implement-feature`, { timeout: 30000 })
+// Execution mapping: @~/.maestro/workflows/shell-exec-protocol.md
 // NEVER skip — implementation must complete before convergence check
 ```
 

package/.codex/skills/team-lifecycle-v4/roles/planner/role.md

@@ -36,16 +36,12 @@ Codebase-informed implementation planning with complexity assessment.
 3. Check <session>/explorations/cache-index.json for cached explorations
 4. Explore codebase (cache-aware):
    ```
-   exec_command({
-     cmd: `maestro delegate "PURPOSE: Explore codebase to inform planning
+   shell_exec(`maestro delegate "PURPOSE: Explore codebase to inform planning
    TASK: * Search for relevant patterns * Identify files to modify * Document integration points
    MODE: analysis
    CONTEXT: @**/*
-   EXPECTED: JSON with: relevant_files[], patterns[], integration_points[], recommendations[]" --role explore --mode analysis`,
-     yield_time_ms: 30000,
-     max_output_tokens: 6000
-   })
-   // ⚠️ If session_id returned → poll write_stdin until completion (see @~/.maestro/workflows/delegate-protocol.codex.md)
+   EXPECTED: JSON with: relevant_files[], patterns[], integration_points[], recommendations[]" --role explore --mode analysis`, { timeout: 30000 })
+   // Execution mapping: @~/.maestro/workflows/shell-exec-protocol.md
    // NEVER skip — delegate result is required for plan generation
    ```
 5. Store results in <session>/explorations/
@@ -54,17 +50,13 @@ Codebase-informed implementation planning with complexity assessment.
 
 Generate plan.json + .task/TASK-*.json:
 ```
-exec_command({
-  cmd: `maestro delegate "PURPOSE: Generate implementation plan from exploration results
+shell_exec(`maestro delegate "PURPOSE: Generate implementation plan from exploration results
 TASK: * Create plan.json overview * Generate TASK-*.json files (2-7 tasks) * Define dependencies * Set convergence criteria
 MODE: write
 CONTEXT: @<session>/explorations/*.json
 EXPECTED: Files: plan.json + .task/TASK-*.json
-CONSTRAINTS: 2-7 tasks, include id/title/files[]/convergence.criteria/depends_on" --role implement --mode write`,
-  yield_time_ms: 30000,
-  max_output_tokens: 6000
-})
-// ⚠️ If session_id returned → poll write_stdin until completion (see @~/.maestro/workflows/delegate-protocol.codex.md)
+CONSTRAINTS: 2-7 tasks, include id/title/files[]/convergence.criteria/depends_on" --role implement --mode write`, { timeout: 30000 })
+// Execution mapping: @~/.maestro/workflows/shell-exec-protocol.md
 // NEVER skip — must wait for plan files to be written
 ```
 

package/.codex/skills/team-lifecycle-v4/roles/writer/role.md

@@ -61,17 +61,13 @@ Template-driven document generation with progressive dependency loading.
 
 CLI generation:
 ```
-exec_command({
-  cmd: `maestro delegate "PURPOSE: Generate <doc-type> document following template
+shell_exec(`maestro delegate "PURPOSE: Generate <doc-type> document following template
 TASK: * Load template * Apply spec config and discovery context * Integrate prior feedback * Generate all sections
 MODE: write
 CONTEXT: @<session>/spec/*.json @<template-path>
 EXPECTED: Document at <output-path> with YAML frontmatter, all sections, cross-references
-CONSTRAINTS: Follow document standards" --role implement --mode write --cd <session>`,
-  yield_time_ms: 30000,
-  max_output_tokens: 6000
-})
-// ⚠️ If session_id returned → poll write_stdin until completion (see @~/.maestro/workflows/delegate-protocol.codex.md)
+CONSTRAINTS: Follow document standards" --role implement --mode write --cd <session>`, { timeout: 30000 })
+// Execution mapping: @~/.maestro/workflows/shell-exec-protocol.md
 // NEVER skip — document must be fully written before validation
 ```
 

package/.codex/skills/team-quality-assurance/roles/scout/role.md

@@ -51,11 +51,8 @@ EXPECTED: List of findings with severity (critical/high/medium/low), file:line r
 CONSTRAINTS: Focus on actionable findings only
 ```
 ```
-exec_command({
-  cmd: `maestro delegate "<prompt>" --role analyze --mode analysis`,
-  yield_time_ms: 30000, max_output_tokens: 6000
-})
-// ⚠️ If session_id returned → poll write_stdin until completion (see @~/.maestro/workflows/delegate-protocol.codex.md)
+shell_exec(`maestro delegate "<prompt>" --role analyze --mode analysis`, { timeout: 30000 })
+// Execution mapping: @~/.maestro/workflows/shell-exec-protocol.md
 // NEVER skip — each perspective's findings are required for aggregation
 ```
 

package/.codex/skills/team-review/roles/reviewer/role.md

@@ -54,11 +54,8 @@ Build prompt per group requesting 6 enrichment fields per finding:
 
 Execute via:
 ```
-exec_command({
-  cmd: `maestro delegate "<prompt>" --role review --mode analysis --rule analysis-diagnose-bug-root-cause`,
-  yield_time_ms: 30000, max_output_tokens: 6000
-})
-// ⚠️ If session_id returned → poll write_stdin until completion (see @~/.maestro/workflows/delegate-protocol.codex.md)
+shell_exec(`maestro delegate "<prompt>" --role review --mode analysis --rule analysis-diagnose-bug-root-cause`, { timeout: 30000 })
+// Execution mapping: @~/.maestro/workflows/shell-exec-protocol.md
 // NEVER skip — enrichment results are required for report generation
 ```
 Parse JSON array responses, merge with originals (CLI-enriched replace originals, unenriched get defaults). Write `<session>/review/enriched-findings.json`.

package/.codex/skills/team-review/roles/scanner/role.md

@@ -61,11 +61,8 @@ Build prompt with target file patterns, toolchain dedup summary, and per-dimensi
 
 Execute via:
 ```
-exec_command({
-  cmd: `maestro delegate "<prompt>" --role review --mode analysis --rule analysis-review-code-quality`,
-  yield_time_ms: 30000, max_output_tokens: 6000
-})
-// ⚠️ If session_id returned → poll write_stdin until completion (see @~/.maestro/workflows/delegate-protocol.codex.md)
+shell_exec(`maestro delegate "<prompt>" --role review --mode analysis --rule analysis-review-code-quality`, { timeout: 30000 })
+// Execution mapping: @~/.maestro/workflows/shell-exec-protocol.md
 // NEVER skip — semantic findings are required for aggregation
 ```
 Parse JSON array response, validate required fields (dimension, title, location.file), enforce per-dimension limit (max 5 each), filter minimum severity (medium+). Write `<session>/scan/semantic-findings.json`.

package/.codex/skills/team-tech-debt/roles/executor/role.md

@@ -37,19 +37,15 @@ For each batch, use CLI tool for implementation:
 **Per-batch delegation**:
 
 ```
-exec_command({
-  cmd: `maestro delegate "PURPOSE: Apply tech debt fixes in batch; success = all items fixed without breaking changes
+shell_exec(`maestro delegate "PURPOSE: Apply tech debt fixes in batch; success = all items fixed without breaking changes
 TASK: <batch-type-specific-tasks>
 MODE: write
 CONTEXT: @<worktree-path>/**/* | Memory: Remediation plan context
 EXPECTED: Code changes that fix debt items, maintain backward compatibility, pass existing tests
 CONSTRAINTS: Minimal changes only | No new features | No suppressions | Read files before modifying
 Batch type: <refactor|update-deps|add-tests|add-docs|restructure>
-Items: <list-of-items-with-file-paths-and-descriptions>" --role implement --mode write --cd "<worktree-path>"`,
-  yield_time_ms: 30000,
-  max_output_tokens: 6000
-})
-// ⚠️ If session_id returned → poll write_stdin until completion (see @~/.maestro/workflows/delegate-protocol.codex.md)
+Items: <list-of-items-with-file-paths-and-descriptions>" --role implement --mode write --cd "<worktree-path>"`, { timeout: 30000 })
+// Execution mapping: @~/.maestro/workflows/shell-exec-protocol.md
 // NEVER skip — must wait for batch fix to complete before next batch or validation
 ```
 

package/.codex/skills/team-tech-debt/roles/scanner/role.md

@@ -63,11 +63,8 @@ Multi-dimension tech debt scanner. Scan codebase across 5 dimensions (code, arch
 
 **Delegate execution protocol** (applies to ALL fan-out CLI calls):
 ```
-exec_command({
-  cmd: `maestro delegate "<prompt>" --role <role> --mode analysis`,
-  yield_time_ms: 30000, max_output_tokens: 6000
-})
-// ⚠️ If session_id returned → poll write_stdin until completion (see @~/.maestro/workflows/delegate-protocol.codex.md)
+shell_exec(`maestro delegate "<prompt>" --role <role> --mode analysis`, { timeout: 30000 })
+// Execution mapping: @~/.maestro/workflows/shell-exec-protocol.md
 // NEVER skip — each fan-out result is required for fan-in merge
 ```
 

package/.codex/skills/team-tech-debt/roles/validator/role.md

@@ -58,17 +58,13 @@ Execute 4-layer validation (all commands in worktree):
 **Auto-fix attempt** (when total_regressions <= 3):
 - Use CLI tool to fix regressions in worktree:
   ```
-  exec_command({
-    cmd: `cd "${worktreePath}" && maestro delegate "PURPOSE: Fix regressions found in validation
+  shell_exec(`cd "${worktreePath}" && maestro delegate "PURPOSE: Fix regressions found in validation
   TASK: ${regressionDetails}
   MODE: write
   CONTEXT: @${modifiedFiles.join(' @')}
   EXPECTED: Fixed regressions
-  CONSTRAINTS: Fix only regressions | Preserve debt cleanup changes | No suppressions" --role implement --mode write`,
-    yield_time_ms: 30000,
-    max_output_tokens: 6000
-  })
-  // ⚠️ If session_id returned → poll write_stdin until completion (see @~/.maestro/workflows/delegate-protocol.codex.md)
+  CONSTRAINTS: Fix only regressions | Preserve debt cleanup changes | No suppressions" --role implement --mode write`, { timeout: 30000 })
+  // Execution mapping: @~/.maestro/workflows/shell-exec-protocol.md
   // NEVER skip — must wait for fix before re-running validation
   ```
 - Re-run validation checks after fix attempt

package/.codex/skills/team-testing/roles/executor/role.md

@@ -61,19 +61,15 @@ Bash("<test-command> 2>&1 || true")
 **Auto-fix delegation** (on failure):
 
 ```
-exec_command({
-  cmd: `maestro delegate "PURPOSE: Fix test failures to achieve pass rate >= 0.95; success = all tests pass
+shell_exec(`maestro delegate "PURPOSE: Fix test failures to achieve pass rate >= 0.95; success = all tests pass
 TASK: • Analyze test failure output • Identify root causes • Fix test code only (not source) • Preserve test intent
 MODE: write
 CONTEXT: @<session>/<test-dir>/**/* | Memory: Test framework: <framework>, iteration <N>/3
 EXPECTED: Fixed test files with: corrected assertions, proper async handling, fixed imports, maintained coverage
 CONSTRAINTS: Only modify test files | Preserve test structure | No source code changes
 Test failures:
-<test-output>" --role implement --mode write --cd <session>`,
-  yield_time_ms: 30000,
-  max_output_tokens: 6000
-})
-// ⚠️ If session_id returned → poll write_stdin until completion (see @~/.maestro/workflows/delegate-protocol.codex.md)
+<test-output>" --role implement --mode write --cd <session>`, { timeout: 30000 })
+// Execution mapping: @~/.maestro/workflows/shell-exec-protocol.md
 // NEVER skip — must wait for fix to complete before re-running tests
 ```
 

package/.codex/skills/team-testing/roles/generator/role.md

@@ -63,8 +63,7 @@ For revision mode:
 **CLI delegation** (medium/high complexity):
 
 ```
-exec_command({
-  cmd: `maestro delegate "PURPOSE: Generate <layer> tests using <framework> to achieve coverage target; success = all priority files covered with quality tests
+shell_exec(`maestro delegate "PURPOSE: Generate <layer> tests using <framework> to achieve coverage target; success = all priority files covered with quality tests
 TASK: • Analyze source files • Generate test cases (happy path, edge cases, errors) • Write test files with proper structure • Ensure import resolution
 MODE: write
 CONTEXT: @<source-files> @<session>/strategy/test-strategy.md | Memory: Framework: <framework>, Layer: <layer>, Round: <round>
@@ -73,11 +72,8 @@ Effective patterns: <patterns-from-meta>>
 EXPECTED: Test files in <session>/tests/<layer>/ with: proper test structure, comprehensive coverage, correct imports, framework conventions
 CONSTRAINTS: Follow test strategy priorities | Use framework best practices | <layer>-appropriate assertions
 Source files to test:
-<file-list-with-content>" --role implement --mode write --cd <session>`,
-  yield_time_ms: 30000,
-  max_output_tokens: 6000
-})
-// ⚠️ If session_id returned → poll write_stdin until completion (see @~/.maestro/workflows/delegate-protocol.codex.md)
+<file-list-with-content>" --role implement --mode write --cd <session>`, { timeout: 30000 })
+// Execution mapping: @~/.maestro/workflows/shell-exec-protocol.md
 // NEVER skip — must wait for test files to be generated before verification
 ```
 

package/dashboard/dist-server/dashboard/src/server/wiki/embedding.d.ts

@@ -28,6 +28,19 @@ export interface DeviceConfig {
     dtype: DtypeType;
     batchSize: number;
 }
+export interface EmbeddingApiConfig {
+    baseUrl: string;
+    apiKey: string;
+    model: string;
+    dimensions?: number;
+    /** Model context window in tokens. Used for dynamic batch sizing. Default: 8192. */
+    contextLength?: number;
+    /** Fixed batch size (number of texts). Overrides dynamic batching when set. */
+    batchSize?: number;
+    concurrency?: number;
+}
+export declare function loadEmbeddingApiConfig(): EmbeddingApiConfig | null;
+export declare function isApiMode(): boolean;
 export interface RankedResult {
     docId: string;
     score: number;
@@ -38,7 +51,6 @@ export interface RRFSignal {
     results: RankedResult[];
 }
 export declare function mergeRRFSignals(signals: RRFSignal[], limit: number, k?: number): RankedResult[];
-export declare function mergeRRF(bm25Results: RankedResult[], vectorResults: RankedResult[], limit: number, k?: number, bm25Weight?: number, vectorWeight?: number): RankedResult[];
 /**
  * Hybrid fusion: RRF for ordering stability + BM25 magnitude for score discrimination.
  * finalScore = alpha * rrfNorm + (1-alpha) * bm25Norm
@@ -62,7 +74,16 @@ export interface HardwareInfo {
     reason: string;
 }
 export declare function getHardwareInfo(): Promise<HardwareInfo>;
+export declare function getModelId(): string;
 export declare const DEFAULT_MODEL_ID = "Xenova/multilingual-e5-small";
+export type ModelProgressCallback = (info: {
+    status: string;
+    file?: string;
+    progress?: number;
+    loaded?: number;
+    total?: number;
+}) => void;
+export declare function setProgressCallback(cb: ModelProgressCallback | null): void;
 export declare function isAvailable(): Promise<boolean>;
 export declare function getUnavailableReason(): string | null;
 export declare function embedTexts(texts: string[]): Promise<Float32Array[]>;
@@ -78,5 +99,5 @@ export interface DocForEmbedding {
     body?: string;
 }
 export declare function hashDocContent(d: DocForEmbedding): string;
-export declare function buildEmbeddingIndex(docs: DocForEmbedding[], existingIndex?: EmbeddingIndex | null): Promise<EmbeddingIndex>;
+export declare function buildEmbeddingIndex(docs: DocForEmbedding[], existingIndex?: EmbeddingIndex | null, precomputedHashes?: string[]): Promise<EmbeddingIndex>;
 export {};